From: Gui Chen Date: Thu, 16 Aug 2012 13:17:51 +0000 (+0800) Subject: import source from 1.3.40 X-Git-Tag: 2.0_alpha^0 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;ds=sidebyside;p=external%2Fswig.git import source from 1.3.40 Signed-off-by: Gui Chen --- diff --git a/ANNOUNCE b/ANNOUNCE new file mode 100644 index 0000000..64e195d --- /dev/null +++ b/ANNOUNCE @@ -0,0 +1,37 @@ +*** ANNOUNCE: SWIG 1.3.40 (18 August 2009) *** + +http://www.swig.org + + +We're pleased to announce SWIG-1.3.40, the latest installment in the +SWIG development effort. SWIG-1.3.40 includes a number of bug fixes +and enhancements. + +What is SWIG? +------------- + +SWIG is a software development tool that reads C/C++ header files and +generates the wrapper code needed to make C and C++ code accessible +from other languages including Perl, Python, Tcl, Ruby, PHP, Java, +Scheme (Guile, MzScheme, CHICKEN), Ocaml, Lua, Pike, C#, Modula-3, Octave, R, +Common Lisp (CLISP, Allegro CL, CFFI, UFFI). SWIG can also export its parse +tree in the form of XML and Lisp s-expressions. Major applications of +SWIG include generation of scripting language extension modules, rapid +prototyping, testing, and user interface development for large C/C++ +systems. + +Availability: +------------- +The release is available for download on Sourceforge at + + http://prdownloads.sourceforge.net/swig/swig-1.3.40.tar.gz + +A Windows version is also available at + + http://prdownloads.sourceforge.net/swig/swigwin-1.3.40.zip + +Please report problems with this release to the swig-dev mailing list, +details at http://www.swig.org/mail.html. + +--- The SWIG Developers + diff --git a/CCache/COPYING b/CCache/COPYING new file mode 100644 index 0000000..a43ea21 --- /dev/null +++ b/CCache/COPYING @@ -0,0 +1,339 @@ + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc. + 675 Mass Ave, Cambridge, MA 02139, USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + Appendix: How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) 19yy + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) 19yy name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w' and `show c'; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + , 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. diff --git a/CCache/Makefile.in b/CCache/Makefile.in new file mode 100644 index 0000000..29cf8db --- /dev/null +++ b/CCache/Makefile.in @@ -0,0 +1,73 @@ +datarootdir = @datarootdir@ +srcdir=@srcdir@ +VPATH=@srcdir@ + +prefix=@prefix@ +exec_prefix=@exec_prefix@ +bindir=@bindir@ +mandir=@mandir@ +INSTALLCMD=@INSTALL@ +PACKAGE_NAME=@PACKAGE_NAME@ +# Soft link test can be skipped on systems that don't support soft linking +NOSOFTLINKSTEST= + +CC=@CC@ +CFLAGS=@CFLAGS@ -I. +SWIG=swig +SWIG_LIB=../../Lib +EXEEXT=@EXEEXT@ + +# Use standard autoconf approach to transform executable name using --program-prefix and --program-suffix +transform = @program_transform_name@ + +LIBS= @LIBS@ +OBJS= ccache.o mdfour.o hash.o execute.o util.o args.o stats.o \ + cleanup.o snprintf.o unify.o +HEADERS = ccache.h mdfour.h + +all: $(PACKAGE_NAME)$(EXEEXT) + +# Note that HTML documentation is actually generated and used from the main SWIG documentation Makefile +docs: $(PACKAGE_NAME).1 web/ccache-man.html + +$(PACKAGE_NAME)$(EXEEXT): $(OBJS) $(HEADERS) + $(CC) $(CFLAGS) $(LDFLAGS) -o $@ $(OBJS) $(LIBS) + +$(PACKAGE_NAME).1: ccache.yo + -yodl2man -o $(PACKAGE_NAME).1 ccache.yo + +web/ccache-man.html: ccache.yo + mkdir -p man + yodl2html -o web/ccache-man.html ccache.yo + +install: $(PACKAGE_NAME)$(EXEEXT) $(PACKAGE_NAME).1 + ${INSTALLCMD} -d $(DESTDIR)${bindir} + ${INSTALLCMD} -m 755 $(PACKAGE_NAME)$(EXEEXT) $(DESTDIR)${bindir}/`echo $(PACKAGE_NAME) | sed '$(transform)'`$(EXEEXT) + ${INSTALLCMD} -d $(DESTDIR)${mandir}/man1 + ${INSTALLCMD} -m 644 ${srcdir}/$(PACKAGE_NAME).1 $(DESTDIR)${mandir}/man1/`echo $(PACKAGE_NAME) | sed '$(transform)'`.1 + +uninstall: $(PACKAGE_NAME)$(EXEEXT) $(PACKAGE_NAME).1 + rm -f $(DESTDIR)${bindir}/`echo $(PACKAGE_NAME) | sed '$(transform)'`$(EXEEXT) + rm -f $(DESTDIR)${mandir}/man1/`echo $(PACKAGE_NAME) | sed '$(transform)'`.1 + +clean: + /bin/rm -f $(OBJS) *~ $(PACKAGE_NAME)$(EXEEXT) + +distclean-docs: + rm -f $(PACKAGE_NAME).1 web/ccache-man.html + +check : test + +test: test.sh + SWIG_LIB='$(SWIG_LIB)' PATH=../..:$$PATH SWIG='$(SWIG)' CC='$(CC)' NOSOFTLINKSTEST='$(NOSOFTLINKSTEST)' ./test.sh + +check: test + +distclean: clean distclean-docs + /bin/rm -f Makefile config.h config.sub config.log build-stamp config.status configure config.h + +# FIXME: To fix this, test.sh needs to be able to take ccache from the +# installed prefix, not from the source dir. +installcheck: + @echo "WARNING! This is not really \"installcheck\" yet." + $(MAKE) check diff --git a/CCache/README b/CCache/README new file mode 100644 index 0000000..6e68a6e --- /dev/null +++ b/CCache/README @@ -0,0 +1,31 @@ +This is a re-implementation of "compilercache" in C + +The original compilercache scripts were by Erik Thiele +(erikyyy@erikyyy.de) and I would like to thank him for an excellent +piece of work. See http://www.erikyyy.de/compilercache/ for the +original shell scripts. + +I wrote ccache because I wanted to get a bit more speed out of a +compiler cache and I wanted to remove some of the limitations of the +shell-script version. + +Please see the manual page and documentation at +http://ccache.samba.org/ + +INSTALLATION +------------ + +Please run: + + ./configure + make + make install + +then read the ccache manual page + +----------- + +Andrew Tridgell +http://samba.org/~tridge/ +bugs@ccache.samba.org + diff --git a/CCache/README.swig b/CCache/README.swig new file mode 100644 index 0000000..aea0f3d --- /dev/null +++ b/CCache/README.swig @@ -0,0 +1,8 @@ +This directory contains a version of ccache. The initial version was based on ccache-2.4 plus +debian patches 01-02, 04-14, see the debian/patches subdirectory. The ccache-win32-2.4 modifications +to ccache-2.4 have also been merged in. + +Changes have been made to support cacheing the output from SWIG. The ability to cache c/c++ compiler +output has been retained. + +Additional features added are the CCACHE_VERBOSE and CCACHE_SWIG environment variables, see docs. diff --git a/CCache/args.c b/CCache/args.c new file mode 100644 index 0000000..31e5471 --- /dev/null +++ b/CCache/args.c @@ -0,0 +1,91 @@ +/* + convenient routines for argument list handling + + Copyright (C) Andrew Tridgell 2002 + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. +*/ + +#include "ccache.h" + +ARGS *args_init(int init_argc, char **init_args) +{ + ARGS *args; + int i; + args = (ARGS *)x_malloc(sizeof(ARGS)); + args->argc = 0; + args->argv = (char **)x_malloc(sizeof(char *)); + args->argv[0] = NULL; + for (i=0;iargv = (char**)x_realloc(args->argv, (args->argc + 2) * sizeof(char *)); + args->argv[args->argc] = x_strdup(s); + args->argc++; + args->argv[args->argc] = NULL; +} + +/* pop the last element off the args list */ +void args_pop(ARGS *args, int n) +{ + while (n--) { + args->argc--; + free(args->argv[args->argc]); + args->argv[args->argc] = NULL; + } +} + +/* remove the first element of the argument list */ +void args_remove_first(ARGS *args) +{ + free(args->argv[0]); + memmove(&args->argv[0], + &args->argv[1], + args->argc * sizeof(args->argv[0])); + args->argc--; +} + +/* add an argument into the front of the argument list */ +void args_add_prefix(ARGS *args, const char *s) +{ + args->argv = (char**)x_realloc(args->argv, (args->argc + 2) * sizeof(char *)); + memmove(&args->argv[1], &args->argv[0], + (args->argc+1) * sizeof(args->argv[0])); + args->argv[0] = x_strdup(s); + args->argc++; +} + +/* strip any arguments beginning with the specified prefix */ +void args_strip(ARGS *args, const char *prefix) +{ + int i; + for (i=0; iargc; ) { + if (strncmp(args->argv[i], prefix, strlen(prefix)) == 0) { + free(args->argv[i]); + memmove(&args->argv[i], + &args->argv[i+1], + args->argc * sizeof(args->argv[i])); + args->argc--; + } else { + i++; + } + } +} diff --git a/CCache/ccache-swig.1 b/CCache/ccache-swig.1 new file mode 100644 index 0000000..292873a --- /dev/null +++ b/CCache/ccache-swig.1 @@ -0,0 +1,453 @@ +.TH "ccache-swig" "1" "" "" "" + +.PP +.SH "NAME" +ccache-swig \- a fast compiler cache +.PP +.SH "SYNOPSIS" + +.PP +ccache-swig [OPTION] +.PP +ccache-swig [COMPILER OPTIONS] +.PP + [COMPILER OPTIONS] +.PP +.SH "DESCRIPTION" + +.PP +ccache-swig is a compiler cache\&. It speeds up re-compilation of C/C++/SWIG code +by caching previous compiles and detecting when the same compile is +being done again\&. ccache-swig is ccache plus support for SWIG\&. ccache +and ccache-swig are used interchangeably in this document\&. +.PP +.SH "OPTIONS SUMMARY" + +.PP +Here is a summary of the options to ccache-swig\&. +.PP +.nf + +-s show statistics summary +-z zero statistics +-c run a cache cleanup +-C clear the cache completely +-F set maximum files in cache +-M set maximum size of cache (use G, M or K) +-h this help page +-V print version number + +.fi + +.PP +.SH "OPTIONS" + +.PP +These options only apply when you invoke ccache as "ccache-swig"\&. When +invoked as a compiler none of these options apply\&. In that case your +normal compiler options apply and you should refer to your compilers +documentation\&. +.PP +.IP "\fB-h\fP" +Print a options summary page +.IP +.IP "\fB-s\fP" +Print the current statistics summary for the cache\&. The +statistics are stored spread across the subdirectories of the +cache\&. Using "ccache-swig -s" adds up the statistics across all +subdirectories and prints the totals\&. +.IP +.IP "\fB-z\fP" +Zero the cache statistics\&. +.IP +.IP "\fB-V\fP" +Print the ccache version number +.IP +.IP "\fB-c\fP" +Clean the cache and re-calculate the cache file count and +size totals\&. Normally the -c option should not be necessary as ccache +keeps the cache below the specified limits at runtime and keeps +statistics up to date on each compile\&. This option is mostly useful +if you manually modify the cache contents or believe that the cache +size statistics may be inaccurate\&. +.IP +.IP "\fB-C\fP" +Clear the entire cache, removing all cached files\&. +.IP +.IP "\fB-F \fP" +This sets the maximum number of files allowed in +the cache\&. The value is stored inside the cache directory and applies +to all future compiles\&. Due to the way the value is stored the actual +value used is always rounded down to the nearest multiple of 16\&. +.IP +.IP "\fB-M \fP" +This sets the maximum cache size\&. You can specify +a value in gigabytes, megabytes or kilobytes by appending a G, M or K +to the value\&. The default is gigabytes\&. The actual value stored is +rounded down to the nearest multiple of 16 kilobytes\&. +.IP +.SH "INSTALLATION" + +.PP +There are two ways to use ccache\&. You can either prefix your compile +commands with "ccache-swig" or you can create a symbolic link between +ccache-swig and the names of your compilers\&. The first method is most +convenient if you just want to try out ccache or wish to use it for +some specific projects\&. The second method is most useful for when you +wish to use ccache for all your compiles\&. +.PP +To install for usage by the first method just copy ccache-swig to somewhere +in your path\&. +.PP +To install for the second method do something like this: +.nf + + cp ccache-swig /usr/local/bin/ + ln -s /usr/local/bin/ccache-swig /usr/local/bin/gcc + ln -s /usr/local/bin/ccache-swig /usr/local/bin/g++ + ln -s /usr/local/bin/ccache-swig /usr/local/bin/cc + ln -s /usr/local/bin/ccache-swig /usr/local/bin/swig + +.fi +This will work as long as /usr/local/bin comes before the path to gcc +(which is usually in /usr/bin)\&. After installing you may wish to run +"which gcc" to make sure that the correct link is being used\&. +.PP +Note! Do not use a hard link, use a symbolic link\&. A hardlink will +cause "interesting" problems\&. +.PP +.SH "EXTRA OPTIONS" + +.PP +When run as a compiler front end ccache usually just takes the same +command line options as the compiler you are using\&. The only exception +to this is the option \&'--ccache-skip\&'\&. That option can be used to tell +ccache that the next option is definitely not a input filename, and +should be passed along to the compiler as-is\&. +.PP +The reason this can be important is that ccache does need to parse the +command line and determine what is an input filename and what is a +compiler option, as it needs the input filename to determine the name +of the resulting object file (among other things)\&. The heuristic +ccache uses in this parse is that any string on the command line that +exists as a file is treated as an input file name (usually a C +file)\&. By using --ccache-skip you can force an option to not be +treated as an input file name and instead be passed along to the +compiler as a command line option\&. +.PP +.SH "ENVIRONMENT VARIABLES" + +.PP +ccache uses a number of environment variables to control operation\&. In +most cases you won\&'t need any of these as the defaults will be fine\&. +.PP +.IP "\fBCCACHE_DIR\fP" +the CCACHE_DIR environment variable specifies +where ccache will keep its cached compiler output\&. The default is +"$HOME/\&.ccache"\&. +.IP +.IP "\fBCCACHE_TEMPDIR\fP" +the CCACHE_TEMPDIR environment variable specifies +where ccache will put temporary files\&. The default is the same as +CCACHE_DIR\&. Note that the CCACHE_TEMPDIR path must be on the same +filesystem as the CCACHE_DIR path, so that renames of files between +the two directories can work\&. +.IP +.IP "\fBCCACHE_LOGFILE\fP" +If you set the CCACHE_LOGFILE environment +variable then ccache will write some log information on cache hits +and misses in that file\&. This is useful for tracking down problems\&. +.IP +.IP "\fBCCACHE_VERBOSE\fP" +If you set the CCACHE_VERBOSE environment +variable then ccache will display on stdout all the compiler invocations +that it makes\&. This can useful for debugging unexpected problems\&. +.IP +.IP "\fBCCACHE_PATH\fP" +You can optionally set CCACHE_PATH to a colon +separated path where ccache will look for the real compilers\&. If you +don\&'t do this then ccache will look for the first executable matching +the compiler name in the normal PATH that isn\&'t a symbolic link to +ccache itself\&. +.IP +.IP "\fBCCACHE_CC\fP" +You can optionally set CCACHE_CC to force the name +of the compiler to use\&. If you don\&'t do this then ccache works it out +from the command line\&. +.IP +.IP "\fBCCACHE_PREFIX\fP" +This option adds a prefix to the command line +that ccache runs when invoking the compiler\&. Also see the section +below on using ccache with distcc\&. +.IP +.IP "\fBCCACHE_DISABLE\fP" +If you set the environment variable +CCACHE_DISABLE then ccache will just call the real compiler, +bypassing the cache completely\&. +.IP +.IP "\fBCCACHE_READONLY\fP" +the CCACHE_READONLY environment variable +tells ccache to attempt to use existing cached object files, but not +to try to add anything new to the cache\&. If you are using this because +your CCACHE_DIR is read-only, then you may find that you also need to +set CCACHE_TEMPDIR as otherwise ccache will fail to create the +temporary files\&. +.IP +.IP "\fBCCACHE_CPP2\fP" +If you set the environment variable CCACHE_CPP2 +then ccache will not use the optimisation of avoiding the 2nd call to +the pre-processor by compiling the pre-processed output that was used +for finding the hash in the case of a cache miss\&. This is primarily a +debugging option, although it is possible that some unusual compilers +will have problems with the intermediate filename extensions used in +this optimisation, in which case this option could allow ccache to be +used\&. +.IP +.IP "\fBCCACHE_NOCOMPRESS\fP" +If you set the environment variable +CCACHE_NOCOMPRESS then there is no compression used on files that go +into the cache\&. However, this setting has no effect on how files are +retrieved from the cache, compressed results will still be usable\&. +.IP +.IP "\fBCCACHE_NOSTATS\fP" +If you set the environment variable +CCACHE_NOSTATS then ccache will not update the statistics files on +each compile\&. +.IP +.IP "\fBCCACHE_NLEVELS\fP" +The environment variable CCACHE_NLEVELS allows +you to choose the number of levels of hash in the cache directory\&. The +default is 2\&. The minimum is 1 and the maximum is 8\&. +.IP +.IP "\fBCCACHE_HARDLINK\fP" +If you set the environment variable +CCACHE_HARDLINK then ccache will attempt to use hard links from the +cache directory when creating the compiler output rather than using a +file copy\&. Using hard links is faster, but can confuse programs like +\&'make\&' that rely on modification times\&. Hard links are never made for +compressed cache files\&. +.IP +.IP "\fBCCACHE_RECACHE\fP" +This forces ccache to not use any cached +results, even if it finds them\&. New results are still cached, but +existing cache entries are ignored\&. +.IP +.IP "\fBCCACHE_UMASK\fP" +This sets the umask for ccache and all child +processes (such as the compiler)\&. This is mostly useful when you wish +to share your cache with other users\&. Note that this also affects the +file permissions set on the object files created from your +compilations\&. +.IP +.IP "\fBCCACHE_HASHDIR\fP" +This tells ccache to hash the current working +directory when calculating the hash that is used to distinguish two +compiles\&. This prevents a problem with the storage of the current +working directory in the debug info of a object file, which can lead +ccache to give a cached object file that has the working directory in +the debug info set incorrectly\&. This option is off by default as the +incorrect setting of this debug info rarely causes problems\&. If you +strike problems with gdb not using the correct directory then enable +this option\&. +.IP +.IP "\fBCCACHE_UNIFY\fP" +If you set the environment variable CCACHE_UNIFY +then ccache will use the C/C++ unifier when hashing the pre-processor +output if -g is not used in the compile\&. The unifier is slower than a +normal hash, so setting this environment variable loses a little bit +of speed, but it means that ccache can take advantage of not +recompiling when the changes to the source code consist of +reformatting only\&. Note that using CCACHE_UNIFY changes the hash, so +cached compiles with CCACHE_UNIFY set cannot be used when +CCACHE_UNIFY is not set and vice versa\&. The reason the unifier is off +by default is that it can give incorrect line number information in +compiler warning messages\&. +.IP +.IP "\fBCCACHE_EXTENSION\fP" +Normally ccache tries to automatically +determine the extension to use for intermediate C pre-processor files +based on the type of file being compiled\&. Unfortunately this sometimes +doesn\&'t work, for example when using the aCC compiler on HP-UX\&. On +systems like this you can use the CCACHE_EXTENSION option to override +the default\&. On HP-UX set this environment variable to "i" if you use +the aCC compiler\&. +.IP +.IP "\fBCCACHE_STRIPC\fP" +If you set the environment variable +CCACHE_STRIPC then ccache will strip the -c option when invoking +the preprocessor\&. This option is primarily for the Sun Workshop +C++ compiler as without this option an unwarranted warning is displayed: +CC: Warning: "-E" redefines product from "object" to "source (stdout)" +when -E and -c is used together\&. +.IP +.IP "\fBCCACHE_SWIG\fP" +When using SWIG as the compiler and it does not +have \&'swig\&' in the executable name, then the CCACHE_SWIG environment +variable needs to be set in order for ccache to work correctly with +SWIG\&. The use of CCACHE_CPP2 is also recommended for SWIG due to some +preprocessor quirks, however, use of CCACHE_CPP2 can often be skipped +-- check your generated code with and without this option set\&. Known +problems are using preprocessor directives within %inline blocks and +the use of \&'#pragma SWIG\&'\&. +.IP +.SH "CACHE SIZE MANAGEMENT" + +.PP +By default ccache has a one gigabyte limit on the cache size and no +maximum number of files\&. You can set a different limit using the +"ccache -M" and "ccache -F" options, which set the size and number of +files limits\&. +.PP +When these limits are reached ccache will reduce the cache to 20% +below the numbers you specified in order to avoid doing the cache +clean operation too often\&. +.PP +.SH "CACHE COMPRESSION" + +.PP +By default on most platforms ccache will compress all files it puts +into the cache +using the zlib compression\&. While this involves a negligible +performance slowdown, it significantly increases the number of files +that fit in the cache\&. You can turn off compression setting the +CCACHE_NOCOMPRESS environment variable\&. +.PP +.SH "HOW IT WORKS" + +.PP +The basic idea is to detect when you are compiling exactly the same +code a 2nd time and use the previously compiled output\&. You detect +that it is the same code by forming a hash of: +.PP +.IP o +the pre-processor output from running the compiler with -E +.IP o +the command line options +.IP o +the real compilers size and modification time +.IP o +any stderr output generated by the compiler + +.PP +These are hashed using md4 (a strong hash) and a cache file is formed +based on that hash result\&. When the same compilation is done a second +time ccache is able to supply the correct compiler output (including +all warnings etc) from the cache\&. +.PP +ccache has been carefully written to always produce exactly the same +compiler output that you would get without the cache\&. If you ever +discover a case where ccache changes the output of your compiler then +please let me know\&. +.PP +.SH "USING CCACHE WITH DISTCC" + +.PP +distcc is a very useful program for distributing compilation across a +range of compiler servers\&. It is often useful to combine distcc with +ccache, so that compiles that are done are sped up by distcc, but that +ccache avoids the compile completely where possible\&. +.PP +To use distcc with ccache I recommend using the CCACHE_PREFIX +option\&. You just need to set the environment variable CCACHE_PREFIX to +\&'distcc\&' and ccache will prefix the command line used with the +compiler with the command \&'distcc\&'\&. +.PP +.SH "SHARING A CACHE" + +.PP +A group of developers can increase the cache hit rate by sharing a +cache directory\&. The hard links however cause unwanted side effects, +as all links to a cached file share the file\&'s modification timestamp\&. +This results in false dependencies to be triggered by timestamp-based +build systems whenever another user links to an existing +file\&. Typically, users will see that their libraries and binaries are +relinked without reason\&. To share a cache without side effects, the +following conditions need to be met: +.PP +.IP o +Use the same \fBCCACHE_DIR\fP environment variable setting +.IP o +Unset the \fBCCACHE_HARDLINK\fP environment variable +.IP o +Make sure everyone sets the CCACHE_UMASK environment variable +to 002, this ensures that cached files are accessible to everyone in +the group\&. +.IP o +Make sure that all users have write permission in the entire +cache directory (and that you trust all users of the shared cache)\&. +.IP o +Make sure that the setgid bit is set on all directories in the +cache\&. This tells the filesystem to inherit group ownership for new +directories\&. The command "chmod g+s `find $CCACHE_DIR -type d`" might +be useful for this\&. +.IP o +Set \fBCCACHE_NOCOMPRESS\fP for all users, if there are users with +versions of ccache that do not support compression\&. + +.PP +.SH "HISTORY" + +.PP +ccache was inspired by the compilercache shell script script written +by Erik Thiele and I would like to thank him for an excellent piece of +work\&. See +http://www\&.erikyyy\&.de/compilercache/ +for the Erik\&'s scripts\&. +ccache-swig is a port of the original ccache with support added for use +with SWIG\&. +.PP +I wrote ccache because I wanted to get a bit more speed out of a +compiler cache and I wanted to remove some of the limitations of the +shell-script version\&. +.PP +.SH "DIFFERENCES FROM COMPILERCACHE" + +.PP +The biggest differences between Erik\&'s compilercache script and ccache +are: +.IP o +ccache is written in C, which makes it a bit faster (calling out to +external programs is mostly what slowed down the scripts)\&. +.IP o +ccache can automatically find the real compiler +.IP o +ccache keeps statistics on hits/misses +.IP o +ccache can do automatic cache management +.IP o +ccache can cache compiler output that includes warnings\&. In many +cases this gives ccache a much higher cache hit rate\&. +.IP o +ccache can handle a much wider ranger of compiler options +.IP o +ccache avoids a double call to cpp on a cache miss + +.PP +.SH "CREDITS" + +.PP +Thanks to the following people for their contributions to ccache +.IP o +Erik Thiele for the original compilercache script +.IP o +Luciano Rocha for the idea of compiling the pre-processor output +to avoid a 2nd cpp pass +.IP o +Paul Russell for many suggestions and the debian packaging + +.PP +.SH "AUTHOR" + +.PP +ccache was written by Andrew Tridgell +http://samba\&.org/~tridge/\&. +ccache was adapted to create ccache-swig for use with SWIG by William Fulton\&. +.PP +If you wish to report a problem or make a suggestion then please email +the SWIG developers on the swig-devel mailing list, see +http://www\&.swig\&.org/mail\&.html +.PP +ccache is released under the GNU General Public License version 2 or +later\&. Please see the file COPYING for license details\&. +.PP + diff --git a/CCache/ccache.c b/CCache/ccache.c new file mode 100644 index 0000000..d1696da --- /dev/null +++ b/CCache/ccache.c @@ -0,0 +1,1388 @@ +/* + a re-implementation of the compilercache scripts in C + + The idea is based on the shell-script compilercache by Erik Thiele + + Copyright (C) Andrew Tridgell 2002 + Copyright (C) Martin Pool 2003 + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. +*/ + +#include "ccache.h" + +/* verbose mode */ +int ccache_verbose = 0; + +/* the base cache directory */ +char *cache_dir = NULL; + +/* the directory for temporary files */ +static char *temp_dir = NULL; + +/* the debug logfile name, if set */ +char *cache_logfile = NULL; + +/* the argument list after processing */ +static ARGS *stripped_args; + +/* the original argument list */ +static ARGS *orig_args; + +/* the output filename being compiled to */ +static char *output_file; + +/* the source file */ +static char *input_file; + +/* the name of the file containing the cached object code */ +static char *hashname; + +/* the extension of the file after pre-processing */ +static const char *i_extension; + +/* the name of the temporary pre-processor file */ +static char *i_tmpfile; + +/* are we compiling a .i or .ii file directly? */ +static int direct_i_file; + +/* the name of the cpp stderr file */ +static char *cpp_stderr; + +/* the name of the statistics file */ +char *stats_file = NULL; + +/* can we safely use the unification hashing backend? */ +static int enable_unify; + +/* should we strip -c when running the preprocessor only? */ +static int strip_c_option; + +/* customisation for using the SWIG compiler */ +static int swig; + +/* a list of supported file extensions, and the equivalent + extension for code that has been through the pre-processor +*/ +static struct { + char *extension; + char *i_extension; +} extensions[] = { + {"c", "i"}, + {"C", "ii"}, + {"m", "mi"}, + {"cc", "ii"}, + {"CC", "ii"}, + {"cpp", "ii"}, + {"CPP", "ii"}, + {"cxx", "ii"}, + {"CXX", "ii"}, + {"c++", "ii"}, + {"C++", "ii"}, + {"i", "i"}, + {"ii", "ii"}, + {NULL, NULL}}; + +/* + something went badly wrong - just execute the real compiler +*/ +static void failed(void) +{ + char *e; + + /* delete intermediate pre-processor file if needed */ + if (i_tmpfile) { + if (!direct_i_file) { + unlink(i_tmpfile); + } + free(i_tmpfile); + i_tmpfile = NULL; + } + + /* delete the cpp stderr file if necessary */ + if (cpp_stderr) { + unlink(cpp_stderr); + free(cpp_stderr); + cpp_stderr = NULL; + } + + /* strip any local args */ + args_strip(orig_args, "--ccache-"); + + if ((e=getenv("CCACHE_PREFIX"))) { + char *p = find_executable(e, MYNAME); + if (!p) { + cc_log("could not find executable (%s)\n", e); + perror(e); + exit(1); + } + args_add_prefix(orig_args, p); + } + + if (ccache_verbose) { + display_execute_args(orig_args->argv); + } + + if (swig) { + putenv("CCACHE_OUTFILES"); + } + +#ifndef _WIN32 + execv(orig_args->argv[0], orig_args->argv); + cc_log("execv returned (%s)!\n", strerror(errno)); + perror(orig_args->argv[0]); + exit(1); +#else + /* execv on Windows causes the 'non-regular' testcase to fail, so use Win32 API instead */ + { + PROCESS_INFORMATION pinfo; + STARTUPINFO sinfo; + BOOL ret; + DWORD exitcode; + char *args; + + ZeroMemory(&pinfo, sizeof(PROCESS_INFORMATION)); + ZeroMemory(&sinfo, sizeof(STARTUPINFO)); + sinfo.cb = sizeof(STARTUPINFO); + args = argvtos(orig_args->argv); + ret = CreateProcessA(orig_args->argv[0], args, NULL, NULL, TRUE, 0, NULL, NULL, + &sinfo, &pinfo); + if (!ret) { + exitcode = 1; + cc_log("CreateProcessA failed starting %s\n", orig_args->argv[0]); + perror_win32(orig_args->argv[0]); + } else { + WaitForSingleObject(pinfo.hProcess, INFINITE); + GetExitCodeProcess(pinfo.hProcess, &exitcode); + CloseHandle(pinfo.hProcess); + CloseHandle(pinfo.hThread); + } + free(args); + exit(exitcode); + } +#endif +} + + +/* return a string to be used to distinguish temporary files + this also tries to cope with NFS by adding the local hostname +*/ +static const char *tmp_string(void) +{ + static char *ret; + + if (!ret) { + char hostname[200]; + strcpy(hostname, "unknown"); +#if HAVE_GETHOSTNAME + gethostname(hostname, sizeof(hostname)-1); +#endif + hostname[sizeof(hostname)-1] = 0; + if (asprintf(&ret, "%s.%u", hostname, (unsigned)getpid()) == -1) { + fatal("could not allocate tmp_string"); + } + } + + return ret; +} + +/* update cached file sizes and count helper function for to_cache() */ +static void to_cache_stats_helper(struct stat *pstat, char *cached_filename, char *tmp_outfiles, int *files_size, int *cached_files_count) +{ +#if ENABLE_ZLIB + /* do an extra stat on the cache file for the size statistics */ + if (stat(cached_filename, pstat) != 0) { + cc_log("failed to stat cache files - %s\n", strerror(errno)); + stats_update(STATS_ERROR); + if (tmp_outfiles) { + unlink(tmp_outfiles); + } + failed(); + } +#else + (void)cached_filename; + (void)tmp_outfiles; +#endif + (*files_size) += file_size(pstat); + (*cached_files_count)++; +} + +/* run the real compiler and put the result in cache */ +static void to_cache(ARGS *args) +{ + char *path_stderr; + char *tmp_stdout, *tmp_stderr, *tmp_outfiles; + struct stat st1; + int status; + int cached_files_count = 0; + int files_size = 0; + + x_asprintf(&tmp_stdout, "%s/tmp.stdout.%s", temp_dir, tmp_string()); + x_asprintf(&tmp_stderr, "%s/tmp.stderr.%s", temp_dir, tmp_string()); + x_asprintf(&tmp_outfiles, "%s/tmp.outfiles.%s", temp_dir, tmp_string()); + + if (strip_c_option && !swig) { + args_add(stripped_args, "-c"); + } + + if (output_file) { + args_add(args, "-o"); + args_add(args, output_file); + } + + /* Turn off DEPENDENCIES_OUTPUT when running cc1, because + * otherwise it will emit a line like + * + * tmp.stdout.vexed.732.o: /home/mbp/.ccache/tmp.stdout.vexed.732.i + * + * unsetenv() is on BSD and Linux but not portable. */ + putenv("DEPENDENCIES_OUTPUT"); + + /* Give SWIG a filename for it to create and populate with a list of files that it generates */ + if (swig) { + char *ccache_outfiles; + x_asprintf(&ccache_outfiles, "CCACHE_OUTFILES=%s", tmp_outfiles); + unlink(tmp_outfiles); + if (getenv("CCACHE_OUTFILES") || putenv(ccache_outfiles) == -1) { + cc_log("CCACHE_OUTFILES env variable already set or could not be set\n"); + stats_update(STATS_ERROR); + failed(); + } + } + + if (getenv("CCACHE_CPP2")) { + args_add(args, input_file); + } else { + if (swig) { + args_add(args, "-nopreprocess"); + } + args_add(args, i_tmpfile); + } + status = execute(args->argv, tmp_stdout, tmp_stderr); + args_pop(args, 3); + + if (stat(tmp_stdout, &st1) != 0 || st1.st_size != 0) { + cc_log("compiler produced stdout for %s\n", input_file); + stats_update(STATS_STDOUT); + unlink(tmp_stdout); + unlink(tmp_stderr); + unlink(tmp_outfiles); + if (!swig) unlink(output_file); + failed(); + } + unlink(tmp_stdout); + + if (status != 0) { + int fd; + cc_log("compile of %s gave status = %d\n", input_file, status); + stats_update(STATS_STATUS); + + fd = open(tmp_stderr, O_RDONLY | O_BINARY); + if (fd != -1) { + if (cpp_stderr) { + /* we might have some stderr from cpp */ + int fd2 = open(cpp_stderr, O_RDONLY | O_BINARY); + if (fd2 != -1) { + copy_fd(fd2, 2); + close(fd2); + unlink(cpp_stderr); + cpp_stderr = NULL; + } + } + + /* we can use a quick method of + getting the failed output */ + copy_fd(fd, 2); + close(fd); + unlink(tmp_stderr); + if (i_tmpfile && !direct_i_file) { + unlink(i_tmpfile); + } + exit(status); + } + + unlink(tmp_stderr); + unlink(tmp_outfiles); + if (!swig) unlink(output_file); + failed(); + } else { + int hardlink = (getenv("CCACHE_NOCOMPRESS") != 0) && (getenv("CCACHE_HARDLINK") != 0); + if (swig) { + /* read the list of generated files and copy each of them into the cache */ + FILE *file; + file = fopen(tmp_outfiles, "r"); + if (file) { + char out_filename[FILENAME_MAX + 1]; + char out_filename_cache[FILENAME_MAX + 1]; + while (fgets(out_filename, FILENAME_MAX, file)) { + char *linefeed = strchr(out_filename, '\n'); + if (linefeed) { + char *potential_cr = linefeed - 1; + if (potential_cr >= out_filename && *potential_cr == '\r') + *potential_cr = 0; + *linefeed = 0; + + if (cached_files_count == 0) { + strcpy(out_filename_cache, hashname); + } else { + sprintf(out_filename_cache, "%s.%d", hashname, cached_files_count); + } + + if (commit_to_cache(out_filename, out_filename_cache, hardlink) != 0) { + fclose(file); + unlink(tmp_outfiles); + failed(); + } + to_cache_stats_helper(&st1, out_filename_cache, tmp_outfiles, &files_size, &cached_files_count); + } else { + cached_files_count = 0; + break; + } + } + fclose(file); + if (cached_files_count == 0) { + cc_log("failed to copy output files to cache - internal error\n"); + stats_update(STATS_ERROR); + unlink(tmp_outfiles); + failed(); + } + + /* also copy the (uncompressed) file containing the list of generated files into the cache */ + sprintf(out_filename_cache, "%s.outfiles", hashname); + if (stat(tmp_outfiles, &st1) != 0 || + safe_rename(tmp_outfiles, out_filename_cache) != 0) { + cc_log("failed to copy outfiles file to cache - %s\n", strerror(errno)); + stats_update(STATS_ERROR); + unlink(tmp_outfiles); + failed(); + } + to_cache_stats_helper(&st1, out_filename_cache, tmp_outfiles, &files_size, &cached_files_count); + unlink(tmp_outfiles); + } else { + cc_log("failed to open temp outfiles file - %s\n", strerror(errno)); + stats_update(STATS_ERROR); + failed(); + } + } else { + if (commit_to_cache(output_file, hashname, hardlink) != 0) { + failed(); + } + to_cache_stats_helper(&st1, hashname, 0, &files_size, &cached_files_count); + } + } + + x_asprintf(&path_stderr, "%s.stderr", hashname); + + if (stat(tmp_stderr, &st1) != 0 || + move_file(tmp_stderr, path_stderr) != 0) { + cc_log("failed to rename tmp files - %s\n", strerror(errno)); + stats_update(STATS_ERROR); + failed(); + } + + to_cache_stats_helper(&st1, path_stderr, 0, &files_size, &cached_files_count); + + cc_log("Placed %d files for %s into cache\n", cached_files_count, input_file); + stats_tocache(files_size, cached_files_count); + + free(tmp_stderr); + free(tmp_stdout); + free(tmp_outfiles); + free(path_stderr); +} + +/* find the hash for a command. The hash includes all argument lists, + plus the output from running the compiler with -E */ +static void find_hash(ARGS *args) +{ + int i; + char *path_stdout, *path_stderr; + char *hash_dir; + char *s; + struct stat st; + int status; + int nlevels = 2; + char *input_base; + char *tmp; + + if ((s = getenv("CCACHE_NLEVELS"))) { + nlevels = atoi(s); + if (nlevels < 1) nlevels = 1; + if (nlevels > 8) nlevels = 8; + } + + hash_start(); + + /* when we are doing the unifying tricks we need to include + the input file name in the hash to get the warnings right */ + if (enable_unify || swig) { + hash_string(input_file); + } + + if (swig) { + if (output_file) { + hash_string(output_file); + } + } else { + /* we have to hash the extension, as a .i file isn't treated the same + by the compiler as a .ii file */ + hash_string(i_extension); + } + + /* first the arguments */ + for (i=1;iargc;i++) { + /* some arguments don't contribute to the hash. The + theory is that these arguments will change the + output of -E if they are going to have any effect + at all, or they only affect linking */ + if (i < args->argc-1) { + if (strcmp(args->argv[i], "-I") == 0 || + strcmp(args->argv[i], "-include") == 0 || + strcmp(args->argv[i], "-L") == 0 || + strcmp(args->argv[i], "-D") == 0 || + strcmp(args->argv[i], "-idirafter") == 0 || + strcmp(args->argv[i], "-isystem") == 0) { + i++; + continue; + } + } + if (strncmp(args->argv[i], "-I", 2) == 0 || + strncmp(args->argv[i], "-L", 2) == 0 || + strncmp(args->argv[i], "-D", 2) == 0 || + strncmp(args->argv[i], "-idirafter", 10) == 0 || + strncmp(args->argv[i], "-isystem", 8) == 0) { + continue; + } + + if (strncmp(args->argv[i], "--specs=", 8) == 0 && + stat(args->argv[i]+8, &st) == 0) { + /* if given a explicit specs file, then hash that file, but + don't include the path to it in the hash */ + hash_file(args->argv[i]+8); + continue; + } + + /* all other arguments are included in the hash */ + hash_string(args->argv[i]); + } + + /* the compiler driver size and date. This is a simple minded way + to try and detect compiler upgrades. It is not 100% reliable */ + if (stat(args->argv[0], &st) != 0) { + cc_log("Couldn't stat the compiler!? (argv[0]='%s')\n", args->argv[0]); + stats_update(STATS_COMPILER); + failed(); + } + + /* also include the hash of the compiler name - as some compilers + use hard links and behave differently depending on the real name */ + if (st.st_nlink > 1) { + hash_string(str_basename(args->argv[0])); + } + + hash_int(st.st_size); + hash_int(st.st_mtime); + + /* possibly hash the current working directory */ + if (getenv("CCACHE_HASHDIR")) { + char *cwd = gnu_getcwd(); + if (cwd) { + hash_string(cwd); + free(cwd); + } + } + + /* ~/hello.c -> tmp.hello.123.i + limit the basename to 10 + characters in order to cope with filesystem with small + maximum filename length limits */ + input_base = str_basename(input_file); + tmp = strchr(input_base, '.'); + if (tmp != NULL) { + *tmp = 0; + } + if (strlen(input_base) > 10) { + input_base[10] = 0; + } + + /* now the run */ + x_asprintf(&path_stdout, "%s/%s.tmp.%s.%s", temp_dir, + input_base, tmp_string(), + i_extension); + x_asprintf(&path_stderr, "%s/tmp.cpp_stderr.%s", temp_dir, tmp_string()); + + if (!direct_i_file) { + /* run cpp on the input file to obtain the .i */ + args_add(args, "-E"); + args_add(args, input_file); + status = execute(args->argv, path_stdout, path_stderr); + args_pop(args, 2); + } else { + /* we are compiling a .i or .ii file - that means we + can skip the cpp stage and directly form the + correct i_tmpfile */ + path_stdout = x_strdup(input_file); + if (create_empty_file(path_stderr) != 0) { + cc_log("failed to create empty stderr file\n"); + stats_update(STATS_ERROR); + failed(); + } + status = 0; + } + + if (status != 0) { + if (!direct_i_file) { + unlink(path_stdout); + } + unlink(path_stderr); + cc_log("the preprocessor gave %d\n", status); + stats_update(STATS_PREPROCESSOR); + failed(); + } + + /* if the compilation is with -g then we have to include the whole of the + preprocessor output, which means we are sensitive to line number + information. Otherwise we can discard line number info, which makes + us less sensitive to reformatting changes + + Note! I have now disabled the unification code by default + as it gives the wrong line numbers for warnings. Pity. + */ + if (!enable_unify) { + hash_file(path_stdout); + } else { + if (unify_hash(path_stdout) != 0) { + stats_update(STATS_ERROR); + failed(); + } + } + hash_file(path_stderr); + + i_tmpfile = path_stdout; + + if (!getenv("CCACHE_CPP2")) { + /* if we are using the CPP trick then we need to remember this stderr + data and output it just before the main stderr from the compiler + pass */ + cpp_stderr = path_stderr; + } else { + unlink(path_stderr); + free(path_stderr); + } + + /* we use a N level subdir for the cache path to reduce the impact + on filesystems which are slow for large directories + */ + s = hash_result(); + x_asprintf(&hash_dir, "%s/%c", cache_dir, s[0]); + x_asprintf(&stats_file, "%s/stats", hash_dir); + for (i=1; i= out_filename && *potential_cr == '\r') + *potential_cr = 0; + *linefeed = 0; + + if (retrieved_files_count == 0) { + strcpy(out_filename_cache, hashname); + } else { + sprintf(out_filename_cache, "%s.%d", hashname, retrieved_files_count); + } + + passfail = retrieve_from_cache(out_filename_cache, out_filename, hardlink); + if (passfail == -1) { + break; + } + + retrieved_files_count++; + } else { + cc_log("failed to copy output files from cache - internal error\n"); + stats_update(STATS_ERROR); + passfail = -1; + break; + } + } + if (retrieved_files_count == 0) { + cc_log("failed to copy output files from cache - internal error\n"); + stats_update(STATS_ERROR); + passfail = -1; + } + fclose(file); + } else { + cc_log("failed to open cached outfiles file - %s\n", strerror(errno)); + stats_update(STATS_ERROR); + } + } else { + passfail = retrieve_from_cache(hashname, output_file, hardlink); + } + + free(stderr_file); + if (passfail == -1) { + close(fd_stderr); + unlink(stderr_file); + return; + } + } + + /* get rid of the intermediate preprocessor file */ + if (i_tmpfile) { + if (!direct_i_file) { + unlink(i_tmpfile); + } + free(i_tmpfile); + i_tmpfile = NULL; + } + + /* send the cpp stderr, if applicable */ + fd_cpp_stderr = open(cpp_stderr, O_RDONLY | O_BINARY); + if (fd_cpp_stderr != -1) { + copy_fd(fd_cpp_stderr, 2); + close(fd_cpp_stderr); + unlink(cpp_stderr); + free(cpp_stderr); + cpp_stderr = NULL; + } + + /* send the stderr */ + copy_fd(fd_stderr, 2); + close(fd_stderr); + + /* and exit with the right status code */ + if (first) { + cc_log("got cached result for %s\n", input_file); + stats_update(STATS_CACHED); + } + + exit(0); +} + +/* find the real compiler. We just search the PATH to find a executable of the + same name that isn't a link to ourselves */ +static void find_compiler(int argc, char **argv) +{ + char *base; + char *path; + + orig_args = args_init(argc, argv); + + base = str_basename(argv[0]); + + /* we might be being invoked like "ccache gcc -c foo.c" */ + if (strcmp(base, MYNAME) == 0) { + args_remove_first(orig_args); + free(base); + if (strchr(argv[1],'/') +#ifdef _WIN32 + || strchr(argv[1],'\\') +#endif + ) { + /* a full path was given */ + return; + } + base = str_basename(argv[1]); + } + + /* support user override of the compiler */ + if ((path=getenv("CCACHE_CC"))) { + base = x_strdup(path); + } + + orig_args->argv[0] = find_executable(base, MYNAME); + + /* can't find the compiler! */ + if (!orig_args->argv[0]) { + stats_update(STATS_COMPILER); + cc_log("could not find compiler (%s)\n", base); + perror(base); + exit(1); + } +} + + +/* check a filename for C/C++ extension. Return the pre-processor + extension */ +static const char *check_extension(const char *fname, int *direct_i) +{ + int i; + const char *p; + + if (direct_i) { + *direct_i = 0; + } + + if (swig) return "ii"; /* any file extension is acceptable as input for SWIG */ + + p = strrchr(fname, '.'); + if (!p) return NULL; + p++; + for (i=0; extensions[i].extension; i++) { + if (strcmp(p, extensions[i].extension) == 0) { + if (direct_i && strcmp(p, extensions[i].i_extension) == 0) { + *direct_i = 1; + } + p = getenv("CCACHE_EXTENSION"); + if (p) return p; + return extensions[i].i_extension; + } + } + return NULL; +} + + +/* + process the compiler options to form the correct set of options + for obtaining the preprocessor output +*/ +static void process_args(int argc, char **argv) +{ + int i; + int found_c_opt = 0; + int found_S_opt = 0; + struct stat st; + char *e; + /* is gcc being asked to output dependencies? */ + int generating_dependencies = 0; + /* is the dependency makefile name overridden with -MF? */ + int dependency_filename_specified = 0; + /* is the dependency makefile target name specified with -MQ or -MF? */ + int dependency_target_specified = 0; + + + stripped_args = args_init(0, NULL); + + args_add(stripped_args, argv[0]); + + /* -c not required for SWIG */ + if (swig) { + found_c_opt = 1; + } + + for (i=1; iargv[0]); + if (strstr(basename, "swig") || getenv("CCACHE_SWIG")) { + swig = 1; + } + free(basename); +} + +/* the main ccache driver function */ +static void ccache(int argc, char *argv[]) +{ + /* find the real compiler */ + find_compiler(argc, argv); + + /* use the real compiler if HOME is not set */ + if (!cache_dir) { + cc_log("Unable to determine home directory\n"); + cc_log("ccache is disabled\n"); + failed(); + } + + /* we might be disabled */ + if (getenv("CCACHE_DISABLE")) { + cc_log("ccache is disabled\n"); + failed(); + } + + if (getenv("CCACHE_STRIPC")) { + strip_c_option = 1; + } + + if (getenv("CCACHE_UNIFY")) { + enable_unify = 1; + } + + detect_swig(); + + /* process argument list, returning a new set of arguments for pre-processing */ + process_args(orig_args->argc, orig_args->argv); + + /* run with -E to find the hash */ + find_hash(stripped_args); + + /* if we can return from cache at this point then do */ + from_cache(1); + + if (getenv("CCACHE_READONLY")) { + cc_log("read-only set - doing real compile\n"); + failed(); + } + + /* run real compiler, sending output to cache */ + to_cache(stripped_args); + + /* return from cache */ + from_cache(0); + + /* oh oh! */ + cc_log("secondary from_cache failed!\n"); + stats_update(STATS_ERROR); + failed(); +} + + +static void usage(void) +{ + printf("%s, a compiler cache including support for SWIG. Version %s\n", MYNAME, CCACHE_VERSION); + printf("Copyright Andrew Tridgell, 2002\n\n"); + + printf("Usage:\n"); + printf("\t" MYNAME " [options]\n"); + printf("\t" MYNAME " compiler [compile options]\n"); + printf("\tcompiler [compile options] (via symbolic link)\n"); + printf("\nOptions:\n"); + + printf("-s show statistics summary\n"); + printf("-z zero statistics\n"); + printf("-c run a cache cleanup\n"); + printf("-C clear the cache completely\n"); + printf("-F set maximum files in cache\n"); + printf("-M set maximum size of cache (use G, M or K)\n"); + printf("-h this help page\n"); + printf("-V print version number\n"); +} + +static void check_cache_dir(void) +{ + if (!cache_dir) { + fatal("Unable to determine home directory"); + } +} + +/* the main program when not doing a compile */ +static int ccache_main(int argc, char *argv[]) +{ + int c; + size_t v; + + while ((c = getopt(argc, argv, "hszcCF:M:V")) != -1) { + switch (c) { + case 'V': + printf("%s version %s\n", MYNAME, CCACHE_VERSION); + printf("Copyright Andrew Tridgell 2002\n"); + printf("Released under the GNU GPL v2 or later\n"); + exit(0); + + case 'h': + usage(); + exit(0); + + case 's': + check_cache_dir(); + stats_summary(); + break; + + case 'c': + check_cache_dir(); + cleanup_all(cache_dir); + printf("Cleaned cache\n"); + break; + + case 'C': + check_cache_dir(); + wipe_all(cache_dir); + printf("Cleared cache\n"); + break; + + case 'z': + check_cache_dir(); + stats_zero(); + printf("Statistics cleared\n"); + break; + + case 'F': + check_cache_dir(); + v = atoi(optarg); + if (stats_set_limits(v, -1) == 0) { + printf("Set cache file limit to %u\n", (unsigned)v); + } else { + printf("Could not set cache file limit.\n"); + exit(1); + } + break; + + case 'M': + check_cache_dir(); + v = value_units(optarg); + if (stats_set_limits(-1, v) == 0) { + printf("Set cache size limit to %uk\n", (unsigned)v); + } else { + printf("Could not set cache size limit.\n"); + exit(1); + } + break; + + default: + usage(); + exit(1); + } + } + + return 0; +} + + +/* Make a copy of stderr that will not be cached, so things like + distcc can send networking errors to it. */ +static void setup_uncached_err(void) +{ + char *buf; + int uncached_fd; + + uncached_fd = dup(2); + if (uncached_fd == -1) { + cc_log("dup(2) failed\n"); + stats_update(STATS_ERROR); + failed(); + } + + /* leak a pointer to the environment */ + x_asprintf(&buf, "UNCACHED_ERR_FD=%d", uncached_fd); + + if (putenv(buf) == -1) { + cc_log("putenv failed\n"); + stats_update(STATS_ERROR); + failed(); + } +} + + +int main(int argc, char *argv[]) +{ + char *p; + + cache_dir = getenv("CCACHE_DIR"); + if (!cache_dir) { + const char *home_directory = get_home_directory(); + if (home_directory) { + x_asprintf(&cache_dir, "%s/.ccache", home_directory); + } + } + + cache_logfile = getenv("CCACHE_LOGFILE"); + + if (getenv("CCACHE_VERBOSE")) { + ccache_verbose = 1; + } + + setup_uncached_err(); + + + /* the user might have set CCACHE_UMASK */ + p = getenv("CCACHE_UMASK"); + if (p) { + mode_t mask; + errno = 0; + mask = strtol(p, NULL, 8); + if (errno == 0) { + umask(mask); + } + } + + + /* check if we are being invoked as "ccache" */ + if (strlen(argv[0]) >= strlen(MYNAME) && + strcmp(argv[0] + strlen(argv[0]) - strlen(MYNAME), MYNAME) == 0) { + if (argc < 2) { + usage(); + exit(1); + } + /* if the first argument isn't an option, then assume we are + being passed a compiler name and options */ + if (argv[1][0] == '-') { + return ccache_main(argc, argv); + } + } + + /* make sure the cache dir exists */ + if (cache_dir && (create_dir(cache_dir) != 0)) { + fprintf(stderr,"ccache: failed to create %s (%s)\n", + cache_dir, strerror(errno)); + exit(1); + } + + temp_dir = getenv("CCACHE_TEMPDIR"); + if (!temp_dir) { + x_asprintf(&temp_dir, "%s/temp", cache_dir); + /* make sure temp dir exists if not supplied by user */ + if (temp_dir && create_dir(temp_dir) != 0) { + fprintf(stderr,"ccache: failed to create %s (%s)\n", + temp_dir, strerror(errno)); + exit(1); + } + } + + if (!getenv("CCACHE_READONLY")) { + if (create_cachedirtag(cache_dir) != 0) { + fprintf(stderr,"ccache: failed to create %s/CACHEDIR.TAG (%s)\n", + cache_dir, strerror(errno)); + exit(1); + } + } + + ccache(argc, argv); + return 1; +} diff --git a/CCache/ccache.h b/CCache/ccache.h new file mode 100644 index 0000000..668ce82 --- /dev/null +++ b/CCache/ccache.h @@ -0,0 +1,205 @@ +#include "ccache_swig_config.h" + +#define CCACHE_VERSION SWIG_VERSION + +#ifndef _WIN32 +#include "config.h" +#else +#include +#define PACKAGE_NAME "ccache-swig.exe" +#endif + +#include +#include +#include +#include +#include +#include + +#ifndef _WIN32 + #include + #include +#else +#define _WIN32_WINNT 0x0500 + #include + #include +#endif + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#ifdef HAVE_PWD_H +#include +#endif +#ifdef HAVE_SYS_TIME_H +#include +#endif + +#ifdef ENABLE_ZLIB +#include +#endif + +#define STATUS_NOTFOUND 3 +#define STATUS_FATAL 4 +#define STATUS_NOCACHE 5 + +#define MYNAME PACKAGE_NAME + +#define LIMIT_MULTIPLE 0.8 + +/* default maximum cache size */ +#ifndef DEFAULT_MAXSIZE +#define DEFAULT_MAXSIZE (1000*1000) +#endif + +/* file copy mode */ +#ifdef ENABLE_ZLIB +#define COPY_UNCOMPRESSED 0 +#define COPY_FROM_CACHE 1 +#define COPY_TO_CACHE 2 +#endif + +enum stats { + STATS_NONE=0, + STATS_STDOUT, + STATS_STATUS, + STATS_ERROR, + STATS_TOCACHE, + STATS_PREPROCESSOR, + STATS_COMPILER, + STATS_MISSING, + STATS_CACHED, + STATS_ARGS, + STATS_LINK, + STATS_NUMFILES, + STATS_TOTALSIZE, + STATS_MAXFILES, + STATS_MAXSIZE, + STATS_NOTC, + STATS_DEVICE, + STATS_NOINPUT, + STATS_ENVIRONMMENT, + STATS_MULTIPLE, + STATS_CONFTEST, + STATS_UNSUPPORTED, + STATS_OUTSTDOUT, + + STATS_END +}; + +typedef unsigned uint32; + +#include "mdfour.h" + +void hash_start(void); +void hash_string(const char *s); +void hash_int(int x); +void hash_file(const char *fname); +char *hash_result(void); +void hash_buffer(const char *s, int len); + +void cc_log(const char *format, ...); +void fatal(const char *msg); + +void copy_fd(int fd_in, int fd_out); +int safe_rename(const char* oldpath, const char* newpath); +int move_file(const char *src, const char *dest); +int test_if_compressed(const char *filename); + +int commit_to_cache(const char *src, const char *dest, int hardlink); +int retrieve_from_cache(const char *src, const char *dest, int hardlink); + +int create_dir(const char *dir); +int create_cachedirtag(const char *dir); +void x_asprintf(char **ptr, const char *format, ...); +char *x_strdup(const char *s); +void *x_realloc(void *ptr, size_t size); +void *x_malloc(size_t size); +void traverse(const char *dir, void (*fn)(const char *, struct stat *)); +char *str_basename(const char *s); +char *dirname(char *s); +int lock_fd(int fd); +size_t file_size(struct stat *st); +int safe_open(const char *fname); +char *x_realpath(const char *path); +char *gnu_getcwd(void); +int create_empty_file(const char *fname); +const char *get_home_directory(void); +int x_utimes(const char *filename); +#ifdef _WIN32 +void perror_win32(LPTSTR pszFunction); +#endif + +void stats_update(enum stats stat); +void stats_zero(void); +void stats_summary(void); +void stats_tocache(size_t size, size_t numfiles); +void stats_read(const char *stats_file, unsigned counters[STATS_END]); +int stats_set_limits(long maxfiles, long maxsize); +size_t value_units(const char *s); +void display_size(unsigned v); +void stats_set_sizes(const char *dir, size_t num_files, size_t total_size); + +int unify_hash(const char *fname); + +#ifndef HAVE_VASPRINTF +int vasprintf(char **, const char *, va_list ); +#endif +#ifndef HAVE_ASPRINTF +int asprintf(char **ptr, const char *format, ...); +#endif + +#ifndef HAVE_SNPRINTF +int snprintf(char *,size_t ,const char *, ...); +#endif + +void cleanup_dir(const char *dir, size_t maxfiles, size_t maxsize); +void cleanup_all(const char *dir); +void wipe_all(const char *dir); + +#ifdef _WIN32 +char *argvtos(char **argv); +#endif +int execute(char **argv, + const char *path_stdout, + const char *path_stderr); +char *find_executable(const char *name, const char *exclude_name); +void display_execute_args(char **argv); + +typedef struct { + char **argv; + int argc; +} ARGS; + + +ARGS *args_init(int , char **); +void args_add(ARGS *args, const char *s); +void args_add_prefix(ARGS *args, const char *s); +void args_pop(ARGS *args, int n); +void args_strip(ARGS *args, const char *prefix); +void args_remove_first(ARGS *args); + +extern int ccache_verbose; + +#if HAVE_COMPAR_FN_T +#define COMPAR_FN_T __compar_fn_t +#else +typedef int (*COMPAR_FN_T)(const void *, const void *); +#endif + +/* work with silly DOS binary open */ +#ifndef O_BINARY +#define O_BINARY 0 +#endif + +/* mkstemp() on some versions of cygwin don't handle binary files, so + override */ +#ifdef __CYGWIN__ +#undef HAVE_MKSTEMP +#endif diff --git a/CCache/ccache.yo b/CCache/ccache.yo new file mode 100644 index 0000000..2477662 --- /dev/null +++ b/CCache/ccache.yo @@ -0,0 +1,422 @@ +whenman( +COMMENT(html output not great if included when using html2doc) +manpage(ccache-swig)(1)()()() +) + +whenhtml(htmlcommand( + + + + +ccache-swig(1) manpage + + + + +

Using SWIG with ccache - ccache-swig(1) manpage

+ +
+ + +)) + + +manpagename(ccache-swig)(a fast compiler cache) + +whenhtml(htmlcommand( +ccache-swig - a fast compiler cache +)) + +manpagesynopsis() + +ccache-swig [OPTION] + +ccache-swig [COMPILER OPTIONS] + + [COMPILER OPTIONS] + +manpagedescription() + +ccache-swig is a compiler cache. It speeds up re-compilation of C/C++/SWIG code +by caching previous compiles and detecting when the same compile is +being done again. ccache-swig is ccache plus support for SWIG. ccache +and ccache-swig are used interchangeably in this document. + +manpagesection(OPTIONS SUMMARY) + +Here is a summary of the options to ccache-swig. + +verb( +-s show statistics summary +-z zero statistics +-c run a cache cleanup +-C clear the cache completely +-F set maximum files in cache +-M set maximum size of cache (use G, M or K) +-h this help page +-V print version number +) + +manpageoptions() + +These options only apply when you invoke ccache as "ccache-swig". When +invoked as a compiler none of these options apply. In that case your +normal compiler options apply and you should refer to your compilers +documentation. + +startdit() +dit(bf(-h)) Print a options summary page + +dit(bf(-s)) Print the current statistics summary for the cache. The +statistics are stored spread across the subdirectories of the +cache. Using "ccache-swig -s" adds up the statistics across all +subdirectories and prints the totals. + +dit(bf(-z)) Zero the cache statistics. + +dit(bf(-V)) Print the ccache version number + +dit(bf(-c)) Clean the cache and re-calculate the cache file count and +size totals. Normally the -c option should not be necessary as ccache +keeps the cache below the specified limits at runtime and keeps +statistics up to date on each compile. This option is mostly useful +if you manually modify the cache contents or believe that the cache +size statistics may be inaccurate. + +dit(bf(-C)) Clear the entire cache, removing all cached files. + +dit(bf(-F )) This sets the maximum number of files allowed in +the cache. The value is stored inside the cache directory and applies +to all future compiles. Due to the way the value is stored the actual +value used is always rounded down to the nearest multiple of 16. + +dit(bf(-M )) This sets the maximum cache size. You can specify +a value in gigabytes, megabytes or kilobytes by appending a G, M or K +to the value. The default is gigabytes. The actual value stored is +rounded down to the nearest multiple of 16 kilobytes. + +enddit() + +manpagesection(INSTALLATION) + +There are two ways to use ccache. You can either prefix your compile +commands with "ccache-swig" or you can create a symbolic link between +ccache-swig and the names of your compilers. The first method is most +convenient if you just want to try out ccache or wish to use it for +some specific projects. The second method is most useful for when you +wish to use ccache for all your compiles. + +To install for usage by the first method just copy ccache-swig to somewhere +in your path. + +To install for the second method do something like this: +verb( + cp ccache-swig /usr/local/bin/ + ln -s /usr/local/bin/ccache-swig /usr/local/bin/gcc + ln -s /usr/local/bin/ccache-swig /usr/local/bin/g++ + ln -s /usr/local/bin/ccache-swig /usr/local/bin/cc + ln -s /usr/local/bin/ccache-swig /usr/local/bin/swig +) +This will work as long as /usr/local/bin comes before the path to gcc +(which is usually in /usr/bin). After installing you may wish to run +"which gcc" to make sure that the correct link is being used. + +Note! Do not use a hard link, use a symbolic link. A hardlink will +cause "interesting" problems. + +manpagesection(EXTRA OPTIONS) + +When run as a compiler front end ccache usually just takes the same +command line options as the compiler you are using. The only exception +to this is the option '--ccache-skip'. That option can be used to tell +ccache that the next option is definitely not a input filename, and +should be passed along to the compiler as-is. + +The reason this can be important is that ccache does need to parse the +command line and determine what is an input filename and what is a +compiler option, as it needs the input filename to determine the name +of the resulting object file (among other things). The heuristic +ccache uses in this parse is that any string on the command line that +exists as a file is treated as an input file name (usually a C +file). By using --ccache-skip you can force an option to not be +treated as an input file name and instead be passed along to the +compiler as a command line option. + +manpagesection(ENVIRONMENT VARIABLES) + +ccache uses a number of environment variables to control operation. In +most cases you won't need any of these as the defaults will be fine. + +startdit() + +dit(bf(CCACHE_DIR)) the CCACHE_DIR environment variable specifies +where ccache will keep its cached compiler output. The default is +"$HOME/.ccache". + +dit(bf(CCACHE_TEMPDIR)) the CCACHE_TEMPDIR environment variable specifies +where ccache will put temporary files. The default is the same as +CCACHE_DIR. Note that the CCACHE_TEMPDIR path must be on the same +filesystem as the CCACHE_DIR path, so that renames of files between +the two directories can work. + +dit(bf(CCACHE_LOGFILE)) If you set the CCACHE_LOGFILE environment +variable then ccache will write some log information on cache hits +and misses in that file. This is useful for tracking down problems. + +dit(bf(CCACHE_VERBOSE)) If you set the CCACHE_VERBOSE environment +variable then ccache will display on stdout all the compiler invocations +that it makes. This can useful for debugging unexpected problems. + +dit(bf(CCACHE_PATH)) You can optionally set CCACHE_PATH to a colon +separated path where ccache will look for the real compilers. If you +don't do this then ccache will look for the first executable matching +the compiler name in the normal PATH that isn't a symbolic link to +ccache itself. + +dit(bf(CCACHE_CC)) You can optionally set CCACHE_CC to force the name +of the compiler to use. If you don't do this then ccache works it out +from the command line. + +dit(bf(CCACHE_PREFIX)) This option adds a prefix to the command line +that ccache runs when invoking the compiler. Also see the section +below on using ccache with distcc. + +dit(bf(CCACHE_DISABLE)) If you set the environment variable +CCACHE_DISABLE then ccache will just call the real compiler, +bypassing the cache completely. + +dit(bf(CCACHE_READONLY)) the CCACHE_READONLY environment variable +tells ccache to attempt to use existing cached object files, but not +to try to add anything new to the cache. If you are using this because +your CCACHE_DIR is read-only, then you may find that you also need to +set CCACHE_TEMPDIR as otherwise ccache will fail to create the +temporary files. + +dit(bf(CCACHE_CPP2)) If you set the environment variable CCACHE_CPP2 +then ccache will not use the optimisation of avoiding the 2nd call to +the pre-processor by compiling the pre-processed output that was used +for finding the hash in the case of a cache miss. This is primarily a +debugging option, although it is possible that some unusual compilers +will have problems with the intermediate filename extensions used in +this optimisation, in which case this option could allow ccache to be +used. + +dit(bf(CCACHE_NOCOMPRESS)) If you set the environment variable +CCACHE_NOCOMPRESS then there is no compression used on files that go +into the cache. However, this setting has no effect on how files are +retrieved from the cache, compressed results will still be usable. + +dit(bf(CCACHE_NOSTATS)) If you set the environment variable +CCACHE_NOSTATS then ccache will not update the statistics files on +each compile. + +dit(bf(CCACHE_NLEVELS)) The environment variable CCACHE_NLEVELS allows +you to choose the number of levels of hash in the cache directory. The +default is 2. The minimum is 1 and the maximum is 8. + +dit(bf(CCACHE_HARDLINK)) If you set the environment variable +CCACHE_HARDLINK then ccache will attempt to use hard links from the +cache directory when creating the compiler output rather than using a +file copy. Using hard links is faster, but can confuse programs like +'make' that rely on modification times. Hard links are never made for +compressed cache files. + +dit(bf(CCACHE_RECACHE)) This forces ccache to not use any cached +results, even if it finds them. New results are still cached, but +existing cache entries are ignored. + +dit(bf(CCACHE_UMASK)) This sets the umask for ccache and all child +processes (such as the compiler). This is mostly useful when you wish +to share your cache with other users. Note that this also affects the +file permissions set on the object files created from your +compilations. + +dit(bf(CCACHE_HASHDIR)) This tells ccache to hash the current working +directory when calculating the hash that is used to distinguish two +compiles. This prevents a problem with the storage of the current +working directory in the debug info of a object file, which can lead +ccache to give a cached object file that has the working directory in +the debug info set incorrectly. This option is off by default as the +incorrect setting of this debug info rarely causes problems. If you +strike problems with gdb not using the correct directory then enable +this option. + +dit(bf(CCACHE_UNIFY)) If you set the environment variable CCACHE_UNIFY +then ccache will use the C/C++ unifier when hashing the pre-processor +output if -g is not used in the compile. The unifier is slower than a +normal hash, so setting this environment variable loses a little bit +of speed, but it means that ccache can take advantage of not +recompiling when the changes to the source code consist of +reformatting only. Note that using CCACHE_UNIFY changes the hash, so +cached compiles with CCACHE_UNIFY set cannot be used when +CCACHE_UNIFY is not set and vice versa. The reason the unifier is off +by default is that it can give incorrect line number information in +compiler warning messages. + +dit(bf(CCACHE_EXTENSION)) Normally ccache tries to automatically +determine the extension to use for intermediate C pre-processor files +based on the type of file being compiled. Unfortunately this sometimes +doesn't work, for example when using the aCC compiler on HP-UX. On +systems like this you can use the CCACHE_EXTENSION option to override +the default. On HP-UX set this environment variable to "i" if you use +the aCC compiler. + +dit(bf(CCACHE_STRIPC)) If you set the environment variable +CCACHE_STRIPC then ccache will strip the -c option when invoking +the preprocessor. This option is primarily for the Sun Workshop +C++ compiler as without this option an unwarranted warning is displayed: +CC: Warning: "-E" redefines product from "object" to "source (stdout)" +when -E and -c is used together. + +dit(bf(CCACHE_SWIG)) When using SWIG as the compiler and it does not +have 'swig' in the executable name, then the CCACHE_SWIG environment +variable needs to be set in order for ccache to work correctly with +SWIG. The use of CCACHE_CPP2 is also recommended for SWIG due to some +preprocessor quirks, however, use of CCACHE_CPP2 can often be skipped +-- check your generated code with and without this option set. Known +problems are using preprocessor directives within %inline blocks and +the use of '#pragma SWIG'. + +enddit() + +manpagesection(CACHE SIZE MANAGEMENT) + +By default ccache has a one gigabyte limit on the cache size and no +maximum number of files. You can set a different limit using the +"ccache -M" and "ccache -F" options, which set the size and number of +files limits. + +When these limits are reached ccache will reduce the cache to 20% +below the numbers you specified in order to avoid doing the cache +clean operation too often. + +manpagesection(CACHE COMPRESSION) + +By default on most platforms ccache will compress all files it puts +into the cache +using the zlib compression. While this involves a negligible +performance slowdown, it significantly increases the number of files +that fit in the cache. You can turn off compression setting the +CCACHE_NOCOMPRESS environment variable. + +manpagesection(HOW IT WORKS) + +The basic idea is to detect when you are compiling exactly the same +code a 2nd time and use the previously compiled output. You detect +that it is the same code by forming a hash of: + +itemization( + it() the pre-processor output from running the compiler with -E + it() the command line options + it() the real compilers size and modification time + it() any stderr output generated by the compiler +) + +These are hashed using md4 (a strong hash) and a cache file is formed +based on that hash result. When the same compilation is done a second +time ccache is able to supply the correct compiler output (including +all warnings etc) from the cache. + +ccache has been carefully written to always produce exactly the same +compiler output that you would get without the cache. If you ever +discover a case where ccache changes the output of your compiler then +please let me know. + +manpagesection(USING CCACHE WITH DISTCC) + +distcc is a very useful program for distributing compilation across a +range of compiler servers. It is often useful to combine distcc with +ccache, so that compiles that are done are sped up by distcc, but that +ccache avoids the compile completely where possible. + +To use distcc with ccache I recommend using the CCACHE_PREFIX +option. You just need to set the environment variable CCACHE_PREFIX to +'distcc' and ccache will prefix the command line used with the +compiler with the command 'distcc'. + +manpagesection(SHARING A CACHE) + +A group of developers can increase the cache hit rate by sharing a +cache directory. The hard links however cause unwanted side effects, +as all links to a cached file share the file's modification timestamp. +This results in false dependencies to be triggered by timestamp-based +build systems whenever another user links to an existing +file. Typically, users will see that their libraries and binaries are +relinked without reason. To share a cache without side effects, the +following conditions need to be met: + +itemization( + it() Use the same bf(CCACHE_DIR) environment variable setting + it() Unset the bf(CCACHE_HARDLINK) environment variable + it() Make sure everyone sets the CCACHE_UMASK environment variable + to 002, this ensures that cached files are accessible to everyone in + the group. + it() Make sure that all users have write permission in the entire + cache directory (and that you trust all users of the shared cache). + it() Make sure that the setgid bit is set on all directories in the + cache. This tells the filesystem to inherit group ownership for new + directories. The command "chmod g+s `find $CCACHE_DIR -type d`" might + be useful for this. + it() Set bf(CCACHE_NOCOMPRESS) for all users, if there are users with + versions of ccache that do not support compression. +) + +manpagesection(HISTORY) + +ccache was inspired by the compilercache shell script script written +by Erik Thiele and I would like to thank him for an excellent piece of +work. See +url(http://www.erikyyy.de/compilercache/)(http://www.erikyyy.de/compilercache/) +for the Erik's scripts. +ccache-swig is a port of the original ccache with support added for use +with SWIG. + +I wrote ccache because I wanted to get a bit more speed out of a +compiler cache and I wanted to remove some of the limitations of the +shell-script version. + +manpagesection(DIFFERENCES FROM COMPILERCACHE) + +The biggest differences between Erik's compilercache script and ccache +are: +itemization( +it() ccache is written in C, which makes it a bit faster (calling out to + external programs is mostly what slowed down the scripts). +it() ccache can automatically find the real compiler +it() ccache keeps statistics on hits/misses +it() ccache can do automatic cache management +it() ccache can cache compiler output that includes warnings. In many + cases this gives ccache a much higher cache hit rate. +it() ccache can handle a much wider ranger of compiler options +it() ccache avoids a double call to cpp on a cache miss +) + +manpagesection(CREDITS) + +Thanks to the following people for their contributions to ccache +itemization( + it() Erik Thiele for the original compilercache script + it() Luciano Rocha for the idea of compiling the pre-processor output + to avoid a 2nd cpp pass + it() Paul Russell for many suggestions and the debian packaging +) + +manpageauthor() + +ccache was written by Andrew Tridgell +url(http://samba.org/~tridge/)(http://samba.org/~tridge/). +ccache was adapted to create ccache-swig for use with SWIG by William Fulton. + +If you wish to report a problem or make a suggestion then please email +the SWIG developers on the swig-devel mailing list, see +url(http://www.swig.org/mail.html)(http://www.swig.org/mail.html) + +ccache is released under the GNU General Public License version 2 or +later. Please see the file COPYING for license details. + +whenhtml(htmlcommand( + + + + +)) diff --git a/CCache/ccache_swig_config.h.in b/CCache/ccache_swig_config.h.in new file mode 100644 index 0000000..bbb205f --- /dev/null +++ b/CCache/ccache_swig_config.h.in @@ -0,0 +1 @@ +#define SWIG_VERSION "@PACKAGE_VERSION@" diff --git a/CCache/cleanup.c b/CCache/cleanup.c new file mode 100644 index 0000000..9931228 --- /dev/null +++ b/CCache/cleanup.c @@ -0,0 +1,193 @@ +/* + Copyright (C) Andrew Tridgell 2002 + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. +*/ +/* + functions to cleanup the cache directory when it gets too large + */ + +#include "ccache.h" + +static struct files { + char *fname; + time_t mtime; + size_t size; +} **files; +static unsigned allocated; +static unsigned num_files; +static size_t total_size; +static size_t total_files; +static size_t size_threshold; +static size_t files_threshold; + +/* file comparison function to try to delete the oldest files first */ +static int files_compare(struct files **f1, struct files **f2) +{ + if ((*f2)->mtime == (*f1)->mtime) { + return strcmp((*f2)->fname, (*f1)->fname); + } + if ((*f2)->mtime > (*f1)->mtime) { + return -1; + } + return 1; +} + +/* this builds the list of files in the cache */ +static void traverse_fn(const char *fname, struct stat *st) +{ + char *p; + + if (!S_ISREG(st->st_mode)) return; + + p = str_basename(fname); + if (strcmp(p, "stats") == 0) { + free(p); + return; + } + free(p); + + if (num_files == allocated) { + allocated = 10000 + num_files*2; + files = (struct files **)x_realloc(files, + sizeof(struct files *)*allocated); + } + + files[num_files] = (struct files *)x_malloc(sizeof(struct files)); + files[num_files]->fname = x_strdup(fname); + files[num_files]->mtime = st->st_mtime; + files[num_files]->size = file_size(st) / 1024; + total_size += files[num_files]->size; + num_files++; +} + +/* sort the files we've found and delete the oldest ones until we are + below the thresholds */ +static void sort_and_clean(void) +{ + unsigned i; + + if (num_files > 1) { + /* sort in ascending data order */ + qsort(files, num_files, sizeof(struct files *), + (COMPAR_FN_T)files_compare); + } + + /* delete enough files to bring us below the threshold */ + for (i=0;ifname) != 0 && errno != ENOENT) { + fprintf(stderr, "unlink %s - %s\n", + files[i]->fname, strerror(errno)); + continue; + } + + total_size -= files[i]->size; + } + + total_files = num_files - i; +} + +/* cleanup in one cache subdir */ +void cleanup_dir(const char *dir, size_t maxfiles, size_t maxsize) +{ + unsigned i; + + size_threshold = maxsize * LIMIT_MULTIPLE; + files_threshold = maxfiles * LIMIT_MULTIPLE; + + num_files = 0; + total_size = 0; + + /* build a list of files */ + traverse(dir, traverse_fn); + + /* clean the cache */ + sort_and_clean(); + + stats_set_sizes(dir, total_files, total_size); + + /* free it up */ + for (i=0;ifname); + free(files[i]); + files[i] = NULL; + } + if (files) free(files); + allocated = 0; + files = NULL; + + num_files = 0; + total_size = 0; +} + +/* cleanup in all cache subdirs */ +void cleanup_all(const char *dir) +{ + unsigned counters[STATS_END]; + char *dname, *sfile; + int i; + + for (i=0;i<=0xF;i++) { + x_asprintf(&dname, "%s/%1x", dir, i); + x_asprintf(&sfile, "%s/%1x/stats", dir, i); + + memset(counters, 0, sizeof(counters)); + stats_read(sfile, counters); + + cleanup_dir(dname, + counters[STATS_MAXFILES], + counters[STATS_MAXSIZE]); + free(dname); + free(sfile); + } +} + + +/* traverse function for wiping files */ +static void wipe_fn(const char *fname, struct stat *st) +{ + char *p; + + if (!S_ISREG(st->st_mode)) return; + + p = str_basename(fname); + if (strcmp(p, "stats") == 0) { + free(p); + return; + } + free(p); + + unlink(fname); +} + + +/* wipe all cached files in all subdirs */ +void wipe_all(const char *dir) +{ + char *dname; + int i; + + for (i=0;i<=0xF;i++) { + x_asprintf(&dname, "%s/%1x", dir, i); + traverse(dir, wipe_fn); + free(dname); + } + + /* and fix the counters */ + cleanup_all(dir); +} diff --git a/CCache/config.h.in b/CCache/config.h.in new file mode 100644 index 0000000..893f98b --- /dev/null +++ b/CCache/config.h.in @@ -0,0 +1,115 @@ +/* config.h.in. Generated from configure.in by autoheader. */ + +/* Define to 1 if you would like to have zlib compression for ccache. */ +#undef ENABLE_ZLIB + +/* Define to 1 if you have the `asprintf' function. */ +#undef HAVE_ASPRINTF + +/* */ +#undef HAVE_C99_VSNPRINTF + +/* */ +#undef HAVE_COMPAR_FN_T + +/* Define to 1 if you have the header file. */ +#undef HAVE_CTYPE_H + +/* Define to 1 if you have the header file, and it defines `DIR'. + */ +#undef HAVE_DIRENT_H + +/* Define to 1 if you have the `gethostname' function. */ +#undef HAVE_GETHOSTNAME + +/* Define to 1 if you have the `getpwuid' function. */ +#undef HAVE_GETPWUID + +/* Define to 1 if you have the header file. */ +#undef HAVE_INTTYPES_H + +/* Define to 1 if you have the header file. */ +#undef HAVE_MEMORY_H + +/* Define to 1 if you have the `mkstemp' function. */ +#undef HAVE_MKSTEMP + +/* Define to 1 if you have the header file, and it defines `DIR'. */ +#undef HAVE_NDIR_H + +/* Define to 1 if you have the header file. */ +#undef HAVE_PWD_H + +/* Define to 1 if you have the `realpath' function. */ +#undef HAVE_REALPATH + +/* Define to 1 if you have the `snprintf' function. */ +#undef HAVE_SNPRINTF + +/* Define to 1 if you have the header file. */ +#undef HAVE_STDINT_H + +/* Define to 1 if you have the header file. */ +#undef HAVE_STDLIB_H + +/* Define to 1 if you have the header file. */ +#undef HAVE_STRINGS_H + +/* Define to 1 if you have the header file. */ +#undef HAVE_STRING_H + +/* Define to 1 if you have the header file, and it defines `DIR'. + */ +#undef HAVE_SYS_DIR_H + +/* Define to 1 if you have the header file, and it defines `DIR'. + */ +#undef HAVE_SYS_NDIR_H + +/* Define to 1 if you have the header file. */ +#undef HAVE_SYS_STAT_H + +/* Define to 1 if you have the header file. */ +#undef HAVE_SYS_TIME_H + +/* Define to 1 if you have the header file. */ +#undef HAVE_SYS_TYPES_H + +/* Define to 1 if you have that is POSIX.1 compatible. */ +#undef HAVE_SYS_WAIT_H + +/* Define to 1 if you have the header file. */ +#undef HAVE_UNISTD_H + +/* Define to 1 if you have the `utimes' function. */ +#undef HAVE_UTIMES + +/* Define to 1 if you have the `vasprintf' function. */ +#undef HAVE_VASPRINTF + +/* Define to 1 if you have the `vsnprintf' function. */ +#undef HAVE_VSNPRINTF + +/* Define to the address where bug reports for this package should be sent. */ +#undef PACKAGE_BUGREPORT + +/* Define to the full name of this package. */ +#undef PACKAGE_NAME + +/* Define to the full name and version of this package. */ +#undef PACKAGE_STRING + +/* Define to the one symbol short name of this package. */ +#undef PACKAGE_TARNAME + +/* Define to the version of this package. */ +#undef PACKAGE_VERSION + +/* Define to 1 if you have the ANSI C header files. */ +#undef STDC_HEADERS + +/* Define to 1 if you can safely include both and . */ +#undef TIME_WITH_SYS_TIME + +/* Define _GNU_SOURCE so that we get all necessary prototypes */ +#undef _GNU_SOURCE diff --git a/CCache/configure b/CCache/configure new file mode 100755 index 0000000..ddc25ec --- /dev/null +++ b/CCache/configure @@ -0,0 +1,5653 @@ +#! /bin/sh +# Guess values for system-dependent variables and create Makefiles. +# Generated by GNU Autoconf 2.61 for ccache-swig 0.0. +# +# Copyright (C) 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, +# 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc. +# This configure script is free software; the Free Software Foundation +# gives unlimited permission to copy, distribute and modify it. +## --------------------- ## +## M4sh Initialization. ## +## --------------------- ## + +# Be more Bourne compatible +DUALCASE=1; export DUALCASE # for MKS sh +if test -n "${ZSH_VERSION+set}" && (emulate sh) >/dev/null 2>&1; then + emulate sh + NULLCMD=: + # Zsh 3.x and 4.x performs word splitting on ${1+"$@"}, which + # is contrary to our usage. Disable this feature. + alias -g '${1+"$@"}'='"$@"' + setopt NO_GLOB_SUBST +else + case `(set -o) 2>/dev/null` in + *posix*) set -o posix ;; +esac + +fi + + + + +# PATH needs CR +# Avoid depending upon Character Ranges. +as_cr_letters='abcdefghijklmnopqrstuvwxyz' +as_cr_LETTERS='ABCDEFGHIJKLMNOPQRSTUVWXYZ' +as_cr_Letters=$as_cr_letters$as_cr_LETTERS +as_cr_digits='0123456789' +as_cr_alnum=$as_cr_Letters$as_cr_digits + +# The user is always right. +if test "${PATH_SEPARATOR+set}" != set; then + echo "#! /bin/sh" >conf$$.sh + echo "exit 0" >>conf$$.sh + chmod +x conf$$.sh + if (PATH="/nonexistent;."; conf$$.sh) >/dev/null 2>&1; then + PATH_SEPARATOR=';' + else + PATH_SEPARATOR=: + fi + rm -f conf$$.sh +fi + +# Support unset when possible. +if ( (MAIL=60; unset MAIL) || exit) >/dev/null 2>&1; then + as_unset=unset +else + as_unset=false +fi + + +# IFS +# We need space, tab and new line, in precisely that order. Quoting is +# there to prevent editors from complaining about space-tab. +# (If _AS_PATH_WALK were called with IFS unset, it would disable word +# splitting by setting IFS to empty value.) +as_nl=' +' +IFS=" "" $as_nl" + +# Find who we are. Look in the path if we contain no directory separator. +case $0 in + *[\\/]* ) as_myself=$0 ;; + *) as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + test -z "$as_dir" && as_dir=. + test -r "$as_dir/$0" && as_myself=$as_dir/$0 && break +done +IFS=$as_save_IFS + + ;; +esac +# We did not find ourselves, most probably we were run as `sh COMMAND' +# in which case we are not to be found in the path. +if test "x$as_myself" = x; then + as_myself=$0 +fi +if test ! -f "$as_myself"; then + echo "$as_myself: error: cannot find myself; rerun with an absolute file name" >&2 + { (exit 1); exit 1; } +fi + +# Work around bugs in pre-3.0 UWIN ksh. +for as_var in ENV MAIL MAILPATH +do ($as_unset $as_var) >/dev/null 2>&1 && $as_unset $as_var +done +PS1='$ ' +PS2='> ' +PS4='+ ' + +# NLS nuisances. +for as_var in \ + LANG LANGUAGE LC_ADDRESS LC_ALL LC_COLLATE LC_CTYPE LC_IDENTIFICATION \ + LC_MEASUREMENT LC_MESSAGES LC_MONETARY LC_NAME LC_NUMERIC LC_PAPER \ + LC_TELEPHONE LC_TIME +do + if (set +x; test -z "`(eval $as_var=C; export $as_var) 2>&1`"); then + eval $as_var=C; export $as_var + else + ($as_unset $as_var) >/dev/null 2>&1 && $as_unset $as_var + fi +done + +# Required to use basename. +if expr a : '\(a\)' >/dev/null 2>&1 && + test "X`expr 00001 : '.*\(...\)'`" = X001; then + as_expr=expr +else + as_expr=false +fi + +if (basename -- /) >/dev/null 2>&1 && test "X`basename -- / 2>&1`" = "X/"; then + as_basename=basename +else + as_basename=false +fi + + +# Name of the executable. +as_me=`$as_basename -- "$0" || +$as_expr X/"$0" : '.*/\([^/][^/]*\)/*$' \| \ + X"$0" : 'X\(//\)$' \| \ + X"$0" : 'X\(/\)' \| . 2>/dev/null || +echo X/"$0" | + sed '/^.*\/\([^/][^/]*\)\/*$/{ + s//\1/ + q + } + /^X\/\(\/\/\)$/{ + s//\1/ + q + } + /^X\/\(\/\).*/{ + s//\1/ + q + } + s/.*/./; q'` + +# CDPATH. +$as_unset CDPATH + + +if test "x$CONFIG_SHELL" = x; then + if (eval ":") 2>/dev/null; then + as_have_required=yes +else + as_have_required=no +fi + + if test $as_have_required = yes && (eval ": +(as_func_return () { + (exit \$1) +} +as_func_success () { + as_func_return 0 +} +as_func_failure () { + as_func_return 1 +} +as_func_ret_success () { + return 0 +} +as_func_ret_failure () { + return 1 +} + +exitcode=0 +if as_func_success; then + : +else + exitcode=1 + echo as_func_success failed. +fi + +if as_func_failure; then + exitcode=1 + echo as_func_failure succeeded. +fi + +if as_func_ret_success; then + : +else + exitcode=1 + echo as_func_ret_success failed. +fi + +if as_func_ret_failure; then + exitcode=1 + echo as_func_ret_failure succeeded. +fi + +if ( set x; as_func_ret_success y && test x = \"\$1\" ); then + : +else + exitcode=1 + echo positional parameters were not saved. +fi + +test \$exitcode = 0) || { (exit 1); exit 1; } + +( + as_lineno_1=\$LINENO + as_lineno_2=\$LINENO + test \"x\$as_lineno_1\" != \"x\$as_lineno_2\" && + test \"x\`expr \$as_lineno_1 + 1\`\" = \"x\$as_lineno_2\") || { (exit 1); exit 1; } +") 2> /dev/null; then + : +else + as_candidate_shells= + as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in /bin$PATH_SEPARATOR/usr/bin$PATH_SEPARATOR$PATH +do + IFS=$as_save_IFS + test -z "$as_dir" && as_dir=. + case $as_dir in + /*) + for as_base in sh bash ksh sh5; do + as_candidate_shells="$as_candidate_shells $as_dir/$as_base" + done;; + esac +done +IFS=$as_save_IFS + + + for as_shell in $as_candidate_shells $SHELL; do + # Try only shells that exist, to save several forks. + if { test -f "$as_shell" || test -f "$as_shell.exe"; } && + { ("$as_shell") 2> /dev/null <<\_ASEOF +if test -n "${ZSH_VERSION+set}" && (emulate sh) >/dev/null 2>&1; then + emulate sh + NULLCMD=: + # Zsh 3.x and 4.x performs word splitting on ${1+"$@"}, which + # is contrary to our usage. Disable this feature. + alias -g '${1+"$@"}'='"$@"' + setopt NO_GLOB_SUBST +else + case `(set -o) 2>/dev/null` in + *posix*) set -o posix ;; +esac + +fi + + +: +_ASEOF +}; then + CONFIG_SHELL=$as_shell + as_have_required=yes + if { "$as_shell" 2> /dev/null <<\_ASEOF +if test -n "${ZSH_VERSION+set}" && (emulate sh) >/dev/null 2>&1; then + emulate sh + NULLCMD=: + # Zsh 3.x and 4.x performs word splitting on ${1+"$@"}, which + # is contrary to our usage. Disable this feature. + alias -g '${1+"$@"}'='"$@"' + setopt NO_GLOB_SUBST +else + case `(set -o) 2>/dev/null` in + *posix*) set -o posix ;; +esac + +fi + + +: +(as_func_return () { + (exit $1) +} +as_func_success () { + as_func_return 0 +} +as_func_failure () { + as_func_return 1 +} +as_func_ret_success () { + return 0 +} +as_func_ret_failure () { + return 1 +} + +exitcode=0 +if as_func_success; then + : +else + exitcode=1 + echo as_func_success failed. +fi + +if as_func_failure; then + exitcode=1 + echo as_func_failure succeeded. +fi + +if as_func_ret_success; then + : +else + exitcode=1 + echo as_func_ret_success failed. +fi + +if as_func_ret_failure; then + exitcode=1 + echo as_func_ret_failure succeeded. +fi + +if ( set x; as_func_ret_success y && test x = "$1" ); then + : +else + exitcode=1 + echo positional parameters were not saved. +fi + +test $exitcode = 0) || { (exit 1); exit 1; } + +( + as_lineno_1=$LINENO + as_lineno_2=$LINENO + test "x$as_lineno_1" != "x$as_lineno_2" && + test "x`expr $as_lineno_1 + 1`" = "x$as_lineno_2") || { (exit 1); exit 1; } + +_ASEOF +}; then + break +fi + +fi + + done + + if test "x$CONFIG_SHELL" != x; then + for as_var in BASH_ENV ENV + do ($as_unset $as_var) >/dev/null 2>&1 && $as_unset $as_var + done + export CONFIG_SHELL + exec "$CONFIG_SHELL" "$as_myself" ${1+"$@"} +fi + + + if test $as_have_required = no; then + echo This script requires a shell more modern than all the + echo shells that I found on your system. Please install a + echo modern shell, or manually run the script under such a + echo shell if you do have one. + { (exit 1); exit 1; } +fi + + +fi + +fi + + + +(eval "as_func_return () { + (exit \$1) +} +as_func_success () { + as_func_return 0 +} +as_func_failure () { + as_func_return 1 +} +as_func_ret_success () { + return 0 +} +as_func_ret_failure () { + return 1 +} + +exitcode=0 +if as_func_success; then + : +else + exitcode=1 + echo as_func_success failed. +fi + +if as_func_failure; then + exitcode=1 + echo as_func_failure succeeded. +fi + +if as_func_ret_success; then + : +else + exitcode=1 + echo as_func_ret_success failed. +fi + +if as_func_ret_failure; then + exitcode=1 + echo as_func_ret_failure succeeded. +fi + +if ( set x; as_func_ret_success y && test x = \"\$1\" ); then + : +else + exitcode=1 + echo positional parameters were not saved. +fi + +test \$exitcode = 0") || { + echo No shell found that supports shell functions. + echo Please tell autoconf@gnu.org about your system, + echo including any error possibly output before this + echo message +} + + + + as_lineno_1=$LINENO + as_lineno_2=$LINENO + test "x$as_lineno_1" != "x$as_lineno_2" && + test "x`expr $as_lineno_1 + 1`" = "x$as_lineno_2" || { + + # Create $as_me.lineno as a copy of $as_myself, but with $LINENO + # uniformly replaced by the line number. The first 'sed' inserts a + # line-number line after each line using $LINENO; the second 'sed' + # does the real work. The second script uses 'N' to pair each + # line-number line with the line containing $LINENO, and appends + # trailing '-' during substitution so that $LINENO is not a special + # case at line end. + # (Raja R Harinath suggested sed '=', and Paul Eggert wrote the + # scripts with optimization help from Paolo Bonzini. Blame Lee + # E. McMahon (1931-1989) for sed's syntax. :-) + sed -n ' + p + /[$]LINENO/= + ' <$as_myself | + sed ' + s/[$]LINENO.*/&-/ + t lineno + b + :lineno + N + :loop + s/[$]LINENO\([^'$as_cr_alnum'_].*\n\)\(.*\)/\2\1\2/ + t loop + s/-\n.*// + ' >$as_me.lineno && + chmod +x "$as_me.lineno" || + { echo "$as_me: error: cannot create $as_me.lineno; rerun with a POSIX shell" >&2 + { (exit 1); exit 1; }; } + + # Don't try to exec as it changes $[0], causing all sort of problems + # (the dirname of $[0] is not the place where we might find the + # original and so on. Autoconf is especially sensitive to this). + . "./$as_me.lineno" + # Exit status is that of the last command. + exit +} + + +if (as_dir=`dirname -- /` && test "X$as_dir" = X/) >/dev/null 2>&1; then + as_dirname=dirname +else + as_dirname=false +fi + +ECHO_C= ECHO_N= ECHO_T= +case `echo -n x` in +-n*) + case `echo 'x\c'` in + *c*) ECHO_T=' ';; # ECHO_T is single tab character. + *) ECHO_C='\c';; + esac;; +*) + ECHO_N='-n';; +esac + +if expr a : '\(a\)' >/dev/null 2>&1 && + test "X`expr 00001 : '.*\(...\)'`" = X001; then + as_expr=expr +else + as_expr=false +fi + +rm -f conf$$ conf$$.exe conf$$.file +if test -d conf$$.dir; then + rm -f conf$$.dir/conf$$.file +else + rm -f conf$$.dir + mkdir conf$$.dir +fi +echo >conf$$.file +if ln -s conf$$.file conf$$ 2>/dev/null; then + as_ln_s='ln -s' + # ... but there are two gotchas: + # 1) On MSYS, both `ln -s file dir' and `ln file dir' fail. + # 2) DJGPP < 2.04 has no symlinks; `ln -s' creates a wrapper executable. + # In both cases, we have to default to `cp -p'. + ln -s conf$$.file conf$$.dir 2>/dev/null && test ! -f conf$$.exe || + as_ln_s='cp -p' +elif ln conf$$.file conf$$ 2>/dev/null; then + as_ln_s=ln +else + as_ln_s='cp -p' +fi +rm -f conf$$ conf$$.exe conf$$.dir/conf$$.file conf$$.file +rmdir conf$$.dir 2>/dev/null + +if mkdir -p . 2>/dev/null; then + as_mkdir_p=: +else + test -d ./-p && rmdir ./-p + as_mkdir_p=false +fi + +if test -x / >/dev/null 2>&1; then + as_test_x='test -x' +else + if ls -dL / >/dev/null 2>&1; then + as_ls_L_option=L + else + as_ls_L_option= + fi + as_test_x=' + eval sh -c '\'' + if test -d "$1"; then + test -d "$1/."; + else + case $1 in + -*)set "./$1";; + esac; + case `ls -ld'$as_ls_L_option' "$1" 2>/dev/null` in + ???[sx]*):;;*)false;;esac;fi + '\'' sh + ' +fi +as_executable_p=$as_test_x + +# Sed expression to map a string onto a valid CPP name. +as_tr_cpp="eval sed 'y%*$as_cr_letters%P$as_cr_LETTERS%;s%[^_$as_cr_alnum]%_%g'" + +# Sed expression to map a string onto a valid variable name. +as_tr_sh="eval sed 'y%*+%pp%;s%[^_$as_cr_alnum]%_%g'" + + + +exec 7<&0 &1 + +# Name of the host. +# hostname on some systems (SVR3.2, Linux) returns a bogus exit status, +# so uname gets run too. +ac_hostname=`(hostname || uname -n) 2>/dev/null | sed 1q` + +# +# Initializations. +# +ac_default_prefix=/usr/local +ac_clean_files= +ac_config_libobj_dir=. +LIBOBJS= +cross_compiling=no +subdirs= +MFLAGS= +MAKEFLAGS= +SHELL=${CONFIG_SHELL-/bin/sh} + +# Identity of this package. +PACKAGE_NAME='ccache-swig' +PACKAGE_TARNAME='ccache-swig' +PACKAGE_VERSION='0.0' +PACKAGE_STRING='ccache-swig 0.0' +PACKAGE_BUGREPORT='' + +ac_unique_file="ccache.h" +# Factoring default headers for most tests. +ac_includes_default="\ +#include +#ifdef HAVE_SYS_TYPES_H +# include +#endif +#ifdef HAVE_SYS_STAT_H +# include +#endif +#ifdef STDC_HEADERS +# include +# include +#else +# ifdef HAVE_STDLIB_H +# include +# endif +#endif +#ifdef HAVE_STRING_H +# if !defined STDC_HEADERS && defined HAVE_MEMORY_H +# include +# endif +# include +#endif +#ifdef HAVE_STRINGS_H +# include +#endif +#ifdef HAVE_INTTYPES_H +# include +#endif +#ifdef HAVE_STDINT_H +# include +#endif +#ifdef HAVE_UNISTD_H +# include +#endif" + +ac_subst_vars='SHELL +PATH_SEPARATOR +PACKAGE_NAME +PACKAGE_TARNAME +PACKAGE_VERSION +PACKAGE_STRING +PACKAGE_BUGREPORT +exec_prefix +prefix +program_transform_name +bindir +sbindir +libexecdir +datarootdir +datadir +sysconfdir +sharedstatedir +localstatedir +includedir +oldincludedir +docdir +infodir +htmldir +dvidir +pdfdir +psdir +libdir +localedir +mandir +DEFS +ECHO_C +ECHO_N +ECHO_T +LIBS +build_alias +host_alias +target_alias +CC +CFLAGS +LDFLAGS +CPPFLAGS +ac_ct_CC +EXEEXT +OBJEXT +CPP +INSTALL_PROGRAM +INSTALL_SCRIPT +INSTALL_DATA +GREP +EGREP +LIBOBJS +LTLIBOBJS' +ac_subst_files='' + ac_precious_vars='build_alias +host_alias +target_alias +CC +CFLAGS +LDFLAGS +LIBS +CPPFLAGS +CPP' + + +# Initialize some variables set by options. +ac_init_help= +ac_init_version=false +# The variables have the same names as the options, with +# dashes changed to underlines. +cache_file=/dev/null +exec_prefix=NONE +no_create= +no_recursion= +prefix=NONE +program_prefix=NONE +program_suffix=NONE +program_transform_name=s,x,x, +silent= +site= +srcdir= +verbose= +x_includes=NONE +x_libraries=NONE + +# Installation directory options. +# These are left unexpanded so users can "make install exec_prefix=/foo" +# and all the variables that are supposed to be based on exec_prefix +# by default will actually change. +# Use braces instead of parens because sh, perl, etc. also accept them. +# (The list follows the same order as the GNU Coding Standards.) +bindir='${exec_prefix}/bin' +sbindir='${exec_prefix}/sbin' +libexecdir='${exec_prefix}/libexec' +datarootdir='${prefix}/share' +datadir='${datarootdir}' +sysconfdir='${prefix}/etc' +sharedstatedir='${prefix}/com' +localstatedir='${prefix}/var' +includedir='${prefix}/include' +oldincludedir='/usr/include' +docdir='${datarootdir}/doc/${PACKAGE_TARNAME}' +infodir='${datarootdir}/info' +htmldir='${docdir}' +dvidir='${docdir}' +pdfdir='${docdir}' +psdir='${docdir}' +libdir='${exec_prefix}/lib' +localedir='${datarootdir}/locale' +mandir='${datarootdir}/man' + +ac_prev= +ac_dashdash= +for ac_option +do + # If the previous option needs an argument, assign it. + if test -n "$ac_prev"; then + eval $ac_prev=\$ac_option + ac_prev= + continue + fi + + case $ac_option in + *=*) ac_optarg=`expr "X$ac_option" : '[^=]*=\(.*\)'` ;; + *) ac_optarg=yes ;; + esac + + # Accept the important Cygnus configure options, so we can diagnose typos. + + case $ac_dashdash$ac_option in + --) + ac_dashdash=yes ;; + + -bindir | --bindir | --bindi | --bind | --bin | --bi) + ac_prev=bindir ;; + -bindir=* | --bindir=* | --bindi=* | --bind=* | --bin=* | --bi=*) + bindir=$ac_optarg ;; + + -build | --build | --buil | --bui | --bu) + ac_prev=build_alias ;; + -build=* | --build=* | --buil=* | --bui=* | --bu=*) + build_alias=$ac_optarg ;; + + -cache-file | --cache-file | --cache-fil | --cache-fi \ + | --cache-f | --cache- | --cache | --cach | --cac | --ca | --c) + ac_prev=cache_file ;; + -cache-file=* | --cache-file=* | --cache-fil=* | --cache-fi=* \ + | --cache-f=* | --cache-=* | --cache=* | --cach=* | --cac=* | --ca=* | --c=*) + cache_file=$ac_optarg ;; + + --config-cache | -C) + cache_file=config.cache ;; + + -datadir | --datadir | --datadi | --datad) + ac_prev=datadir ;; + -datadir=* | --datadir=* | --datadi=* | --datad=*) + datadir=$ac_optarg ;; + + -datarootdir | --datarootdir | --datarootdi | --datarootd | --dataroot \ + | --dataroo | --dataro | --datar) + ac_prev=datarootdir ;; + -datarootdir=* | --datarootdir=* | --datarootdi=* | --datarootd=* \ + | --dataroot=* | --dataroo=* | --dataro=* | --datar=*) + datarootdir=$ac_optarg ;; + + -disable-* | --disable-*) + ac_feature=`expr "x$ac_option" : 'x-*disable-\(.*\)'` + # Reject names that are not valid shell variable names. + expr "x$ac_feature" : ".*[^-._$as_cr_alnum]" >/dev/null && + { echo "$as_me: error: invalid feature name: $ac_feature" >&2 + { (exit 1); exit 1; }; } + ac_feature=`echo $ac_feature | sed 's/[-.]/_/g'` + eval enable_$ac_feature=no ;; + + -docdir | --docdir | --docdi | --doc | --do) + ac_prev=docdir ;; + -docdir=* | --docdir=* | --docdi=* | --doc=* | --do=*) + docdir=$ac_optarg ;; + + -dvidir | --dvidir | --dvidi | --dvid | --dvi | --dv) + ac_prev=dvidir ;; + -dvidir=* | --dvidir=* | --dvidi=* | --dvid=* | --dvi=* | --dv=*) + dvidir=$ac_optarg ;; + + -enable-* | --enable-*) + ac_feature=`expr "x$ac_option" : 'x-*enable-\([^=]*\)'` + # Reject names that are not valid shell variable names. + expr "x$ac_feature" : ".*[^-._$as_cr_alnum]" >/dev/null && + { echo "$as_me: error: invalid feature name: $ac_feature" >&2 + { (exit 1); exit 1; }; } + ac_feature=`echo $ac_feature | sed 's/[-.]/_/g'` + eval enable_$ac_feature=\$ac_optarg ;; + + -exec-prefix | --exec_prefix | --exec-prefix | --exec-prefi \ + | --exec-pref | --exec-pre | --exec-pr | --exec-p | --exec- \ + | --exec | --exe | --ex) + ac_prev=exec_prefix ;; + -exec-prefix=* | --exec_prefix=* | --exec-prefix=* | --exec-prefi=* \ + | --exec-pref=* | --exec-pre=* | --exec-pr=* | --exec-p=* | --exec-=* \ + | --exec=* | --exe=* | --ex=*) + exec_prefix=$ac_optarg ;; + + -gas | --gas | --ga | --g) + # Obsolete; use --with-gas. + with_gas=yes ;; + + -help | --help | --hel | --he | -h) + ac_init_help=long ;; + -help=r* | --help=r* | --hel=r* | --he=r* | -hr*) + ac_init_help=recursive ;; + -help=s* | --help=s* | --hel=s* | --he=s* | -hs*) + ac_init_help=short ;; + + -host | --host | --hos | --ho) + ac_prev=host_alias ;; + -host=* | --host=* | --hos=* | --ho=*) + host_alias=$ac_optarg ;; + + -htmldir | --htmldir | --htmldi | --htmld | --html | --htm | --ht) + ac_prev=htmldir ;; + -htmldir=* | --htmldir=* | --htmldi=* | --htmld=* | --html=* | --htm=* \ + | --ht=*) + htmldir=$ac_optarg ;; + + -includedir | --includedir | --includedi | --included | --include \ + | --includ | --inclu | --incl | --inc) + ac_prev=includedir ;; + -includedir=* | --includedir=* | --includedi=* | --included=* | --include=* \ + | --includ=* | --inclu=* | --incl=* | --inc=*) + includedir=$ac_optarg ;; + + -infodir | --infodir | --infodi | --infod | --info | --inf) + ac_prev=infodir ;; + -infodir=* | --infodir=* | --infodi=* | --infod=* | --info=* | --inf=*) + infodir=$ac_optarg ;; + + -libdir | --libdir | --libdi | --libd) + ac_prev=libdir ;; + -libdir=* | --libdir=* | --libdi=* | --libd=*) + libdir=$ac_optarg ;; + + -libexecdir | --libexecdir | --libexecdi | --libexecd | --libexec \ + | --libexe | --libex | --libe) + ac_prev=libexecdir ;; + -libexecdir=* | --libexecdir=* | --libexecdi=* | --libexecd=* | --libexec=* \ + | --libexe=* | --libex=* | --libe=*) + libexecdir=$ac_optarg ;; + + -localedir | --localedir | --localedi | --localed | --locale) + ac_prev=localedir ;; + -localedir=* | --localedir=* | --localedi=* | --localed=* | --locale=*) + localedir=$ac_optarg ;; + + -localstatedir | --localstatedir | --localstatedi | --localstated \ + | --localstate | --localstat | --localsta | --localst | --locals) + ac_prev=localstatedir ;; + -localstatedir=* | --localstatedir=* | --localstatedi=* | --localstated=* \ + | --localstate=* | --localstat=* | --localsta=* | --localst=* | --locals=*) + localstatedir=$ac_optarg ;; + + -mandir | --mandir | --mandi | --mand | --man | --ma | --m) + ac_prev=mandir ;; + -mandir=* | --mandir=* | --mandi=* | --mand=* | --man=* | --ma=* | --m=*) + mandir=$ac_optarg ;; + + -nfp | --nfp | --nf) + # Obsolete; use --without-fp. + with_fp=no ;; + + -no-create | --no-create | --no-creat | --no-crea | --no-cre \ + | --no-cr | --no-c | -n) + no_create=yes ;; + + -no-recursion | --no-recursion | --no-recursio | --no-recursi \ + | --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r) + no_recursion=yes ;; + + -oldincludedir | --oldincludedir | --oldincludedi | --oldincluded \ + | --oldinclude | --oldinclud | --oldinclu | --oldincl | --oldinc \ + | --oldin | --oldi | --old | --ol | --o) + ac_prev=oldincludedir ;; + -oldincludedir=* | --oldincludedir=* | --oldincludedi=* | --oldincluded=* \ + | --oldinclude=* | --oldinclud=* | --oldinclu=* | --oldincl=* | --oldinc=* \ + | --oldin=* | --oldi=* | --old=* | --ol=* | --o=*) + oldincludedir=$ac_optarg ;; + + -prefix | --prefix | --prefi | --pref | --pre | --pr | --p) + ac_prev=prefix ;; + -prefix=* | --prefix=* | --prefi=* | --pref=* | --pre=* | --pr=* | --p=*) + prefix=$ac_optarg ;; + + -program-prefix | --program-prefix | --program-prefi | --program-pref \ + | --program-pre | --program-pr | --program-p) + ac_prev=program_prefix ;; + -program-prefix=* | --program-prefix=* | --program-prefi=* \ + | --program-pref=* | --program-pre=* | --program-pr=* | --program-p=*) + program_prefix=$ac_optarg ;; + + -program-suffix | --program-suffix | --program-suffi | --program-suff \ + | --program-suf | --program-su | --program-s) + ac_prev=program_suffix ;; + -program-suffix=* | --program-suffix=* | --program-suffi=* \ + | --program-suff=* | --program-suf=* | --program-su=* | --program-s=*) + program_suffix=$ac_optarg ;; + + -program-transform-name | --program-transform-name \ + | --program-transform-nam | --program-transform-na \ + | --program-transform-n | --program-transform- \ + | --program-transform | --program-transfor \ + | --program-transfo | --program-transf \ + | --program-trans | --program-tran \ + | --progr-tra | --program-tr | --program-t) + ac_prev=program_transform_name ;; + -program-transform-name=* | --program-transform-name=* \ + | --program-transform-nam=* | --program-transform-na=* \ + | --program-transform-n=* | --program-transform-=* \ + | --program-transform=* | --program-transfor=* \ + | --program-transfo=* | --program-transf=* \ + | --program-trans=* | --program-tran=* \ + | --progr-tra=* | --program-tr=* | --program-t=*) + program_transform_name=$ac_optarg ;; + + -pdfdir | --pdfdir | --pdfdi | --pdfd | --pdf | --pd) + ac_prev=pdfdir ;; + -pdfdir=* | --pdfdir=* | --pdfdi=* | --pdfd=* | --pdf=* | --pd=*) + pdfdir=$ac_optarg ;; + + -psdir | --psdir | --psdi | --psd | --ps) + ac_prev=psdir ;; + -psdir=* | --psdir=* | --psdi=* | --psd=* | --ps=*) + psdir=$ac_optarg ;; + + -q | -quiet | --quiet | --quie | --qui | --qu | --q \ + | -silent | --silent | --silen | --sile | --sil) + silent=yes ;; + + -sbindir | --sbindir | --sbindi | --sbind | --sbin | --sbi | --sb) + ac_prev=sbindir ;; + -sbindir=* | --sbindir=* | --sbindi=* | --sbind=* | --sbin=* \ + | --sbi=* | --sb=*) + sbindir=$ac_optarg ;; + + -sharedstatedir | --sharedstatedir | --sharedstatedi \ + | --sharedstated | --sharedstate | --sharedstat | --sharedsta \ + | --sharedst | --shareds | --shared | --share | --shar \ + | --sha | --sh) + ac_prev=sharedstatedir ;; + -sharedstatedir=* | --sharedstatedir=* | --sharedstatedi=* \ + | --sharedstated=* | --sharedstate=* | --sharedstat=* | --sharedsta=* \ + | --sharedst=* | --shareds=* | --shared=* | --share=* | --shar=* \ + | --sha=* | --sh=*) + sharedstatedir=$ac_optarg ;; + + -site | --site | --sit) + ac_prev=site ;; + -site=* | --site=* | --sit=*) + site=$ac_optarg ;; + + -srcdir | --srcdir | --srcdi | --srcd | --src | --sr) + ac_prev=srcdir ;; + -srcdir=* | --srcdir=* | --srcdi=* | --srcd=* | --src=* | --sr=*) + srcdir=$ac_optarg ;; + + -sysconfdir | --sysconfdir | --sysconfdi | --sysconfd | --sysconf \ + | --syscon | --sysco | --sysc | --sys | --sy) + ac_prev=sysconfdir ;; + -sysconfdir=* | --sysconfdir=* | --sysconfdi=* | --sysconfd=* | --sysconf=* \ + | --syscon=* | --sysco=* | --sysc=* | --sys=* | --sy=*) + sysconfdir=$ac_optarg ;; + + -target | --target | --targe | --targ | --tar | --ta | --t) + ac_prev=target_alias ;; + -target=* | --target=* | --targe=* | --targ=* | --tar=* | --ta=* | --t=*) + target_alias=$ac_optarg ;; + + -v | -verbose | --verbose | --verbos | --verbo | --verb) + verbose=yes ;; + + -version | --version | --versio | --versi | --vers | -V) + ac_init_version=: ;; + + -with-* | --with-*) + ac_package=`expr "x$ac_option" : 'x-*with-\([^=]*\)'` + # Reject names that are not valid shell variable names. + expr "x$ac_package" : ".*[^-._$as_cr_alnum]" >/dev/null && + { echo "$as_me: error: invalid package name: $ac_package" >&2 + { (exit 1); exit 1; }; } + ac_package=`echo $ac_package | sed 's/[-.]/_/g'` + eval with_$ac_package=\$ac_optarg ;; + + -without-* | --without-*) + ac_package=`expr "x$ac_option" : 'x-*without-\(.*\)'` + # Reject names that are not valid shell variable names. + expr "x$ac_package" : ".*[^-._$as_cr_alnum]" >/dev/null && + { echo "$as_me: error: invalid package name: $ac_package" >&2 + { (exit 1); exit 1; }; } + ac_package=`echo $ac_package | sed 's/[-.]/_/g'` + eval with_$ac_package=no ;; + + --x) + # Obsolete; use --with-x. + with_x=yes ;; + + -x-includes | --x-includes | --x-include | --x-includ | --x-inclu \ + | --x-incl | --x-inc | --x-in | --x-i) + ac_prev=x_includes ;; + -x-includes=* | --x-includes=* | --x-include=* | --x-includ=* | --x-inclu=* \ + | --x-incl=* | --x-inc=* | --x-in=* | --x-i=*) + x_includes=$ac_optarg ;; + + -x-libraries | --x-libraries | --x-librarie | --x-librari \ + | --x-librar | --x-libra | --x-libr | --x-lib | --x-li | --x-l) + ac_prev=x_libraries ;; + -x-libraries=* | --x-libraries=* | --x-librarie=* | --x-librari=* \ + | --x-librar=* | --x-libra=* | --x-libr=* | --x-lib=* | --x-li=* | --x-l=*) + x_libraries=$ac_optarg ;; + + -*) { echo "$as_me: error: unrecognized option: $ac_option +Try \`$0 --help' for more information." >&2 + { (exit 1); exit 1; }; } + ;; + + *=*) + ac_envvar=`expr "x$ac_option" : 'x\([^=]*\)='` + # Reject names that are not valid shell variable names. + expr "x$ac_envvar" : ".*[^_$as_cr_alnum]" >/dev/null && + { echo "$as_me: error: invalid variable name: $ac_envvar" >&2 + { (exit 1); exit 1; }; } + eval $ac_envvar=\$ac_optarg + export $ac_envvar ;; + + *) + # FIXME: should be removed in autoconf 3.0. + echo "$as_me: WARNING: you should use --build, --host, --target" >&2 + expr "x$ac_option" : ".*[^-._$as_cr_alnum]" >/dev/null && + echo "$as_me: WARNING: invalid host type: $ac_option" >&2 + : ${build_alias=$ac_option} ${host_alias=$ac_option} ${target_alias=$ac_option} + ;; + + esac +done + +if test -n "$ac_prev"; then + ac_option=--`echo $ac_prev | sed 's/_/-/g'` + { echo "$as_me: error: missing argument to $ac_option" >&2 + { (exit 1); exit 1; }; } +fi + +# Be sure to have absolute directory names. +for ac_var in exec_prefix prefix bindir sbindir libexecdir datarootdir \ + datadir sysconfdir sharedstatedir localstatedir includedir \ + oldincludedir docdir infodir htmldir dvidir pdfdir psdir \ + libdir localedir mandir +do + eval ac_val=\$$ac_var + case $ac_val in + [\\/$]* | ?:[\\/]* ) continue;; + NONE | '' ) case $ac_var in *prefix ) continue;; esac;; + esac + { echo "$as_me: error: expected an absolute directory name for --$ac_var: $ac_val" >&2 + { (exit 1); exit 1; }; } +done + +# There might be people who depend on the old broken behavior: `$host' +# used to hold the argument of --host etc. +# FIXME: To remove some day. +build=$build_alias +host=$host_alias +target=$target_alias + +# FIXME: To remove some day. +if test "x$host_alias" != x; then + if test "x$build_alias" = x; then + cross_compiling=maybe + echo "$as_me: WARNING: If you wanted to set the --build type, don't use --host. + If a cross compiler is detected then cross compile mode will be used." >&2 + elif test "x$build_alias" != "x$host_alias"; then + cross_compiling=yes + fi +fi + +ac_tool_prefix= +test -n "$host_alias" && ac_tool_prefix=$host_alias- + +test "$silent" = yes && exec 6>/dev/null + + +ac_pwd=`pwd` && test -n "$ac_pwd" && +ac_ls_di=`ls -di .` && +ac_pwd_ls_di=`cd "$ac_pwd" && ls -di .` || + { echo "$as_me: error: Working directory cannot be determined" >&2 + { (exit 1); exit 1; }; } +test "X$ac_ls_di" = "X$ac_pwd_ls_di" || + { echo "$as_me: error: pwd does not report name of working directory" >&2 + { (exit 1); exit 1; }; } + + +# Find the source files, if location was not specified. +if test -z "$srcdir"; then + ac_srcdir_defaulted=yes + # Try the directory containing this script, then the parent directory. + ac_confdir=`$as_dirname -- "$0" || +$as_expr X"$0" : 'X\(.*[^/]\)//*[^/][^/]*/*$' \| \ + X"$0" : 'X\(//\)[^/]' \| \ + X"$0" : 'X\(//\)$' \| \ + X"$0" : 'X\(/\)' \| . 2>/dev/null || +echo X"$0" | + sed '/^X\(.*[^/]\)\/\/*[^/][^/]*\/*$/{ + s//\1/ + q + } + /^X\(\/\/\)[^/].*/{ + s//\1/ + q + } + /^X\(\/\/\)$/{ + s//\1/ + q + } + /^X\(\/\).*/{ + s//\1/ + q + } + s/.*/./; q'` + srcdir=$ac_confdir + if test ! -r "$srcdir/$ac_unique_file"; then + srcdir=.. + fi +else + ac_srcdir_defaulted=no +fi +if test ! -r "$srcdir/$ac_unique_file"; then + test "$ac_srcdir_defaulted" = yes && srcdir="$ac_confdir or .." + { echo "$as_me: error: cannot find sources ($ac_unique_file) in $srcdir" >&2 + { (exit 1); exit 1; }; } +fi +ac_msg="sources are in $srcdir, but \`cd $srcdir' does not work" +ac_abs_confdir=`( + cd "$srcdir" && test -r "./$ac_unique_file" || { echo "$as_me: error: $ac_msg" >&2 + { (exit 1); exit 1; }; } + pwd)` +# When building in place, set srcdir=. +if test "$ac_abs_confdir" = "$ac_pwd"; then + srcdir=. +fi +# Remove unnecessary trailing slashes from srcdir. +# Double slashes in file names in object file debugging info +# mess up M-x gdb in Emacs. +case $srcdir in +*/) srcdir=`expr "X$srcdir" : 'X\(.*[^/]\)' \| "X$srcdir" : 'X\(.*\)'`;; +esac +for ac_var in $ac_precious_vars; do + eval ac_env_${ac_var}_set=\${${ac_var}+set} + eval ac_env_${ac_var}_value=\$${ac_var} + eval ac_cv_env_${ac_var}_set=\${${ac_var}+set} + eval ac_cv_env_${ac_var}_value=\$${ac_var} +done + +# +# Report the --help message. +# +if test "$ac_init_help" = "long"; then + # Omit some internal or obsolete options to make the list less imposing. + # This message is too long to be a string in the A/UX 3.1 sh. + cat <<_ACEOF +\`configure' configures ccache-swig 0.0 to adapt to many kinds of systems. + +Usage: $0 [OPTION]... [VAR=VALUE]... + +To assign environment variables (e.g., CC, CFLAGS...), specify them as +VAR=VALUE. See below for descriptions of some of the useful variables. + +Defaults for the options are specified in brackets. + +Configuration: + -h, --help display this help and exit + --help=short display options specific to this package + --help=recursive display the short help of all the included packages + -V, --version display version information and exit + -q, --quiet, --silent do not print \`checking...' messages + --cache-file=FILE cache test results in FILE [disabled] + -C, --config-cache alias for \`--cache-file=config.cache' + -n, --no-create do not create output files + --srcdir=DIR find the sources in DIR [configure dir or \`..'] + +Installation directories: + --prefix=PREFIX install architecture-independent files in PREFIX + [$ac_default_prefix] + --exec-prefix=EPREFIX install architecture-dependent files in EPREFIX + [PREFIX] + +By default, \`make install' will install all the files in +\`$ac_default_prefix/bin', \`$ac_default_prefix/lib' etc. You can specify +an installation prefix other than \`$ac_default_prefix' using \`--prefix', +for instance \`--prefix=\$HOME'. + +For better control, use the options below. + +Fine tuning of the installation directories: + --bindir=DIR user executables [EPREFIX/bin] + --sbindir=DIR system admin executables [EPREFIX/sbin] + --libexecdir=DIR program executables [EPREFIX/libexec] + --sysconfdir=DIR read-only single-machine data [PREFIX/etc] + --sharedstatedir=DIR modifiable architecture-independent data [PREFIX/com] + --localstatedir=DIR modifiable single-machine data [PREFIX/var] + --libdir=DIR object code libraries [EPREFIX/lib] + --includedir=DIR C header files [PREFIX/include] + --oldincludedir=DIR C header files for non-gcc [/usr/include] + --datarootdir=DIR read-only arch.-independent data root [PREFIX/share] + --datadir=DIR read-only architecture-independent data [DATAROOTDIR] + --infodir=DIR info documentation [DATAROOTDIR/info] + --localedir=DIR locale-dependent data [DATAROOTDIR/locale] + --mandir=DIR man documentation [DATAROOTDIR/man] + --docdir=DIR documentation root [DATAROOTDIR/doc/ccache-swig] + --htmldir=DIR html documentation [DOCDIR] + --dvidir=DIR dvi documentation [DOCDIR] + --pdfdir=DIR pdf documentation [DOCDIR] + --psdir=DIR ps documentation [DOCDIR] +_ACEOF + + cat <<\_ACEOF + +Program names: + --program-prefix=PREFIX prepend PREFIX to installed program names + --program-suffix=SUFFIX append SUFFIX to installed program names + --program-transform-name=PROGRAM run sed PROGRAM on installed program names +_ACEOF +fi + +if test -n "$ac_init_help"; then + case $ac_init_help in + short | recursive ) echo "Configuration of ccache-swig 0.0:";; + esac + cat <<\_ACEOF + +Optional Features: + --disable-FEATURE do not include FEATURE (same as --enable-FEATURE=no) + --enable-FEATURE[=ARG] include FEATURE [ARG=yes] + --enable-zlib enable zlib support for ccache compression + +Some influential environment variables: + CC C compiler command + CFLAGS C compiler flags + LDFLAGS linker flags, e.g. -L if you have libraries in a + nonstandard directory + LIBS libraries to pass to the linker, e.g. -l + CPPFLAGS C/C++/Objective C preprocessor flags, e.g. -I if + you have headers in a nonstandard directory + CPP C preprocessor + +Use these variables to override the choices made by `configure' or to help +it to find libraries and programs with nonstandard names/locations. + +_ACEOF +ac_status=$? +fi + +if test "$ac_init_help" = "recursive"; then + # If there are subdirs, report their specific --help. + for ac_dir in : $ac_subdirs_all; do test "x$ac_dir" = x: && continue + test -d "$ac_dir" || continue + ac_builddir=. + +case "$ac_dir" in +.) ac_dir_suffix= ac_top_builddir_sub=. ac_top_build_prefix= ;; +*) + ac_dir_suffix=/`echo "$ac_dir" | sed 's,^\.[\\/],,'` + # A ".." for each directory in $ac_dir_suffix. + ac_top_builddir_sub=`echo "$ac_dir_suffix" | sed 's,/[^\\/]*,/..,g;s,/,,'` + case $ac_top_builddir_sub in + "") ac_top_builddir_sub=. ac_top_build_prefix= ;; + *) ac_top_build_prefix=$ac_top_builddir_sub/ ;; + esac ;; +esac +ac_abs_top_builddir=$ac_pwd +ac_abs_builddir=$ac_pwd$ac_dir_suffix +# for backward compatibility: +ac_top_builddir=$ac_top_build_prefix + +case $srcdir in + .) # We are building in place. + ac_srcdir=. + ac_top_srcdir=$ac_top_builddir_sub + ac_abs_top_srcdir=$ac_pwd ;; + [\\/]* | ?:[\\/]* ) # Absolute name. + ac_srcdir=$srcdir$ac_dir_suffix; + ac_top_srcdir=$srcdir + ac_abs_top_srcdir=$srcdir ;; + *) # Relative name. + ac_srcdir=$ac_top_build_prefix$srcdir$ac_dir_suffix + ac_top_srcdir=$ac_top_build_prefix$srcdir + ac_abs_top_srcdir=$ac_pwd/$srcdir ;; +esac +ac_abs_srcdir=$ac_abs_top_srcdir$ac_dir_suffix + + cd "$ac_dir" || { ac_status=$?; continue; } + # Check for guested configure. + if test -f "$ac_srcdir/configure.gnu"; then + echo && + $SHELL "$ac_srcdir/configure.gnu" --help=recursive + elif test -f "$ac_srcdir/configure"; then + echo && + $SHELL "$ac_srcdir/configure" --help=recursive + else + echo "$as_me: WARNING: no configuration information is in $ac_dir" >&2 + fi || ac_status=$? + cd "$ac_pwd" || { ac_status=$?; break; } + done +fi + +test -n "$ac_init_help" && exit $ac_status +if $ac_init_version; then + cat <<\_ACEOF +ccache-swig configure 0.0 +generated by GNU Autoconf 2.61 + +Copyright (C) 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, +2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc. +This configure script is free software; the Free Software Foundation +gives unlimited permission to copy, distribute and modify it. +_ACEOF + exit +fi +cat >config.log <<_ACEOF +This file contains any messages produced by compilers while +running configure, to aid debugging if configure makes a mistake. + +It was created by ccache-swig $as_me 0.0, which was +generated by GNU Autoconf 2.61. Invocation command line was + + $ $0 $@ + +_ACEOF +exec 5>>config.log +{ +cat <<_ASUNAME +## --------- ## +## Platform. ## +## --------- ## + +hostname = `(hostname || uname -n) 2>/dev/null | sed 1q` +uname -m = `(uname -m) 2>/dev/null || echo unknown` +uname -r = `(uname -r) 2>/dev/null || echo unknown` +uname -s = `(uname -s) 2>/dev/null || echo unknown` +uname -v = `(uname -v) 2>/dev/null || echo unknown` + +/usr/bin/uname -p = `(/usr/bin/uname -p) 2>/dev/null || echo unknown` +/bin/uname -X = `(/bin/uname -X) 2>/dev/null || echo unknown` + +/bin/arch = `(/bin/arch) 2>/dev/null || echo unknown` +/usr/bin/arch -k = `(/usr/bin/arch -k) 2>/dev/null || echo unknown` +/usr/convex/getsysinfo = `(/usr/convex/getsysinfo) 2>/dev/null || echo unknown` +/usr/bin/hostinfo = `(/usr/bin/hostinfo) 2>/dev/null || echo unknown` +/bin/machine = `(/bin/machine) 2>/dev/null || echo unknown` +/usr/bin/oslevel = `(/usr/bin/oslevel) 2>/dev/null || echo unknown` +/bin/universe = `(/bin/universe) 2>/dev/null || echo unknown` + +_ASUNAME + +as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + test -z "$as_dir" && as_dir=. + echo "PATH: $as_dir" +done +IFS=$as_save_IFS + +} >&5 + +cat >&5 <<_ACEOF + + +## ----------- ## +## Core tests. ## +## ----------- ## + +_ACEOF + + +# Keep a trace of the command line. +# Strip out --no-create and --no-recursion so they do not pile up. +# Strip out --silent because we don't want to record it for future runs. +# Also quote any args containing shell meta-characters. +# Make two passes to allow for proper duplicate-argument suppression. +ac_configure_args= +ac_configure_args0= +ac_configure_args1= +ac_must_keep_next=false +for ac_pass in 1 2 +do + for ac_arg + do + case $ac_arg in + -no-create | --no-c* | -n | -no-recursion | --no-r*) continue ;; + -q | -quiet | --quiet | --quie | --qui | --qu | --q \ + | -silent | --silent | --silen | --sile | --sil) + continue ;; + *\'*) + ac_arg=`echo "$ac_arg" | sed "s/'/'\\\\\\\\''/g"` ;; + esac + case $ac_pass in + 1) ac_configure_args0="$ac_configure_args0 '$ac_arg'" ;; + 2) + ac_configure_args1="$ac_configure_args1 '$ac_arg'" + if test $ac_must_keep_next = true; then + ac_must_keep_next=false # Got value, back to normal. + else + case $ac_arg in + *=* | --config-cache | -C | -disable-* | --disable-* \ + | -enable-* | --enable-* | -gas | --g* | -nfp | --nf* \ + | -q | -quiet | --q* | -silent | --sil* | -v | -verb* \ + | -with-* | --with-* | -without-* | --without-* | --x) + case "$ac_configure_args0 " in + "$ac_configure_args1"*" '$ac_arg' "* ) continue ;; + esac + ;; + -* ) ac_must_keep_next=true ;; + esac + fi + ac_configure_args="$ac_configure_args '$ac_arg'" + ;; + esac + done +done +$as_unset ac_configure_args0 || test "${ac_configure_args0+set}" != set || { ac_configure_args0=; export ac_configure_args0; } +$as_unset ac_configure_args1 || test "${ac_configure_args1+set}" != set || { ac_configure_args1=; export ac_configure_args1; } + +# When interrupted or exit'd, cleanup temporary files, and complete +# config.log. We remove comments because anyway the quotes in there +# would cause problems or look ugly. +# WARNING: Use '\'' to represent an apostrophe within the trap. +# WARNING: Do not start the trap code with a newline, due to a FreeBSD 4.0 bug. +trap 'exit_status=$? + # Save into config.log some information that might help in debugging. + { + echo + + cat <<\_ASBOX +## ---------------- ## +## Cache variables. ## +## ---------------- ## +_ASBOX + echo + # The following way of writing the cache mishandles newlines in values, +( + for ac_var in `(set) 2>&1 | sed -n '\''s/^\([a-zA-Z_][a-zA-Z0-9_]*\)=.*/\1/p'\''`; do + eval ac_val=\$$ac_var + case $ac_val in #( + *${as_nl}*) + case $ac_var in #( + *_cv_*) { echo "$as_me:$LINENO: WARNING: Cache variable $ac_var contains a newline." >&5 +echo "$as_me: WARNING: Cache variable $ac_var contains a newline." >&2;} ;; + esac + case $ac_var in #( + _ | IFS | as_nl) ;; #( + *) $as_unset $ac_var ;; + esac ;; + esac + done + (set) 2>&1 | + case $as_nl`(ac_space='\'' '\''; set) 2>&1` in #( + *${as_nl}ac_space=\ *) + sed -n \ + "s/'\''/'\''\\\\'\'''\''/g; + s/^\\([_$as_cr_alnum]*_cv_[_$as_cr_alnum]*\\)=\\(.*\\)/\\1='\''\\2'\''/p" + ;; #( + *) + sed -n "/^[_$as_cr_alnum]*_cv_[_$as_cr_alnum]*=/p" + ;; + esac | + sort +) + echo + + cat <<\_ASBOX +## ----------------- ## +## Output variables. ## +## ----------------- ## +_ASBOX + echo + for ac_var in $ac_subst_vars + do + eval ac_val=\$$ac_var + case $ac_val in + *\'\''*) ac_val=`echo "$ac_val" | sed "s/'\''/'\''\\\\\\\\'\'''\''/g"`;; + esac + echo "$ac_var='\''$ac_val'\''" + done | sort + echo + + if test -n "$ac_subst_files"; then + cat <<\_ASBOX +## ------------------- ## +## File substitutions. ## +## ------------------- ## +_ASBOX + echo + for ac_var in $ac_subst_files + do + eval ac_val=\$$ac_var + case $ac_val in + *\'\''*) ac_val=`echo "$ac_val" | sed "s/'\''/'\''\\\\\\\\'\'''\''/g"`;; + esac + echo "$ac_var='\''$ac_val'\''" + done | sort + echo + fi + + if test -s confdefs.h; then + cat <<\_ASBOX +## ----------- ## +## confdefs.h. ## +## ----------- ## +_ASBOX + echo + cat confdefs.h + echo + fi + test "$ac_signal" != 0 && + echo "$as_me: caught signal $ac_signal" + echo "$as_me: exit $exit_status" + } >&5 + rm -f core *.core core.conftest.* && + rm -f -r conftest* confdefs* conf$$* $ac_clean_files && + exit $exit_status +' 0 +for ac_signal in 1 2 13 15; do + trap 'ac_signal='$ac_signal'; { (exit 1); exit 1; }' $ac_signal +done +ac_signal=0 + +# confdefs.h avoids OS command line length limits that DEFS can exceed. +rm -f -r conftest* confdefs.h + +# Predefined preprocessor variables. + +cat >>confdefs.h <<_ACEOF +#define PACKAGE_NAME "$PACKAGE_NAME" +_ACEOF + + +cat >>confdefs.h <<_ACEOF +#define PACKAGE_TARNAME "$PACKAGE_TARNAME" +_ACEOF + + +cat >>confdefs.h <<_ACEOF +#define PACKAGE_VERSION "$PACKAGE_VERSION" +_ACEOF + + +cat >>confdefs.h <<_ACEOF +#define PACKAGE_STRING "$PACKAGE_STRING" +_ACEOF + + +cat >>confdefs.h <<_ACEOF +#define PACKAGE_BUGREPORT "$PACKAGE_BUGREPORT" +_ACEOF + + +# Let the site file select an alternate cache file if it wants to. +# Prefer explicitly selected file to automatically selected ones. +if test -n "$CONFIG_SITE"; then + set x "$CONFIG_SITE" +elif test "x$prefix" != xNONE; then + set x "$prefix/share/config.site" "$prefix/etc/config.site" +else + set x "$ac_default_prefix/share/config.site" \ + "$ac_default_prefix/etc/config.site" +fi +shift +for ac_site_file +do + if test -r "$ac_site_file"; then + { echo "$as_me:$LINENO: loading site script $ac_site_file" >&5 +echo "$as_me: loading site script $ac_site_file" >&6;} + sed 's/^/| /' "$ac_site_file" >&5 + . "$ac_site_file" + fi +done + +if test -r "$cache_file"; then + # Some versions of bash will fail to source /dev/null (special + # files actually), so we avoid doing that. + if test -f "$cache_file"; then + { echo "$as_me:$LINENO: loading cache $cache_file" >&5 +echo "$as_me: loading cache $cache_file" >&6;} + case $cache_file in + [\\/]* | ?:[\\/]* ) . "$cache_file";; + *) . "./$cache_file";; + esac + fi +else + { echo "$as_me:$LINENO: creating cache $cache_file" >&5 +echo "$as_me: creating cache $cache_file" >&6;} + >$cache_file +fi + +# Check that the precious variables saved in the cache have kept the same +# value. +ac_cache_corrupted=false +for ac_var in $ac_precious_vars; do + eval ac_old_set=\$ac_cv_env_${ac_var}_set + eval ac_new_set=\$ac_env_${ac_var}_set + eval ac_old_val=\$ac_cv_env_${ac_var}_value + eval ac_new_val=\$ac_env_${ac_var}_value + case $ac_old_set,$ac_new_set in + set,) + { echo "$as_me:$LINENO: error: \`$ac_var' was set to \`$ac_old_val' in the previous run" >&5 +echo "$as_me: error: \`$ac_var' was set to \`$ac_old_val' in the previous run" >&2;} + ac_cache_corrupted=: ;; + ,set) + { echo "$as_me:$LINENO: error: \`$ac_var' was not set in the previous run" >&5 +echo "$as_me: error: \`$ac_var' was not set in the previous run" >&2;} + ac_cache_corrupted=: ;; + ,);; + *) + if test "x$ac_old_val" != "x$ac_new_val"; then + { echo "$as_me:$LINENO: error: \`$ac_var' has changed since the previous run:" >&5 +echo "$as_me: error: \`$ac_var' has changed since the previous run:" >&2;} + { echo "$as_me:$LINENO: former value: $ac_old_val" >&5 +echo "$as_me: former value: $ac_old_val" >&2;} + { echo "$as_me:$LINENO: current value: $ac_new_val" >&5 +echo "$as_me: current value: $ac_new_val" >&2;} + ac_cache_corrupted=: + fi;; + esac + # Pass precious variables to config.status. + if test "$ac_new_set" = set; then + case $ac_new_val in + *\'*) ac_arg=$ac_var=`echo "$ac_new_val" | sed "s/'/'\\\\\\\\''/g"` ;; + *) ac_arg=$ac_var=$ac_new_val ;; + esac + case " $ac_configure_args " in + *" '$ac_arg' "*) ;; # Avoid dups. Use of quotes ensures accuracy. + *) ac_configure_args="$ac_configure_args '$ac_arg'" ;; + esac + fi +done +if $ac_cache_corrupted; then + { echo "$as_me:$LINENO: error: changes in the environment can compromise the build" >&5 +echo "$as_me: error: changes in the environment can compromise the build" >&2;} + { { echo "$as_me:$LINENO: error: run \`make distclean' and/or \`rm $cache_file' and start over" >&5 +echo "$as_me: error: run \`make distclean' and/or \`rm $cache_file' and start over" >&2;} + { (exit 1); exit 1; }; } +fi + + + + + + + + + + + + + + + + + + + + + + + + + +ac_ext=c +ac_cpp='$CPP $CPPFLAGS' +ac_compile='$CC -c $CFLAGS $CPPFLAGS conftest.$ac_ext >&5' +ac_link='$CC -o conftest$ac_exeext $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS >&5' +ac_compiler_gnu=$ac_cv_c_compiler_gnu + + # Get version from SWIG in ccache_swig_config.h.in + + + +{ echo "$as_me:$LINENO: Configuring ccache" >&5 +echo "$as_me: Configuring ccache" >&6;} + +ac_config_headers="$ac_config_headers config.h" + + +ac_ext=c +ac_cpp='$CPP $CPPFLAGS' +ac_compile='$CC -c $CFLAGS $CPPFLAGS conftest.$ac_ext >&5' +ac_link='$CC -o conftest$ac_exeext $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS >&5' +ac_compiler_gnu=$ac_cv_c_compiler_gnu +if test -n "$ac_tool_prefix"; then + # Extract the first word of "${ac_tool_prefix}gcc", so it can be a program name with args. +set dummy ${ac_tool_prefix}gcc; ac_word=$2 +{ echo "$as_me:$LINENO: checking for $ac_word" >&5 +echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; } +if test "${ac_cv_prog_CC+set}" = set; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +else + if test -n "$CC"; then + ac_cv_prog_CC="$CC" # Let the user override the test. +else +as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + test -z "$as_dir" && as_dir=. + for ac_exec_ext in '' $ac_executable_extensions; do + if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then + ac_cv_prog_CC="${ac_tool_prefix}gcc" + echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi +done +done +IFS=$as_save_IFS + +fi +fi +CC=$ac_cv_prog_CC +if test -n "$CC"; then + { echo "$as_me:$LINENO: result: $CC" >&5 +echo "${ECHO_T}$CC" >&6; } +else + { echo "$as_me:$LINENO: result: no" >&5 +echo "${ECHO_T}no" >&6; } +fi + + +fi +if test -z "$ac_cv_prog_CC"; then + ac_ct_CC=$CC + # Extract the first word of "gcc", so it can be a program name with args. +set dummy gcc; ac_word=$2 +{ echo "$as_me:$LINENO: checking for $ac_word" >&5 +echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; } +if test "${ac_cv_prog_ac_ct_CC+set}" = set; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +else + if test -n "$ac_ct_CC"; then + ac_cv_prog_ac_ct_CC="$ac_ct_CC" # Let the user override the test. +else +as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + test -z "$as_dir" && as_dir=. + for ac_exec_ext in '' $ac_executable_extensions; do + if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then + ac_cv_prog_ac_ct_CC="gcc" + echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi +done +done +IFS=$as_save_IFS + +fi +fi +ac_ct_CC=$ac_cv_prog_ac_ct_CC +if test -n "$ac_ct_CC"; then + { echo "$as_me:$LINENO: result: $ac_ct_CC" >&5 +echo "${ECHO_T}$ac_ct_CC" >&6; } +else + { echo "$as_me:$LINENO: result: no" >&5 +echo "${ECHO_T}no" >&6; } +fi + + if test "x$ac_ct_CC" = x; then + CC="" + else + case $cross_compiling:$ac_tool_warned in +yes:) +{ echo "$as_me:$LINENO: WARNING: In the future, Autoconf will not detect cross-tools +whose name does not start with the host triplet. If you think this +configuration is useful to you, please write to autoconf@gnu.org." >&5 +echo "$as_me: WARNING: In the future, Autoconf will not detect cross-tools +whose name does not start with the host triplet. If you think this +configuration is useful to you, please write to autoconf@gnu.org." >&2;} +ac_tool_warned=yes ;; +esac + CC=$ac_ct_CC + fi +else + CC="$ac_cv_prog_CC" +fi + +if test -z "$CC"; then + if test -n "$ac_tool_prefix"; then + # Extract the first word of "${ac_tool_prefix}cc", so it can be a program name with args. +set dummy ${ac_tool_prefix}cc; ac_word=$2 +{ echo "$as_me:$LINENO: checking for $ac_word" >&5 +echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; } +if test "${ac_cv_prog_CC+set}" = set; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +else + if test -n "$CC"; then + ac_cv_prog_CC="$CC" # Let the user override the test. +else +as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + test -z "$as_dir" && as_dir=. + for ac_exec_ext in '' $ac_executable_extensions; do + if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then + ac_cv_prog_CC="${ac_tool_prefix}cc" + echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi +done +done +IFS=$as_save_IFS + +fi +fi +CC=$ac_cv_prog_CC +if test -n "$CC"; then + { echo "$as_me:$LINENO: result: $CC" >&5 +echo "${ECHO_T}$CC" >&6; } +else + { echo "$as_me:$LINENO: result: no" >&5 +echo "${ECHO_T}no" >&6; } +fi + + + fi +fi +if test -z "$CC"; then + # Extract the first word of "cc", so it can be a program name with args. +set dummy cc; ac_word=$2 +{ echo "$as_me:$LINENO: checking for $ac_word" >&5 +echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; } +if test "${ac_cv_prog_CC+set}" = set; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +else + if test -n "$CC"; then + ac_cv_prog_CC="$CC" # Let the user override the test. +else + ac_prog_rejected=no +as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + test -z "$as_dir" && as_dir=. + for ac_exec_ext in '' $ac_executable_extensions; do + if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then + if test "$as_dir/$ac_word$ac_exec_ext" = "/usr/ucb/cc"; then + ac_prog_rejected=yes + continue + fi + ac_cv_prog_CC="cc" + echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi +done +done +IFS=$as_save_IFS + +if test $ac_prog_rejected = yes; then + # We found a bogon in the path, so make sure we never use it. + set dummy $ac_cv_prog_CC + shift + if test $# != 0; then + # We chose a different compiler from the bogus one. + # However, it has the same basename, so the bogon will be chosen + # first if we set CC to just the basename; use the full file name. + shift + ac_cv_prog_CC="$as_dir/$ac_word${1+' '}$@" + fi +fi +fi +fi +CC=$ac_cv_prog_CC +if test -n "$CC"; then + { echo "$as_me:$LINENO: result: $CC" >&5 +echo "${ECHO_T}$CC" >&6; } +else + { echo "$as_me:$LINENO: result: no" >&5 +echo "${ECHO_T}no" >&6; } +fi + + +fi +if test -z "$CC"; then + if test -n "$ac_tool_prefix"; then + for ac_prog in cl.exe + do + # Extract the first word of "$ac_tool_prefix$ac_prog", so it can be a program name with args. +set dummy $ac_tool_prefix$ac_prog; ac_word=$2 +{ echo "$as_me:$LINENO: checking for $ac_word" >&5 +echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; } +if test "${ac_cv_prog_CC+set}" = set; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +else + if test -n "$CC"; then + ac_cv_prog_CC="$CC" # Let the user override the test. +else +as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + test -z "$as_dir" && as_dir=. + for ac_exec_ext in '' $ac_executable_extensions; do + if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then + ac_cv_prog_CC="$ac_tool_prefix$ac_prog" + echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi +done +done +IFS=$as_save_IFS + +fi +fi +CC=$ac_cv_prog_CC +if test -n "$CC"; then + { echo "$as_me:$LINENO: result: $CC" >&5 +echo "${ECHO_T}$CC" >&6; } +else + { echo "$as_me:$LINENO: result: no" >&5 +echo "${ECHO_T}no" >&6; } +fi + + + test -n "$CC" && break + done +fi +if test -z "$CC"; then + ac_ct_CC=$CC + for ac_prog in cl.exe +do + # Extract the first word of "$ac_prog", so it can be a program name with args. +set dummy $ac_prog; ac_word=$2 +{ echo "$as_me:$LINENO: checking for $ac_word" >&5 +echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; } +if test "${ac_cv_prog_ac_ct_CC+set}" = set; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +else + if test -n "$ac_ct_CC"; then + ac_cv_prog_ac_ct_CC="$ac_ct_CC" # Let the user override the test. +else +as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + test -z "$as_dir" && as_dir=. + for ac_exec_ext in '' $ac_executable_extensions; do + if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then + ac_cv_prog_ac_ct_CC="$ac_prog" + echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi +done +done +IFS=$as_save_IFS + +fi +fi +ac_ct_CC=$ac_cv_prog_ac_ct_CC +if test -n "$ac_ct_CC"; then + { echo "$as_me:$LINENO: result: $ac_ct_CC" >&5 +echo "${ECHO_T}$ac_ct_CC" >&6; } +else + { echo "$as_me:$LINENO: result: no" >&5 +echo "${ECHO_T}no" >&6; } +fi + + + test -n "$ac_ct_CC" && break +done + + if test "x$ac_ct_CC" = x; then + CC="" + else + case $cross_compiling:$ac_tool_warned in +yes:) +{ echo "$as_me:$LINENO: WARNING: In the future, Autoconf will not detect cross-tools +whose name does not start with the host triplet. If you think this +configuration is useful to you, please write to autoconf@gnu.org." >&5 +echo "$as_me: WARNING: In the future, Autoconf will not detect cross-tools +whose name does not start with the host triplet. If you think this +configuration is useful to you, please write to autoconf@gnu.org." >&2;} +ac_tool_warned=yes ;; +esac + CC=$ac_ct_CC + fi +fi + +fi + + +test -z "$CC" && { { echo "$as_me:$LINENO: error: no acceptable C compiler found in \$PATH +See \`config.log' for more details." >&5 +echo "$as_me: error: no acceptable C compiler found in \$PATH +See \`config.log' for more details." >&2;} + { (exit 1); exit 1; }; } + +# Provide some information about the compiler. +echo "$as_me:$LINENO: checking for C compiler version" >&5 +ac_compiler=`set X $ac_compile; echo $2` +{ (ac_try="$ac_compiler --version >&5" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_compiler --version >&5") 2>&5 + ac_status=$? + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } +{ (ac_try="$ac_compiler -v >&5" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_compiler -v >&5") 2>&5 + ac_status=$? + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } +{ (ac_try="$ac_compiler -V >&5" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_compiler -V >&5") 2>&5 + ac_status=$? + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } + +cat >conftest.$ac_ext <<_ACEOF +/* confdefs.h. */ +_ACEOF +cat confdefs.h >>conftest.$ac_ext +cat >>conftest.$ac_ext <<_ACEOF +/* end confdefs.h. */ + +int +main () +{ + + ; + return 0; +} +_ACEOF +ac_clean_files_save=$ac_clean_files +ac_clean_files="$ac_clean_files a.out a.exe b.out" +# Try to create an executable without -o first, disregard a.out. +# It will help us diagnose broken compilers, and finding out an intuition +# of exeext. +{ echo "$as_me:$LINENO: checking for C compiler default output file name" >&5 +echo $ECHO_N "checking for C compiler default output file name... $ECHO_C" >&6; } +ac_link_default=`echo "$ac_link" | sed 's/ -o *conftest[^ ]*//'` +# +# List of possible output files, starting from the most likely. +# The algorithm is not robust to junk in `.', hence go to wildcards (a.*) +# only as a last resort. b.out is created by i960 compilers. +ac_files='a_out.exe a.exe conftest.exe a.out conftest a.* conftest.* b.out' +# +# The IRIX 6 linker writes into existing files which may not be +# executable, retaining their permissions. Remove them first so a +# subsequent execution test works. +ac_rmfiles= +for ac_file in $ac_files +do + case $ac_file in + *.$ac_ext | *.xcoff | *.tds | *.d | *.pdb | *.xSYM | *.bb | *.bbg | *.map | *.inf | *.o | *.obj ) ;; + * ) ac_rmfiles="$ac_rmfiles $ac_file";; + esac +done +rm -f $ac_rmfiles + +if { (ac_try="$ac_link_default" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_link_default") 2>&5 + ac_status=$? + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); }; then + # Autoconf-2.13 could set the ac_cv_exeext variable to `no'. +# So ignore a value of `no', otherwise this would lead to `EXEEXT = no' +# in a Makefile. We should not override ac_cv_exeext if it was cached, +# so that the user can short-circuit this test for compilers unknown to +# Autoconf. +for ac_file in $ac_files '' +do + test -f "$ac_file" || continue + case $ac_file in + *.$ac_ext | *.xcoff | *.tds | *.d | *.pdb | *.xSYM | *.bb | *.bbg | *.map | *.inf | *.o | *.obj ) + ;; + [ab].out ) + # We found the default executable, but exeext='' is most + # certainly right. + break;; + *.* ) + if test "${ac_cv_exeext+set}" = set && test "$ac_cv_exeext" != no; + then :; else + ac_cv_exeext=`expr "$ac_file" : '[^.]*\(\..*\)'` + fi + # We set ac_cv_exeext here because the later test for it is not + # safe: cross compilers may not add the suffix if given an `-o' + # argument, so we may need to know it at that point already. + # Even if this section looks crufty: it has the advantage of + # actually working. + break;; + * ) + break;; + esac +done +test "$ac_cv_exeext" = no && ac_cv_exeext= + +else + ac_file='' +fi + +{ echo "$as_me:$LINENO: result: $ac_file" >&5 +echo "${ECHO_T}$ac_file" >&6; } +if test -z "$ac_file"; then + echo "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + +{ { echo "$as_me:$LINENO: error: C compiler cannot create executables +See \`config.log' for more details." >&5 +echo "$as_me: error: C compiler cannot create executables +See \`config.log' for more details." >&2;} + { (exit 77); exit 77; }; } +fi + +ac_exeext=$ac_cv_exeext + +# Check that the compiler produces executables we can run. If not, either +# the compiler is broken, or we cross compile. +{ echo "$as_me:$LINENO: checking whether the C compiler works" >&5 +echo $ECHO_N "checking whether the C compiler works... $ECHO_C" >&6; } +# FIXME: These cross compiler hacks should be removed for Autoconf 3.0 +# If not cross compiling, check that we can run a simple program. +if test "$cross_compiling" != yes; then + if { ac_try='./$ac_file' + { (case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_try") 2>&5 + ac_status=$? + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); }; }; then + cross_compiling=no + else + if test "$cross_compiling" = maybe; then + cross_compiling=yes + else + { { echo "$as_me:$LINENO: error: cannot run C compiled programs. +If you meant to cross compile, use \`--host'. +See \`config.log' for more details." >&5 +echo "$as_me: error: cannot run C compiled programs. +If you meant to cross compile, use \`--host'. +See \`config.log' for more details." >&2;} + { (exit 1); exit 1; }; } + fi + fi +fi +{ echo "$as_me:$LINENO: result: yes" >&5 +echo "${ECHO_T}yes" >&6; } + +rm -f a.out a.exe conftest$ac_cv_exeext b.out +ac_clean_files=$ac_clean_files_save +# Check that the compiler produces executables we can run. If not, either +# the compiler is broken, or we cross compile. +{ echo "$as_me:$LINENO: checking whether we are cross compiling" >&5 +echo $ECHO_N "checking whether we are cross compiling... $ECHO_C" >&6; } +{ echo "$as_me:$LINENO: result: $cross_compiling" >&5 +echo "${ECHO_T}$cross_compiling" >&6; } + +{ echo "$as_me:$LINENO: checking for suffix of executables" >&5 +echo $ECHO_N "checking for suffix of executables... $ECHO_C" >&6; } +if { (ac_try="$ac_link" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_link") 2>&5 + ac_status=$? + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); }; then + # If both `conftest.exe' and `conftest' are `present' (well, observable) +# catch `conftest.exe'. For instance with Cygwin, `ls conftest' will +# work properly (i.e., refer to `conftest.exe'), while it won't with +# `rm'. +for ac_file in conftest.exe conftest conftest.*; do + test -f "$ac_file" || continue + case $ac_file in + *.$ac_ext | *.xcoff | *.tds | *.d | *.pdb | *.xSYM | *.bb | *.bbg | *.map | *.inf | *.o | *.obj ) ;; + *.* ) ac_cv_exeext=`expr "$ac_file" : '[^.]*\(\..*\)'` + break;; + * ) break;; + esac +done +else + { { echo "$as_me:$LINENO: error: cannot compute suffix of executables: cannot compile and link +See \`config.log' for more details." >&5 +echo "$as_me: error: cannot compute suffix of executables: cannot compile and link +See \`config.log' for more details." >&2;} + { (exit 1); exit 1; }; } +fi + +rm -f conftest$ac_cv_exeext +{ echo "$as_me:$LINENO: result: $ac_cv_exeext" >&5 +echo "${ECHO_T}$ac_cv_exeext" >&6; } + +rm -f conftest.$ac_ext +EXEEXT=$ac_cv_exeext +ac_exeext=$EXEEXT +{ echo "$as_me:$LINENO: checking for suffix of object files" >&5 +echo $ECHO_N "checking for suffix of object files... $ECHO_C" >&6; } +if test "${ac_cv_objext+set}" = set; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +else + cat >conftest.$ac_ext <<_ACEOF +/* confdefs.h. */ +_ACEOF +cat confdefs.h >>conftest.$ac_ext +cat >>conftest.$ac_ext <<_ACEOF +/* end confdefs.h. */ + +int +main () +{ + + ; + return 0; +} +_ACEOF +rm -f conftest.o conftest.obj +if { (ac_try="$ac_compile" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_compile") 2>&5 + ac_status=$? + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); }; then + for ac_file in conftest.o conftest.obj conftest.*; do + test -f "$ac_file" || continue; + case $ac_file in + *.$ac_ext | *.xcoff | *.tds | *.d | *.pdb | *.xSYM | *.bb | *.bbg | *.map | *.inf ) ;; + *) ac_cv_objext=`expr "$ac_file" : '.*\.\(.*\)'` + break;; + esac +done +else + echo "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + +{ { echo "$as_me:$LINENO: error: cannot compute suffix of object files: cannot compile +See \`config.log' for more details." >&5 +echo "$as_me: error: cannot compute suffix of object files: cannot compile +See \`config.log' for more details." >&2;} + { (exit 1); exit 1; }; } +fi + +rm -f conftest.$ac_cv_objext conftest.$ac_ext +fi +{ echo "$as_me:$LINENO: result: $ac_cv_objext" >&5 +echo "${ECHO_T}$ac_cv_objext" >&6; } +OBJEXT=$ac_cv_objext +ac_objext=$OBJEXT +{ echo "$as_me:$LINENO: checking whether we are using the GNU C compiler" >&5 +echo $ECHO_N "checking whether we are using the GNU C compiler... $ECHO_C" >&6; } +if test "${ac_cv_c_compiler_gnu+set}" = set; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +else + cat >conftest.$ac_ext <<_ACEOF +/* confdefs.h. */ +_ACEOF +cat confdefs.h >>conftest.$ac_ext +cat >>conftest.$ac_ext <<_ACEOF +/* end confdefs.h. */ + +int +main () +{ +#ifndef __GNUC__ + choke me +#endif + + ; + return 0; +} +_ACEOF +rm -f conftest.$ac_objext +if { (ac_try="$ac_compile" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_compiler_gnu=yes +else + echo "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + + ac_compiler_gnu=no +fi + +rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +ac_cv_c_compiler_gnu=$ac_compiler_gnu + +fi +{ echo "$as_me:$LINENO: result: $ac_cv_c_compiler_gnu" >&5 +echo "${ECHO_T}$ac_cv_c_compiler_gnu" >&6; } +GCC=`test $ac_compiler_gnu = yes && echo yes` +ac_test_CFLAGS=${CFLAGS+set} +ac_save_CFLAGS=$CFLAGS +{ echo "$as_me:$LINENO: checking whether $CC accepts -g" >&5 +echo $ECHO_N "checking whether $CC accepts -g... $ECHO_C" >&6; } +if test "${ac_cv_prog_cc_g+set}" = set; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +else + ac_save_c_werror_flag=$ac_c_werror_flag + ac_c_werror_flag=yes + ac_cv_prog_cc_g=no + CFLAGS="-g" + cat >conftest.$ac_ext <<_ACEOF +/* confdefs.h. */ +_ACEOF +cat confdefs.h >>conftest.$ac_ext +cat >>conftest.$ac_ext <<_ACEOF +/* end confdefs.h. */ + +int +main () +{ + + ; + return 0; +} +_ACEOF +rm -f conftest.$ac_objext +if { (ac_try="$ac_compile" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_prog_cc_g=yes +else + echo "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + + CFLAGS="" + cat >conftest.$ac_ext <<_ACEOF +/* confdefs.h. */ +_ACEOF +cat confdefs.h >>conftest.$ac_ext +cat >>conftest.$ac_ext <<_ACEOF +/* end confdefs.h. */ + +int +main () +{ + + ; + return 0; +} +_ACEOF +rm -f conftest.$ac_objext +if { (ac_try="$ac_compile" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + : +else + echo "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + + ac_c_werror_flag=$ac_save_c_werror_flag + CFLAGS="-g" + cat >conftest.$ac_ext <<_ACEOF +/* confdefs.h. */ +_ACEOF +cat confdefs.h >>conftest.$ac_ext +cat >>conftest.$ac_ext <<_ACEOF +/* end confdefs.h. */ + +int +main () +{ + + ; + return 0; +} +_ACEOF +rm -f conftest.$ac_objext +if { (ac_try="$ac_compile" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_prog_cc_g=yes +else + echo "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + + +fi + +rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +fi + +rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +fi + +rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + ac_c_werror_flag=$ac_save_c_werror_flag +fi +{ echo "$as_me:$LINENO: result: $ac_cv_prog_cc_g" >&5 +echo "${ECHO_T}$ac_cv_prog_cc_g" >&6; } +if test "$ac_test_CFLAGS" = set; then + CFLAGS=$ac_save_CFLAGS +elif test $ac_cv_prog_cc_g = yes; then + if test "$GCC" = yes; then + CFLAGS="-g -O2" + else + CFLAGS="-g" + fi +else + if test "$GCC" = yes; then + CFLAGS="-O2" + else + CFLAGS= + fi +fi +{ echo "$as_me:$LINENO: checking for $CC option to accept ISO C89" >&5 +echo $ECHO_N "checking for $CC option to accept ISO C89... $ECHO_C" >&6; } +if test "${ac_cv_prog_cc_c89+set}" = set; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +else + ac_cv_prog_cc_c89=no +ac_save_CC=$CC +cat >conftest.$ac_ext <<_ACEOF +/* confdefs.h. */ +_ACEOF +cat confdefs.h >>conftest.$ac_ext +cat >>conftest.$ac_ext <<_ACEOF +/* end confdefs.h. */ +#include +#include +#include +#include +/* Most of the following tests are stolen from RCS 5.7's src/conf.sh. */ +struct buf { int x; }; +FILE * (*rcsopen) (struct buf *, struct stat *, int); +static char *e (p, i) + char **p; + int i; +{ + return p[i]; +} +static char *f (char * (*g) (char **, int), char **p, ...) +{ + char *s; + va_list v; + va_start (v,p); + s = g (p, va_arg (v,int)); + va_end (v); + return s; +} + +/* OSF 4.0 Compaq cc is some sort of almost-ANSI by default. It has + function prototypes and stuff, but not '\xHH' hex character constants. + These don't provoke an error unfortunately, instead are silently treated + as 'x'. The following induces an error, until -std is added to get + proper ANSI mode. Curiously '\x00'!='x' always comes out true, for an + array size at least. It's necessary to write '\x00'==0 to get something + that's true only with -std. */ +int osf4_cc_array ['\x00' == 0 ? 1 : -1]; + +/* IBM C 6 for AIX is almost-ANSI by default, but it replaces macro parameters + inside strings and character constants. */ +#define FOO(x) 'x' +int xlc6_cc_array[FOO(a) == 'x' ? 1 : -1]; + +int test (int i, double x); +struct s1 {int (*f) (int a);}; +struct s2 {int (*f) (double a);}; +int pairnames (int, char **, FILE *(*)(struct buf *, struct stat *, int), int, int); +int argc; +char **argv; +int +main () +{ +return f (e, argv, 0) != argv[0] || f (e, argv, 1) != argv[1]; + ; + return 0; +} +_ACEOF +for ac_arg in '' -qlanglvl=extc89 -qlanglvl=ansi -std \ + -Ae "-Aa -D_HPUX_SOURCE" "-Xc -D__EXTENSIONS__" +do + CC="$ac_save_CC $ac_arg" + rm -f conftest.$ac_objext +if { (ac_try="$ac_compile" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_prog_cc_c89=$ac_arg +else + echo "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + + +fi + +rm -f core conftest.err conftest.$ac_objext + test "x$ac_cv_prog_cc_c89" != "xno" && break +done +rm -f conftest.$ac_ext +CC=$ac_save_CC + +fi +# AC_CACHE_VAL +case "x$ac_cv_prog_cc_c89" in + x) + { echo "$as_me:$LINENO: result: none needed" >&5 +echo "${ECHO_T}none needed" >&6; } ;; + xno) + { echo "$as_me:$LINENO: result: unsupported" >&5 +echo "${ECHO_T}unsupported" >&6; } ;; + *) + CC="$CC $ac_cv_prog_cc_c89" + { echo "$as_me:$LINENO: result: $ac_cv_prog_cc_c89" >&5 +echo "${ECHO_T}$ac_cv_prog_cc_c89" >&6; } ;; +esac + + +ac_ext=c +ac_cpp='$CPP $CPPFLAGS' +ac_compile='$CC -c $CFLAGS $CPPFLAGS conftest.$ac_ext >&5' +ac_link='$CC -o conftest$ac_exeext $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS >&5' +ac_compiler_gnu=$ac_cv_c_compiler_gnu + +ac_ext=c +ac_cpp='$CPP $CPPFLAGS' +ac_compile='$CC -c $CFLAGS $CPPFLAGS conftest.$ac_ext >&5' +ac_link='$CC -o conftest$ac_exeext $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS >&5' +ac_compiler_gnu=$ac_cv_c_compiler_gnu +{ echo "$as_me:$LINENO: checking how to run the C preprocessor" >&5 +echo $ECHO_N "checking how to run the C preprocessor... $ECHO_C" >&6; } +# On Suns, sometimes $CPP names a directory. +if test -n "$CPP" && test -d "$CPP"; then + CPP= +fi +if test -z "$CPP"; then + if test "${ac_cv_prog_CPP+set}" = set; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +else + # Double quotes because CPP needs to be expanded + for CPP in "$CC -E" "$CC -E -traditional-cpp" "/lib/cpp" + do + ac_preproc_ok=false +for ac_c_preproc_warn_flag in '' yes +do + # Use a header file that comes with gcc, so configuring glibc + # with a fresh cross-compiler works. + # Prefer to if __STDC__ is defined, since + # exists even on freestanding compilers. + # On the NeXT, cc -E runs the code through the compiler's parser, + # not just through cpp. "Syntax error" is here to catch this case. + cat >conftest.$ac_ext <<_ACEOF +/* confdefs.h. */ +_ACEOF +cat confdefs.h >>conftest.$ac_ext +cat >>conftest.$ac_ext <<_ACEOF +/* end confdefs.h. */ +#ifdef __STDC__ +# include +#else +# include +#endif + Syntax error +_ACEOF +if { (ac_try="$ac_cpp conftest.$ac_ext" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + : +else + echo "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + + # Broken: fails on valid input. +continue +fi + +rm -f conftest.err conftest.$ac_ext + + # OK, works on sane cases. Now check whether nonexistent headers + # can be detected and how. + cat >conftest.$ac_ext <<_ACEOF +/* confdefs.h. */ +_ACEOF +cat confdefs.h >>conftest.$ac_ext +cat >>conftest.$ac_ext <<_ACEOF +/* end confdefs.h. */ +#include +_ACEOF +if { (ac_try="$ac_cpp conftest.$ac_ext" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + # Broken: success on invalid input. +continue +else + echo "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + + # Passes both tests. +ac_preproc_ok=: +break +fi + +rm -f conftest.err conftest.$ac_ext + +done +# Because of `break', _AC_PREPROC_IFELSE's cleaning code was skipped. +rm -f conftest.err conftest.$ac_ext +if $ac_preproc_ok; then + break +fi + + done + ac_cv_prog_CPP=$CPP + +fi + CPP=$ac_cv_prog_CPP +else + ac_cv_prog_CPP=$CPP +fi +{ echo "$as_me:$LINENO: result: $CPP" >&5 +echo "${ECHO_T}$CPP" >&6; } +ac_preproc_ok=false +for ac_c_preproc_warn_flag in '' yes +do + # Use a header file that comes with gcc, so configuring glibc + # with a fresh cross-compiler works. + # Prefer to if __STDC__ is defined, since + # exists even on freestanding compilers. + # On the NeXT, cc -E runs the code through the compiler's parser, + # not just through cpp. "Syntax error" is here to catch this case. + cat >conftest.$ac_ext <<_ACEOF +/* confdefs.h. */ +_ACEOF +cat confdefs.h >>conftest.$ac_ext +cat >>conftest.$ac_ext <<_ACEOF +/* end confdefs.h. */ +#ifdef __STDC__ +# include +#else +# include +#endif + Syntax error +_ACEOF +if { (ac_try="$ac_cpp conftest.$ac_ext" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + : +else + echo "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + + # Broken: fails on valid input. +continue +fi + +rm -f conftest.err conftest.$ac_ext + + # OK, works on sane cases. Now check whether nonexistent headers + # can be detected and how. + cat >conftest.$ac_ext <<_ACEOF +/* confdefs.h. */ +_ACEOF +cat confdefs.h >>conftest.$ac_ext +cat >>conftest.$ac_ext <<_ACEOF +/* end confdefs.h. */ +#include +_ACEOF +if { (ac_try="$ac_cpp conftest.$ac_ext" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + # Broken: success on invalid input. +continue +else + echo "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + + # Passes both tests. +ac_preproc_ok=: +break +fi + +rm -f conftest.err conftest.$ac_ext + +done +# Because of `break', _AC_PREPROC_IFELSE's cleaning code was skipped. +rm -f conftest.err conftest.$ac_ext +if $ac_preproc_ok; then + : +else + { { echo "$as_me:$LINENO: error: C preprocessor \"$CPP\" fails sanity check +See \`config.log' for more details." >&5 +echo "$as_me: error: C preprocessor \"$CPP\" fails sanity check +See \`config.log' for more details." >&2;} + { (exit 1); exit 1; }; } +fi + +ac_ext=c +ac_cpp='$CPP $CPPFLAGS' +ac_compile='$CC -c $CFLAGS $CPPFLAGS conftest.$ac_ext >&5' +ac_link='$CC -o conftest$ac_exeext $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS >&5' +ac_compiler_gnu=$ac_cv_c_compiler_gnu + +ac_aux_dir= +for ac_dir in "$srcdir" "$srcdir/.." "$srcdir/../.."; do + if test -f "$ac_dir/install-sh"; then + ac_aux_dir=$ac_dir + ac_install_sh="$ac_aux_dir/install-sh -c" + break + elif test -f "$ac_dir/install.sh"; then + ac_aux_dir=$ac_dir + ac_install_sh="$ac_aux_dir/install.sh -c" + break + elif test -f "$ac_dir/shtool"; then + ac_aux_dir=$ac_dir + ac_install_sh="$ac_aux_dir/shtool install -c" + break + fi +done +if test -z "$ac_aux_dir"; then + { { echo "$as_me:$LINENO: error: cannot find install-sh or install.sh in \"$srcdir\" \"$srcdir/..\" \"$srcdir/../..\"" >&5 +echo "$as_me: error: cannot find install-sh or install.sh in \"$srcdir\" \"$srcdir/..\" \"$srcdir/../..\"" >&2;} + { (exit 1); exit 1; }; } +fi + +# These three variables are undocumented and unsupported, +# and are intended to be withdrawn in a future Autoconf release. +# They can cause serious problems if a builder's source tree is in a directory +# whose full name contains unusual characters. +ac_config_guess="$SHELL $ac_aux_dir/config.guess" # Please don't use this var. +ac_config_sub="$SHELL $ac_aux_dir/config.sub" # Please don't use this var. +ac_configure="$SHELL $ac_aux_dir/configure" # Please don't use this var. + + +# Find a good install program. We prefer a C program (faster), +# so one script is as good as another. But avoid the broken or +# incompatible versions: +# SysV /etc/install, /usr/sbin/install +# SunOS /usr/etc/install +# IRIX /sbin/install +# AIX /bin/install +# AmigaOS /C/install, which installs bootblocks on floppy discs +# AIX 4 /usr/bin/installbsd, which doesn't work without a -g flag +# AFS /usr/afsws/bin/install, which mishandles nonexistent args +# SVR4 /usr/ucb/install, which tries to use the nonexistent group "staff" +# OS/2's system install, which has a completely different semantic +# ./install, which can be erroneously created by make from ./install.sh. +{ echo "$as_me:$LINENO: checking for a BSD-compatible install" >&5 +echo $ECHO_N "checking for a BSD-compatible install... $ECHO_C" >&6; } +if test -z "$INSTALL"; then +if test "${ac_cv_path_install+set}" = set; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +else + as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + test -z "$as_dir" && as_dir=. + # Account for people who put trailing slashes in PATH elements. +case $as_dir/ in + ./ | .// | /cC/* | \ + /etc/* | /usr/sbin/* | /usr/etc/* | /sbin/* | /usr/afsws/bin/* | \ + ?:\\/os2\\/install\\/* | ?:\\/OS2\\/INSTALL\\/* | \ + /usr/ucb/* ) ;; + *) + # OSF1 and SCO ODT 3.0 have their own names for install. + # Don't use installbsd from OSF since it installs stuff as root + # by default. + for ac_prog in ginstall scoinst install; do + for ac_exec_ext in '' $ac_executable_extensions; do + if { test -f "$as_dir/$ac_prog$ac_exec_ext" && $as_test_x "$as_dir/$ac_prog$ac_exec_ext"; }; then + if test $ac_prog = install && + grep dspmsg "$as_dir/$ac_prog$ac_exec_ext" >/dev/null 2>&1; then + # AIX install. It has an incompatible calling convention. + : + elif test $ac_prog = install && + grep pwplus "$as_dir/$ac_prog$ac_exec_ext" >/dev/null 2>&1; then + # program-specific install script used by HP pwplus--don't use. + : + else + ac_cv_path_install="$as_dir/$ac_prog$ac_exec_ext -c" + break 3 + fi + fi + done + done + ;; +esac +done +IFS=$as_save_IFS + + +fi + if test "${ac_cv_path_install+set}" = set; then + INSTALL=$ac_cv_path_install + else + # As a last resort, use the slow shell script. Don't cache a + # value for INSTALL within a source directory, because that will + # break other packages using the cache if that directory is + # removed, or if the value is a relative name. + INSTALL=$ac_install_sh + fi +fi +{ echo "$as_me:$LINENO: result: $INSTALL" >&5 +echo "${ECHO_T}$INSTALL" >&6; } + +# Use test -z because SunOS4 sh mishandles braces in ${var-val}. +# It thinks the first close brace ends the variable substitution. +test -z "$INSTALL_PROGRAM" && INSTALL_PROGRAM='${INSTALL}' + +test -z "$INSTALL_SCRIPT" && INSTALL_SCRIPT='${INSTALL}' + +test -z "$INSTALL_DATA" && INSTALL_DATA='${INSTALL} -m 644' + +test "$program_prefix" != NONE && + program_transform_name="s&^&$program_prefix&;$program_transform_name" +# Use a double $ so make ignores it. +test "$program_suffix" != NONE && + program_transform_name="s&\$&$program_suffix&;$program_transform_name" +# Double any \ or $. echo might interpret backslashes. +# By default was `s,x,x', remove it if useless. +cat <<\_ACEOF >conftest.sed +s/[\\$]/&&/g;s/;s,x,x,$// +_ACEOF +program_transform_name=`echo $program_transform_name | sed -f conftest.sed` +rm -f conftest.sed + # for program_transform_name + + +cat >>confdefs.h <<\_ACEOF +#define _GNU_SOURCE 1 +_ACEOF + + +# If GCC, turn on warnings. +if test "x$GCC" = "xyes" +then + CFLAGS="$CFLAGS -Wall -W" +else + CFLAGS="$CFLAGS -O" +fi + + + + + + + +ac_header_dirent=no +for ac_hdr in dirent.h sys/ndir.h sys/dir.h ndir.h; do + as_ac_Header=`echo "ac_cv_header_dirent_$ac_hdr" | $as_tr_sh` +{ echo "$as_me:$LINENO: checking for $ac_hdr that defines DIR" >&5 +echo $ECHO_N "checking for $ac_hdr that defines DIR... $ECHO_C" >&6; } +if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +else + cat >conftest.$ac_ext <<_ACEOF +/* confdefs.h. */ +_ACEOF +cat confdefs.h >>conftest.$ac_ext +cat >>conftest.$ac_ext <<_ACEOF +/* end confdefs.h. */ +#include +#include <$ac_hdr> + +int +main () +{ +if ((DIR *) 0) +return 0; + ; + return 0; +} +_ACEOF +rm -f conftest.$ac_objext +if { (ac_try="$ac_compile" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + eval "$as_ac_Header=yes" +else + echo "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + + eval "$as_ac_Header=no" +fi + +rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +fi +ac_res=`eval echo '${'$as_ac_Header'}'` + { echo "$as_me:$LINENO: result: $ac_res" >&5 +echo "${ECHO_T}$ac_res" >&6; } +if test `eval echo '${'$as_ac_Header'}'` = yes; then + cat >>confdefs.h <<_ACEOF +#define `echo "HAVE_$ac_hdr" | $as_tr_cpp` 1 +_ACEOF + +ac_header_dirent=$ac_hdr; break +fi + +done +# Two versions of opendir et al. are in -ldir and -lx on SCO Xenix. +if test $ac_header_dirent = dirent.h; then + { echo "$as_me:$LINENO: checking for library containing opendir" >&5 +echo $ECHO_N "checking for library containing opendir... $ECHO_C" >&6; } +if test "${ac_cv_search_opendir+set}" = set; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +else + ac_func_search_save_LIBS=$LIBS +cat >conftest.$ac_ext <<_ACEOF +/* confdefs.h. */ +_ACEOF +cat confdefs.h >>conftest.$ac_ext +cat >>conftest.$ac_ext <<_ACEOF +/* end confdefs.h. */ + +/* Override any GCC internal prototype to avoid an error. + Use char because int might match the return type of a GCC + builtin and then its argument prototype would still apply. */ +#ifdef __cplusplus +extern "C" +#endif +char opendir (); +int +main () +{ +return opendir (); + ; + return 0; +} +_ACEOF +for ac_lib in '' dir; do + if test -z "$ac_lib"; then + ac_res="none required" + else + ac_res=-l$ac_lib + LIBS="-l$ac_lib $ac_func_search_save_LIBS" + fi + rm -f conftest.$ac_objext conftest$ac_exeext +if { (ac_try="$ac_link" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest$ac_exeext && + $as_test_x conftest$ac_exeext; then + ac_cv_search_opendir=$ac_res +else + echo "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + + +fi + +rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext + if test "${ac_cv_search_opendir+set}" = set; then + break +fi +done +if test "${ac_cv_search_opendir+set}" = set; then + : +else + ac_cv_search_opendir=no +fi +rm conftest.$ac_ext +LIBS=$ac_func_search_save_LIBS +fi +{ echo "$as_me:$LINENO: result: $ac_cv_search_opendir" >&5 +echo "${ECHO_T}$ac_cv_search_opendir" >&6; } +ac_res=$ac_cv_search_opendir +if test "$ac_res" != no; then + test "$ac_res" = "none required" || LIBS="$ac_res $LIBS" + +fi + +else + { echo "$as_me:$LINENO: checking for library containing opendir" >&5 +echo $ECHO_N "checking for library containing opendir... $ECHO_C" >&6; } +if test "${ac_cv_search_opendir+set}" = set; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +else + ac_func_search_save_LIBS=$LIBS +cat >conftest.$ac_ext <<_ACEOF +/* confdefs.h. */ +_ACEOF +cat confdefs.h >>conftest.$ac_ext +cat >>conftest.$ac_ext <<_ACEOF +/* end confdefs.h. */ + +/* Override any GCC internal prototype to avoid an error. + Use char because int might match the return type of a GCC + builtin and then its argument prototype would still apply. */ +#ifdef __cplusplus +extern "C" +#endif +char opendir (); +int +main () +{ +return opendir (); + ; + return 0; +} +_ACEOF +for ac_lib in '' x; do + if test -z "$ac_lib"; then + ac_res="none required" + else + ac_res=-l$ac_lib + LIBS="-l$ac_lib $ac_func_search_save_LIBS" + fi + rm -f conftest.$ac_objext conftest$ac_exeext +if { (ac_try="$ac_link" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest$ac_exeext && + $as_test_x conftest$ac_exeext; then + ac_cv_search_opendir=$ac_res +else + echo "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + + +fi + +rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext + if test "${ac_cv_search_opendir+set}" = set; then + break +fi +done +if test "${ac_cv_search_opendir+set}" = set; then + : +else + ac_cv_search_opendir=no +fi +rm conftest.$ac_ext +LIBS=$ac_func_search_save_LIBS +fi +{ echo "$as_me:$LINENO: result: $ac_cv_search_opendir" >&5 +echo "${ECHO_T}$ac_cv_search_opendir" >&6; } +ac_res=$ac_cv_search_opendir +if test "$ac_res" != no; then + test "$ac_res" = "none required" || LIBS="$ac_res $LIBS" + +fi + +fi + +{ echo "$as_me:$LINENO: checking whether time.h and sys/time.h may both be included" >&5 +echo $ECHO_N "checking whether time.h and sys/time.h may both be included... $ECHO_C" >&6; } +if test "${ac_cv_header_time+set}" = set; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +else + cat >conftest.$ac_ext <<_ACEOF +/* confdefs.h. */ +_ACEOF +cat confdefs.h >>conftest.$ac_ext +cat >>conftest.$ac_ext <<_ACEOF +/* end confdefs.h. */ +#include +#include +#include + +int +main () +{ +if ((struct tm *) 0) +return 0; + ; + return 0; +} +_ACEOF +rm -f conftest.$ac_objext +if { (ac_try="$ac_compile" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_header_time=yes +else + echo "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_header_time=no +fi + +rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +fi +{ echo "$as_me:$LINENO: result: $ac_cv_header_time" >&5 +echo "${ECHO_T}$ac_cv_header_time" >&6; } +if test $ac_cv_header_time = yes; then + +cat >>confdefs.h <<\_ACEOF +#define TIME_WITH_SYS_TIME 1 +_ACEOF + +fi + +{ echo "$as_me:$LINENO: checking for sys/wait.h that is POSIX.1 compatible" >&5 +echo $ECHO_N "checking for sys/wait.h that is POSIX.1 compatible... $ECHO_C" >&6; } +if test "${ac_cv_header_sys_wait_h+set}" = set; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +else + cat >conftest.$ac_ext <<_ACEOF +/* confdefs.h. */ +_ACEOF +cat confdefs.h >>conftest.$ac_ext +cat >>conftest.$ac_ext <<_ACEOF +/* end confdefs.h. */ +#include +#include +#ifndef WEXITSTATUS +# define WEXITSTATUS(stat_val) ((unsigned int) (stat_val) >> 8) +#endif +#ifndef WIFEXITED +# define WIFEXITED(stat_val) (((stat_val) & 255) == 0) +#endif + +int +main () +{ + int s; + wait (&s); + s = WIFEXITED (s) ? WEXITSTATUS (s) : 1; + ; + return 0; +} +_ACEOF +rm -f conftest.$ac_objext +if { (ac_try="$ac_compile" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_header_sys_wait_h=yes +else + echo "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_header_sys_wait_h=no +fi + +rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +fi +{ echo "$as_me:$LINENO: result: $ac_cv_header_sys_wait_h" >&5 +echo "${ECHO_T}$ac_cv_header_sys_wait_h" >&6; } +if test $ac_cv_header_sys_wait_h = yes; then + +cat >>confdefs.h <<\_ACEOF +#define HAVE_SYS_WAIT_H 1 +_ACEOF + +fi + + + +{ echo "$as_me:$LINENO: checking for grep that handles long lines and -e" >&5 +echo $ECHO_N "checking for grep that handles long lines and -e... $ECHO_C" >&6; } +if test "${ac_cv_path_GREP+set}" = set; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +else + # Extract the first word of "grep ggrep" to use in msg output +if test -z "$GREP"; then +set dummy grep ggrep; ac_prog_name=$2 +if test "${ac_cv_path_GREP+set}" = set; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +else + ac_path_GREP_found=false +# Loop through the user's path and test for each of PROGNAME-LIST +as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH$PATH_SEPARATOR/usr/xpg4/bin +do + IFS=$as_save_IFS + test -z "$as_dir" && as_dir=. + for ac_prog in grep ggrep; do + for ac_exec_ext in '' $ac_executable_extensions; do + ac_path_GREP="$as_dir/$ac_prog$ac_exec_ext" + { test -f "$ac_path_GREP" && $as_test_x "$ac_path_GREP"; } || continue + # Check for GNU ac_path_GREP and select it if it is found. + # Check for GNU $ac_path_GREP +case `"$ac_path_GREP" --version 2>&1` in +*GNU*) + ac_cv_path_GREP="$ac_path_GREP" ac_path_GREP_found=:;; +*) + ac_count=0 + echo $ECHO_N "0123456789$ECHO_C" >"conftest.in" + while : + do + cat "conftest.in" "conftest.in" >"conftest.tmp" + mv "conftest.tmp" "conftest.in" + cp "conftest.in" "conftest.nl" + echo 'GREP' >> "conftest.nl" + "$ac_path_GREP" -e 'GREP$' -e '-(cannot match)-' < "conftest.nl" >"conftest.out" 2>/dev/null || break + diff "conftest.out" "conftest.nl" >/dev/null 2>&1 || break + ac_count=`expr $ac_count + 1` + if test $ac_count -gt ${ac_path_GREP_max-0}; then + # Best one so far, save it but keep looking for a better one + ac_cv_path_GREP="$ac_path_GREP" + ac_path_GREP_max=$ac_count + fi + # 10*(2^10) chars as input seems more than enough + test $ac_count -gt 10 && break + done + rm -f conftest.in conftest.tmp conftest.nl conftest.out;; +esac + + + $ac_path_GREP_found && break 3 + done +done + +done +IFS=$as_save_IFS + + +fi + +GREP="$ac_cv_path_GREP" +if test -z "$GREP"; then + { { echo "$as_me:$LINENO: error: no acceptable $ac_prog_name could be found in $PATH$PATH_SEPARATOR/usr/xpg4/bin" >&5 +echo "$as_me: error: no acceptable $ac_prog_name could be found in $PATH$PATH_SEPARATOR/usr/xpg4/bin" >&2;} + { (exit 1); exit 1; }; } +fi + +else + ac_cv_path_GREP=$GREP +fi + + +fi +{ echo "$as_me:$LINENO: result: $ac_cv_path_GREP" >&5 +echo "${ECHO_T}$ac_cv_path_GREP" >&6; } + GREP="$ac_cv_path_GREP" + + +{ echo "$as_me:$LINENO: checking for egrep" >&5 +echo $ECHO_N "checking for egrep... $ECHO_C" >&6; } +if test "${ac_cv_path_EGREP+set}" = set; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +else + if echo a | $GREP -E '(a|b)' >/dev/null 2>&1 + then ac_cv_path_EGREP="$GREP -E" + else + # Extract the first word of "egrep" to use in msg output +if test -z "$EGREP"; then +set dummy egrep; ac_prog_name=$2 +if test "${ac_cv_path_EGREP+set}" = set; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +else + ac_path_EGREP_found=false +# Loop through the user's path and test for each of PROGNAME-LIST +as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH$PATH_SEPARATOR/usr/xpg4/bin +do + IFS=$as_save_IFS + test -z "$as_dir" && as_dir=. + for ac_prog in egrep; do + for ac_exec_ext in '' $ac_executable_extensions; do + ac_path_EGREP="$as_dir/$ac_prog$ac_exec_ext" + { test -f "$ac_path_EGREP" && $as_test_x "$ac_path_EGREP"; } || continue + # Check for GNU ac_path_EGREP and select it if it is found. + # Check for GNU $ac_path_EGREP +case `"$ac_path_EGREP" --version 2>&1` in +*GNU*) + ac_cv_path_EGREP="$ac_path_EGREP" ac_path_EGREP_found=:;; +*) + ac_count=0 + echo $ECHO_N "0123456789$ECHO_C" >"conftest.in" + while : + do + cat "conftest.in" "conftest.in" >"conftest.tmp" + mv "conftest.tmp" "conftest.in" + cp "conftest.in" "conftest.nl" + echo 'EGREP' >> "conftest.nl" + "$ac_path_EGREP" 'EGREP$' < "conftest.nl" >"conftest.out" 2>/dev/null || break + diff "conftest.out" "conftest.nl" >/dev/null 2>&1 || break + ac_count=`expr $ac_count + 1` + if test $ac_count -gt ${ac_path_EGREP_max-0}; then + # Best one so far, save it but keep looking for a better one + ac_cv_path_EGREP="$ac_path_EGREP" + ac_path_EGREP_max=$ac_count + fi + # 10*(2^10) chars as input seems more than enough + test $ac_count -gt 10 && break + done + rm -f conftest.in conftest.tmp conftest.nl conftest.out;; +esac + + + $ac_path_EGREP_found && break 3 + done +done + +done +IFS=$as_save_IFS + + +fi + +EGREP="$ac_cv_path_EGREP" +if test -z "$EGREP"; then + { { echo "$as_me:$LINENO: error: no acceptable $ac_prog_name could be found in $PATH$PATH_SEPARATOR/usr/xpg4/bin" >&5 +echo "$as_me: error: no acceptable $ac_prog_name could be found in $PATH$PATH_SEPARATOR/usr/xpg4/bin" >&2;} + { (exit 1); exit 1; }; } +fi + +else + ac_cv_path_EGREP=$EGREP +fi + + + fi +fi +{ echo "$as_me:$LINENO: result: $ac_cv_path_EGREP" >&5 +echo "${ECHO_T}$ac_cv_path_EGREP" >&6; } + EGREP="$ac_cv_path_EGREP" + + +{ echo "$as_me:$LINENO: checking for ANSI C header files" >&5 +echo $ECHO_N "checking for ANSI C header files... $ECHO_C" >&6; } +if test "${ac_cv_header_stdc+set}" = set; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +else + cat >conftest.$ac_ext <<_ACEOF +/* confdefs.h. */ +_ACEOF +cat confdefs.h >>conftest.$ac_ext +cat >>conftest.$ac_ext <<_ACEOF +/* end confdefs.h. */ +#include +#include +#include +#include + +int +main () +{ + + ; + return 0; +} +_ACEOF +rm -f conftest.$ac_objext +if { (ac_try="$ac_compile" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_header_stdc=yes +else + echo "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_header_stdc=no +fi + +rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + +if test $ac_cv_header_stdc = yes; then + # SunOS 4.x string.h does not declare mem*, contrary to ANSI. + cat >conftest.$ac_ext <<_ACEOF +/* confdefs.h. */ +_ACEOF +cat confdefs.h >>conftest.$ac_ext +cat >>conftest.$ac_ext <<_ACEOF +/* end confdefs.h. */ +#include + +_ACEOF +if (eval "$ac_cpp conftest.$ac_ext") 2>&5 | + $EGREP "memchr" >/dev/null 2>&1; then + : +else + ac_cv_header_stdc=no +fi +rm -f conftest* + +fi + +if test $ac_cv_header_stdc = yes; then + # ISC 2.0.2 stdlib.h does not declare free, contrary to ANSI. + cat >conftest.$ac_ext <<_ACEOF +/* confdefs.h. */ +_ACEOF +cat confdefs.h >>conftest.$ac_ext +cat >>conftest.$ac_ext <<_ACEOF +/* end confdefs.h. */ +#include + +_ACEOF +if (eval "$ac_cpp conftest.$ac_ext") 2>&5 | + $EGREP "free" >/dev/null 2>&1; then + : +else + ac_cv_header_stdc=no +fi +rm -f conftest* + +fi + +if test $ac_cv_header_stdc = yes; then + # /bin/cc in Irix-4.0.5 gets non-ANSI ctype macros unless using -ansi. + if test "$cross_compiling" = yes; then + : +else + cat >conftest.$ac_ext <<_ACEOF +/* confdefs.h. */ +_ACEOF +cat confdefs.h >>conftest.$ac_ext +cat >>conftest.$ac_ext <<_ACEOF +/* end confdefs.h. */ +#include +#include +#if ((' ' & 0x0FF) == 0x020) +# define ISLOWER(c) ('a' <= (c) && (c) <= 'z') +# define TOUPPER(c) (ISLOWER(c) ? 'A' + ((c) - 'a') : (c)) +#else +# define ISLOWER(c) \ + (('a' <= (c) && (c) <= 'i') \ + || ('j' <= (c) && (c) <= 'r') \ + || ('s' <= (c) && (c) <= 'z')) +# define TOUPPER(c) (ISLOWER(c) ? ((c) | 0x40) : (c)) +#endif + +#define XOR(e, f) (((e) && !(f)) || (!(e) && (f))) +int +main () +{ + int i; + for (i = 0; i < 256; i++) + if (XOR (islower (i), ISLOWER (i)) + || toupper (i) != TOUPPER (i)) + return 2; + return 0; +} +_ACEOF +rm -f conftest$ac_exeext +if { (ac_try="$ac_link" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_link") 2>&5 + ac_status=$? + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { ac_try='./conftest$ac_exeext' + { (case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_try") 2>&5 + ac_status=$? + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); }; }; then + : +else + echo "$as_me: program exited with status $ac_status" >&5 +echo "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + +( exit $ac_status ) +ac_cv_header_stdc=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext conftest.$ac_objext conftest.$ac_ext +fi + + +fi +fi +{ echo "$as_me:$LINENO: result: $ac_cv_header_stdc" >&5 +echo "${ECHO_T}$ac_cv_header_stdc" >&6; } +if test $ac_cv_header_stdc = yes; then + +cat >>confdefs.h <<\_ACEOF +#define STDC_HEADERS 1 +_ACEOF + +fi + +# On IRIX 5.3, sys/types and inttypes.h are conflicting. + + + + + + + + + +for ac_header in sys/types.h sys/stat.h stdlib.h string.h memory.h strings.h \ + inttypes.h stdint.h unistd.h +do +as_ac_Header=`echo "ac_cv_header_$ac_header" | $as_tr_sh` +{ echo "$as_me:$LINENO: checking for $ac_header" >&5 +echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } +if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +else + cat >conftest.$ac_ext <<_ACEOF +/* confdefs.h. */ +_ACEOF +cat confdefs.h >>conftest.$ac_ext +cat >>conftest.$ac_ext <<_ACEOF +/* end confdefs.h. */ +$ac_includes_default + +#include <$ac_header> +_ACEOF +rm -f conftest.$ac_objext +if { (ac_try="$ac_compile" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + eval "$as_ac_Header=yes" +else + echo "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + + eval "$as_ac_Header=no" +fi + +rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +fi +ac_res=`eval echo '${'$as_ac_Header'}'` + { echo "$as_me:$LINENO: result: $ac_res" >&5 +echo "${ECHO_T}$ac_res" >&6; } +if test `eval echo '${'$as_ac_Header'}'` = yes; then + cat >>confdefs.h <<_ACEOF +#define `echo "HAVE_$ac_header" | $as_tr_cpp` 1 +_ACEOF + +fi + +done + + + + + + + + +for ac_header in ctype.h strings.h stdlib.h string.h pwd.h sys/time.h +do +as_ac_Header=`echo "ac_cv_header_$ac_header" | $as_tr_sh` +if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then + { echo "$as_me:$LINENO: checking for $ac_header" >&5 +echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } +if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +fi +ac_res=`eval echo '${'$as_ac_Header'}'` + { echo "$as_me:$LINENO: result: $ac_res" >&5 +echo "${ECHO_T}$ac_res" >&6; } +else + # Is the header compilable? +{ echo "$as_me:$LINENO: checking $ac_header usability" >&5 +echo $ECHO_N "checking $ac_header usability... $ECHO_C" >&6; } +cat >conftest.$ac_ext <<_ACEOF +/* confdefs.h. */ +_ACEOF +cat confdefs.h >>conftest.$ac_ext +cat >>conftest.$ac_ext <<_ACEOF +/* end confdefs.h. */ +$ac_includes_default +#include <$ac_header> +_ACEOF +rm -f conftest.$ac_objext +if { (ac_try="$ac_compile" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes +else + echo "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no +fi + +rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +echo "${ECHO_T}$ac_header_compiler" >&6; } + +# Is the header present? +{ echo "$as_me:$LINENO: checking $ac_header presence" >&5 +echo $ECHO_N "checking $ac_header presence... $ECHO_C" >&6; } +cat >conftest.$ac_ext <<_ACEOF +/* confdefs.h. */ +_ACEOF +cat confdefs.h >>conftest.$ac_ext +cat >>conftest.$ac_ext <<_ACEOF +/* end confdefs.h. */ +#include <$ac_header> +_ACEOF +if { (ac_try="$ac_cpp conftest.$ac_ext" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes +else + echo "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no +fi + +rm -f conftest.err conftest.$ac_ext +{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +echo "${ECHO_T}$ac_header_preproc" >&6; } + +# So? What about this header? +case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) + { echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 +echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} + { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 +echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) + { echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 +echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} + { echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 +echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} + { echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 +echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} + { echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 +echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} + { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 +echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} + { echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 +echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} + + ;; +esac +{ echo "$as_me:$LINENO: checking for $ac_header" >&5 +echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } +if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +else + eval "$as_ac_Header=\$ac_header_preproc" +fi +ac_res=`eval echo '${'$as_ac_Header'}'` + { echo "$as_me:$LINENO: result: $ac_res" >&5 +echo "${ECHO_T}$ac_res" >&6; } + +fi +if test `eval echo '${'$as_ac_Header'}'` = yes; then + cat >>confdefs.h <<_ACEOF +#define `echo "HAVE_$ac_header" | $as_tr_cpp` 1 +_ACEOF + +fi + +done + + + + + + + + +for ac_func in realpath snprintf vsnprintf vasprintf asprintf mkstemp +do +as_ac_var=`echo "ac_cv_func_$ac_func" | $as_tr_sh` +{ echo "$as_me:$LINENO: checking for $ac_func" >&5 +echo $ECHO_N "checking for $ac_func... $ECHO_C" >&6; } +if { as_var=$as_ac_var; eval "test \"\${$as_var+set}\" = set"; }; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +else + cat >conftest.$ac_ext <<_ACEOF +/* confdefs.h. */ +_ACEOF +cat confdefs.h >>conftest.$ac_ext +cat >>conftest.$ac_ext <<_ACEOF +/* end confdefs.h. */ +/* Define $ac_func to an innocuous variant, in case declares $ac_func. + For example, HP-UX 11i declares gettimeofday. */ +#define $ac_func innocuous_$ac_func + +/* System header to define __stub macros and hopefully few prototypes, + which can conflict with char $ac_func (); below. + Prefer to if __STDC__ is defined, since + exists even on freestanding compilers. */ + +#ifdef __STDC__ +# include +#else +# include +#endif + +#undef $ac_func + +/* Override any GCC internal prototype to avoid an error. + Use char because int might match the return type of a GCC + builtin and then its argument prototype would still apply. */ +#ifdef __cplusplus +extern "C" +#endif +char $ac_func (); +/* The GNU C library defines this for functions which it implements + to always fail with ENOSYS. Some functions are actually named + something starting with __ and the normal name is an alias. */ +#if defined __stub_$ac_func || defined __stub___$ac_func +choke me +#endif + +int +main () +{ +return $ac_func (); + ; + return 0; +} +_ACEOF +rm -f conftest.$ac_objext conftest$ac_exeext +if { (ac_try="$ac_link" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest$ac_exeext && + $as_test_x conftest$ac_exeext; then + eval "$as_ac_var=yes" +else + echo "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + + eval "$as_ac_var=no" +fi + +rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext +fi +ac_res=`eval echo '${'$as_ac_var'}'` + { echo "$as_me:$LINENO: result: $ac_res" >&5 +echo "${ECHO_T}$ac_res" >&6; } +if test `eval echo '${'$as_ac_var'}'` = yes; then + cat >>confdefs.h <<_ACEOF +#define `echo "HAVE_$ac_func" | $as_tr_cpp` 1 +_ACEOF + +fi +done + + + +for ac_func in gethostname getpwuid +do +as_ac_var=`echo "ac_cv_func_$ac_func" | $as_tr_sh` +{ echo "$as_me:$LINENO: checking for $ac_func" >&5 +echo $ECHO_N "checking for $ac_func... $ECHO_C" >&6; } +if { as_var=$as_ac_var; eval "test \"\${$as_var+set}\" = set"; }; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +else + cat >conftest.$ac_ext <<_ACEOF +/* confdefs.h. */ +_ACEOF +cat confdefs.h >>conftest.$ac_ext +cat >>conftest.$ac_ext <<_ACEOF +/* end confdefs.h. */ +/* Define $ac_func to an innocuous variant, in case declares $ac_func. + For example, HP-UX 11i declares gettimeofday. */ +#define $ac_func innocuous_$ac_func + +/* System header to define __stub macros and hopefully few prototypes, + which can conflict with char $ac_func (); below. + Prefer to if __STDC__ is defined, since + exists even on freestanding compilers. */ + +#ifdef __STDC__ +# include +#else +# include +#endif + +#undef $ac_func + +/* Override any GCC internal prototype to avoid an error. + Use char because int might match the return type of a GCC + builtin and then its argument prototype would still apply. */ +#ifdef __cplusplus +extern "C" +#endif +char $ac_func (); +/* The GNU C library defines this for functions which it implements + to always fail with ENOSYS. Some functions are actually named + something starting with __ and the normal name is an alias. */ +#if defined __stub_$ac_func || defined __stub___$ac_func +choke me +#endif + +int +main () +{ +return $ac_func (); + ; + return 0; +} +_ACEOF +rm -f conftest.$ac_objext conftest$ac_exeext +if { (ac_try="$ac_link" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest$ac_exeext && + $as_test_x conftest$ac_exeext; then + eval "$as_ac_var=yes" +else + echo "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + + eval "$as_ac_var=no" +fi + +rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext +fi +ac_res=`eval echo '${'$as_ac_var'}'` + { echo "$as_me:$LINENO: result: $ac_res" >&5 +echo "${ECHO_T}$ac_res" >&6; } +if test `eval echo '${'$as_ac_var'}'` = yes; then + cat >>confdefs.h <<_ACEOF +#define `echo "HAVE_$ac_func" | $as_tr_cpp` 1 +_ACEOF + +fi +done + + +for ac_func in utimes +do +as_ac_var=`echo "ac_cv_func_$ac_func" | $as_tr_sh` +{ echo "$as_me:$LINENO: checking for $ac_func" >&5 +echo $ECHO_N "checking for $ac_func... $ECHO_C" >&6; } +if { as_var=$as_ac_var; eval "test \"\${$as_var+set}\" = set"; }; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +else + cat >conftest.$ac_ext <<_ACEOF +/* confdefs.h. */ +_ACEOF +cat confdefs.h >>conftest.$ac_ext +cat >>conftest.$ac_ext <<_ACEOF +/* end confdefs.h. */ +/* Define $ac_func to an innocuous variant, in case declares $ac_func. + For example, HP-UX 11i declares gettimeofday. */ +#define $ac_func innocuous_$ac_func + +/* System header to define __stub macros and hopefully few prototypes, + which can conflict with char $ac_func (); below. + Prefer to if __STDC__ is defined, since + exists even on freestanding compilers. */ + +#ifdef __STDC__ +# include +#else +# include +#endif + +#undef $ac_func + +/* Override any GCC internal prototype to avoid an error. + Use char because int might match the return type of a GCC + builtin and then its argument prototype would still apply. */ +#ifdef __cplusplus +extern "C" +#endif +char $ac_func (); +/* The GNU C library defines this for functions which it implements + to always fail with ENOSYS. Some functions are actually named + something starting with __ and the normal name is an alias. */ +#if defined __stub_$ac_func || defined __stub___$ac_func +choke me +#endif + +int +main () +{ +return $ac_func (); + ; + return 0; +} +_ACEOF +rm -f conftest.$ac_objext conftest$ac_exeext +if { (ac_try="$ac_link" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest$ac_exeext && + $as_test_x conftest$ac_exeext; then + eval "$as_ac_var=yes" +else + echo "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + + eval "$as_ac_var=no" +fi + +rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext +fi +ac_res=`eval echo '${'$as_ac_var'}'` + { echo "$as_me:$LINENO: result: $ac_res" >&5 +echo "${ECHO_T}$ac_res" >&6; } +if test `eval echo '${'$as_ac_var'}'` = yes; then + cat >>confdefs.h <<_ACEOF +#define `echo "HAVE_$ac_func" | $as_tr_cpp` 1 +_ACEOF + +fi +done + + +{ echo "$as_me:$LINENO: checking for compar_fn_t in stdlib.h" >&5 +echo $ECHO_N "checking for compar_fn_t in stdlib.h... $ECHO_C" >&6; } +if test "${ccache_cv_COMPAR_FN_T+set}" = set; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +else + + cat >conftest.$ac_ext <<_ACEOF +/* confdefs.h. */ +_ACEOF +cat confdefs.h >>conftest.$ac_ext +cat >>conftest.$ac_ext <<_ACEOF +/* end confdefs.h. */ +#include +int +main () +{ + +void test_fn(void) { qsort(NULL, 0, 0, (__compar_fn_t)NULL); } + + ; + return 0; +} +_ACEOF +rm -f conftest.$ac_objext +if { (ac_try="$ac_compile" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ccache_cv_COMPAR_FN_T=yes +else + echo "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + + ccache_cv_COMPAR_FN_T=no +fi + +rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +fi +{ echo "$as_me:$LINENO: result: $ccache_cv_COMPAR_FN_T" >&5 +echo "${ECHO_T}$ccache_cv_COMPAR_FN_T" >&6; } +if test x"$ccache_cv_COMPAR_FN_T" = x"yes"; then + +cat >>confdefs.h <<\_ACEOF +#define HAVE_COMPAR_FN_T 1 +_ACEOF + +fi + +{ echo "$as_me:$LINENO: checking for C99 vsnprintf" >&5 +echo $ECHO_N "checking for C99 vsnprintf... $ECHO_C" >&6; } +if test "${ccache_cv_HAVE_C99_VSNPRINTF+set}" = set; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +else + +if test "$cross_compiling" = yes; then + ccache_cv_HAVE_C99_VSNPRINTF=cross +else + cat >conftest.$ac_ext <<_ACEOF +/* confdefs.h. */ +_ACEOF +cat confdefs.h >>conftest.$ac_ext +cat >>conftest.$ac_ext <<_ACEOF +/* end confdefs.h. */ + +#include +#include +void foo(const char *format, ...) { + va_list ap; + int len; + char buf[5]; + + va_start(ap, format); + len = vsnprintf(0, 0, format, ap); + va_end(ap); + if (len != 5) exit(1); + + if (snprintf(buf, 3, "hello") != 5 || strcmp(buf, "he") != 0) exit(1); + + exit(0); +} +main() { foo("hello"); } + +_ACEOF +rm -f conftest$ac_exeext +if { (ac_try="$ac_link" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_link") 2>&5 + ac_status=$? + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { ac_try='./conftest$ac_exeext' + { (case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_try") 2>&5 + ac_status=$? + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); }; }; then + ccache_cv_HAVE_C99_VSNPRINTF=yes +else + echo "$as_me: program exited with status $ac_status" >&5 +echo "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + +( exit $ac_status ) +ccache_cv_HAVE_C99_VSNPRINTF=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext conftest.$ac_objext conftest.$ac_ext +fi + + +fi +{ echo "$as_me:$LINENO: result: $ccache_cv_HAVE_C99_VSNPRINTF" >&5 +echo "${ECHO_T}$ccache_cv_HAVE_C99_VSNPRINTF" >&6; } +if test x"$ccache_cv_HAVE_C99_VSNPRINTF" = x"yes"; then + +cat >>confdefs.h <<\_ACEOF +#define HAVE_C99_VSNPRINTF 1 +_ACEOF + +fi + +# Check whether --enable-zlib was given. +if test "${enable_zlib+set}" = set; then + enableval=$enable_zlib; +else + enable_zlib=yes +fi + + +if test x"$enable_zlib" = x"yes"; then + if test "${ac_cv_header_zlib_h+set}" = set; then + { echo "$as_me:$LINENO: checking for zlib.h" >&5 +echo $ECHO_N "checking for zlib.h... $ECHO_C" >&6; } +if test "${ac_cv_header_zlib_h+set}" = set; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +fi +{ echo "$as_me:$LINENO: result: $ac_cv_header_zlib_h" >&5 +echo "${ECHO_T}$ac_cv_header_zlib_h" >&6; } +else + # Is the header compilable? +{ echo "$as_me:$LINENO: checking zlib.h usability" >&5 +echo $ECHO_N "checking zlib.h usability... $ECHO_C" >&6; } +cat >conftest.$ac_ext <<_ACEOF +/* confdefs.h. */ +_ACEOF +cat confdefs.h >>conftest.$ac_ext +cat >>conftest.$ac_ext <<_ACEOF +/* end confdefs.h. */ +$ac_includes_default +#include +_ACEOF +rm -f conftest.$ac_objext +if { (ac_try="$ac_compile" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes +else + echo "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no +fi + +rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +echo "${ECHO_T}$ac_header_compiler" >&6; } + +# Is the header present? +{ echo "$as_me:$LINENO: checking zlib.h presence" >&5 +echo $ECHO_N "checking zlib.h presence... $ECHO_C" >&6; } +cat >conftest.$ac_ext <<_ACEOF +/* confdefs.h. */ +_ACEOF +cat confdefs.h >>conftest.$ac_ext +cat >>conftest.$ac_ext <<_ACEOF +/* end confdefs.h. */ +#include +_ACEOF +if { (ac_try="$ac_cpp conftest.$ac_ext" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes +else + echo "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no +fi + +rm -f conftest.err conftest.$ac_ext +{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +echo "${ECHO_T}$ac_header_preproc" >&6; } + +# So? What about this header? +case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) + { echo "$as_me:$LINENO: WARNING: zlib.h: accepted by the compiler, rejected by the preprocessor!" >&5 +echo "$as_me: WARNING: zlib.h: accepted by the compiler, rejected by the preprocessor!" >&2;} + { echo "$as_me:$LINENO: WARNING: zlib.h: proceeding with the compiler's result" >&5 +echo "$as_me: WARNING: zlib.h: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) + { echo "$as_me:$LINENO: WARNING: zlib.h: present but cannot be compiled" >&5 +echo "$as_me: WARNING: zlib.h: present but cannot be compiled" >&2;} + { echo "$as_me:$LINENO: WARNING: zlib.h: check for missing prerequisite headers?" >&5 +echo "$as_me: WARNING: zlib.h: check for missing prerequisite headers?" >&2;} + { echo "$as_me:$LINENO: WARNING: zlib.h: see the Autoconf documentation" >&5 +echo "$as_me: WARNING: zlib.h: see the Autoconf documentation" >&2;} + { echo "$as_me:$LINENO: WARNING: zlib.h: section \"Present But Cannot Be Compiled\"" >&5 +echo "$as_me: WARNING: zlib.h: section \"Present But Cannot Be Compiled\"" >&2;} + { echo "$as_me:$LINENO: WARNING: zlib.h: proceeding with the preprocessor's result" >&5 +echo "$as_me: WARNING: zlib.h: proceeding with the preprocessor's result" >&2;} + { echo "$as_me:$LINENO: WARNING: zlib.h: in the future, the compiler will take precedence" >&5 +echo "$as_me: WARNING: zlib.h: in the future, the compiler will take precedence" >&2;} + + ;; +esac +{ echo "$as_me:$LINENO: checking for zlib.h" >&5 +echo $ECHO_N "checking for zlib.h... $ECHO_C" >&6; } +if test "${ac_cv_header_zlib_h+set}" = set; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +else + ac_cv_header_zlib_h=$ac_header_preproc +fi +{ echo "$as_me:$LINENO: result: $ac_cv_header_zlib_h" >&5 +echo "${ECHO_T}$ac_cv_header_zlib_h" >&6; } + +fi +if test $ac_cv_header_zlib_h = yes; then + { echo "$as_me:$LINENO: checking for gzdopen in -lz" >&5 +echo $ECHO_N "checking for gzdopen in -lz... $ECHO_C" >&6; } +if test "${ac_cv_lib_z_gzdopen+set}" = set; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +else + ac_check_lib_save_LIBS=$LIBS +LIBS="-lz $LIBS" +cat >conftest.$ac_ext <<_ACEOF +/* confdefs.h. */ +_ACEOF +cat confdefs.h >>conftest.$ac_ext +cat >>conftest.$ac_ext <<_ACEOF +/* end confdefs.h. */ + +/* Override any GCC internal prototype to avoid an error. + Use char because int might match the return type of a GCC + builtin and then its argument prototype would still apply. */ +#ifdef __cplusplus +extern "C" +#endif +char gzdopen (); +int +main () +{ +return gzdopen (); + ; + return 0; +} +_ACEOF +rm -f conftest.$ac_objext conftest$ac_exeext +if { (ac_try="$ac_link" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest$ac_exeext && + $as_test_x conftest$ac_exeext; then + ac_cv_lib_z_gzdopen=yes +else + echo "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_z_gzdopen=no +fi + +rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext +LIBS=$ac_check_lib_save_LIBS +fi +{ echo "$as_me:$LINENO: result: $ac_cv_lib_z_gzdopen" >&5 +echo "${ECHO_T}$ac_cv_lib_z_gzdopen" >&6; } +if test $ac_cv_lib_z_gzdopen = yes; then + LIBS="-lz $LIBS" + +cat >>confdefs.h <<\_ACEOF +#define ENABLE_ZLIB 1 +_ACEOF + +fi + +fi + + +fi + +ac_config_files="$ac_config_files Makefile" + +cat >confcache <<\_ACEOF +# This file is a shell script that caches the results of configure +# tests run on this system so they can be shared between configure +# scripts and configure runs, see configure's option --config-cache. +# It is not useful on other systems. If it contains results you don't +# want to keep, you may remove or edit it. +# +# config.status only pays attention to the cache file if you give it +# the --recheck option to rerun configure. +# +# `ac_cv_env_foo' variables (set or unset) will be overridden when +# loading this file, other *unset* `ac_cv_foo' will be assigned the +# following values. + +_ACEOF + +# The following way of writing the cache mishandles newlines in values, +# but we know of no workaround that is simple, portable, and efficient. +# So, we kill variables containing newlines. +# Ultrix sh set writes to stderr and can't be redirected directly, +# and sets the high bit in the cache file unless we assign to the vars. +( + for ac_var in `(set) 2>&1 | sed -n 's/^\([a-zA-Z_][a-zA-Z0-9_]*\)=.*/\1/p'`; do + eval ac_val=\$$ac_var + case $ac_val in #( + *${as_nl}*) + case $ac_var in #( + *_cv_*) { echo "$as_me:$LINENO: WARNING: Cache variable $ac_var contains a newline." >&5 +echo "$as_me: WARNING: Cache variable $ac_var contains a newline." >&2;} ;; + esac + case $ac_var in #( + _ | IFS | as_nl) ;; #( + *) $as_unset $ac_var ;; + esac ;; + esac + done + + (set) 2>&1 | + case $as_nl`(ac_space=' '; set) 2>&1` in #( + *${as_nl}ac_space=\ *) + # `set' does not quote correctly, so add quotes (double-quote + # substitution turns \\\\ into \\, and sed turns \\ into \). + sed -n \ + "s/'/'\\\\''/g; + s/^\\([_$as_cr_alnum]*_cv_[_$as_cr_alnum]*\\)=\\(.*\\)/\\1='\\2'/p" + ;; #( + *) + # `set' quotes correctly as required by POSIX, so do not add quotes. + sed -n "/^[_$as_cr_alnum]*_cv_[_$as_cr_alnum]*=/p" + ;; + esac | + sort +) | + sed ' + /^ac_cv_env_/b end + t clear + :clear + s/^\([^=]*\)=\(.*[{}].*\)$/test "${\1+set}" = set || &/ + t end + s/^\([^=]*\)=\(.*\)$/\1=${\1=\2}/ + :end' >>confcache +if diff "$cache_file" confcache >/dev/null 2>&1; then :; else + if test -w "$cache_file"; then + test "x$cache_file" != "x/dev/null" && + { echo "$as_me:$LINENO: updating cache $cache_file" >&5 +echo "$as_me: updating cache $cache_file" >&6;} + cat confcache >$cache_file + else + { echo "$as_me:$LINENO: not updating unwritable cache $cache_file" >&5 +echo "$as_me: not updating unwritable cache $cache_file" >&6;} + fi +fi +rm -f confcache + +test "x$prefix" = xNONE && prefix=$ac_default_prefix +# Let make expand exec_prefix. +test "x$exec_prefix" = xNONE && exec_prefix='${prefix}' + +DEFS=-DHAVE_CONFIG_H + +ac_libobjs= +ac_ltlibobjs= +for ac_i in : $LIBOBJS; do test "x$ac_i" = x: && continue + # 1. Remove the extension, and $U if already installed. + ac_script='s/\$U\././;s/\.o$//;s/\.obj$//' + ac_i=`echo "$ac_i" | sed "$ac_script"` + # 2. Prepend LIBOBJDIR. When used with automake>=1.10 LIBOBJDIR + # will be set to the directory where LIBOBJS objects are built. + ac_libobjs="$ac_libobjs \${LIBOBJDIR}$ac_i\$U.$ac_objext" + ac_ltlibobjs="$ac_ltlibobjs \${LIBOBJDIR}$ac_i"'$U.lo' +done +LIBOBJS=$ac_libobjs + +LTLIBOBJS=$ac_ltlibobjs + + + +: ${CONFIG_STATUS=./config.status} +ac_clean_files_save=$ac_clean_files +ac_clean_files="$ac_clean_files $CONFIG_STATUS" +{ echo "$as_me:$LINENO: creating $CONFIG_STATUS" >&5 +echo "$as_me: creating $CONFIG_STATUS" >&6;} +cat >$CONFIG_STATUS <<_ACEOF +#! $SHELL +# Generated by $as_me. +# Run this file to recreate the current configuration. +# Compiler output produced by configure, useful for debugging +# configure, is in config.log if it exists. + +debug=false +ac_cs_recheck=false +ac_cs_silent=false +SHELL=\${CONFIG_SHELL-$SHELL} +_ACEOF + +cat >>$CONFIG_STATUS <<\_ACEOF +## --------------------- ## +## M4sh Initialization. ## +## --------------------- ## + +# Be more Bourne compatible +DUALCASE=1; export DUALCASE # for MKS sh +if test -n "${ZSH_VERSION+set}" && (emulate sh) >/dev/null 2>&1; then + emulate sh + NULLCMD=: + # Zsh 3.x and 4.x performs word splitting on ${1+"$@"}, which + # is contrary to our usage. Disable this feature. + alias -g '${1+"$@"}'='"$@"' + setopt NO_GLOB_SUBST +else + case `(set -o) 2>/dev/null` in + *posix*) set -o posix ;; +esac + +fi + + + + +# PATH needs CR +# Avoid depending upon Character Ranges. +as_cr_letters='abcdefghijklmnopqrstuvwxyz' +as_cr_LETTERS='ABCDEFGHIJKLMNOPQRSTUVWXYZ' +as_cr_Letters=$as_cr_letters$as_cr_LETTERS +as_cr_digits='0123456789' +as_cr_alnum=$as_cr_Letters$as_cr_digits + +# The user is always right. +if test "${PATH_SEPARATOR+set}" != set; then + echo "#! /bin/sh" >conf$$.sh + echo "exit 0" >>conf$$.sh + chmod +x conf$$.sh + if (PATH="/nonexistent;."; conf$$.sh) >/dev/null 2>&1; then + PATH_SEPARATOR=';' + else + PATH_SEPARATOR=: + fi + rm -f conf$$.sh +fi + +# Support unset when possible. +if ( (MAIL=60; unset MAIL) || exit) >/dev/null 2>&1; then + as_unset=unset +else + as_unset=false +fi + + +# IFS +# We need space, tab and new line, in precisely that order. Quoting is +# there to prevent editors from complaining about space-tab. +# (If _AS_PATH_WALK were called with IFS unset, it would disable word +# splitting by setting IFS to empty value.) +as_nl=' +' +IFS=" "" $as_nl" + +# Find who we are. Look in the path if we contain no directory separator. +case $0 in + *[\\/]* ) as_myself=$0 ;; + *) as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + test -z "$as_dir" && as_dir=. + test -r "$as_dir/$0" && as_myself=$as_dir/$0 && break +done +IFS=$as_save_IFS + + ;; +esac +# We did not find ourselves, most probably we were run as `sh COMMAND' +# in which case we are not to be found in the path. +if test "x$as_myself" = x; then + as_myself=$0 +fi +if test ! -f "$as_myself"; then + echo "$as_myself: error: cannot find myself; rerun with an absolute file name" >&2 + { (exit 1); exit 1; } +fi + +# Work around bugs in pre-3.0 UWIN ksh. +for as_var in ENV MAIL MAILPATH +do ($as_unset $as_var) >/dev/null 2>&1 && $as_unset $as_var +done +PS1='$ ' +PS2='> ' +PS4='+ ' + +# NLS nuisances. +for as_var in \ + LANG LANGUAGE LC_ADDRESS LC_ALL LC_COLLATE LC_CTYPE LC_IDENTIFICATION \ + LC_MEASUREMENT LC_MESSAGES LC_MONETARY LC_NAME LC_NUMERIC LC_PAPER \ + LC_TELEPHONE LC_TIME +do + if (set +x; test -z "`(eval $as_var=C; export $as_var) 2>&1`"); then + eval $as_var=C; export $as_var + else + ($as_unset $as_var) >/dev/null 2>&1 && $as_unset $as_var + fi +done + +# Required to use basename. +if expr a : '\(a\)' >/dev/null 2>&1 && + test "X`expr 00001 : '.*\(...\)'`" = X001; then + as_expr=expr +else + as_expr=false +fi + +if (basename -- /) >/dev/null 2>&1 && test "X`basename -- / 2>&1`" = "X/"; then + as_basename=basename +else + as_basename=false +fi + + +# Name of the executable. +as_me=`$as_basename -- "$0" || +$as_expr X/"$0" : '.*/\([^/][^/]*\)/*$' \| \ + X"$0" : 'X\(//\)$' \| \ + X"$0" : 'X\(/\)' \| . 2>/dev/null || +echo X/"$0" | + sed '/^.*\/\([^/][^/]*\)\/*$/{ + s//\1/ + q + } + /^X\/\(\/\/\)$/{ + s//\1/ + q + } + /^X\/\(\/\).*/{ + s//\1/ + q + } + s/.*/./; q'` + +# CDPATH. +$as_unset CDPATH + + + + as_lineno_1=$LINENO + as_lineno_2=$LINENO + test "x$as_lineno_1" != "x$as_lineno_2" && + test "x`expr $as_lineno_1 + 1`" = "x$as_lineno_2" || { + + # Create $as_me.lineno as a copy of $as_myself, but with $LINENO + # uniformly replaced by the line number. The first 'sed' inserts a + # line-number line after each line using $LINENO; the second 'sed' + # does the real work. The second script uses 'N' to pair each + # line-number line with the line containing $LINENO, and appends + # trailing '-' during substitution so that $LINENO is not a special + # case at line end. + # (Raja R Harinath suggested sed '=', and Paul Eggert wrote the + # scripts with optimization help from Paolo Bonzini. Blame Lee + # E. McMahon (1931-1989) for sed's syntax. :-) + sed -n ' + p + /[$]LINENO/= + ' <$as_myself | + sed ' + s/[$]LINENO.*/&-/ + t lineno + b + :lineno + N + :loop + s/[$]LINENO\([^'$as_cr_alnum'_].*\n\)\(.*\)/\2\1\2/ + t loop + s/-\n.*// + ' >$as_me.lineno && + chmod +x "$as_me.lineno" || + { echo "$as_me: error: cannot create $as_me.lineno; rerun with a POSIX shell" >&2 + { (exit 1); exit 1; }; } + + # Don't try to exec as it changes $[0], causing all sort of problems + # (the dirname of $[0] is not the place where we might find the + # original and so on. Autoconf is especially sensitive to this). + . "./$as_me.lineno" + # Exit status is that of the last command. + exit +} + + +if (as_dir=`dirname -- /` && test "X$as_dir" = X/) >/dev/null 2>&1; then + as_dirname=dirname +else + as_dirname=false +fi + +ECHO_C= ECHO_N= ECHO_T= +case `echo -n x` in +-n*) + case `echo 'x\c'` in + *c*) ECHO_T=' ';; # ECHO_T is single tab character. + *) ECHO_C='\c';; + esac;; +*) + ECHO_N='-n';; +esac + +if expr a : '\(a\)' >/dev/null 2>&1 && + test "X`expr 00001 : '.*\(...\)'`" = X001; then + as_expr=expr +else + as_expr=false +fi + +rm -f conf$$ conf$$.exe conf$$.file +if test -d conf$$.dir; then + rm -f conf$$.dir/conf$$.file +else + rm -f conf$$.dir + mkdir conf$$.dir +fi +echo >conf$$.file +if ln -s conf$$.file conf$$ 2>/dev/null; then + as_ln_s='ln -s' + # ... but there are two gotchas: + # 1) On MSYS, both `ln -s file dir' and `ln file dir' fail. + # 2) DJGPP < 2.04 has no symlinks; `ln -s' creates a wrapper executable. + # In both cases, we have to default to `cp -p'. + ln -s conf$$.file conf$$.dir 2>/dev/null && test ! -f conf$$.exe || + as_ln_s='cp -p' +elif ln conf$$.file conf$$ 2>/dev/null; then + as_ln_s=ln +else + as_ln_s='cp -p' +fi +rm -f conf$$ conf$$.exe conf$$.dir/conf$$.file conf$$.file +rmdir conf$$.dir 2>/dev/null + +if mkdir -p . 2>/dev/null; then + as_mkdir_p=: +else + test -d ./-p && rmdir ./-p + as_mkdir_p=false +fi + +if test -x / >/dev/null 2>&1; then + as_test_x='test -x' +else + if ls -dL / >/dev/null 2>&1; then + as_ls_L_option=L + else + as_ls_L_option= + fi + as_test_x=' + eval sh -c '\'' + if test -d "$1"; then + test -d "$1/."; + else + case $1 in + -*)set "./$1";; + esac; + case `ls -ld'$as_ls_L_option' "$1" 2>/dev/null` in + ???[sx]*):;;*)false;;esac;fi + '\'' sh + ' +fi +as_executable_p=$as_test_x + +# Sed expression to map a string onto a valid CPP name. +as_tr_cpp="eval sed 'y%*$as_cr_letters%P$as_cr_LETTERS%;s%[^_$as_cr_alnum]%_%g'" + +# Sed expression to map a string onto a valid variable name. +as_tr_sh="eval sed 'y%*+%pp%;s%[^_$as_cr_alnum]%_%g'" + + +exec 6>&1 + +# Save the log message, to keep $[0] and so on meaningful, and to +# report actual input values of CONFIG_FILES etc. instead of their +# values after options handling. +ac_log=" +This file was extended by ccache-swig $as_me 0.0, which was +generated by GNU Autoconf 2.61. Invocation command line was + + CONFIG_FILES = $CONFIG_FILES + CONFIG_HEADERS = $CONFIG_HEADERS + CONFIG_LINKS = $CONFIG_LINKS + CONFIG_COMMANDS = $CONFIG_COMMANDS + $ $0 $@ + +on `(hostname || uname -n) 2>/dev/null | sed 1q` +" + +_ACEOF + +cat >>$CONFIG_STATUS <<_ACEOF +# Files that config.status was made for. +config_files="$ac_config_files" +config_headers="$ac_config_headers" + +_ACEOF + +cat >>$CONFIG_STATUS <<\_ACEOF +ac_cs_usage="\ +\`$as_me' instantiates files from templates according to the +current configuration. + +Usage: $0 [OPTIONS] [FILE]... + + -h, --help print this help, then exit + -V, --version print version number and configuration settings, then exit + -q, --quiet do not print progress messages + -d, --debug don't remove temporary files + --recheck update $as_me by reconfiguring in the same conditions + --file=FILE[:TEMPLATE] + instantiate the configuration file FILE + --header=FILE[:TEMPLATE] + instantiate the configuration header FILE + +Configuration files: +$config_files + +Configuration headers: +$config_headers + +Report bugs to ." + +_ACEOF +cat >>$CONFIG_STATUS <<_ACEOF +ac_cs_version="\\ +ccache-swig config.status 0.0 +configured by $0, generated by GNU Autoconf 2.61, + with options \\"`echo "$ac_configure_args" | sed 's/^ //; s/[\\""\`\$]/\\\\&/g'`\\" + +Copyright (C) 2006 Free Software Foundation, Inc. +This config.status script is free software; the Free Software Foundation +gives unlimited permission to copy, distribute and modify it." + +ac_pwd='$ac_pwd' +srcdir='$srcdir' +INSTALL='$INSTALL' +_ACEOF + +cat >>$CONFIG_STATUS <<\_ACEOF +# If no file are specified by the user, then we need to provide default +# value. By we need to know if files were specified by the user. +ac_need_defaults=: +while test $# != 0 +do + case $1 in + --*=*) + ac_option=`expr "X$1" : 'X\([^=]*\)='` + ac_optarg=`expr "X$1" : 'X[^=]*=\(.*\)'` + ac_shift=: + ;; + *) + ac_option=$1 + ac_optarg=$2 + ac_shift=shift + ;; + esac + + case $ac_option in + # Handling of the options. + -recheck | --recheck | --rechec | --reche | --rech | --rec | --re | --r) + ac_cs_recheck=: ;; + --version | --versio | --versi | --vers | --ver | --ve | --v | -V ) + echo "$ac_cs_version"; exit ;; + --debug | --debu | --deb | --de | --d | -d ) + debug=: ;; + --file | --fil | --fi | --f ) + $ac_shift + CONFIG_FILES="$CONFIG_FILES $ac_optarg" + ac_need_defaults=false;; + --header | --heade | --head | --hea ) + $ac_shift + CONFIG_HEADERS="$CONFIG_HEADERS $ac_optarg" + ac_need_defaults=false;; + --he | --h) + # Conflict between --help and --header + { echo "$as_me: error: ambiguous option: $1 +Try \`$0 --help' for more information." >&2 + { (exit 1); exit 1; }; };; + --help | --hel | -h ) + echo "$ac_cs_usage"; exit ;; + -q | -quiet | --quiet | --quie | --qui | --qu | --q \ + | -silent | --silent | --silen | --sile | --sil | --si | --s) + ac_cs_silent=: ;; + + # This is an error. + -*) { echo "$as_me: error: unrecognized option: $1 +Try \`$0 --help' for more information." >&2 + { (exit 1); exit 1; }; } ;; + + *) ac_config_targets="$ac_config_targets $1" + ac_need_defaults=false ;; + + esac + shift +done + +ac_configure_extra_args= + +if $ac_cs_silent; then + exec 6>/dev/null + ac_configure_extra_args="$ac_configure_extra_args --silent" +fi + +_ACEOF +cat >>$CONFIG_STATUS <<_ACEOF +if \$ac_cs_recheck; then + echo "running CONFIG_SHELL=$SHELL $SHELL $0 "$ac_configure_args \$ac_configure_extra_args " --no-create --no-recursion" >&6 + CONFIG_SHELL=$SHELL + export CONFIG_SHELL + exec $SHELL "$0"$ac_configure_args \$ac_configure_extra_args --no-create --no-recursion +fi + +_ACEOF +cat >>$CONFIG_STATUS <<\_ACEOF +exec 5>>config.log +{ + echo + sed 'h;s/./-/g;s/^.../## /;s/...$/ ##/;p;x;p;x' <<_ASBOX +## Running $as_me. ## +_ASBOX + echo "$ac_log" +} >&5 + +_ACEOF +cat >>$CONFIG_STATUS <<_ACEOF +_ACEOF + +cat >>$CONFIG_STATUS <<\_ACEOF + +# Handling of arguments. +for ac_config_target in $ac_config_targets +do + case $ac_config_target in + "config.h") CONFIG_HEADERS="$CONFIG_HEADERS config.h" ;; + "Makefile") CONFIG_FILES="$CONFIG_FILES Makefile" ;; + + *) { { echo "$as_me:$LINENO: error: invalid argument: $ac_config_target" >&5 +echo "$as_me: error: invalid argument: $ac_config_target" >&2;} + { (exit 1); exit 1; }; };; + esac +done + + +# If the user did not use the arguments to specify the items to instantiate, +# then the envvar interface is used. Set only those that are not. +# We use the long form for the default assignment because of an extremely +# bizarre bug on SunOS 4.1.3. +if $ac_need_defaults; then + test "${CONFIG_FILES+set}" = set || CONFIG_FILES=$config_files + test "${CONFIG_HEADERS+set}" = set || CONFIG_HEADERS=$config_headers +fi + +# Have a temporary directory for convenience. Make it in the build tree +# simply because there is no reason against having it here, and in addition, +# creating and moving files from /tmp can sometimes cause problems. +# Hook for its removal unless debugging. +# Note that there is a small window in which the directory will not be cleaned: +# after its creation but before its name has been assigned to `$tmp'. +$debug || +{ + tmp= + trap 'exit_status=$? + { test -z "$tmp" || test ! -d "$tmp" || rm -fr "$tmp"; } && exit $exit_status +' 0 + trap '{ (exit 1); exit 1; }' 1 2 13 15 +} +# Create a (secure) tmp directory for tmp files. + +{ + tmp=`(umask 077 && mktemp -d "./confXXXXXX") 2>/dev/null` && + test -n "$tmp" && test -d "$tmp" +} || +{ + tmp=./conf$$-$RANDOM + (umask 077 && mkdir "$tmp") +} || +{ + echo "$me: cannot create a temporary directory in ." >&2 + { (exit 1); exit 1; } +} + +# +# Set up the sed scripts for CONFIG_FILES section. +# + +# No need to generate the scripts if there are no CONFIG_FILES. +# This happens for instance when ./config.status config.h +if test -n "$CONFIG_FILES"; then + +_ACEOF + + + +ac_delim='%!_!# ' +for ac_last_try in false false false false false :; do + cat >conf$$subs.sed <<_ACEOF +SHELL!$SHELL$ac_delim +PATH_SEPARATOR!$PATH_SEPARATOR$ac_delim +PACKAGE_NAME!$PACKAGE_NAME$ac_delim +PACKAGE_TARNAME!$PACKAGE_TARNAME$ac_delim +PACKAGE_VERSION!$PACKAGE_VERSION$ac_delim +PACKAGE_STRING!$PACKAGE_STRING$ac_delim +PACKAGE_BUGREPORT!$PACKAGE_BUGREPORT$ac_delim +exec_prefix!$exec_prefix$ac_delim +prefix!$prefix$ac_delim +program_transform_name!$program_transform_name$ac_delim +bindir!$bindir$ac_delim +sbindir!$sbindir$ac_delim +libexecdir!$libexecdir$ac_delim +datarootdir!$datarootdir$ac_delim +datadir!$datadir$ac_delim +sysconfdir!$sysconfdir$ac_delim +sharedstatedir!$sharedstatedir$ac_delim +localstatedir!$localstatedir$ac_delim +includedir!$includedir$ac_delim +oldincludedir!$oldincludedir$ac_delim +docdir!$docdir$ac_delim +infodir!$infodir$ac_delim +htmldir!$htmldir$ac_delim +dvidir!$dvidir$ac_delim +pdfdir!$pdfdir$ac_delim +psdir!$psdir$ac_delim +libdir!$libdir$ac_delim +localedir!$localedir$ac_delim +mandir!$mandir$ac_delim +DEFS!$DEFS$ac_delim +ECHO_C!$ECHO_C$ac_delim +ECHO_N!$ECHO_N$ac_delim +ECHO_T!$ECHO_T$ac_delim +LIBS!$LIBS$ac_delim +build_alias!$build_alias$ac_delim +host_alias!$host_alias$ac_delim +target_alias!$target_alias$ac_delim +CC!$CC$ac_delim +CFLAGS!$CFLAGS$ac_delim +LDFLAGS!$LDFLAGS$ac_delim +CPPFLAGS!$CPPFLAGS$ac_delim +ac_ct_CC!$ac_ct_CC$ac_delim +EXEEXT!$EXEEXT$ac_delim +OBJEXT!$OBJEXT$ac_delim +CPP!$CPP$ac_delim +INSTALL_PROGRAM!$INSTALL_PROGRAM$ac_delim +INSTALL_SCRIPT!$INSTALL_SCRIPT$ac_delim +INSTALL_DATA!$INSTALL_DATA$ac_delim +GREP!$GREP$ac_delim +EGREP!$EGREP$ac_delim +LIBOBJS!$LIBOBJS$ac_delim +LTLIBOBJS!$LTLIBOBJS$ac_delim +_ACEOF + + if test `sed -n "s/.*$ac_delim\$/X/p" conf$$subs.sed | grep -c X` = 52; then + break + elif $ac_last_try; then + { { echo "$as_me:$LINENO: error: could not make $CONFIG_STATUS" >&5 +echo "$as_me: error: could not make $CONFIG_STATUS" >&2;} + { (exit 1); exit 1; }; } + else + ac_delim="$ac_delim!$ac_delim _$ac_delim!! " + fi +done + +ac_eof=`sed -n '/^CEOF[0-9]*$/s/CEOF/0/p' conf$$subs.sed` +if test -n "$ac_eof"; then + ac_eof=`echo "$ac_eof" | sort -nru | sed 1q` + ac_eof=`expr $ac_eof + 1` +fi + +cat >>$CONFIG_STATUS <<_ACEOF +cat >"\$tmp/subs-1.sed" <<\CEOF$ac_eof +/@[a-zA-Z_][a-zA-Z_0-9]*@/!b end +_ACEOF +sed ' +s/[,\\&]/\\&/g; s/@/@|#_!!_#|/g +s/^/s,@/; s/!/@,|#_!!_#|/ +:n +t n +s/'"$ac_delim"'$/,g/; t +s/$/\\/; p +N; s/^.*\n//; s/[,\\&]/\\&/g; s/@/@|#_!!_#|/g; b n +' >>$CONFIG_STATUS >$CONFIG_STATUS <<_ACEOF +:end +s/|#_!!_#|//g +CEOF$ac_eof +_ACEOF + + +# VPATH may cause trouble with some makes, so we remove $(srcdir), +# ${srcdir} and @srcdir@ from VPATH if srcdir is ".", strip leading and +# trailing colons and then remove the whole line if VPATH becomes empty +# (actually we leave an empty line to preserve line numbers). +if test "x$srcdir" = x.; then + ac_vpsub='/^[ ]*VPATH[ ]*=/{ +s/:*\$(srcdir):*/:/ +s/:*\${srcdir}:*/:/ +s/:*@srcdir@:*/:/ +s/^\([^=]*=[ ]*\):*/\1/ +s/:*$// +s/^[^=]*=[ ]*$// +}' +fi + +cat >>$CONFIG_STATUS <<\_ACEOF +fi # test -n "$CONFIG_FILES" + + +for ac_tag in :F $CONFIG_FILES :H $CONFIG_HEADERS +do + case $ac_tag in + :[FHLC]) ac_mode=$ac_tag; continue;; + esac + case $ac_mode$ac_tag in + :[FHL]*:*);; + :L* | :C*:*) { { echo "$as_me:$LINENO: error: Invalid tag $ac_tag." >&5 +echo "$as_me: error: Invalid tag $ac_tag." >&2;} + { (exit 1); exit 1; }; };; + :[FH]-) ac_tag=-:-;; + :[FH]*) ac_tag=$ac_tag:$ac_tag.in;; + esac + ac_save_IFS=$IFS + IFS=: + set x $ac_tag + IFS=$ac_save_IFS + shift + ac_file=$1 + shift + + case $ac_mode in + :L) ac_source=$1;; + :[FH]) + ac_file_inputs= + for ac_f + do + case $ac_f in + -) ac_f="$tmp/stdin";; + *) # Look for the file first in the build tree, then in the source tree + # (if the path is not absolute). The absolute path cannot be DOS-style, + # because $ac_f cannot contain `:'. + test -f "$ac_f" || + case $ac_f in + [\\/$]*) false;; + *) test -f "$srcdir/$ac_f" && ac_f="$srcdir/$ac_f";; + esac || + { { echo "$as_me:$LINENO: error: cannot find input file: $ac_f" >&5 +echo "$as_me: error: cannot find input file: $ac_f" >&2;} + { (exit 1); exit 1; }; };; + esac + ac_file_inputs="$ac_file_inputs $ac_f" + done + + # Let's still pretend it is `configure' which instantiates (i.e., don't + # use $as_me), people would be surprised to read: + # /* config.h. Generated by config.status. */ + configure_input="Generated from "`IFS=: + echo $* | sed 's|^[^:]*/||;s|:[^:]*/|, |g'`" by configure." + if test x"$ac_file" != x-; then + configure_input="$ac_file. $configure_input" + { echo "$as_me:$LINENO: creating $ac_file" >&5 +echo "$as_me: creating $ac_file" >&6;} + fi + + case $ac_tag in + *:-:* | *:-) cat >"$tmp/stdin";; + esac + ;; + esac + + ac_dir=`$as_dirname -- "$ac_file" || +$as_expr X"$ac_file" : 'X\(.*[^/]\)//*[^/][^/]*/*$' \| \ + X"$ac_file" : 'X\(//\)[^/]' \| \ + X"$ac_file" : 'X\(//\)$' \| \ + X"$ac_file" : 'X\(/\)' \| . 2>/dev/null || +echo X"$ac_file" | + sed '/^X\(.*[^/]\)\/\/*[^/][^/]*\/*$/{ + s//\1/ + q + } + /^X\(\/\/\)[^/].*/{ + s//\1/ + q + } + /^X\(\/\/\)$/{ + s//\1/ + q + } + /^X\(\/\).*/{ + s//\1/ + q + } + s/.*/./; q'` + { as_dir="$ac_dir" + case $as_dir in #( + -*) as_dir=./$as_dir;; + esac + test -d "$as_dir" || { $as_mkdir_p && mkdir -p "$as_dir"; } || { + as_dirs= + while :; do + case $as_dir in #( + *\'*) as_qdir=`echo "$as_dir" | sed "s/'/'\\\\\\\\''/g"`;; #( + *) as_qdir=$as_dir;; + esac + as_dirs="'$as_qdir' $as_dirs" + as_dir=`$as_dirname -- "$as_dir" || +$as_expr X"$as_dir" : 'X\(.*[^/]\)//*[^/][^/]*/*$' \| \ + X"$as_dir" : 'X\(//\)[^/]' \| \ + X"$as_dir" : 'X\(//\)$' \| \ + X"$as_dir" : 'X\(/\)' \| . 2>/dev/null || +echo X"$as_dir" | + sed '/^X\(.*[^/]\)\/\/*[^/][^/]*\/*$/{ + s//\1/ + q + } + /^X\(\/\/\)[^/].*/{ + s//\1/ + q + } + /^X\(\/\/\)$/{ + s//\1/ + q + } + /^X\(\/\).*/{ + s//\1/ + q + } + s/.*/./; q'` + test -d "$as_dir" && break + done + test -z "$as_dirs" || eval "mkdir $as_dirs" + } || test -d "$as_dir" || { { echo "$as_me:$LINENO: error: cannot create directory $as_dir" >&5 +echo "$as_me: error: cannot create directory $as_dir" >&2;} + { (exit 1); exit 1; }; }; } + ac_builddir=. + +case "$ac_dir" in +.) ac_dir_suffix= ac_top_builddir_sub=. ac_top_build_prefix= ;; +*) + ac_dir_suffix=/`echo "$ac_dir" | sed 's,^\.[\\/],,'` + # A ".." for each directory in $ac_dir_suffix. + ac_top_builddir_sub=`echo "$ac_dir_suffix" | sed 's,/[^\\/]*,/..,g;s,/,,'` + case $ac_top_builddir_sub in + "") ac_top_builddir_sub=. ac_top_build_prefix= ;; + *) ac_top_build_prefix=$ac_top_builddir_sub/ ;; + esac ;; +esac +ac_abs_top_builddir=$ac_pwd +ac_abs_builddir=$ac_pwd$ac_dir_suffix +# for backward compatibility: +ac_top_builddir=$ac_top_build_prefix + +case $srcdir in + .) # We are building in place. + ac_srcdir=. + ac_top_srcdir=$ac_top_builddir_sub + ac_abs_top_srcdir=$ac_pwd ;; + [\\/]* | ?:[\\/]* ) # Absolute name. + ac_srcdir=$srcdir$ac_dir_suffix; + ac_top_srcdir=$srcdir + ac_abs_top_srcdir=$srcdir ;; + *) # Relative name. + ac_srcdir=$ac_top_build_prefix$srcdir$ac_dir_suffix + ac_top_srcdir=$ac_top_build_prefix$srcdir + ac_abs_top_srcdir=$ac_pwd/$srcdir ;; +esac +ac_abs_srcdir=$ac_abs_top_srcdir$ac_dir_suffix + + + case $ac_mode in + :F) + # + # CONFIG_FILE + # + + case $INSTALL in + [\\/$]* | ?:[\\/]* ) ac_INSTALL=$INSTALL ;; + *) ac_INSTALL=$ac_top_build_prefix$INSTALL ;; + esac +_ACEOF + +cat >>$CONFIG_STATUS <<\_ACEOF +# If the template does not know about datarootdir, expand it. +# FIXME: This hack should be removed a few years after 2.60. +ac_datarootdir_hack=; ac_datarootdir_seen= + +case `sed -n '/datarootdir/ { + p + q +} +/@datadir@/p +/@docdir@/p +/@infodir@/p +/@localedir@/p +/@mandir@/p +' $ac_file_inputs` in +*datarootdir*) ac_datarootdir_seen=yes;; +*@datadir@*|*@docdir@*|*@infodir@*|*@localedir@*|*@mandir@*) + { echo "$as_me:$LINENO: WARNING: $ac_file_inputs seems to ignore the --datarootdir setting" >&5 +echo "$as_me: WARNING: $ac_file_inputs seems to ignore the --datarootdir setting" >&2;} +_ACEOF +cat >>$CONFIG_STATUS <<_ACEOF + ac_datarootdir_hack=' + s&@datadir@&$datadir&g + s&@docdir@&$docdir&g + s&@infodir@&$infodir&g + s&@localedir@&$localedir&g + s&@mandir@&$mandir&g + s&\\\${datarootdir}&$datarootdir&g' ;; +esac +_ACEOF + +# Neutralize VPATH when `$srcdir' = `.'. +# Shell code in configure.ac might set extrasub. +# FIXME: do we really want to maintain this feature? +cat >>$CONFIG_STATUS <<_ACEOF + sed "$ac_vpsub +$extrasub +_ACEOF +cat >>$CONFIG_STATUS <<\_ACEOF +:t +/@[a-zA-Z_][a-zA-Z_0-9]*@/!b +s&@configure_input@&$configure_input&;t t +s&@top_builddir@&$ac_top_builddir_sub&;t t +s&@srcdir@&$ac_srcdir&;t t +s&@abs_srcdir@&$ac_abs_srcdir&;t t +s&@top_srcdir@&$ac_top_srcdir&;t t +s&@abs_top_srcdir@&$ac_abs_top_srcdir&;t t +s&@builddir@&$ac_builddir&;t t +s&@abs_builddir@&$ac_abs_builddir&;t t +s&@abs_top_builddir@&$ac_abs_top_builddir&;t t +s&@INSTALL@&$ac_INSTALL&;t t +$ac_datarootdir_hack +" $ac_file_inputs | sed -f "$tmp/subs-1.sed" >$tmp/out + +test -z "$ac_datarootdir_hack$ac_datarootdir_seen" && + { ac_out=`sed -n '/\${datarootdir}/p' "$tmp/out"`; test -n "$ac_out"; } && + { ac_out=`sed -n '/^[ ]*datarootdir[ ]*:*=/p' "$tmp/out"`; test -z "$ac_out"; } && + { echo "$as_me:$LINENO: WARNING: $ac_file contains a reference to the variable \`datarootdir' +which seems to be undefined. Please make sure it is defined." >&5 +echo "$as_me: WARNING: $ac_file contains a reference to the variable \`datarootdir' +which seems to be undefined. Please make sure it is defined." >&2;} + + rm -f "$tmp/stdin" + case $ac_file in + -) cat "$tmp/out"; rm -f "$tmp/out";; + *) rm -f "$ac_file"; mv "$tmp/out" $ac_file;; + esac + ;; + :H) + # + # CONFIG_HEADER + # +_ACEOF + +# Transform confdefs.h into a sed script `conftest.defines', that +# substitutes the proper values into config.h.in to produce config.h. +rm -f conftest.defines conftest.tail +# First, append a space to every undef/define line, to ease matching. +echo 's/$/ /' >conftest.defines +# Then, protect against being on the right side of a sed subst, or in +# an unquoted here document, in config.status. If some macros were +# called several times there might be several #defines for the same +# symbol, which is useless. But do not sort them, since the last +# AC_DEFINE must be honored. +ac_word_re=[_$as_cr_Letters][_$as_cr_alnum]* +# These sed commands are passed to sed as "A NAME B PARAMS C VALUE D", where +# NAME is the cpp macro being defined, VALUE is the value it is being given. +# PARAMS is the parameter list in the macro definition--in most cases, it's +# just an empty string. +ac_dA='s,^\\([ #]*\\)[^ ]*\\([ ]*' +ac_dB='\\)[ (].*,\\1define\\2' +ac_dC=' ' +ac_dD=' ,' + +uniq confdefs.h | + sed -n ' + t rset + :rset + s/^[ ]*#[ ]*define[ ][ ]*// + t ok + d + :ok + s/[\\&,]/\\&/g + s/^\('"$ac_word_re"'\)\(([^()]*)\)[ ]*\(.*\)/ '"$ac_dA"'\1'"$ac_dB"'\2'"${ac_dC}"'\3'"$ac_dD"'/p + s/^\('"$ac_word_re"'\)[ ]*\(.*\)/'"$ac_dA"'\1'"$ac_dB$ac_dC"'\2'"$ac_dD"'/p + ' >>conftest.defines + +# Remove the space that was appended to ease matching. +# Then replace #undef with comments. This is necessary, for +# example, in the case of _POSIX_SOURCE, which is predefined and required +# on some systems where configure will not decide to define it. +# (The regexp can be short, since the line contains either #define or #undef.) +echo 's/ $// +s,^[ #]*u.*,/* & */,' >>conftest.defines + +# Break up conftest.defines: +ac_max_sed_lines=50 + +# First sed command is: sed -f defines.sed $ac_file_inputs >"$tmp/out1" +# Second one is: sed -f defines.sed "$tmp/out1" >"$tmp/out2" +# Third one will be: sed -f defines.sed "$tmp/out2" >"$tmp/out1" +# et cetera. +ac_in='$ac_file_inputs' +ac_out='"$tmp/out1"' +ac_nxt='"$tmp/out2"' + +while : +do + # Write a here document: + cat >>$CONFIG_STATUS <<_ACEOF + # First, check the format of the line: + cat >"\$tmp/defines.sed" <<\\CEOF +/^[ ]*#[ ]*undef[ ][ ]*$ac_word_re[ ]*\$/b def +/^[ ]*#[ ]*define[ ][ ]*$ac_word_re[( ]/b def +b +:def +_ACEOF + sed ${ac_max_sed_lines}q conftest.defines >>$CONFIG_STATUS + echo 'CEOF + sed -f "$tmp/defines.sed"' "$ac_in >$ac_out" >>$CONFIG_STATUS + ac_in=$ac_out; ac_out=$ac_nxt; ac_nxt=$ac_in + sed 1,${ac_max_sed_lines}d conftest.defines >conftest.tail + grep . conftest.tail >/dev/null || break + rm -f conftest.defines + mv conftest.tail conftest.defines +done +rm -f conftest.defines conftest.tail + +echo "ac_result=$ac_in" >>$CONFIG_STATUS +cat >>$CONFIG_STATUS <<\_ACEOF + if test x"$ac_file" != x-; then + echo "/* $configure_input */" >"$tmp/config.h" + cat "$ac_result" >>"$tmp/config.h" + if diff $ac_file "$tmp/config.h" >/dev/null 2>&1; then + { echo "$as_me:$LINENO: $ac_file is unchanged" >&5 +echo "$as_me: $ac_file is unchanged" >&6;} + else + rm -f $ac_file + mv "$tmp/config.h" $ac_file + fi + else + echo "/* $configure_input */" + cat "$ac_result" + fi + rm -f "$tmp/out12" + ;; + + + esac + +done # for ac_tag + + +{ (exit 0); exit 0; } +_ACEOF +chmod +x $CONFIG_STATUS +ac_clean_files=$ac_clean_files_save + + +# configure is writing to config.log, and then calls config.status. +# config.status does its own redirection, appending to config.log. +# Unfortunately, on DOS this fails, as config.log is still kept open +# by configure, so config.status won't be able to write to it; its +# output is simply discarded. So we exec the FD to /dev/null, +# effectively closing config.log, so it can be properly (re)opened and +# appended to by config.status. When coming back to configure, we +# need to make the FD available again. +if test "$no_create" != yes; then + ac_cs_success=: + ac_config_status_args= + test "$silent" = yes && + ac_config_status_args="$ac_config_status_args --quiet" + exec 5>/dev/null + $SHELL $CONFIG_STATUS $ac_config_status_args || ac_cs_success=false + exec 5>>config.log + # Use ||, not &&, to avoid exiting from the if with $? = 1, which + # would make configure fail if this is the last instruction. + $ac_cs_success || { (exit 1); exit 1; } +fi + diff --git a/CCache/configure.in b/CCache/configure.in new file mode 100644 index 0000000..dfbf86d --- /dev/null +++ b/CCache/configure.in @@ -0,0 +1,87 @@ +dnl Process this file with autoconf to produce a configure script. + +AC_INIT([ccache-swig], [0.0]) # Get version from SWIG in ccache_swig_config.h.in +AC_PREREQ(2.52) +AC_CONFIG_SRCDIR([ccache.h]) + +AC_MSG_NOTICE([Configuring ccache]) + +AC_CONFIG_HEADER(config.h) + +dnl Checks for programs. +AC_PROG_CC +AC_PROG_CPP +AC_PROG_INSTALL +AC_ARG_PROGRAM # for program_transform_name + +AC_DEFINE([_GNU_SOURCE], 1, + [Define _GNU_SOURCE so that we get all necessary prototypes]) + +# If GCC, turn on warnings. +if test "x$GCC" = "xyes" +then + CFLAGS="$CFLAGS -Wall -W" +else + CFLAGS="$CFLAGS -O" +fi + +AC_HEADER_DIRENT +AC_HEADER_TIME +AC_HEADER_SYS_WAIT + +AC_CHECK_HEADERS(ctype.h strings.h stdlib.h string.h pwd.h sys/time.h) + +AC_CHECK_FUNCS(realpath snprintf vsnprintf vasprintf asprintf mkstemp) +AC_CHECK_FUNCS(gethostname getpwuid) +AC_CHECK_FUNCS(utimes) + +AC_CACHE_CHECK([for compar_fn_t in stdlib.h],ccache_cv_COMPAR_FN_T, [ + AC_TRY_COMPILE( +[#include ], +[ +void test_fn(void) { qsort(NULL, 0, 0, (__compar_fn_t)NULL); } +], + ccache_cv_COMPAR_FN_T=yes,ccache_cv_COMPAR_FN_T=no)]) +if test x"$ccache_cv_COMPAR_FN_T" = x"yes"; then + AC_DEFINE(HAVE_COMPAR_FN_T, 1, [ ]) +fi + +dnl Note: This could be replaced by AC_FUNC_SNPRINTF() in the autoconf macro archive +AC_CACHE_CHECK([for C99 vsnprintf],ccache_cv_HAVE_C99_VSNPRINTF,[ +AC_TRY_RUN([ +#include +#include +void foo(const char *format, ...) { + va_list ap; + int len; + char buf[5]; + + va_start(ap, format); + len = vsnprintf(0, 0, format, ap); + va_end(ap); + if (len != 5) exit(1); + + if (snprintf(buf, 3, "hello") != 5 || strcmp(buf, "he") != 0) exit(1); + + exit(0); +} +main() { foo("hello"); } +], +ccache_cv_HAVE_C99_VSNPRINTF=yes,ccache_cv_HAVE_C99_VSNPRINTF=no,ccache_cv_HAVE_C99_VSNPRINTF=cross)]) +if test x"$ccache_cv_HAVE_C99_VSNPRINTF" = x"yes"; then + AC_DEFINE(HAVE_C99_VSNPRINTF, 1, [ ]) +fi + +dnl Check for zlib. +dnl Note: This could be replaced by CHECK_ZLIB() in the autoconf macro archive +AC_ARG_ENABLE([zlib], + AS_HELP_STRING([--enable-zlib], [enable zlib support for ccache compression]),, + [enable_zlib=yes]) + +if test x"$enable_zlib" = x"yes"; then + AC_CHECK_HEADER(zlib.h, AC_CHECK_LIB(z, gzdopen, [LIBS="-lz $LIBS" + AC_DEFINE([ENABLE_ZLIB], 1, [Define to 1 if you would like to have zlib compression for ccache.]) ] )) +fi + +AC_CONFIG_FILES([Makefile]) +AC_OUTPUT diff --git a/CCache/debian/NEWS b/CCache/debian/NEWS new file mode 100644 index 0000000..be245dc --- /dev/null +++ b/CCache/debian/NEWS @@ -0,0 +1,22 @@ +ccache (2.4-8) unstable; urgency=high + + zlib compression is now enabled by default in order to increase the amount + of object files that can fit in the cache. + + The impact on performance is supposed to be almost negligible + (see http://www.gustaebel.de/lars/ccache/). If you do want to disable + it however, simply export the CCACHE_NOCOMPRESS environment variable. + + Note that a zlib-enabled ccache will still read your existing + uncompressed cache. If you want to compress/uncompress your cache, + see the manage-cache.sh script under /usr/share/doc/ccache/examples/. + + -- Francois Marier Sun, 20 May 2007 19:45:07 +1200 + +ccache (2.4-1) unstable; urgency=low + + * This release changes the hash input slighly, so you will probably find + that you will not get any hits against your existing cache when you + upgrade. + + -- Francois Marier Sat, 11 Jun 2005 13:54:33 -0400 diff --git a/CCache/debian/README.Debian b/CCache/debian/README.Debian new file mode 100644 index 0000000..5478bb7 --- /dev/null +++ b/CCache/debian/README.Debian @@ -0,0 +1,59 @@ +Installing ccache +----------------- + +The recommended way to use this with Debian is to either create "cc" +and "gcc" symlinks to /usr/bin/ccache in your private bin directory +(which must be before the real cc and gcc in your path), or use +CC="ccache gcc" on the make command line. + +Another option is to just prepend /usr/lib/ccache in your PATH +environment variable, like + + export PATH="/usr/lib/ccache:$PATH" + +Note that ccache works with both native and cross compilers. + +Ignoring whitespace +------------------- + +If you wish to set up ccache so that it ignores blank lines, have a +look at the CCACHE_UNIFY option. However, please note that this +option is off by default since the reported line numbers may not +match the source files anymore. + + +NFS Issues +---------- + +(from John Coiner on the ccache mailing list) + +When CCache creates a hardlinked output file, it calls utime() to update +the timestamp on the object, so that Make realizes that the object has +changed. + +On NFS, utime() has no coherency guarantee, AFAIK. When utime() runs on +host A, and our parallel implementation of Make is running on host B, +sometimes Make doesn't see the new timestamp soon enough -- and neglects +to relink the final binary. That's a one-way ticket to Silent Mysterious +Failure Town. + +Instead of relying on the object file timestamp, we create a dummy file +with a reliable timestamp: + +objs/foo.o objs/foo.o.built : + if ( ccache gcc -o foo.o -c foo.c ) ; \ + then touch objs/foo.o.built ; \ + else exit 1; \ + fi + +binary : objs/foo.o.built + gcc -o binary objs/foo.o + +NFS does make a coherency guarantee, that if a file is written and +close()d on host A, and subsequently open()ed on host B, that the second +open() will reflect all modifications and attributes from the close(). +Since Make does open() when checking timestamps, and the dummy file is +close()d when it's created, the binary will always relink after the +object is recompiled. + + -- Francois Marier Sun, 20 May 2007 17:35:36 +1200 diff --git a/CCache/debian/changelog b/CCache/debian/changelog new file mode 100644 index 0000000..45500d4 --- /dev/null +++ b/CCache/debian/changelog @@ -0,0 +1,221 @@ +ccache (2.4-15) unstable; urgency=low + + * Add a new patch which improve the consistency of timestamps on cached + objects to make sure clean-up is based on least recently used objects. + * Patch the set_limit call so that non-writable cache directories return + an error when attempting to size the max(files|size) (closes: #332527) + + -- Francois Marier Sun, 13 Apr 2008 15:07:05 +1200 + +ccache (2.4-14) unstable; urgency=low + + * Mention the long options everywhere in the manpage + * Merge Gentoo patches: + - respect user's LDFLAGS + - use utimes() for timestamp if possible + + -- Francois Marier Sun, 23 Mar 2008 16:30:11 +1300 + +ccache (2.4-13) unstable; urgency=low + + * Update CACHEDIR.TAG patch to avoid creating the tag file when the + CCACHE_READONLY environment variable is set. (closes: #464356) + * Mention the GNU-style long options in the manpage + + -- Francois Marier Thu, 07 Feb 2008 10:50:42 +1300 + +ccache (2.4-12) unstable; urgency=low + + * Add symlink for gcc 4.3 (closes: #463590) + * Add support for the CACHEDIR.TAG spec, thanks to Karl Chen. + (see http://www.brynosaurus.com/cachedir/) + * Fix hyphens in manpage (lintian notice) + * Bump Standards-Version up to 3.7.3 (no changes) + * Bump debhelper compatibility to 6 + + -- Francois Marier Sat, 02 Feb 2008 10:37:22 +1300 + +ccache (2.4-11) unstable; urgency=low + + * Add the collab-maint repo to debian/control + + -- Francois Marier Tue, 20 Nov 2007 15:26:37 +1300 + +ccache (2.4-10) unstable; urgency=low + + * Document where the patches are from in debian/patches/CREDITS + * debian/rules: + - Fixed "make distclean" lintian warning + - Removed commented-out entries + * Set debhelper compatibility to 5 + * Add homepage field in debian/control + * Add symlinks for MinGW (closes: #445782) + * Bump the version to 5 in the debhelper dependency + + -- Francois Marier Fri, 19 Oct 2007 16:04:37 +1300 + +ccache (2.4-9) unstable; urgency=low + + * Add a symlink for gcc 4.2 (closes: #431007) + * Fix dependencies when using -o (closes: #217713) + + -- Francois Marier Sat, 30 Jun 2007 17:58:44 +1200 + +ccache (2.4-8) unstable; urgency=low + + * Enable zlib compression of the cache by default (closes: #409848). + Thanks to Sami Liedes for suggesting this. + * Disable ccache when profiling (closes: #215849). + Thanks to Ted Percival for the Patch. + * Fix NFS renaming issues and add instructions to the README. + Thanks to John Coiner and instructions. + * Put all patches in debian/patches and apply them at build time. + + -- Francois Marier Sun, 20 May 2007 19:42:34 +1200 + +ccache (2.4-7) unstable; urgency=low + + * Use the real compiler when HOME is not set (closes: #396350) + * Include user script under doc/examples (closes: #392435) + Thanks to Behan Webster! + * Add support for GNU --long options (closes: #297126) + + -- Francois Marier Sat, 18 Nov 2006 00:50:59 -0500 + +ccache (2.4-6) unstable; urgency=low + + * Include symlinks for gcc 4.1 (closes: #372838) + * Update watch file + + -- Francois Marier Tue, 13 Jun 2006 22:17:37 -0400 + +ccache (2.4-5) unstable; urgency=low + + * Document the fact that cross-compiling is supported (closes: #349221) + * Bump Standards-Version up to 3.7.2 (no changes) + + -- Francois Marier Sun, 4 Jun 2006 01:20:07 -0400 + +ccache (2.4-4) unstable; urgency=low + + * Mention another way to use ccache in README.Debian (thanks to Benjamin + Drieu for the suggestion) (closes: #267632) + * Update FSF address + * Fix watch file + + -- Francois Marier Sat, 26 Nov 2005 00:15:13 -0500 + +ccache (2.4-3) unstable; urgency=low + + * Actually use the configuration flags in debian/rules + * Bump Standards-Version up to 3.6.2 (no changes) + + -- Francois Marier Sun, 26 Jun 2005 13:33:19 -0400 + +ccache (2.4-2) unstable; urgency=low + + * Add gcc and g++ symlinks to /usr/lib/ccache (closes: #313490) + * Remove invalid entry from Depends + + -- Francois Marier Wed, 15 Jun 2005 20:51:03 -0400 + +ccache (2.4-1) unstable; urgency=low + + * New maintainer (closes: #312867) + * New upstream version: (closes: #273753, #239640) + - New CCACHE_READONLY and CCACHE_TEMPDIR options + - Fixed handling of hard-linked compilers on AIX + - Fixed handling of HOME environment variable (closes: #299880) + - Show cache directory in stats output + * Fix copyright file + * Add 'distcc' to Suggests (closes: #269158) + * Add a note about whitespace in README.Debian (closes: #229116) + * Update rules to add symmlinks for gcc 3.4 & 4.0 (closes: #261177) + * Acknowledge NMUs (closes: #200185, #177129, #174417) + + -- Francois Marier Sun, 12 Jun 2005 12:05:34 -0400 + +ccache (2.3-1.1) unstable; urgency=low + + * Non-maintainer upload during BSP + * Re-apply patch for + #200185 ccache: Incorrect symlinks in /usr/lib/ccache + (Closes: #200185) + + -- Frank Lichtenheld Fri, 19 Mar 2004 11:14:50 +0100 + +ccache (2.3-1) unstable; urgency=low + + * New upstream release: obsoletes existing caches. + * Tweak package description in arbitrary way (closes: #181721) + + -- Paul Russell Mon, 29 Sep 2003 02:53:20 +0200 + +ccache (2.2-2) unstable; urgency=low + + * Insert more symlinks in ccache dir (closes: #197468) + + -- Paul Russell Mon, 16 Jun 2003 10:52:50 +0100 + +ccache (2.2-1) unstable; urgency=low + + * New upstream release (closes: #150755) + * Insert more symlinks in ccache dir (closes: #144462) + + -- Paul Russell Mon, 17 Feb 2003 07:19:36 +0100 + +ccache (2.1.1-2) unstable; urgency=low + + * Restored /usr/lib/ccache symlinks (closes: #179393) + * Fixed manpage typo (closes: #179564) + * With thanks to Andreas Rottmann. + + -- Paul Russell Wed, 5 Feb 2003 10:01:10 +0100 + +ccache (2.1.1-1) unstable; urgency=low + + * NMU (with maintainer consent). + * New upstream release (closes: #174417, #177129). + * debian/control: + + Build-Depend on and use dephelper 4 (DH_COMPAT = 4). + + Bumped Standards-Version to 3.5.8. + + No full stop on short package description (fixes linda warning). + * debian/copright: + + Make lintian feel comfortable; fixes warnings: + - copyright-should-refer-to-common-license-file-for-gpl + - copyright-lists-upstream-authors-with-dh_make-boilerplate + * Built with g++ 3.2 :-). + + -- Andreas Rottmann Thu, 16 Jan 2003 11:42:38 +0100 + +ccache (1.9-1) unstable; urgency=low + + * New upstream release (closes: #144920) + + -- Paul Russell Mon, 13 May 2002 10:01:09 +0200 + +ccache (1.8-1) unstable; urgency=low + + * New upstream release (closes: #145401) + + -- Paul Russell Fri, 3 May 2002 02:26:32 +0200 + +ccache (1.7-1) unstable; urgency=low + + * New upstream release + * Install symlinks in /usr/lib/ccache (closes: #141337) + + -- Paul Russell Wed, 10 Apr 2002 17:51:21 +0200 + +ccache (1.4-1) unstable; urgency=low + + * New upstream release + + -- Paul Russell Wed, 3 Apr 2002 03:41:46 +0200 + +ccache (1.2-1) unstable; urgency=low + + * Initial Release. + + -- Paul Russell Sun, 31 Mar 2002 14:08:57 +0200 + diff --git a/CCache/debian/compat b/CCache/debian/compat new file mode 100644 index 0000000..1e8b314 --- /dev/null +++ b/CCache/debian/compat @@ -0,0 +1 @@ +6 diff --git a/CCache/debian/control b/CCache/debian/control new file mode 100644 index 0000000..0b7e572 --- /dev/null +++ b/CCache/debian/control @@ -0,0 +1,20 @@ +Source: ccache +Section: devel +Priority: optional +Maintainer: Francois Marier +Build-Depends: debhelper (>> 6), autotools-dev, zlib1g-dev +Standards-Version: 3.7.3 +Homepage: http://ccache.samba.org +Vcs-Svn: svn://svn.debian.org/svn/collab-maint/deb-maint/ccache/ +Vcs-Browser: http://svn.debian.org/wsvn/collab-maint/deb-maint/ccache/ + +Package: ccache +Architecture: any +Depends: ${shlibs:Depends} +Suggests: distcc +Description: Compiler results cacher, for fast recompiles + ccache is a compiler cache. It speeds up re-compilation of C/C++ code + by caching previous compiles and detecting when the same compile is + being done again. + . + This is similar to, but faster than, the compilercache package. diff --git a/CCache/debian/copyright b/CCache/debian/copyright new file mode 100644 index 0000000..7ac791d --- /dev/null +++ b/CCache/debian/copyright @@ -0,0 +1,29 @@ +This package was debianized by Paul Russell on +Sun, 31 Mar 2002 14:08:57 +0200. + +It was downloaded from http://ccache.samba.org/ftp/ccache/ + +The ccache-zlib patch was downloaded from http://www.gustaebel.de/lars/ccache/ + +Upstream Author: Andrew Tridgell + +Copyright: 2002-2005 Andrew Tridgell + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA + +You are free to distribute this software under the terms of the GNU General +Public License. On Debian systems, the complete text of the GNU General +Public License can be found in /usr/share/common-licenses/GPL file. diff --git a/CCache/debian/dirs b/CCache/debian/dirs new file mode 100644 index 0000000..8ceb4c4 --- /dev/null +++ b/CCache/debian/dirs @@ -0,0 +1,3 @@ +usr/bin +usr/lib/ccache +usr/share/man/man1 diff --git a/CCache/debian/docs b/CCache/debian/docs new file mode 100644 index 0000000..e845566 --- /dev/null +++ b/CCache/debian/docs @@ -0,0 +1 @@ +README diff --git a/CCache/debian/examples b/CCache/debian/examples new file mode 100644 index 0000000..fc54922 --- /dev/null +++ b/CCache/debian/examples @@ -0,0 +1,2 @@ +debian/update-ccache +manage-cache.sh diff --git a/CCache/debian/patches/01_no_home.diff b/CCache/debian/patches/01_no_home.diff new file mode 100644 index 0000000..019634c --- /dev/null +++ b/CCache/debian/patches/01_no_home.diff @@ -0,0 +1,100 @@ +--- ccache.c ++++ ccache.c +@@ -836,6 +836,13 @@ + { + /* find the real compiler */ + find_compiler(argc, argv); ++ ++ /* use the real compiler if HOME is not set */ ++ if (!cache_dir) { ++ cc_log("Unable to determine home directory\n"); ++ cc_log("ccache is disabled\n"); ++ failed(); ++ } + + /* we might be disabled */ + if (getenv("CCACHE_DISABLE")) { +@@ -895,6 +902,13 @@ + printf("-V print version number\n"); + } + ++static void check_cache_dir(void) ++{ ++ if (!cache_dir) { ++ fatal("Unable to determine home directory"); ++ } ++} ++ + /* the main program when not doing a compile */ + static int ccache_main(int argc, char *argv[]) + { +@@ -914,31 +928,37 @@ + exit(0); + + case 's': ++ check_cache_dir(); + stats_summary(); + break; + + case 'c': ++ check_cache_dir(); + cleanup_all(cache_dir); + printf("Cleaned cache\n"); + break; + + case 'C': ++ check_cache_dir(); + wipe_all(cache_dir); + printf("Cleared cache\n"); + break; + + case 'z': ++ check_cache_dir(); + stats_zero(); + printf("Statistics cleared\n"); + break; + + case 'F': ++ check_cache_dir(); + v = atoi(optarg); + stats_set_limits(v, -1); + printf("Set cache file limit to %u\n", (unsigned)v); + break; + + case 'M': ++ check_cache_dir(); + v = value_units(optarg); + stats_set_limits(-1, v); + printf("Set cache size limit to %uk\n", (unsigned)v); +@@ -983,7 +1003,10 @@ + + cache_dir = getenv("CCACHE_DIR"); + if (!cache_dir) { +- x_asprintf(&cache_dir, "%s/.ccache", get_home_directory()); ++ const char *home_directory = get_home_directory(); ++ if (home_directory) { ++ x_asprintf(&cache_dir, "%s/.ccache", home_directory); ++ } + } + + temp_dir = getenv("CCACHE_TEMPDIR"); +@@ -1023,7 +1046,7 @@ + } + + /* make sure the cache dir exists */ +- if (create_dir(cache_dir) != 0) { ++ if (cache_dir && (create_dir(cache_dir) != 0)) { + fprintf(stderr,"ccache: failed to create %s (%s)\n", + cache_dir, strerror(errno)); + exit(1); +--- util.c ++++ util.c +@@ -448,7 +448,7 @@ + } + } + #endif +- fatal("Unable to determine home directory"); ++ cc_log("Unable to determine home directory"); + return NULL; + } + diff --git a/CCache/debian/patches/02_ccache-compressed.diff b/CCache/debian/patches/02_ccache-compressed.diff new file mode 100644 index 0000000..5740c2c --- /dev/null +++ b/CCache/debian/patches/02_ccache-compressed.diff @@ -0,0 +1,1026 @@ +Index: ccache.1 +=================================================================== +RCS file: /home/cvsroot/lars/ccache/ccache.1,v +retrieving revision 1.1.1.1.2.1 +retrieving revision 1.6 +diff -u -r1.1.1.1.2.1 -r1.6 +--- ccache.1 21 Nov 2004 17:55:36 -0000 1.1.1.1.2.1 ++++ ccache.1 21 Nov 2004 18:19:28 -0000 1.6 +@@ -210,7 +210,8 @@ + CCACHE_HARDLINK then ccache will attempt to use hard links from the + cache directory when creating the compiler output rather than using a + file copy\&. Using hard links is faster, but can confuse programs like +-\&'make\&' that rely on modification times\&. ++\&'make\&' that rely on modification times\&. Hard links are never made for ++compressed cache files\&. + .IP + .IP "\fBCCACHE_RECACHE\fP" + This forces ccache to not use any cached +@@ -257,6 +258,11 @@ + the default\&. On HP-UX set this environment variable to "i" if you use + the aCC compiler\&. + .IP ++.IP "\fBCCACHE_NOCOMPRESS\fP" ++If you set the environment variable ++CCACHE_NOCOMPRESS then there is no compression used on files that go ++into the cache\&. ++.IP + .PP + .SH "CACHE SIZE MANAGEMENT" + .PP +@@ -269,6 +275,14 @@ + below the numbers you specified in order to avoid doing the cache + clean operation too often\&. + .PP ++.SH "CACHE COMPRESSION" ++.PP ++By default ccache will compress all files it puts into the cache ++using the zlib compression\&. While this involves a negligible ++performance slowdown, it significantly increases the number of files ++that fit in the cache\&. You can turn off compression setting the ++CCACHE_NOCOMPRESS environment variable\&. ++.PP + .SH "HOW IT WORKS" + .PP + The basic idea is to detect when you are compiling exactly the same +Index: ccache.c +=================================================================== +RCS file: /home/cvsroot/lars/ccache/ccache.c,v +retrieving revision 1.1.1.1.2.1 +retrieving revision 1.9 +diff -u -r1.1.1.1.2.1 -r1.9 +--- ccache.c 21 Nov 2004 17:55:36 -0000 1.1.1.1.2.1 ++++ ccache.c 21 Nov 2004 18:19:28 -0000 1.9 +@@ -199,7 +199,7 @@ + fd = open(tmp_stderr, O_RDONLY | O_BINARY); + if (fd != -1) { + if (strcmp(output_file, "/dev/null") == 0 || +- rename(tmp_hashname, output_file) == 0 || errno == ENOENT) { ++ move_file(tmp_hashname, output_file) == 0 || errno == ENOENT) { + if (cpp_stderr) { + /* we might have some stderr from cpp */ + int fd2 = open(cpp_stderr, O_RDONLY | O_BINARY); +@@ -231,14 +231,25 @@ + x_asprintf(&path_stderr, "%s.stderr", hashname); + + if (stat(tmp_stderr, &st1) != 0 || +- stat(tmp_hashname, &st2) != 0 || +- rename(tmp_hashname, hashname) != 0 || +- rename(tmp_stderr, path_stderr) != 0) { ++ stat(tmp_hashname, &st2) != 0 || ++ move_file(tmp_hashname, hashname) != 0 || ++ move_file(tmp_stderr, path_stderr) != 0) { + cc_log("failed to rename tmp files - %s\n", strerror(errno)); + stats_update(STATS_ERROR); + failed(); + } + ++#if ENABLE_ZLIB ++ /* do an extra stat on the cache files for ++ the size statistics */ ++ if (stat(path_stderr, &st1) != 0 || ++ stat(hashname, &st2) != 0) { ++ cc_log("failed to stat cache files - %s\n", strerror(errno)); ++ stats_update(STATS_ERROR); ++ failed(); ++ } ++#endif ++ + cc_log("Placed %s into cache\n", output_file); + stats_tocache(file_size(&st1) + file_size(&st2)); + +@@ -474,7 +485,13 @@ + } + + /* the user might be disabling cache hits */ ++#ifndef ENABLE_ZLIB ++ /* if the cache file is compressed we must recache */ ++ if ((first && getenv("CCACHE_RECACHE")) || ++ test_if_compressed(hashname) == 1) { ++#else + if (first && getenv("CCACHE_RECACHE")) { ++#endif + close(fd_stderr); + unlink(stderr_file); + free(stderr_file); +@@ -487,7 +504,9 @@ + ret = 0; + } else { + unlink(output_file); +- if (getenv("CCACHE_HARDLINK")) { ++ /* only make a hardlink if the cache file is uncompressed */ ++ if (getenv("CCACHE_HARDLINK") && ++ test_if_compressed(hashname) == 0) { + ret = link(hashname, output_file); + } else { + ret = copy_file(hashname, output_file); +Index: ccache.h +=================================================================== +RCS file: /home/cvsroot/lars/ccache/ccache.h,v +retrieving revision 1.1.1.1.2.1 +retrieving revision 1.7 +diff -u -r1.1.1.1.2.1 -r1.7 +--- ccache.h 21 Nov 2004 17:55:36 -0000 1.1.1.1.2.1 ++++ ccache.h 21 Nov 2004 18:19:28 -0000 1.7 +@@ -23,6 +23,10 @@ + #include + #endif + ++#ifdef ENABLE_ZLIB ++#include ++#endif ++ + #define STATUS_NOTFOUND 3 + #define STATUS_FATAL 4 + #define STATUS_NOCACHE 5 +@@ -36,6 +40,13 @@ + #define DEFAULT_MAXSIZE (1000*1000) + #endif + ++/* file copy mode */ ++#ifdef ENABLE_ZLIB ++#define COPY_UNCOMPRESSED 0 ++#define COPY_FROM_CACHE 1 ++#define COPY_TO_CACHE 2 ++#endif ++ + enum stats { + STATS_NONE=0, + STATS_STDOUT, +@@ -79,6 +90,8 @@ + + void copy_fd(int fd_in, int fd_out); + int copy_file(const char *src, const char *dest); ++int move_file(const char *src, const char *dest); ++int test_if_compressed(const char *filename); + + int create_dir(const char *dir); + void x_asprintf(char **ptr, const char *format, ...); +Index: ccache.yo +=================================================================== +RCS file: /home/cvsroot/lars/ccache/ccache.yo,v +retrieving revision 1.1.1.1.2.1 +retrieving revision 1.5 +diff -u -r1.1.1.1.2.1 -r1.5 +--- ccache.yo 21 Nov 2004 17:55:36 -0000 1.1.1.1.2.1 ++++ ccache.yo 21 Nov 2004 18:19:28 -0000 1.5 +@@ -169,6 +169,11 @@ + this optimisation, in which case this option could allow ccache to be + used. + ++dit(bf(CCACHE_NOCOMPRESS)) If you set the environment variable ++CCACHE_NOCOMPRESS then there is no compression used on files that go ++into the cache. However, this setting has no effect on how files are ++retrieved from the cache, compressed results will still be usable. ++ + dit(bf(CCACHE_NOSTATS)) If you set the environment variable + CCACHE_NOSTATS then ccache will not update the statistics files on + each compile. +@@ -181,7 +186,8 @@ + CCACHE_HARDLINK then ccache will attempt to use hard links from the + cache directory when creating the compiler output rather than using a + file copy. Using hard links is faster, but can confuse programs like +-'make' that rely on modification times. ++'make' that rely on modification times. Hard links are never made for ++compressed cache files. + + dit(bf(CCACHE_RECACHE)) This forces ccache to not use any cached + results, even if it finds them. New results are still cached, but +@@ -236,6 +242,14 @@ + below the numbers you specified in order to avoid doing the cache + clean operation too often. + ++manpagesection(CACHE COMPRESSION) ++ ++By default ccache will compress all files it puts into the cache ++using the zlib compression. While this involves a negligible ++performance slowdown, it significantly increases the number of files ++that fit in the cache. You can turn off compression setting the ++CCACHE_NOCOMPRESS environment variable. ++ + manpagesection(HOW IT WORKS) + + The basic idea is to detect when you are compiling exactly the same +@@ -294,6 +308,8 @@ + cache. This tells the filesystem to inherit group ownership for new + directories. The command "chmod g+s `find $CCACHE_DIR -type d`" might + be useful for this. ++ it() Set bf(CCACHE_NOCOMPRESS) for all users, if there are users with ++ versions of ccache that do not support compression. + ) + + manpagesection(HISTORY) +Index: config.h.in +=================================================================== +RCS file: /home/cvsroot/lars/ccache/config.h.in,v +retrieving revision 1.1.1.1 +retrieving revision 1.2 +diff -u -r1.1.1.1 -r1.2 +--- config.h.in 30 Apr 2004 13:13:41 -0000 1.1.1.1 ++++ config.h.in 4 May 2004 20:49:26 -0000 1.2 +@@ -98,3 +98,6 @@ + + /* Define _GNU_SOURCE so that we get all necessary prototypes */ + #undef _GNU_SOURCE ++ ++/* Define to 1 if you like to have zlib compression for the ccache. */ ++#undef ENABLE_ZLIB +Index: configure +=================================================================== +RCS file: /home/cvsroot/lars/ccache/configure,v +retrieving revision 1.1.1.1.2.1 +diff -u -r1.1.1.1.2.1 configure +--- configure 21 Nov 2004 17:55:36 -0000 1.1.1.1.2.1 ++++ configure 21 Nov 2004 18:24:42 -0000 +@@ -836,6 +836,11 @@ + + cat <<\_ACEOF + ++Optional Features: ++ --disable-FEATURE do not include FEATURE (same as --enable-FEATURE=no) ++ --enable-FEATURE[=ARG] include FEATURE [ARG=yes] ++ --enable-zlib enable zlib support for ccache compression ++ + Some influential environment variables: + CC C compiler command + CFLAGS C compiler flags +@@ -936,7 +941,7 @@ + else + echo "$as_me: WARNING: no configuration information is in $ac_dir" >&2 + fi +- cd "$ac_popdir" ++ cd $ac_popdir + done + fi + +@@ -1859,7 +1864,8 @@ + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && +- { ac_try='test -z "$ac_c_werror_flag" || test ! -s conftest.err' ++ { ac_try='test -z "$ac_c_werror_flag" ++ || test ! -s conftest.err' + { (eval echo "$as_me:$LINENO: \"$ac_try\"") >&5 + (eval $ac_try) 2>&5 + ac_status=$? +@@ -1917,7 +1923,8 @@ + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && +- { ac_try='test -z "$ac_c_werror_flag" || test ! -s conftest.err' ++ { ac_try='test -z "$ac_c_werror_flag" ++ || test ! -s conftest.err' + { (eval echo "$as_me:$LINENO: \"$ac_try\"") >&5 + (eval $ac_try) 2>&5 + ac_status=$? +@@ -2033,7 +2040,8 @@ + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && +- { ac_try='test -z "$ac_c_werror_flag" || test ! -s conftest.err' ++ { ac_try='test -z "$ac_c_werror_flag" ++ || test ! -s conftest.err' + { (eval echo "$as_me:$LINENO: \"$ac_try\"") >&5 + (eval $ac_try) 2>&5 + ac_status=$? +@@ -2087,7 +2095,8 @@ + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && +- { ac_try='test -z "$ac_c_werror_flag" || test ! -s conftest.err' ++ { ac_try='test -z "$ac_c_werror_flag" ++ || test ! -s conftest.err' + { (eval echo "$as_me:$LINENO: \"$ac_try\"") >&5 + (eval $ac_try) 2>&5 + ac_status=$? +@@ -2132,7 +2141,8 @@ + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && +- { ac_try='test -z "$ac_c_werror_flag" || test ! -s conftest.err' ++ { ac_try='test -z "$ac_c_werror_flag" ++ || test ! -s conftest.err' + { (eval echo "$as_me:$LINENO: \"$ac_try\"") >&5 + (eval $ac_try) 2>&5 + ac_status=$? +@@ -2176,7 +2186,8 @@ + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && +- { ac_try='test -z "$ac_c_werror_flag" || test ! -s conftest.err' ++ { ac_try='test -z "$ac_c_werror_flag" ++ || test ! -s conftest.err' + { (eval echo "$as_me:$LINENO: \"$ac_try\"") >&5 + (eval $ac_try) 2>&5 + ac_status=$? +@@ -2609,7 +2620,8 @@ + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && +- { ac_try='test -z "$ac_c_werror_flag" || test ! -s conftest.err' ++ { ac_try='test -z "$ac_c_werror_flag" ++ || test ! -s conftest.err' + { (eval echo "$as_me:$LINENO: \"$ac_try\"") >&5 + (eval $ac_try) 2>&5 + ac_status=$? +@@ -2681,7 +2693,8 @@ + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && +- { ac_try='test -z "$ac_c_werror_flag" || test ! -s conftest.err' ++ { ac_try='test -z "$ac_c_werror_flag" ++ || test ! -s conftest.err' + { (eval echo "$as_me:$LINENO: \"$ac_try\"") >&5 + (eval $ac_try) 2>&5 + ac_status=$? +@@ -2735,7 +2748,8 @@ + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && +- { ac_try='test -z "$ac_c_werror_flag" || test ! -s conftest.err' ++ { ac_try='test -z "$ac_c_werror_flag" ++ || test ! -s conftest.err' + { (eval echo "$as_me:$LINENO: \"$ac_try\"") >&5 + (eval $ac_try) 2>&5 + ac_status=$? +@@ -2806,7 +2820,8 @@ + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && +- { ac_try='test -z "$ac_c_werror_flag" || test ! -s conftest.err' ++ { ac_try='test -z "$ac_c_werror_flag" ++ || test ! -s conftest.err' + { (eval echo "$as_me:$LINENO: \"$ac_try\"") >&5 + (eval $ac_try) 2>&5 + ac_status=$? +@@ -2860,7 +2875,8 @@ + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && +- { ac_try='test -z "$ac_c_werror_flag" || test ! -s conftest.err' ++ { ac_try='test -z "$ac_c_werror_flag" ++ || test ! -s conftest.err' + { (eval echo "$as_me:$LINENO: \"$ac_try\"") >&5 + (eval $ac_try) 2>&5 + ac_status=$? +@@ -2927,7 +2943,8 @@ + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && +- { ac_try='test -z "$ac_c_werror_flag" || test ! -s conftest.err' ++ { ac_try='test -z "$ac_c_werror_flag" ++ || test ! -s conftest.err' + { (eval echo "$as_me:$LINENO: \"$ac_try\"") >&5 + (eval $ac_try) 2>&5 + ac_status=$? +@@ -2997,7 +3014,8 @@ + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && +- { ac_try='test -z "$ac_c_werror_flag" || test ! -s conftest.err' ++ { ac_try='test -z "$ac_c_werror_flag" ++ || test ! -s conftest.err' + { (eval echo "$as_me:$LINENO: \"$ac_try\"") >&5 + (eval $ac_try) 2>&5 + ac_status=$? +@@ -3078,7 +3096,8 @@ + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && +- { ac_try='test -z "$ac_c_werror_flag" || test ! -s conftest.err' ++ { ac_try='test -z "$ac_c_werror_flag" ++ || test ! -s conftest.err' + { (eval echo "$as_me:$LINENO: \"$ac_try\"") >&5 + (eval $ac_try) 2>&5 + ac_status=$? +@@ -3248,7 +3267,8 @@ + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && +- { ac_try='test -z "$ac_c_werror_flag" || test ! -s conftest.err' ++ { ac_try='test -z "$ac_c_werror_flag" ++ || test ! -s conftest.err' + { (eval echo "$as_me:$LINENO: \"$ac_try\"") >&5 + (eval $ac_try) 2>&5 + ac_status=$? +@@ -3319,7 +3339,8 @@ + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && +- { ac_try='test -z "$ac_c_werror_flag" || test ! -s conftest.err' ++ { ac_try='test -z "$ac_c_werror_flag" ++ || test ! -s conftest.err' + { (eval echo "$as_me:$LINENO: \"$ac_try\"") >&5 + (eval $ac_try) 2>&5 + ac_status=$? +@@ -3509,7 +3530,8 @@ + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && +- { ac_try='test -z "$ac_c_werror_flag" || test ! -s conftest.err' ++ { ac_try='test -z "$ac_c_werror_flag" ++ || test ! -s conftest.err' + { (eval echo "$as_me:$LINENO: \"$ac_try\"") >&5 + (eval $ac_try) 2>&5 + ac_status=$? +@@ -3611,7 +3633,8 @@ + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && +- { ac_try='test -z "$ac_c_werror_flag" || test ! -s conftest.err' ++ { ac_try='test -z "$ac_c_werror_flag" ++ || test ! -s conftest.err' + { (eval echo "$as_me:$LINENO: \"$ac_try\"") >&5 + (eval $ac_try) 2>&5 + ac_status=$? +@@ -3676,7 +3699,8 @@ + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && +- { ac_try='test -z "$ac_c_werror_flag" || test ! -s conftest.err' ++ { ac_try='test -z "$ac_c_werror_flag" ++ || test ! -s conftest.err' + { (eval echo "$as_me:$LINENO: \"$ac_try\"") >&5 + (eval $ac_try) 2>&5 + ac_status=$? +@@ -3775,6 +3799,229 @@ + + fi + ++# Check whether --enable-zlib or --disable-zlib was given. ++if test "${enable_zlib+set}" = set; then ++ enableval="$enable_zlib" ++ ++else ++ enable_zlib=yes ++fi; ++ ++if test x"$enable_zlib" = x"yes"; then ++ if test "${ac_cv_header_zlib_h+set}" = set; then ++ echo "$as_me:$LINENO: checking for zlib.h" >&5 ++echo $ECHO_N "checking for zlib.h... $ECHO_C" >&6 ++if test "${ac_cv_header_zlib_h+set}" = set; then ++ echo $ECHO_N "(cached) $ECHO_C" >&6 ++fi ++echo "$as_me:$LINENO: result: $ac_cv_header_zlib_h" >&5 ++echo "${ECHO_T}$ac_cv_header_zlib_h" >&6 ++else ++ # Is the header compilable? ++echo "$as_me:$LINENO: checking zlib.h usability" >&5 ++echo $ECHO_N "checking zlib.h usability... $ECHO_C" >&6 ++cat >conftest.$ac_ext <<_ACEOF ++/* confdefs.h. */ ++_ACEOF ++cat confdefs.h >>conftest.$ac_ext ++cat >>conftest.$ac_ext <<_ACEOF ++/* end confdefs.h. */ ++$ac_includes_default ++#include ++_ACEOF ++rm -f conftest.$ac_objext ++if { (eval echo "$as_me:$LINENO: \"$ac_compile\"") >&5 ++ (eval $ac_compile) 2>conftest.er1 ++ ac_status=$? ++ grep -v '^ *+' conftest.er1 >conftest.err ++ rm -f conftest.er1 ++ cat conftest.err >&5 ++ echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ (exit $ac_status); } && ++ { ac_try='test -z "$ac_c_werror_flag" ++ || test ! -s conftest.err' ++ { (eval echo "$as_me:$LINENO: \"$ac_try\"") >&5 ++ (eval $ac_try) 2>&5 ++ ac_status=$? ++ echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ (exit $ac_status); }; } && ++ { ac_try='test -s conftest.$ac_objext' ++ { (eval echo "$as_me:$LINENO: \"$ac_try\"") >&5 ++ (eval $ac_try) 2>&5 ++ ac_status=$? ++ echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ (exit $ac_status); }; }; then ++ ac_header_compiler=yes ++else ++ echo "$as_me: failed program was:" >&5 ++sed 's/^/| /' conftest.$ac_ext >&5 ++ ++ac_header_compiler=no ++fi ++rm -f conftest.err conftest.$ac_objext conftest.$ac_ext ++echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++echo "${ECHO_T}$ac_header_compiler" >&6 ++ ++# Is the header present? ++echo "$as_me:$LINENO: checking zlib.h presence" >&5 ++echo $ECHO_N "checking zlib.h presence... $ECHO_C" >&6 ++cat >conftest.$ac_ext <<_ACEOF ++/* confdefs.h. */ ++_ACEOF ++cat confdefs.h >>conftest.$ac_ext ++cat >>conftest.$ac_ext <<_ACEOF ++/* end confdefs.h. */ ++#include ++_ACEOF ++if { (eval echo "$as_me:$LINENO: \"$ac_cpp conftest.$ac_ext\"") >&5 ++ (eval $ac_cpp conftest.$ac_ext) 2>conftest.er1 ++ ac_status=$? ++ grep -v '^ *+' conftest.er1 >conftest.err ++ rm -f conftest.er1 ++ cat conftest.err >&5 ++ echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ (exit $ac_status); } >/dev/null; then ++ if test -s conftest.err; then ++ ac_cpp_err=$ac_c_preproc_warn_flag ++ ac_cpp_err=$ac_cpp_err$ac_c_werror_flag ++ else ++ ac_cpp_err= ++ fi ++else ++ ac_cpp_err=yes ++fi ++if test -z "$ac_cpp_err"; then ++ ac_header_preproc=yes ++else ++ echo "$as_me: failed program was:" >&5 ++sed 's/^/| /' conftest.$ac_ext >&5 ++ ++ ac_header_preproc=no ++fi ++rm -f conftest.err conftest.$ac_ext ++echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++echo "${ECHO_T}$ac_header_preproc" >&6 ++ ++# So? What about this header? ++case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in ++ yes:no: ) ++ { echo "$as_me:$LINENO: WARNING: zlib.h: accepted by the compiler, rejected by the preprocessor!" >&5 ++echo "$as_me: WARNING: zlib.h: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { echo "$as_me:$LINENO: WARNING: zlib.h: proceeding with the compiler's result" >&5 ++echo "$as_me: WARNING: zlib.h: proceeding with the compiler's result" >&2;} ++ ac_header_preproc=yes ++ ;; ++ no:yes:* ) ++ { echo "$as_me:$LINENO: WARNING: zlib.h: present but cannot be compiled" >&5 ++echo "$as_me: WARNING: zlib.h: present but cannot be compiled" >&2;} ++ { echo "$as_me:$LINENO: WARNING: zlib.h: check for missing prerequisite headers?" >&5 ++echo "$as_me: WARNING: zlib.h: check for missing prerequisite headers?" >&2;} ++ { echo "$as_me:$LINENO: WARNING: zlib.h: see the Autoconf documentation" >&5 ++echo "$as_me: WARNING: zlib.h: see the Autoconf documentation" >&2;} ++ { echo "$as_me:$LINENO: WARNING: zlib.h: section \"Present But Cannot Be Compiled\"" >&5 ++echo "$as_me: WARNING: zlib.h: section \"Present But Cannot Be Compiled\"" >&2;} ++ { echo "$as_me:$LINENO: WARNING: zlib.h: proceeding with the preprocessor's result" >&5 ++echo "$as_me: WARNING: zlib.h: proceeding with the preprocessor's result" >&2;} ++ { echo "$as_me:$LINENO: WARNING: zlib.h: in the future, the compiler will take precedence" >&5 ++echo "$as_me: WARNING: zlib.h: in the future, the compiler will take precedence" >&2;} ++ ( ++ cat <<\_ASBOX ++## ------------------------------------------ ## ++## Report this to the AC_PACKAGE_NAME lists. ## ++## ------------------------------------------ ## ++_ASBOX ++ ) | ++ sed "s/^/$as_me: WARNING: /" >&2 ++ ;; ++esac ++echo "$as_me:$LINENO: checking for zlib.h" >&5 ++echo $ECHO_N "checking for zlib.h... $ECHO_C" >&6 ++if test "${ac_cv_header_zlib_h+set}" = set; then ++ echo $ECHO_N "(cached) $ECHO_C" >&6 ++else ++ ac_cv_header_zlib_h=$ac_header_preproc ++fi ++echo "$as_me:$LINENO: result: $ac_cv_header_zlib_h" >&5 ++echo "${ECHO_T}$ac_cv_header_zlib_h" >&6 ++ ++fi ++if test $ac_cv_header_zlib_h = yes; then ++ echo "$as_me:$LINENO: checking for gzdopen in -lz" >&5 ++echo $ECHO_N "checking for gzdopen in -lz... $ECHO_C" >&6 ++if test "${ac_cv_lib_z_gzdopen+set}" = set; then ++ echo $ECHO_N "(cached) $ECHO_C" >&6 ++else ++ ac_check_lib_save_LIBS=$LIBS ++LIBS="-lz $LIBS" ++cat >conftest.$ac_ext <<_ACEOF ++/* confdefs.h. */ ++_ACEOF ++cat confdefs.h >>conftest.$ac_ext ++cat >>conftest.$ac_ext <<_ACEOF ++/* end confdefs.h. */ ++ ++/* Override any gcc2 internal prototype to avoid an error. */ ++#ifdef __cplusplus ++extern "C" ++#endif ++/* We use char because int might match the return type of a gcc2 ++ builtin and then its argument prototype would still apply. */ ++char gzdopen (); ++int ++main () ++{ ++gzdopen (); ++ ; ++ return 0; ++} ++_ACEOF ++rm -f conftest.$ac_objext conftest$ac_exeext ++if { (eval echo "$as_me:$LINENO: \"$ac_link\"") >&5 ++ (eval $ac_link) 2>conftest.er1 ++ ac_status=$? ++ grep -v '^ *+' conftest.er1 >conftest.err ++ rm -f conftest.er1 ++ cat conftest.err >&5 ++ echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ (exit $ac_status); } && ++ { ac_try='test -z "$ac_c_werror_flag" ++ || test ! -s conftest.err' ++ { (eval echo "$as_me:$LINENO: \"$ac_try\"") >&5 ++ (eval $ac_try) 2>&5 ++ ac_status=$? ++ echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ (exit $ac_status); }; } && ++ { ac_try='test -s conftest$ac_exeext' ++ { (eval echo "$as_me:$LINENO: \"$ac_try\"") >&5 ++ (eval $ac_try) 2>&5 ++ ac_status=$? ++ echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ (exit $ac_status); }; }; then ++ ac_cv_lib_z_gzdopen=yes ++else ++ echo "$as_me: failed program was:" >&5 ++sed 's/^/| /' conftest.$ac_ext >&5 ++ ++ac_cv_lib_z_gzdopen=no ++fi ++rm -f conftest.err conftest.$ac_objext \ ++ conftest$ac_exeext conftest.$ac_ext ++LIBS=$ac_check_lib_save_LIBS ++fi ++echo "$as_me:$LINENO: result: $ac_cv_lib_z_gzdopen" >&5 ++echo "${ECHO_T}$ac_cv_lib_z_gzdopen" >&6 ++if test $ac_cv_lib_z_gzdopen = yes; then ++ LIBS="-lz $LIBS"; cat >>confdefs.h <<\_ACEOF ++#define ENABLE_ZLIB 1 ++_ACEOF ++ ++fi ++ ++fi ++ ++ ++fi ++ + ac_config_files="$ac_config_files Makefile" + + cat >confcache <<\_ACEOF +@@ -4568,6 +4815,11 @@ + *) ac_INSTALL=$ac_top_builddir$INSTALL ;; + esac + ++ if test x"$ac_file" != x-; then ++ { echo "$as_me:$LINENO: creating $ac_file" >&5 ++echo "$as_me: creating $ac_file" >&6;} ++ rm -f "$ac_file" ++ fi + # Let's still pretend it is `configure' which instantiates (i.e., don't + # use $as_me), people would be surprised to read: + # /* config.h. Generated by config.status. */ +@@ -4606,12 +4858,6 @@ + fi;; + esac + done` || { (exit 1); exit 1; } +- +- if test x"$ac_file" != x-; then +- { echo "$as_me:$LINENO: creating $ac_file" >&5 +-echo "$as_me: creating $ac_file" >&6;} +- rm -f "$ac_file" +- fi + _ACEOF + cat >>$CONFIG_STATUS <<_ACEOF + sed "$ac_vpsub +Index: configure.in +=================================================================== +RCS file: /home/cvsroot/lars/ccache/configure.in,v +retrieving revision 1.1.1.1.2.1 +retrieving revision 1.4 +diff -u -r1.1.1.1.2.1 -r1.4 +--- configure.in 21 Nov 2004 17:55:36 -0000 1.1.1.1.2.1 ++++ configure.in 21 Nov 2004 18:19:28 -0000 1.4 +@@ -68,5 +68,14 @@ + AC_DEFINE(HAVE_C99_VSNPRINTF, 1, [ ]) + fi + ++dnl Check for zlib. ++AC_ARG_ENABLE([zlib], ++ AS_HELP_STRING([--enable-zlib], [enable zlib support for ccache compression]),, ++ [enable_zlib=yes]) ++ ++if test x"$enable_zlib" = x"yes"; then ++ AC_CHECK_HEADER(zlib.h, AC_CHECK_LIB(z, gzdopen, LIBS="-lz $LIBS"; AC_DEFINE(ENABLE_ZLIB))) ++fi ++ + AC_CONFIG_FILES([Makefile]) + AC_OUTPUT +Index: util.c +=================================================================== +RCS file: /home/cvsroot/lars/ccache/util.c,v +retrieving revision 1.1.1.1.2.1 +retrieving revision 1.11 +diff -u -r1.1.1.1.2.1 -r1.11 +--- util.c 21 Nov 2004 17:55:36 -0000 1.1.1.1.2.1 ++++ util.c 21 Nov 2004 18:19:28 -0000 1.11 +@@ -44,6 +44,7 @@ + exit(1); + } + ++#ifndef ENABLE_ZLIB + /* copy all data from one file descriptor to another */ + void copy_fd(int fd_in, int fd_out) + { +@@ -57,6 +58,11 @@ + } + } + ++/* move a file using rename */ ++int move_file(const char *src, const char *dest) { ++ return rename(src, dest); ++} ++ + /* copy a file - used when hard links don't work + the copy is done via a temporary file and atomic rename + */ +@@ -120,6 +126,174 @@ + return 0; + } + ++#else /* ENABLE_ZLIB */ ++ ++/* copy all data from one file descriptor to another ++ possibly decompressing it ++*/ ++void copy_fd(int fd_in, int fd_out) { ++ char buf[10240]; ++ int n; ++ gzFile gz_in; ++ ++ gz_in = gzdopen(dup(fd_in), "rb"); ++ ++ if (!gz_in) { ++ fatal("Failed to copy fd"); ++ } ++ ++ while ((n = gzread(gz_in, buf, sizeof(buf))) > 0) { ++ if (write(fd_out, buf, n) != n) { ++ fatal("Failed to copy fd"); ++ } ++ } ++} ++ ++static int _copy_file(const char *src, const char *dest, int mode) { ++ int fd_in, fd_out; ++ gzFile gz_in, gz_out = NULL; ++ char buf[10240]; ++ int n, ret; ++ char *tmp_name; ++ mode_t mask; ++ struct stat st; ++ ++ x_asprintf(&tmp_name, "%s.XXXXXX", dest); ++ ++ if (getenv("CCACHE_NOCOMPRESS")) { ++ mode = COPY_UNCOMPRESSED; ++ } ++ ++ /* open source file */ ++ fd_in = open(src, O_RDONLY); ++ if (fd_in == -1) { ++ return -1; ++ } ++ ++ gz_in = gzdopen(fd_in, "rb"); ++ if (!gz_in) { ++ close(fd_in); ++ return -1; ++ } ++ ++ /* open destination file */ ++ fd_out = mkstemp(tmp_name); ++ if (fd_out == -1) { ++ gzclose(gz_in); ++ free(tmp_name); ++ return -1; ++ } ++ ++ if (mode == COPY_TO_CACHE) { ++ /* The gzip file format occupies at least 20 bytes. So ++ it will always occupy an entire filesystem block, ++ even for empty files. ++ Since most stderr files will be empty, we turn off ++ compression in this case to save space. ++ */ ++ if (fstat(fd_in, &st) != 0) { ++ gzclose(gz_in); ++ close(fd_out); ++ free(tmp_name); ++ return -1; ++ } ++ if (file_size(&st) == 0) { ++ mode = COPY_UNCOMPRESSED; ++ } ++ } ++ ++ if (mode == COPY_TO_CACHE) { ++ gz_out = gzdopen(dup(fd_out), "wb"); ++ if (!gz_out) { ++ gzclose(gz_in); ++ close(fd_out); ++ free(tmp_name); ++ return -1; ++ } ++ } ++ ++ while ((n = gzread(gz_in, buf, sizeof(buf))) > 0) { ++ if (mode == COPY_TO_CACHE) { ++ ret = gzwrite(gz_out, buf, n); ++ } else { ++ ret = write(fd_out, buf, n); ++ } ++ if (ret != n) { ++ gzclose(gz_in); ++ if (gz_out) { ++ gzclose(gz_out); ++ } ++ close(fd_out); ++ unlink(tmp_name); ++ free(tmp_name); ++ return -1; ++ } ++ } ++ ++ gzclose(gz_in); ++ if (gz_out) { ++ gzclose(gz_out); ++ } ++ ++ /* get perms right on the tmp file */ ++ mask = umask(0); ++ fchmod(fd_out, 0666 & ~mask); ++ umask(mask); ++ ++ /* the close can fail on NFS if out of space */ ++ if (close(fd_out) == -1) { ++ unlink(tmp_name); ++ free(tmp_name); ++ return -1; ++ } ++ ++ unlink(dest); ++ ++ if (rename(tmp_name, dest) == -1) { ++ unlink(tmp_name); ++ free(tmp_name); ++ return -1; ++ } ++ ++ free(tmp_name); ++ ++ return 0; ++} ++ ++/* move a file to the cache, compressing it */ ++int move_file(const char *src, const char *dest) { ++ int ret; ++ ++ ret = _copy_file(src, dest, COPY_TO_CACHE); ++ if (ret != -1) unlink(src); ++ return ret; ++} ++ ++/* copy a file from the cache, decompressing it */ ++int copy_file(const char *src, const char *dest) { ++ return _copy_file(src, dest, COPY_FROM_CACHE); ++} ++#endif /* ENABLE_ZLIB */ ++ ++/* test if a file is zlib compressed */ ++int test_if_compressed(const char *filename) { ++ FILE *f; ++ ++ f = fopen(filename, "rb"); ++ if (!f) { ++ return 0; ++ } ++ ++ /* test if file starts with 1F8B, which is zlib's ++ * magic number */ ++ if ((fgetc(f) != 0x1f) || (fgetc(f) != 0x8b)) { ++ fclose(f); ++ return 0; ++ } ++ ++ fclose(f); ++ return 1; ++} + + /* make sure a directory exists */ + int create_dir(const char *dir) +Index: manage-cache.sh +=================================================================== +RCS file: manage-cache.sh +diff -N manage-cache.sh +--- manage-cache.sh 1 Jan 1970 00:00:00 -0000 ++++ manage-cache.sh-cache.sh 12 May 2004 19:22:20 -0000 1.1 +@@ -0,0 +1,68 @@ ++#!/bin/bash ++# ++# 2004-05-12 lars@gustaebel.de ++ ++CCACHE_DIR=${CCACHE_DIR:-$HOME/.ccache} ++ ++echo "Do you want to compress or decompress the ccache in $CCACHE_DIR?" ++read -p "Type c or d: " mode ++ ++if [ "$mode" != "c" ] && [ "$mode" != "d" ] ++then ++ exit 1 ++fi ++ ++is_compressed() { ++ test "$(head -c 2 $1)" = $'\x1f\x8b' ++ return $? ++} ++ ++tmpfile=$(mktemp) ++ ++for dir in 0 1 2 3 4 5 6 7 8 9 a b c d e f ++do ++ # process ccache subdir ++ echo -n "$dir " ++ ++ # find cache files ++ find $CCACHE_DIR/$dir -type f -name '*-*' | ++ sort > $tmpfile ++ ++ oldsize=$(cat $CCACHE_DIR/$dir/stats | cut -d ' ' -f 13) ++ newsize=0 ++ ++ while read file ++ do ++ # empty files will be ignored since compressing ++ # them makes them bigger ++ test $(stat -c %s $file) -eq 0 && continue ++ ++ if [ $mode = c ] ++ then ++ if ! is_compressed $file ++ then ++ gzip $file ++ mv $file.gz $file ++ fi ++ else ++ if is_compressed $file ++ then ++ mv $file $file.gz ++ gzip -d $file.gz ++ fi ++ fi ++ ++ # calculate new size statistic for this subdir ++ let newsize=$newsize+$(stat -c "%B*%b" $file)/1024 ++ done < $tmpfile ++ ++ # update statistic file ++ read -a numbers < $CCACHE_DIR/$dir/stats ++ numbers[12]=$newsize ++ echo "${numbers[*]} " > $CCACHE_DIR/$dir/stats ++done ++echo ++ ++# clean up ++rm $tmpfile ++ +Index: Makefile.in +=================================================================== +RCS file: /home/cvsroot/lars/ccache/Makefile.in,v +retrieving revision 1.1.1.1.2.1 +retrieving revision 1.12 +diff -u -r1.1.1.1.2.1 -r1.12 +--- Makefile.in 21 Nov 2004 17:55:36 -0000 1.1.1.1.2.1 ++++ Makefile.in 21 Nov 2004 18:19:28 -0000 1.12 +@@ -11,6 +11,7 @@ + CFLAGS=@CFLAGS@ -I. + EXEEXT=@EXEEXT@ + ++LIBS= @LIBS@ + OBJS= ccache.o mdfour.o hash.o execute.o util.o args.o stats.o \ + cleanup.o snprintf.o unify.o + HEADERS = ccache.h mdfour.h +@@ -20,7 +21,7 @@ + docs: ccache.1 web/ccache-man.html + + ccache$(EXEEXT): $(OBJS) $(HEADERS) +- $(CC) $(CFLAGS) -o $@ $(OBJS) ++ $(CC) $(CFLAGS) -o $@ $(OBJS) $(LIBS) + + ccache.1: ccache.yo + -yodl2man -o ccache.1 ccache.yo diff --git a/CCache/debian/patches/03_long_options.diff b/CCache/debian/patches/03_long_options.diff new file mode 100644 index 0000000..3235c38 --- /dev/null +++ b/CCache/debian/patches/03_long_options.diff @@ -0,0 +1,133 @@ +Index: ccache.c +=================================================================== +--- ccache.c (révision 7695) ++++ ccache.c (copie de travail) +@@ -22,6 +22,7 @@ + */ + + #include "ccache.h" ++#include + + /* the base cache directory */ + char *cache_dir = NULL; +@@ -885,14 +886,14 @@ + printf("\tcompiler [compile options] (via symbolic link)\n"); + printf("\nOptions:\n"); + +- printf("-s show statistics summary\n"); +- printf("-z zero statistics\n"); +- printf("-c run a cache cleanup\n"); +- printf("-C clear the cache completely\n"); +- printf("-F set maximum files in cache\n"); +- printf("-M set maximum size of cache (use G, M or K)\n"); +- printf("-h this help page\n"); +- printf("-V print version number\n"); ++ printf("-s, --show-stats show statistics summary\n"); ++ printf("-z, --zero-stats zero statistics\n"); ++ printf("-c, --cleanup run a cache cleanup\n"); ++ printf("-C, --clear clear the cache completely\n"); ++ printf("-F , --max-files= set maximum files in cache\n"); ++ printf("-M , --max-size= set maximum size of cache (use G, M or K)\n"); ++ printf("-h, --help this help page\n"); ++ printf("-V, --version print version number\n"); + } + + /* the main program when not doing a compile */ +@@ -901,7 +902,21 @@ + int c; + size_t v; + +- while ((c = getopt(argc, argv, "hszcCF:M:V")) != -1) { ++ static struct option long_options[] = ++ { ++ {"show-stats", no_argument, 0, 's'}, ++ {"zero-stats", no_argument, 0, 'z'}, ++ {"cleanup", no_argument, 0, 'c'}, ++ {"clear", no_argument, 0, 'C'}, ++ {"max-files", required_argument, 0, 'F'}, ++ {"max-size", required_argument, 0, 'M'}, ++ {"help", no_argument, 0, 'h'}, ++ {"version", no_argument, 0, 'V'}, ++ {0, 0, 0, 0} ++ }; ++ int option_index = 0; ++ ++ while ((c = getopt_long(argc, argv, "hszcCF:M:V", long_options, &option_index)) != -1) { + switch (c) { + case 'V': + printf("ccache version %s\n", CCACHE_VERSION); +Index: ccache.1 +=================================================================== +--- ccache.1 (révision 7695) ++++ ccache.1 (copie de travail) +@@ -23,14 +23,14 @@ + .nf + + +--s show statistics summary +--z zero statistics +--c run a cache cleanup +--C clear the cache completely +--F set maximum files in cache +--M set maximum size of cache (use G, M or K) +--h this help page +--V print version number ++\-s, \-\-show-stats show statistics summary ++\-z, \-\-zero-stats zero statistics ++\-c, \-\-cleanup run a cache cleanup ++\-C, \-\-clear clear the cache completely ++\-F , \-\-max-files= set maximum files in cache ++\-M , \-\-max-size= set maximum size of cache (use G, M or K) ++\-h, \-\-help this help page ++\-V, \-\-version print version number + + .fi + +@@ -43,22 +43,22 @@ + normal compiler options apply and you should refer to your compilers + documentation\&. + .PP +-.IP "\fB-h\fP" ++.IP "\fB-h, --help\fP" + Print a options summary page + .IP +-.IP "\fB-s\fP" ++.IP "\fB-s, --show-stats\fP" + Print the current statistics summary for the cache\&. The + statistics are stored spread across the subdirectories of the + cache\&. Using "ccache -s" adds up the statistics across all + subdirectories and prints the totals\&. + .IP +-.IP "\fB-z\fP" ++.IP "\fB-z, --zero-stats\fP" + Zero the cache statistics\&. + .IP +-.IP "\fB-V\fP" ++.IP "\fB-V, --version\fP" + Print the ccache version number + .IP +-.IP "\fB-c\fP" ++.IP "\fB-c, --cleanup\fP" + Clean the cache and re-calculate the cache file count and + size totals\&. Normally the -c option should not be necessary as ccache + keeps the cache below the specified limits at runtime and keeps +@@ -66,16 +66,16 @@ + if you manually modify the cache contents or believe that the cache + size statistics may be inaccurate\&. + .IP +-.IP "\fB-C\fP" ++.IP "\fB-C, --clear\fP" + Clear the entire cache, removing all cached files\&. + .IP +-.IP "\fB-F maxfiles\fP" ++.IP "\fB-F , --max-files=\fP" + This sets the maximum number of files allowed in + the cache\&. The value is stored inside the cache directory and applies + to all future compiles\&. Due to the way the value is stored the actual + value used is always rounded down to the nearest multiple of 16\&. + .IP +-.IP "\fB-M maxsize\fP" ++.IP "\fB-M , --max-size=\fP" + This sets the maximum cache size\&. You can specify + a value in gigabytes, megabytes or kilobytes by appending a G, M or K + to the value\&. The default is gigabytes\&. The actual value stored is diff --git a/CCache/debian/patches/04_ignore_profile.diff b/CCache/debian/patches/04_ignore_profile.diff new file mode 100644 index 0000000..5683750 --- /dev/null +++ b/CCache/debian/patches/04_ignore_profile.diff @@ -0,0 +1,13 @@ +diff -ru ccache-2.4/ccache.c ccache-2.4-tp/ccache.c +--- ccache.c 2007-05-20 03:14:19.000000000 +1000 ++++ ccache.c 2007-05-20 03:17:54.000000000 +1000 +@@ -641,6 +641,9 @@ + + /* these are too hard */ + if (strcmp(argv[i], "-fbranch-probabilities")==0 || ++ strcmp(argv[i], "-fprofile-arcs") == 0 || ++ strcmp(argv[i], "-ftest-coverage") == 0 || ++ strcmp(argv[i], "--coverage") == 0 || + strcmp(argv[i], "-M") == 0 || + strcmp(argv[i], "-MM") == 0 || + strcmp(argv[i], "-x") == 0) { diff --git a/CCache/debian/patches/05_nfs_fix.diff b/CCache/debian/patches/05_nfs_fix.diff new file mode 100644 index 0000000..662d976 --- /dev/null +++ b/CCache/debian/patches/05_nfs_fix.diff @@ -0,0 +1,45 @@ +--- ccache.1.orig 2007-05-20 17:30:57.000000000 +1200 ++++ ccache.1 2007-05-20 17:31:27.000000000 +1200 +@@ -367,12 +367,6 @@ + .IP o + ccache avoids a double call to cpp on a cache miss + .PP +-.SH "BUGS" +-.PP +-When the cache is stored on an NFS filesystem, the filesystem must be +-exported with the \fBno_subtree_check\fP option to make renames between +-directories reliable\&. +-.PP + .SH "CREDITS" + .PP + Thanks to the following people for their contributions to ccache +--- util.c.patched 2007-05-20 18:19:11.000000000 +1200 ++++ util.c 2007-05-20 18:20:55.000000000 +1200 +@@ -58,9 +58,26 @@ + } + } + ++static int safe_rename(const char* oldpath, const char* newpath) ++{ ++ /* safe_rename is for creating entries in the cache. ++ ++ Works like rename(), but it never overwrites an existing ++ cache entry. This avoids corruption on NFS. */ ++ int status = link( oldpath, newpath ); ++ if( status == 0 || errno == EEXIST ) ++ { ++ return unlink( oldpath ); ++ } ++ else ++ { ++ return -1; ++ } ++} ++ + /* move a file using rename */ + int move_file(const char *src, const char *dest) { +- return rename(src, dest); ++ return safe_rename(src, dest); + } + + /* copy a file - used when hard links don't work diff --git a/CCache/debian/patches/06_md.diff b/CCache/debian/patches/06_md.diff new file mode 100644 index 0000000..3f68850 --- /dev/null +++ b/CCache/debian/patches/06_md.diff @@ -0,0 +1,77 @@ +--- ccache.c Mon Sep 13 11:38:30 2004 ++++ ccache.c Thu Jun 21 22:17:32 2007 +@@ -627,6 +627,13 @@ static void process_args(int argc, char + int found_S_opt = 0; + struct stat st; + char *e; ++ /* is gcc being asked to output dependencies? */ ++ int generating_dependencies = 0; ++ /* is the dependency makefile name overridden with -MF? */ ++ int dependency_filename_specified = 0; ++ /* is the dependency makefile target name specified with -MQ or -MF? */ ++ int dependency_target_specified = 0; ++ + + stripped_args = args_init(0, NULL); + +@@ -702,6 +709,18 @@ static void process_args(int argc, char + continue; + } + ++ /* These options require special handling, because they ++ behave differently with gcc -E, when the output ++ file is not specified. */ ++ ++ if (strcmp(argv[i], "-MD") == 0 || strcmp(argv[i], "-MMD") == 0) { ++ generating_dependencies = 1; ++ } else if (strcmp(argv[i], "-MF") == 0) { ++ dependency_filename_specified = 1; ++ } else if (strcmp(argv[i], "-MQ") == 0 || strcmp(argv[i], "-MT") == 0) { ++ dependency_target_specified = 1; ++ } ++ + /* options that take an argument */ + { + const char *opts[] = {"-I", "-include", "-imacros", "-iprefix", +@@ -812,6 +831,41 @@ static void process_args(int argc, char + } + p[1] = found_S_opt ? 's' : 'o'; + p[2] = 0; ++ } ++ ++ /* If dependencies are generated, configure the preprocessor */ ++ ++ if (generating_dependencies && output_file) { ++ if (!dependency_filename_specified) { ++ char *default_depfile_name = x_strdup(output_file); ++ char *p = strrchr(default_depfile_name, '.'); ++ ++ if (p) { ++ if (strlen(p) < 2) { ++ stats_update(STATS_ARGS); ++ failed(); ++ return; ++ } ++ *p = 0; ++ } ++ else { ++ int len = p - default_depfile_name; ++ ++ p = x_malloc(len + 3); ++ strncpy(default_depfile_name, p, len - 1); ++ free(default_depfile_name); ++ default_depfile_name = p; ++ } ++ ++ strcat(default_depfile_name, ".d"); ++ args_add(stripped_args, "-MF"); ++ args_add(stripped_args, default_depfile_name); ++ } ++ ++ if (!dependency_target_specified) { ++ args_add(stripped_args, "-MT"); ++ args_add(stripped_args, output_file); ++ } + } + + /* cope with -o /dev/null */ diff --git a/CCache/debian/patches/07_cachedirtag.diff b/CCache/debian/patches/07_cachedirtag.diff new file mode 100644 index 0000000..683b48d --- /dev/null +++ b/CCache/debian/patches/07_cachedirtag.diff @@ -0,0 +1,75 @@ +Index: ccache.c +=================================================================== +--- ccache.c (révision 7695) ++++ ccache.c (copie de travail) +@@ -1029,6 +1029,14 @@ + exit(1); + } + ++ if (!getenv("CCACHE_READONLY")) { ++ if (create_cachedirtag(cache_dir) != 0) { ++ fprintf(stderr,"ccache: failed to create %s/CACHEDIR.TAG (%s)\n", ++ cache_dir, strerror(errno)); ++ exit(1); ++ } ++ } ++ + ccache(argc, argv); + return 1; + } +Index: ccache.h +=================================================================== +--- ccache.h (révision 7695) ++++ ccache.h (copie de travail) +@@ -81,6 +81,7 @@ + int copy_file(const char *src, const char *dest); + + int create_dir(const char *dir); ++int create_cachedirtag(const char *dir); + void x_asprintf(char **ptr, const char *format, ...); + char *x_strdup(const char *s); + void *x_realloc(void *ptr, size_t size); +Index: util.c +=================================================================== +--- util.c (révision 7695) ++++ util.c (copie de travail) +@@ -138,6 +138,39 @@ + return 0; + } + ++char const CACHEDIR_TAG[] = ++ "Signature: 8a477f597d28d172789f06886806bc55\n" ++ "# This file is a cache directory tag created by ccache.\n" ++ "# For information about cache directory tags, see:\n" ++ "# http://www.brynosaurus.com/cachedir/\n"; ++ ++int create_cachedirtag(const char *dir) ++{ ++ char *filename; ++ struct stat st; ++ FILE *f; ++ x_asprintf(&filename, "%s/CACHEDIR.TAG", dir); ++ if (stat(filename, &st) == 0) { ++ if (S_ISREG(st.st_mode)) { ++ goto success; ++ } ++ errno = EEXIST; ++ goto error; ++ } ++ f = fopen(filename, "w"); ++ if (!f) goto error; ++ if (fwrite(CACHEDIR_TAG, sizeof(CACHEDIR_TAG)-1, 1, f) != 1) { ++ goto error; ++ } ++ if (fclose(f)) goto error; ++success: ++ free(filename); ++ return 0; ++error: ++ free(filename); ++ return 1; ++} ++ + /* + this is like asprintf() but dies if the malloc fails + note that we use vsnprintf in a rather poor way to make this more portable diff --git a/CCache/debian/patches/08_manpage_hyphens.diff b/CCache/debian/patches/08_manpage_hyphens.diff new file mode 100644 index 0000000..55ced4a --- /dev/null +++ b/CCache/debian/patches/08_manpage_hyphens.diff @@ -0,0 +1,89 @@ +Index: ccache.1 +=================================================================== +--- ccache.1 (révision 7695) ++++ ccache.1 (copie de travail) +@@ -49,7 +49,7 @@ + .IP "\fB-s\fP" + Print the current statistics summary for the cache\&. The + statistics are stored spread across the subdirectories of the +-cache\&. Using "ccache -s" adds up the statistics across all ++cache\&. Using "ccache \-s" adds up the statistics across all + subdirectories and prints the totals\&. + .IP + .IP "\fB-z\fP" +@@ -60,7 +60,7 @@ + .IP + .IP "\fB-c\fP" + Clean the cache and re-calculate the cache file count and +-size totals\&. Normally the -c option should not be necessary as ccache ++size totals\&. Normally the \-c option should not be necessary as ccache + keeps the cache below the specified limits at runtime and keeps + statistics up to date on each compile\&. This option is mostly useful + if you manually modify the cache contents or believe that the cache +@@ -100,9 +100,9 @@ + + + cp ccache /usr/local/bin/ +- ln -s /usr/local/bin/ccache /usr/local/bin/gcc +- ln -s /usr/local/bin/ccache /usr/local/bin/g++ +- ln -s /usr/local/bin/ccache /usr/local/bin/cc ++ ln \-s /usr/local/bin/ccache /usr/local/bin/gcc ++ ln \-s /usr/local/bin/ccache /usr/local/bin/g++ ++ ln \-s /usr/local/bin/ccache /usr/local/bin/cc + + .fi + +@@ -118,7 +118,7 @@ + .PP + When run as a compiler front end ccache usually just takes the same + command line options as the compiler you are using\&. The only exception +-to this is the option \&'--ccache-skip\&'\&. That option can be used to tell ++to this is the option \&'\-\-ccache-skip\&'\&. That option can be used to tell + ccache that the next option is definitely not a input filename, and + should be passed along to the compiler as-is\&. + .PP +@@ -128,7 +128,7 @@ + of the resulting object file (among other things)\&. The heuristic + ccache uses in this parse is that any string on the command line that + exists as a file is treated as an input file name (usually a C +-file)\&. By using --ccache-skip you can force an option to not be ++file)\&. By using \-\-ccache-skip you can force an option to not be + treated as an input file name and instead be passed along to the + compiler as a command line option\&. + .PP +@@ -238,7 +238,7 @@ + .IP "\fBCCACHE_UNIFY\fP" + If you set the environment variable CCACHE_UNIFY + then ccache will use the C/C++ unifier when hashing the pre-processor +-output if -g is not used in the compile\&. The unifier is slower than a ++output if \-g is not used in the compile\&. The unifier is slower than a + normal hash, so setting this environment variable loses a little bit + of speed, but it means that ccache can take advantage of not + recompiling when the changes to the source code consist of +@@ -262,7 +262,7 @@ + .PP + By default ccache has a one gigabyte limit on the cache size and no + maximum number of files\&. You can set a different limit using the +-"ccache -M" and "ccache -F" options, which set the size and number of ++"ccache \-M" and "ccache \-F" options, which set the size and number of + files limits\&. + .PP + When these limits are reached ccache will reduce the cache to 20% +@@ -276,7 +276,7 @@ + that it is the same code by forming a hash of: + .PP + .IP o +-the pre-processor output from running the compiler with -E ++the pre-processor output from running the compiler with \-E + .IP o + the command line options + .IP o +@@ -331,7 +331,7 @@ + .IP o + Make sure that the setgid bit is set on all directories in the + cache\&. This tells the filesystem to inherit group ownership for new +-directories\&. The command "chmod g+s `find $CCACHE_DIR -type d`" might ++directories\&. The command "chmod g+s `find $CCACHE_DIR \-type d`" might + be useful for this\&. + .PP + .SH "HISTORY" diff --git a/CCache/debian/patches/09_respect_ldflags.diff b/CCache/debian/patches/09_respect_ldflags.diff new file mode 100644 index 0000000..0ce2c2d --- /dev/null +++ b/CCache/debian/patches/09_respect_ldflags.diff @@ -0,0 +1,11 @@ +--- Makefile.in.orig 2008-03-23 17:01:19.000000000 +1300 ++++ Makefile.in 2008-03-23 17:03:03.000000000 +1300 +@@ -21,7 +21,7 @@ + docs: ccache.1 web/ccache-man.html + + ccache$(EXEEXT): $(OBJS) $(HEADERS) +- $(CC) $(CFLAGS) -o $@ $(OBJS) $(LIBS) ++ $(CC) $(CFLAGS) $(LDFLAGS) -o $@ $(OBJS) $(LIBS) + + ccache.1: ccache.yo + -yodl2man -o ccache.1 ccache.yo diff --git a/CCache/debian/patches/10_lru_cleanup.diff b/CCache/debian/patches/10_lru_cleanup.diff new file mode 100644 index 0000000..24463e5 --- /dev/null +++ b/CCache/debian/patches/10_lru_cleanup.diff @@ -0,0 +1,23 @@ +--- ccache.c (révision 8804) ++++ ccache.c (copie de travail) +@@ -481,6 +481,9 @@ + return; + } + ++ /* update timestamps for LRU cleanup ++ also gives output_file a sensible mtime when hard-linking (for make) */ ++ utime(hashname, NULL); + utime(stderr_file, NULL); + + if (strcmp(output_file, "/dev/null") == 0) { +@@ -513,10 +516,6 @@ + failed(); + } + } +- if (ret == 0) { +- /* update the mtime on the file so that make doesn't get confused */ +- utime(output_file, NULL); +- } + + /* get rid of the intermediate preprocessor file */ + if (i_tmpfile) { diff --git a/CCache/debian/patches/11_utimes.diff b/CCache/debian/patches/11_utimes.diff new file mode 100644 index 0000000..2886bf3 --- /dev/null +++ b/CCache/debian/patches/11_utimes.diff @@ -0,0 +1,85 @@ +--- ccache.c 2004-09-13 03:38:30.000000000 -0700 ++++ ccache.c 2006-06-09 16:29:16.695117780 -0700 +@@ -481,8 +481,13 @@ + + /* update timestamps for LRU cleanup + also gives output_file a sensible mtime when hard-linking (for make) */ ++#ifdef HAVE_UTIMES ++ utimes(hashname, NULL); ++ utimes(stderr_file, NULL); ++#else + utime(hashname, NULL); + utime(stderr_file, NULL); ++#endif + + if (strcmp(output_file, "/dev/null") == 0) { + ret = 0; +--- ccache.h 2004-09-13 03:38:30.000000000 -0700 ++++ ccache.h 2006-06-09 16:28:16.601658626 -0700 +@@ -22,6 +22,9 @@ + #ifdef HAVE_PWD_H + #include + #endif ++#ifdef HAVE_SYS_TIME_H ++#include ++#endif + + #define STATUS_NOTFOUND 3 + #define STATUS_FATAL 4 +--- config.h.in 2003-09-27 21:48:17.000000000 -0700 ++++ config.h.in 2006-06-09 16:25:43.000000000 -0700 +@@ -19,6 +19,9 @@ + /* Define to 1 if you have the `gethostname' function. */ + #undef HAVE_GETHOSTNAME + ++/* Define to 1 if you have the `getpwuid' function. */ ++#undef HAVE_GETPWUID ++ + /* Define to 1 if you have the header file. */ + #undef HAVE_INTTYPES_H + +@@ -31,6 +34,9 @@ + /* Define to 1 if you have the header file, and it defines `DIR'. */ + #undef HAVE_NDIR_H + ++/* Define to 1 if you have the header file. */ ++#undef HAVE_PWD_H ++ + /* Define to 1 if you have the `realpath' function. */ + #undef HAVE_REALPATH + +@@ -60,6 +66,9 @@ + /* Define to 1 if you have the header file. */ + #undef HAVE_SYS_STAT_H + ++/* Define to 1 if you have the header file. */ ++#undef HAVE_SYS_TIME_H ++ + /* Define to 1 if you have the header file. */ + #undef HAVE_SYS_TYPES_H + +@@ -69,6 +78,9 @@ + /* Define to 1 if you have the header file. */ + #undef HAVE_UNISTD_H + ++/* Define to 1 if you have the `utimes' function. */ ++#undef HAVE_UTIMES ++ + /* Define to 1 if you have the `vasprintf' function. */ + #undef HAVE_VASPRINTF + +--- configure.in 2004-09-13 03:38:30.000000000 -0700 ++++ configure.in 2006-06-09 16:25:15.541288184 -0700 +@@ -27,10 +27,11 @@ + AC_HEADER_TIME + AC_HEADER_SYS_WAIT + +-AC_CHECK_HEADERS(ctype.h strings.h stdlib.h string.h pwd.h) ++AC_CHECK_HEADERS(ctype.h strings.h stdlib.h string.h pwd.h sys/time.h) + + AC_CHECK_FUNCS(realpath snprintf vsnprintf vasprintf asprintf mkstemp) + AC_CHECK_FUNCS(gethostname getpwuid) ++AC_CHECK_FUNCS(utimes) + + AC_CACHE_CHECK([for compar_fn_t in stdlib.h],ccache_cv_COMPAR_FN_T, [ + AC_TRY_COMPILE( diff --git a/CCache/debian/patches/12_cachesize_permissions.diff b/CCache/debian/patches/12_cachesize_permissions.diff new file mode 100644 index 0000000..28801b7 --- /dev/null +++ b/CCache/debian/patches/12_cachesize_permissions.diff @@ -0,0 +1,83 @@ +--- stats.c (révision 8804) ++++ stats.c (copie de travail) +@@ -286,7 +286,7 @@ + + + /* set the per directory limits */ +-void stats_set_limits(long maxfiles, long maxsize) ++int stats_set_limits(long maxfiles, long maxsize) + { + int dir; + unsigned counters[STATS_END]; +@@ -298,7 +298,9 @@ + maxsize /= 16; + } + +- create_dir(cache_dir); ++ if (create_dir(cache_dir) != 0) { ++ return 1; ++ } + + /* set the limits in each directory */ + for (dir=0;dir<=0xF;dir++) { +@@ -306,7 +308,9 @@ + int fd; + + x_asprintf(&cdir, "%s/%1x", cache_dir, dir); +- create_dir(cdir); ++ if (create_dir(cdir) != 0) { ++ return 1; ++ } + x_asprintf(&fname, "%s/stats", cdir); + free(cdir); + +@@ -326,6 +330,8 @@ + } + free(fname); + } ++ ++ return 0; + } + + /* set the per directory sizes */ +--- ccache.c (révision 8804) ++++ ccache.c (copie de travail) +@@ -935,15 +934,23 @@ + case 'F': + check_cache_dir(); + v = atoi(optarg); +- stats_set_limits(v, -1); +- printf("Set cache file limit to %u\n", (unsigned)v); ++ if (stats_set_limits(v, -1) == 0) { ++ printf("Set cache file limit to %u\n", (unsigned)v); ++ } else { ++ printf("Could not set cache file limit.\n"); ++ exit(1); ++ } + break; + + case 'M': + check_cache_dir(); + v = value_units(optarg); +- stats_set_limits(-1, v); +- printf("Set cache size limit to %uk\n", (unsigned)v); ++ if (stats_set_limits(-1, v) == 0) { ++ printf("Set cache size limit to %uk\n", (unsigned)v); ++ } else { ++ printf("Could not set cache size limit.\n"); ++ exit(1); ++ } + break; + + default: +--- ccache.h (révision 8804) ++++ ccache.h (copie de travail) +@@ -101,7 +101,7 @@ + void stats_summary(void); + void stats_tocache(size_t size); + void stats_read(const char *stats_file, unsigned counters[STATS_END]); +-void stats_set_limits(long maxfiles, long maxsize); ++int stats_set_limits(long maxfiles, long maxsize); + size_t value_units(const char *s); + void display_size(unsigned v); + void stats_set_sizes(const char *dir, size_t num_files, size_t total_size); diff --git a/CCache/debian/patches/13_html_links.diff b/CCache/debian/patches/13_html_links.diff new file mode 100644 index 0000000..dadf1b6 --- /dev/null +++ b/CCache/debian/patches/13_html_links.diff @@ -0,0 +1,33 @@ +--- web/index.html~ 2004-09-13 13:38:30.000000000 +0300 ++++ web/index.html 2004-09-26 01:04:38.458008118 +0300 +@@ -29,10 +29,10 @@ +
  • fixed handling of HOME environment variable + + +-See the manual page for details ++See the manual page for details + on the new options.

    + +-You can get this release from the download directory ++You can get this release from the download directory + +

    NOTE! This release changes the hash input slighly, so you will + probably find that you will not get any hits against your existing +@@ -87,7 +87,7 @@ + +

    Documentation

    + +-See the manual page ++See the manual page + + +

    Performance

    +@@ -116,7 +116,7 @@ +

    Download

    + + You can download the latest release from the download directory.

    ++href="http://ccache.samba.org/ftp/ccache/">download directory.

    + + For the bleeding edge, you can fetch ccache via CVS or + rsync. To fetch via cvs use the following command: diff --git a/CCache/debian/patches/14_hardlink_doc.diff b/CCache/debian/patches/14_hardlink_doc.diff new file mode 100644 index 0000000..bd9e25b --- /dev/null +++ b/CCache/debian/patches/14_hardlink_doc.diff @@ -0,0 +1,48 @@ +Index: ccache.1 +=================================================================== +RCS file: /cvsroot/ccache/ccache.1,v +retrieving revision 1.26 +diff -u -r1.26 ccache.1 +--- ccache.1 24 Nov 2005 21:10:08 -0000 1.26 ++++ ccache.1 21 Jul 2007 21:03:32 -0000 +@@ -330,7 +330,7 @@ + .IP o + Use the same \fBCCACHE_DIR\fP environment variable setting + .IP o +-Set the \fBCCACHE_NOLINK\fP environment variable ++Unset the \fBCCACHE_HARDLINK\fP environment variable + .IP o + Make sure everyone sets the CCACHE_UMASK environment variable + to 002, this ensures that cached files are accessible to everyone in +Index: ccache.yo +=================================================================== +RCS file: /cvsroot/ccache/ccache.yo,v +retrieving revision 1.27 +diff -u -r1.27 ccache.yo +--- ccache.yo 24 Nov 2005 21:54:09 -0000 1.27 ++++ ccache.yo 21 Jul 2007 21:03:32 -0000 +@@ -289,7 +289,7 @@ + + itemize( + it() Use the same bf(CCACHE_DIR) environment variable setting +- it() Set the bf(CCACHE_NOLINK) environment variable ++ it() Unset the bf(CCACHE_HARDLINK) environment variable + it() Make sure everyone sets the CCACHE_UMASK environment variable + to 002, this ensures that cached files are accessible to everyone in + the group. +Index: web/ccache-man.html +=================================================================== +RCS file: /cvsroot/ccache/web/ccache-man.html,v +retrieving revision 1.25 +diff -u -r1.25 ccache-man.html +--- web/ccache-man.html 13 Sep 2004 10:38:17 -0000 1.25 ++++ web/ccache-man.html 21 Jul 2007 21:03:32 -0000 +@@ -256,7 +256,7 @@ + following conditions need to be met: +

      +
    • Use the same CCACHE_DIR environment variable setting +-
    • Set the CCACHE_NOLINK environment variable ++
    • Unset the CCACHE_HARDLINK environment variable +
    • Make sure everyone sets the CCACHE_UMASK environment variable + to 002, this ensures that cached files are accessible to everyone in + the group. diff --git a/CCache/debian/patches/CREDITS b/CCache/debian/patches/CREDITS new file mode 100644 index 0000000..c4e323b --- /dev/null +++ b/CCache/debian/patches/CREDITS @@ -0,0 +1,47 @@ +01_no_home.diff: + Francois Marier + Made especially for the Debian package. + +02_ccache_compressed.diff: + Lars Gustäbel + http://www.gustaebel.de/lars/ccache/ (downloaded on 2007-05-20) + +03_long_options.diff: + Francois Marier + Made especially for the Debian package. + +04_ignore_profile.diff: + Ted Percival + http://bugs.debian.org/cgi-bin/bugreport.cgi?msg=20;filename=ccache-profile.patch;att=1;bug=215849 + +05_nfs_fix.diff: + John Coiner + http://lists.samba.org/archive/ccache/2007q1/000265.html + +06_md.diff: + Andrea Bittau + http://darkircop.org/ccache/ccache-2.4-md.patch (downloaded on 2007-06-30) + +07_cachedirtag.diff: + Karl Chen + http://lists.samba.org/archive/ccache/2008q1/000316.html (downloaded on 2008-02-02) + +08_manpage_hyphens.diff: + Francois Marier + Made especially for the Debian package. + +09_respect_ldflags.diff: + Lisa Seelye + http://sources.gentoo.org/viewcvs.py/gentoo-x86/dev-util/ccache/files/ccache-2.4-respectflags.patch?rev=1.1&view=markup + +10_lru_cleanup.diff: + RW + http://lists.samba.org/archive/ccache/2008q2/000339.html (downloaded on 2008-04-11) + +11_utimes.diff: + Robin H. Johnson + http://sources.gentoo.org/viewcvs.py/gentoo-x86/dev-util/ccache/files/ccache-2.4-utimes.patch?rev=1.1&view=markup + +12_cachesize_permissions.diff: + Francois Marier + Made especially for the Debian package to fix http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=332527 diff --git a/CCache/debian/rules b/CCache/debian/rules new file mode 100644 index 0000000..c5b538b --- /dev/null +++ b/CCache/debian/rules @@ -0,0 +1,141 @@ +#!/usr/bin/make -f +# Sample debian/rules that uses debhelper. +# GNU copyright 1997 to 1999 by Joey Hess. + +# Uncomment this to turn on verbose mode. +#export DH_VERBOSE=1 + +# These are used for cross-compiling and for saving the configure script +# from having to guess our platform (since we know it already) +export DEB_HOST_GNU_TYPE ?= $(shell dpkg-architecture -qDEB_HOST_GNU_TYPE) +export DEB_BUILD_GNU_TYPE ?= $(shell dpkg-architecture -qDEB_BUILD_GNU_TYPE) + +ifeq ($(DEB_BUILD_GNU_TYPE), $(DEB_HOST_GNU_TYPE)) + confflags += --build $(DEB_HOST_GNU_TYPE) +else + confflags += --build $(DEB_BUILD_GNU_TYPE) --host $(DEB_HOST_GNU_TYPE) +endif + +ifneq (,$(findstring debug,$(DEB_BUILD_OPTIONS))) + CFLAGS += -g +endif +ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS))) + INSTALL_PROGRAM += -s +endif + +config.status: configure + dh_testdir + + # Apply Debian specific patches + cp $(CURDIR)/ccache.c $(CURDIR)/ccache.c.unpatched + cp $(CURDIR)/util.c $(CURDIR)/util.c.unpatched + cp $(CURDIR)/ccache.1 $(CURDIR)/ccache.1.unpatched + cp $(CURDIR)/ccache.h $(CURDIR)/ccache.h.unpatched + cp $(CURDIR)/ccache.yo $(CURDIR)/ccache.yo.unpatched + cp $(CURDIR)/config.h.in $(CURDIR)/config.h.in.unpatched + cp $(CURDIR)/configure $(CURDIR)/configure.unpatched + cp $(CURDIR)/configure.in $(CURDIR)/configure.in.unpatched + cp $(CURDIR)/Makefile.in $(CURDIR)/Makefile.in.unpatched + if test ! -f patch-stamp; then \ + for patch in $(CURDIR)/debian/patches/*.diff ;\ + do \ + echo APPLYING PATCH\: $${patch##*/};\ + patch -p0 < $$patch ;\ + done ;\ + touch patch-stamp ;\ + fi + chmod +x $(CURDIR)/manage-cache.sh + + ./configure $(confflags) --prefix=/usr --mandir=\$${prefix}/share/man --infodir=\$${prefix}/share/info + +build: build-stamp + +build-stamp: config.status + dh_testdir + + $(MAKE) + + touch build-stamp + +clean: + dh_testdir + dh_testroot + rm -f build-stamp + + # Unapply patches + -test -r $(CURDIR)/ccache.c.unpatched && mv $(CURDIR)/ccache.c.unpatched $(CURDIR)/ccache.c + -test -r $(CURDIR)/util.c.unpatched && mv $(CURDIR)/util.c.unpatched $(CURDIR)/util.c + -test -r $(CURDIR)/ccache.1.unpatched && mv $(CURDIR)/ccache.1.unpatched $(CURDIR)/ccache.1 + -test -r $(CURDIR)/ccache.h.unpatched && mv $(CURDIR)/ccache.h.unpatched $(CURDIR)/ccache.h + -test -r $(CURDIR)/ccache.yo.unpatched && mv $(CURDIR)/ccache.yo.unpatched $(CURDIR)/ccache.yo + -test -r $(CURDIR)/config.h.in.unpatched && mv $(CURDIR)/config.h.in.unpatched $(CURDIR)/config.h.in + -test -r $(CURDIR)/configure.unpatched && mv $(CURDIR)/configure.unpatched $(CURDIR)/configure + -test -r $(CURDIR)/configure.in.unpatched && mv $(CURDIR)/configure.in.unpatched $(CURDIR)/configure.in + -test -r $(CURDIR)/Makefile.in.unpatched && mv $(CURDIR)/Makefile.in.unpatched $(CURDIR)/Makefile.in + -rm -f $(CURDIR)/manage-cache.sh + -rm -f patch-stamp + + [ ! -f Makefile ] || $(MAKE) distclean + + dh_clean + + # Update config.sub and config.guess + -test -r /usr/share/misc/config.sub && \ + cp -f /usr/share/misc/config.sub config.sub + -test -r /usr/share/misc/config.guess && \ + cp -f /usr/share/misc/config.guess config.guess + + +install: build + dh_testdir + dh_testroot + dh_clean -k + dh_installdirs + + # Add here commands to install the package into debian/ccache. + $(MAKE) install prefix=$(CURDIR)/debian/ccache/usr + + ln -s ../../bin/ccache $(CURDIR)/debian/ccache/usr/lib/ccache/$(DEB_BUILD_GNU_TYPE)-gcc + ln -s ../../bin/ccache $(CURDIR)/debian/ccache/usr/lib/ccache/$(DEB_BUILD_GNU_TYPE)-g++ + set -e; for ver in 2.95 3.0 3.2 3.3 3.4 4.0 4.1 4.2 4.3; do \ + ln -s ../../bin/ccache $(CURDIR)/debian/ccache/usr/lib/ccache/$(DEB_BUILD_GNU_TYPE)-gcc-$$ver; \ + ln -s ../../bin/ccache $(CURDIR)/debian/ccache/usr/lib/ccache/gcc-$$ver; \ + ln -s ../../bin/ccache $(CURDIR)/debian/ccache/usr/lib/ccache/$(DEB_BUILD_GNU_TYPE)-g++-$$ver; \ + ln -s ../../bin/ccache $(CURDIR)/debian/ccache/usr/lib/ccache/g++-$$ver; \ + done + ln -s ../../bin/ccache $(CURDIR)/debian/ccache/usr/lib/ccache/cc + ln -s ../../bin/ccache $(CURDIR)/debian/ccache/usr/lib/ccache/c++ + ln -s ../../bin/ccache $(CURDIR)/debian/ccache/usr/lib/ccache/gcc + ln -s ../../bin/ccache $(CURDIR)/debian/ccache/usr/lib/ccache/g++ + ln -s ../../bin/ccache $(CURDIR)/debian/ccache/usr/lib/ccache/i586-mingw32msvc-c++ + ln -s ../../bin/ccache $(CURDIR)/debian/ccache/usr/lib/ccache/i586-mingw32msvc-cc + ln -s ../../bin/ccache $(CURDIR)/debian/ccache/usr/lib/ccache/i586-mingw32msvc-g++ + ln -s ../../bin/ccache $(CURDIR)/debian/ccache/usr/lib/ccache/i586-mingw32msvc-gcc + +# Build architecture-independent files here. +binary-indep: build install +# We have nothing to do by default. + +# Build architecture-dependent files here. +binary-arch: build install + dh_testdir + dh_testroot + dh_installdocs + dh_installexamples + dh_installmenu + dh_installcron + dh_installman + dh_installinfo + dh_installchangelogs + dh_link + dh_strip + dh_compress + dh_fixperms + dh_installdeb + dh_shlibdeps + dh_gencontrol + dh_md5sums + dh_builddeb + +binary: binary-indep binary-arch +.PHONY: build clean binary-indep binary-arch binary install diff --git a/CCache/debian/update-ccache b/CCache/debian/update-ccache new file mode 100644 index 0000000..0ef97a1 --- /dev/null +++ b/CCache/debian/update-ccache @@ -0,0 +1,43 @@ +#!/bin/sh +# +# Update compiler links to ccache (in /usr/local/bin) +# +# The idea is that /usr/local/bin is ahead of /usr/bin in your PATH, so adding +# the link /usr/local/bin/cc -> /usr/bin/ccache means that it is run instead of +# /usr/bin/cc +# +# Written by: Behan Webster +# + +DIRECTORY=/usr/local/bin +CCACHE=/usr/bin/ccache +CCDIR=/usr/lib/ccache + +usage() { + echo "Usage: `basename $0` [--directory ] [--remove]" + exit 0 +} + +while [ $# -gt 0 ] ; do + case "$1" in + -d*|--d*|--directory) DIRECTORY=$2; shift; shift;; + -h*|--h*|--help) usage;; + -r*|--r*|--remove) REMOVE=1; shift;; + -t*|--t*|--test) TEST=echo; shift;; + esac +done + +for FILE in `cd $CCDIR; ls` ; do + LINK=$DIRECTORY/$FILE + if [ -z "$REMOVE" ] ; then + # Add link + $TEST ln -fs $CCACHE $LINK + else + # Remove link + if [ -L "$LINK" ] ; then + $TEST rm -f $LINK + fi + fi +done + +# vim: sw=4 ts=4 diff --git a/CCache/debian/watch b/CCache/debian/watch new file mode 100644 index 0000000..a72959e --- /dev/null +++ b/CCache/debian/watch @@ -0,0 +1,2 @@ +version=2 +http://samba.org/ftp/ccache/ccache-(.*)\.tar\.gz diff --git a/CCache/execute.c b/CCache/execute.c new file mode 100644 index 0000000..165b91e --- /dev/null +++ b/CCache/execute.c @@ -0,0 +1,286 @@ +/* + Copyright (C) Andrew Tridgell 2002 + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. +*/ + +#include "ccache.h" + +#ifdef _WIN32 +char *argvtos(char **argv) +{ + int i, len; + char *ptr, *str; + + for (i = 0, len = 0; argv[i]; i++) { + len += strlen(argv[i]) + 3; + } + + str = ptr = (char *)malloc(len + 1); + if (str == NULL) + return NULL; + + for (i = 0; argv[i]; i++) { + len = strlen(argv[i]); + *ptr++ = '"'; + memcpy(ptr, argv[i], len); + ptr += len; + *ptr++ = '"'; + *ptr++ = ' '; + } + *ptr = 0; + + return str; +} +#endif + +/* + execute a compiler backend, capturing all output to the given paths + the full path to the compiler to run is in argv[0] +*/ +int execute(char **argv, + const char *path_stdout, + const char *path_stderr) +{ +#ifdef _WIN32 + +#if 1 + PROCESS_INFORMATION pinfo; + STARTUPINFO sinfo; + BOOL ret; + DWORD exitcode; + char *args; + HANDLE fd_out, fd_err; + SECURITY_ATTRIBUTES sa = {sizeof(SECURITY_ATTRIBUTES), NULL, TRUE}; + + /* TODO: needs moving after possible exit() below, but before stdout is redirected */ + if (ccache_verbose) { + display_execute_args(argv); + } + + fd_out = CreateFile(path_stdout, GENERIC_WRITE, 0, &sa, CREATE_ALWAYS, + FILE_ATTRIBUTE_NORMAL, NULL); + if (fd_out == INVALID_HANDLE_VALUE) { + return STATUS_NOCACHE; + } + + fd_err = CreateFile(path_stderr, GENERIC_WRITE, 0, &sa, CREATE_ALWAYS, + FILE_ATTRIBUTE_NORMAL, NULL); + if (fd_err == INVALID_HANDLE_VALUE) { + return STATUS_NOCACHE; + } + + ZeroMemory(&pinfo, sizeof(PROCESS_INFORMATION)); + ZeroMemory(&sinfo, sizeof(STARTUPINFO)); + + sinfo.cb = sizeof(STARTUPINFO); + sinfo.hStdError = fd_err; + sinfo.hStdOutput = fd_out; + sinfo.hStdInput = GetStdHandle(STD_INPUT_HANDLE); + sinfo.dwFlags |= STARTF_USESTDHANDLES; + + args = argvtos(argv); + + ret = CreateProcessA(argv[0], args, NULL, NULL, TRUE, 0, NULL, NULL, + &sinfo, &pinfo); + + free(args); + CloseHandle(fd_out); + CloseHandle(fd_err); + + if (ret == 0) + return -1; + + WaitForSingleObject(pinfo.hProcess, INFINITE); + GetExitCodeProcess(pinfo.hProcess, &exitcode); + CloseHandle(pinfo.hProcess); + CloseHandle(pinfo.hThread); + + return exitcode; +#else /* possibly slightly faster */ + /* needs fixing to quote commandline options to handle spaces in CCACHE_DIR etc */ + int status = -2; + int fd, std_od = -1, std_ed = -1; + + /* TODO: needs moving after possible exit() below, but before stdout is redirected */ + if (ccache_verbose) { + display_execute_args(argv); + } + + unlink(path_stdout); + std_od = _dup(1); + fd = _open(path_stdout, O_WRONLY|O_CREAT|O_TRUNC|O_EXCL|O_BINARY, 0666); + if (fd == -1) { + exit(STATUS_NOCACHE); + } + _dup2(fd, 1); + _close(fd); + + unlink(path_stderr); + fd = _open(path_stderr, O_WRONLY|O_CREAT|O_TRUNC|O_EXCL|O_BINARY, 0666); + std_ed = _dup(2); + if (fd == -1) { + exit(STATUS_NOCACHE); + } + _dup2(fd, 2); + _close(fd); + + /* Spawn process (_exec* familly doesn't return) */ + status = _spawnv(_P_WAIT, argv[0], (const char **)argv); + + /* Restore descriptors */ + if (std_od != -1) _dup2(std_od, 1); + if (std_ed != -1) _dup2(std_ed, 2); + _flushall(); + + return (status>0); + +#endif + +#else + pid_t pid; + int status; + + pid = fork(); + if (pid == -1) fatal("Failed to fork"); + + if (pid == 0) { + int fd; + + /* TODO: needs moving after possible exit() below, but before stdout is redirected */ + if (ccache_verbose) { + display_execute_args(argv); + } + + unlink(path_stdout); + fd = open(path_stdout, O_WRONLY|O_CREAT|O_TRUNC|O_EXCL|O_BINARY, 0666); + if (fd == -1) { + exit(STATUS_NOCACHE); + } + dup2(fd, 1); + close(fd); + + unlink(path_stderr); + fd = open(path_stderr, O_WRONLY|O_CREAT|O_TRUNC|O_EXCL|O_BINARY, 0666); + if (fd == -1) { + exit(STATUS_NOCACHE); + } + dup2(fd, 2); + close(fd); + + exit(execv(argv[0], argv)); + } + + if (waitpid(pid, &status, 0) != pid) { + fatal("waitpid failed"); + } + + if (WEXITSTATUS(status) == 0 && WIFSIGNALED(status)) { + return -1; + } + + return WEXITSTATUS(status); +#endif +} + + +/* + find an executable by name in $PATH. Exclude any that are links to exclude_name +*/ +char *find_executable(const char *name, const char *exclude_name) +{ +#if _WIN32 + (void)exclude_name; + DWORD ret; + char namebuf[MAX_PATH]; + + ret = SearchPathA(getenv("CCACHE_PATH"), name, ".exe", + sizeof(namebuf), namebuf, NULL); + if (ret != 0) { + return x_strdup(namebuf); + } + + return NULL; +#else + char *path; + char *tok; + struct stat st1, st2; + + if (*name == '/') { + return x_strdup(name); + } + + path = getenv("CCACHE_PATH"); + if (!path) { + path = getenv("PATH"); + } + if (!path) { + cc_log("no PATH variable!?\n"); + stats_update(STATS_ENVIRONMMENT); + return NULL; + } + + path = x_strdup(path); + + /* search the path looking for the first compiler of the right name + that isn't us */ + for (tok=strtok(path,":"); tok; tok = strtok(NULL, ":")) { + char *fname; + x_asprintf(&fname, "%s/%s", tok, name); + /* look for a normal executable file */ + if (access(fname, X_OK) == 0 && + lstat(fname, &st1) == 0 && + stat(fname, &st2) == 0 && + S_ISREG(st2.st_mode)) { + /* if its a symlink then ensure it doesn't + point at something called exclude_name */ + if (S_ISLNK(st1.st_mode)) { + char *buf = x_realpath(fname); + if (buf) { + char *p = str_basename(buf); + if (strcmp(p, exclude_name) == 0) { + /* its a link to "ccache" ! */ + free(p); + free(buf); + continue; + } + free(buf); + free(p); + } + } + + /* found it! */ + free(path); + return fname; + } + free(fname); + } + + return NULL; +#endif +} + +void display_execute_args(char **argv) +{ + if (argv) { + printf("ccache executing: "); + while (*argv) { + printf("%s ", *argv); + ++argv; + } + printf("\n"); + fflush(stdout); + } +} diff --git a/CCache/hash.c b/CCache/hash.c new file mode 100644 index 0000000..d0ce8a6 --- /dev/null +++ b/CCache/hash.c @@ -0,0 +1,80 @@ +/* + Copyright (C) Andrew Tridgell 2002 + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. +*/ +/* + simple front-end functions to mdfour code +*/ + +#include "ccache.h" + +static struct mdfour md; + +void hash_buffer(const char *s, int len) +{ + mdfour_update(&md, (unsigned char *)s, len); +} + +void hash_start(void) +{ + mdfour_begin(&md); +} + +void hash_string(const char *s) +{ + hash_buffer(s, strlen(s)); +} + +void hash_int(int x) +{ + hash_buffer((char *)&x, sizeof(x)); +} + +/* add contents of a file to the hash */ +void hash_file(const char *fname) +{ + char buf[1024]; + int fd, n; + + fd = open(fname, O_RDONLY|O_BINARY); + if (fd == -1) { + cc_log("Failed to open %s\n", fname); + fatal("hash_file"); + } + + while ((n = read(fd, buf, sizeof(buf))) > 0) { + hash_buffer(buf, n); + } + close(fd); +} + +/* return the hash result as a static string */ +char *hash_result(void) +{ + unsigned char sum[16]; + static char ret[53]; + int i; + + hash_buffer(NULL, 0); + mdfour_result(&md, sum); + + for (i=0;i<16;i++) { + sprintf(&ret[i*2], "%02x", (unsigned)sum[i]); + } + sprintf(&ret[i*2], "-%u", (unsigned)md.totalN); + + return ret; +} diff --git a/CCache/install-sh b/CCache/install-sh new file mode 100755 index 0000000..5871924 --- /dev/null +++ b/CCache/install-sh @@ -0,0 +1,238 @@ +#! /bin/sh +# +# install - install a program, script, or datafile +# This comes from X11R5. +# +# Calling this script install-sh is preferred over install.sh, to prevent +# `make' implicit rules from creating a file called install from it +# when there is no Makefile. +# +# This script is compatible with the BSD install script, but was written +# from scratch. +# + + +# set DOITPROG to echo to test this script + +# Don't use :- since 4.3BSD and earlier shells don't like it. +doit="${DOITPROG-}" + + +# put in absolute paths if you don't have them in your path; or use env. vars. + +mvprog="${MVPROG-mv}" +cpprog="${CPPROG-cp}" +chmodprog="${CHMODPROG-chmod}" +chownprog="${CHOWNPROG-chown}" +chgrpprog="${CHGRPPROG-chgrp}" +stripprog="${STRIPPROG-strip}" +rmprog="${RMPROG-rm}" +mkdirprog="${MKDIRPROG-mkdir}" + +transformbasename="" +transform_arg="" +instcmd="$mvprog" +chmodcmd="$chmodprog 0755" +chowncmd="" +chgrpcmd="" +stripcmd="" +rmcmd="$rmprog -f" +mvcmd="$mvprog" +src="" +dst="" +dir_arg="" + +while [ x"$1" != x ]; do + case $1 in + -c) instcmd="$cpprog" + shift + continue;; + + -d) dir_arg=true + shift + continue;; + + -m) chmodcmd="$chmodprog $2" + shift + shift + continue;; + + -o) chowncmd="$chownprog $2" + shift + shift + continue;; + + -g) chgrpcmd="$chgrpprog $2" + shift + shift + continue;; + + -s) stripcmd="$stripprog" + shift + continue;; + + -t=*) transformarg=`echo $1 | sed 's/-t=//'` + shift + continue;; + + -b=*) transformbasename=`echo $1 | sed 's/-b=//'` + shift + continue;; + + *) if [ x"$src" = x ] + then + src=$1 + else + # this colon is to work around a 386BSD /bin/sh bug + : + dst=$1 + fi + shift + continue;; + esac +done + +if [ x"$src" = x ] +then + echo "install: no input file specified" + exit 1 +else + true +fi + +if [ x"$dir_arg" != x ]; then + dst=$src + src="" + + if [ -d $dst ]; then + instcmd=: + else + instcmd=mkdir + fi +else + +# Waiting for this to be detected by the "$instcmd $src $dsttmp" command +# might cause directories to be created, which would be especially bad +# if $src (and thus $dsttmp) contains '*'. + + if [ -f $src -o -d $src ] + then + true + else + echo "install: $src does not exist" + exit 1 + fi + + if [ x"$dst" = x ] + then + echo "install: no destination specified" + exit 1 + else + true + fi + +# If destination is a directory, append the input filename; if your system +# does not like double slashes in filenames, you may need to add some logic + + if [ -d $dst ] + then + dst="$dst"/`basename $src` + else + true + fi +fi + +## this sed command emulates the dirname command +dstdir=`echo $dst | sed -e 's,[^/]*$,,;s,/$,,;s,^$,.,'` + +# Make sure that the destination directory exists. +# this part is taken from Noah Friedman's mkinstalldirs script + +# Skip lots of stat calls in the usual case. +if [ ! -d "$dstdir" ]; then +defaultIFS=' +' +IFS="${IFS-${defaultIFS}}" + +oIFS="${IFS}" +# Some sh's can't handle IFS=/ for some reason. +IFS='%' +set - `echo ${dstdir} | sed -e 's@/@%@g' -e 's@^%@/@'` +IFS="${oIFS}" + +pathcomp='' + +while [ $# -ne 0 ] ; do + pathcomp="${pathcomp}${1}" + shift + + if [ ! -d "${pathcomp}" ] ; + then + $mkdirprog "${pathcomp}" + else + true + fi + + pathcomp="${pathcomp}/" +done +fi + +if [ x"$dir_arg" != x ] +then + $doit $instcmd $dst && + + if [ x"$chowncmd" != x ]; then $doit $chowncmd $dst; else true ; fi && + if [ x"$chgrpcmd" != x ]; then $doit $chgrpcmd $dst; else true ; fi && + if [ x"$stripcmd" != x ]; then $doit $stripcmd $dst; else true ; fi && + if [ x"$chmodcmd" != x ]; then $doit $chmodcmd $dst; else true ; fi +else + +# If we're going to rename the final executable, determine the name now. + + if [ x"$transformarg" = x ] + then + dstfile=`basename $dst` + else + dstfile=`basename $dst $transformbasename | + sed $transformarg`$transformbasename + fi + +# don't allow the sed command to completely eliminate the filename + + if [ x"$dstfile" = x ] + then + dstfile=`basename $dst` + else + true + fi + +# Make a temp file name in the proper directory. + + dsttmp=$dstdir/#inst.$$# + +# Move or copy the file name to the temp name + + $doit $instcmd $src $dsttmp && + + trap "rm -f ${dsttmp}" 0 && + +# and set any options; do chmod last to preserve setuid bits + +# If any of these fail, we abort the whole thing. If we want to +# ignore errors from any of these, just make sure not to ignore +# errors from the above "$doit $instcmd $src $dsttmp" command. + + if [ x"$chowncmd" != x ]; then $doit $chowncmd $dsttmp; else true;fi && + if [ x"$chgrpcmd" != x ]; then $doit $chgrpcmd $dsttmp; else true;fi && + if [ x"$stripcmd" != x ]; then $doit $stripcmd $dsttmp; else true;fi && + if [ x"$chmodcmd" != x ]; then $doit $chmodcmd $dsttmp; else true;fi && + +# Now rename the file to the real destination. + + $doit $rmcmd -f $dstdir/$dstfile && + $doit $mvcmd $dsttmp $dstdir/$dstfile + +fi && + + +exit 0 diff --git a/CCache/mdfour.c b/CCache/mdfour.c new file mode 100644 index 0000000..b098e02 --- /dev/null +++ b/CCache/mdfour.c @@ -0,0 +1,284 @@ +/* + a implementation of MD4 designed for use in the SMB authentication protocol + Copyright (C) Andrew Tridgell 1997-1998. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. +*/ + +#include "ccache.h" + +/* NOTE: This code makes no attempt to be fast! + + It assumes that a int is at least 32 bits long +*/ + +static struct mdfour *m; + +#define MASK32 (0xffffffff) + +#define F(X,Y,Z) ((((X)&(Y)) | ((~(X))&(Z)))) +#define G(X,Y,Z) ((((X)&(Y)) | ((X)&(Z)) | ((Y)&(Z)))) +#define H(X,Y,Z) (((X)^(Y)^(Z))) +#define lshift(x,s) (((((x)<<(s))&MASK32) | (((x)>>(32-(s)))&MASK32))) + +#define ROUND1(a,b,c,d,k,s) a = lshift((a + F(b,c,d) + M[k])&MASK32, s) +#define ROUND2(a,b,c,d,k,s) a = lshift((a + G(b,c,d) + M[k] + 0x5A827999)&MASK32,s) +#define ROUND3(a,b,c,d,k,s) a = lshift((a + H(b,c,d) + M[k] + 0x6ED9EBA1)&MASK32,s) + +/* this applies md4 to 64 byte chunks */ +static void mdfour64(uint32 *M) +{ + uint32 AA, BB, CC, DD; + uint32 A,B,C,D; + + A = m->A; B = m->B; C = m->C; D = m->D; + AA = A; BB = B; CC = C; DD = D; + + ROUND1(A,B,C,D, 0, 3); ROUND1(D,A,B,C, 1, 7); + ROUND1(C,D,A,B, 2, 11); ROUND1(B,C,D,A, 3, 19); + ROUND1(A,B,C,D, 4, 3); ROUND1(D,A,B,C, 5, 7); + ROUND1(C,D,A,B, 6, 11); ROUND1(B,C,D,A, 7, 19); + ROUND1(A,B,C,D, 8, 3); ROUND1(D,A,B,C, 9, 7); + ROUND1(C,D,A,B, 10, 11); ROUND1(B,C,D,A, 11, 19); + ROUND1(A,B,C,D, 12, 3); ROUND1(D,A,B,C, 13, 7); + ROUND1(C,D,A,B, 14, 11); ROUND1(B,C,D,A, 15, 19); + + + ROUND2(A,B,C,D, 0, 3); ROUND2(D,A,B,C, 4, 5); + ROUND2(C,D,A,B, 8, 9); ROUND2(B,C,D,A, 12, 13); + ROUND2(A,B,C,D, 1, 3); ROUND2(D,A,B,C, 5, 5); + ROUND2(C,D,A,B, 9, 9); ROUND2(B,C,D,A, 13, 13); + ROUND2(A,B,C,D, 2, 3); ROUND2(D,A,B,C, 6, 5); + ROUND2(C,D,A,B, 10, 9); ROUND2(B,C,D,A, 14, 13); + ROUND2(A,B,C,D, 3, 3); ROUND2(D,A,B,C, 7, 5); + ROUND2(C,D,A,B, 11, 9); ROUND2(B,C,D,A, 15, 13); + + ROUND3(A,B,C,D, 0, 3); ROUND3(D,A,B,C, 8, 9); + ROUND3(C,D,A,B, 4, 11); ROUND3(B,C,D,A, 12, 15); + ROUND3(A,B,C,D, 2, 3); ROUND3(D,A,B,C, 10, 9); + ROUND3(C,D,A,B, 6, 11); ROUND3(B,C,D,A, 14, 15); + ROUND3(A,B,C,D, 1, 3); ROUND3(D,A,B,C, 9, 9); + ROUND3(C,D,A,B, 5, 11); ROUND3(B,C,D,A, 13, 15); + ROUND3(A,B,C,D, 3, 3); ROUND3(D,A,B,C, 11, 9); + ROUND3(C,D,A,B, 7, 11); ROUND3(B,C,D,A, 15, 15); + + A += AA; B += BB; + C += CC; D += DD; + + A &= MASK32; B &= MASK32; + C &= MASK32; D &= MASK32; + + m->A = A; m->B = B; m->C = C; m->D = D; +} + +static void copy64(uint32 *M, const unsigned char *in) +{ + int i; + + for (i=0;i<16;i++) + M[i] = (in[i*4+3]<<24) | (in[i*4+2]<<16) | + (in[i*4+1]<<8) | (in[i*4+0]<<0); +} + +static void copy4(unsigned char *out,uint32 x) +{ + out[0] = x&0xFF; + out[1] = (x>>8)&0xFF; + out[2] = (x>>16)&0xFF; + out[3] = (x>>24)&0xFF; +} + +void mdfour_begin(struct mdfour *md) +{ + md->A = 0x67452301; + md->B = 0xefcdab89; + md->C = 0x98badcfe; + md->D = 0x10325476; + md->totalN = 0; + md->tail_len = 0; +} + + +static void mdfour_tail(const unsigned char *in, int n) +{ + unsigned char buf[128]; + uint32 M[16]; + uint32 b; + + m->totalN += n; + + b = m->totalN * 8; + + memset(buf, 0, 128); + if (n) memcpy(buf, in, n); + buf[n] = 0x80; + + if (n <= 55) { + copy4(buf+56, b); + copy64(M, buf); + mdfour64(M); + } else { + copy4(buf+120, b); + copy64(M, buf); + mdfour64(M); + copy64(M, buf+64); + mdfour64(M); + } +} + +void mdfour_update(struct mdfour *md, const unsigned char *in, int n) +{ + uint32 M[16]; + + m = md; + + if (in == NULL) { + mdfour_tail(md->tail, md->tail_len); + return; + } + + if (md->tail_len) { + int len = 64 - md->tail_len; + if (len > n) len = n; + memcpy(md->tail+md->tail_len, in, len); + md->tail_len += len; + n -= len; + in += len; + if (md->tail_len == 64) { + copy64(M, md->tail); + mdfour64(M); + m->totalN += 64; + md->tail_len = 0; + } + } + + while (n >= 64) { + copy64(M, in); + mdfour64(M); + in += 64; + n -= 64; + m->totalN += 64; + } + + if (n) { + memcpy(md->tail, in, n); + md->tail_len = n; + } +} + + +void mdfour_result(struct mdfour *md, unsigned char *out) +{ + m = md; + + copy4(out, m->A); + copy4(out+4, m->B); + copy4(out+8, m->C); + copy4(out+12, m->D); +} + + +void mdfour(unsigned char *out, const unsigned char *in, int n) +{ + struct mdfour md; + mdfour_begin(&md); + mdfour_update(&md, in, n); + mdfour_update(&md, NULL, 0); + mdfour_result(&md, out); +} + +#ifdef TEST_MDFOUR +static void file_checksum1(char *fname) +{ + int fd, i; + struct mdfour md; + unsigned char buf[1024], sum[16]; + unsigned chunk; + + fd = open(fname,O_RDONLY|O_BINARY); + if (fd == -1) { + perror("fname"); + exit(1); + } + + chunk = 1 + random() % (sizeof(buf) - 1); + + mdfour_begin(&md); + + while (1) { + int n = read(fd, buf, chunk); + if (n >= 0) { + mdfour_update(&md, buf, n); + } + if (n < chunk) break; + } + + close(fd); + + mdfour_update(&md, NULL, 0); + + mdfour_result(&md, sum); + + for (i=0;i<16;i++) + printf("%02x", sum[i]); + printf("\n"); +} + +#if 0 +#include "../md4.h" + +static void file_checksum2(char *fname) +{ + int fd, i; + MDstruct md; + unsigned char buf[64], sum[16]; + + fd = open(fname,O_RDONLY|O_BINARY); + if (fd == -1) { + perror("fname"); + exit(1); + } + + MDbegin(&md); + + while (1) { + int n = read(fd, buf, sizeof(buf)); + if (n <= 0) break; + MDupdate(&md, buf, n*8); + } + + if (!md.done) { + MDupdate(&md, buf, 0); + } + + close(fd); + + memcpy(sum, md.buffer, 16); + + for (i=0;i<16;i++) + printf("%02x", sum[i]); + printf("\n"); +} +#endif + + int main(int argc, char *argv[]) +{ + file_checksum1(argv[1]); +#if 0 + file_checksum2(argv[1]); +#endif + return 0; +} +#endif diff --git a/CCache/mdfour.h b/CCache/mdfour.h new file mode 100644 index 0000000..92ef2f8 --- /dev/null +++ b/CCache/mdfour.h @@ -0,0 +1,36 @@ +/* + Unix SMB/Netbios implementation. + Version 1.9. + a implementation of MD4 designed for use in the SMB authentication protocol + Copyright (C) Andrew Tridgell 1997-1998. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. +*/ + +struct mdfour { + uint32 A, B, C, D; + uint32 totalN; + unsigned char tail[64]; + unsigned tail_len; +}; + +void mdfour_begin(struct mdfour *md); +void mdfour_update(struct mdfour *md, const unsigned char *in, int n); +void mdfour_result(struct mdfour *md, unsigned char *out); +void mdfour(unsigned char *out, const unsigned char *in, int n); + + + + diff --git a/CCache/packaging/README b/CCache/packaging/README new file mode 100644 index 0000000..fadc342 --- /dev/null +++ b/CCache/packaging/README @@ -0,0 +1,5 @@ +These packaging files are contributd by users of ccache. I do not +maintain them, and they may well need updating before you use them. + +I don't distribute binary packages of ccache myself, but if you wish +to add ccache to a distribution then that's OK diff --git a/CCache/packaging/ccache.spec b/CCache/packaging/ccache.spec new file mode 100644 index 0000000..0972121 --- /dev/null +++ b/CCache/packaging/ccache.spec @@ -0,0 +1,37 @@ +Summary: Compiler Cache +Name: ccache +Version: 2.3 +Release: 1 +Group: Development/Languages +License: GPL +URL: http://ccache.samba.org/ +Source: ccache-%{version}.tar.gz +BuildRoot: %{_tmppath}/%{name}-%{version}-root + +%description +ccache caches gcc output files + +%prep +%setup -q + +%build +%configure +make + +install -d -m 0755 $RPM_BUILD_ROOT%{_bindir} +install -m 0755 ccache $RPM_BUILD_ROOT%{_bindir} +install -d -m 0755 $RPM_BUILD_ROOT%{_mandir}/man1 +install -m 0644 ccache.1 $RPM_BUILD_ROOT%{_mandir}/man1 + +%files +%defattr(-,root,root) +%doc README +%{_mandir}/man1/ccache.1* +%{_bindir}/ccache + +%clean +[ "$RPM_BUILD_ROOT" != "/" ] && rm -rf $RPM_BUILD_ROOT + +%changelog +* Mon Apr 01 2002 Peter Jones +- Created the package diff --git a/CCache/snprintf.c b/CCache/snprintf.c new file mode 100644 index 0000000..32187c1 --- /dev/null +++ b/CCache/snprintf.c @@ -0,0 +1,962 @@ +/* + * Copyright Patrick Powell 1995 + * This code is based on code written by Patrick Powell (papowell@astart.com) + * It may be used for any purpose as long as this notice remains intact + * on all source code distributions + */ + +/************************************************************** + * Original: + * Patrick Powell Tue Apr 11 09:48:21 PDT 1995 + * A bombproof version of doprnt (dopr) included. + * Sigh. This sort of thing is always nasty do deal with. Note that + * the version here does not include floating point... + * + * snprintf() is used instead of sprintf() as it does limit checks + * for string length. This covers a nasty loophole. + * + * The other functions are there to prevent NULL pointers from + * causing nast effects. + * + * More Recently: + * Brandon Long 9/15/96 for mutt 0.43 + * This was ugly. It is still ugly. I opted out of floating point + * numbers, but the formatter understands just about everything + * from the normal C string format, at least as far as I can tell from + * the Solaris 2.5 printf(3S) man page. + * + * Brandon Long 10/22/97 for mutt 0.87.1 + * Ok, added some minimal floating point support, which means this + * probably requires libm on most operating systems. Don't yet + * support the exponent (e,E) and sigfig (g,G). Also, fmtint() + * was pretty badly broken, it just wasn't being exercised in ways + * which showed it, so that's been fixed. Also, formated the code + * to mutt conventions, and removed dead code left over from the + * original. Also, there is now a builtin-test, just compile with: + * gcc -DTEST_SNPRINTF -o snprintf snprintf.c -lm + * and run snprintf for results. + * + * Thomas Roessler 01/27/98 for mutt 0.89i + * The PGP code was using unsigned hexadecimal formats. + * Unfortunately, unsigned formats simply didn't work. + * + * Michael Elkins 03/05/98 for mutt 0.90.8 + * The original code assumed that both snprintf() and vsnprintf() were + * missing. Some systems only have snprintf() but not vsnprintf(), so + * the code is now broken down under HAVE_SNPRINTF and HAVE_VSNPRINTF. + * + * Andrew Tridgell (tridge@samba.org) Oct 1998 + * fixed handling of %.0f + * added test for HAVE_LONG_DOUBLE + * + * tridge@samba.org, idra@samba.org, April 2001 + * got rid of fcvt code (twas buggy and made testing harder) + * added C99 semantics + * + **************************************************************/ + +#ifndef NO_CONFIG_H /* for some tests */ +#include "config.h" +#endif + +#ifdef HAVE_STRING_H +#include +#endif + +#ifdef HAVE_STRINGS_H +#include +#endif +#ifdef HAVE_CTYPE_H +#include +#endif +#include +#include +#ifdef HAVE_STDLIB_H +#include +#endif + +#if defined(HAVE_SNPRINTF) && defined(HAVE_VSNPRINTF) && defined(HAVE_C99_VSNPRINTF) +/* only include stdio.h if we are not re-defining snprintf or vsnprintf */ +#include + /* make the compiler happy with an empty file */ + void dummy_snprintf(void) {} +#else + +#ifdef HAVE_LONG_DOUBLE +#define LDOUBLE long double +#else +#define LDOUBLE double +#endif + +#ifdef HAVE_LONG_LONG +#define LLONG long long +#else +#define LLONG long +#endif + +static size_t dopr(char *buffer, size_t maxlen, const char *format, + va_list args); +static void fmtstr(char *buffer, size_t *currlen, size_t maxlen, + char *value, int flags, int min, int max); +static void fmtint(char *buffer, size_t *currlen, size_t maxlen, + long value, int base, int min, int max, int flags); +static void fmtfp(char *buffer, size_t *currlen, size_t maxlen, + LDOUBLE fvalue, int min, int max, int flags); +static void dopr_outch(char *buffer, size_t *currlen, size_t maxlen, char c); + +/* + * dopr(): poor man's version of doprintf + */ + +/* format read states */ +#define DP_S_DEFAULT 0 +#define DP_S_FLAGS 1 +#define DP_S_MIN 2 +#define DP_S_DOT 3 +#define DP_S_MAX 4 +#define DP_S_MOD 5 +#define DP_S_CONV 6 +#define DP_S_DONE 7 + +/* format flags - Bits */ +#define DP_F_MINUS (1 << 0) +#define DP_F_PLUS (1 << 1) +#define DP_F_SPACE (1 << 2) +#define DP_F_NUM (1 << 3) +#define DP_F_ZERO (1 << 4) +#define DP_F_UP (1 << 5) +#define DP_F_UNSIGNED (1 << 6) + +/* Conversion Flags */ +#define DP_C_SHORT 1 +#define DP_C_LONG 2 +#define DP_C_LDOUBLE 3 +#define DP_C_LLONG 4 + +#define char_to_int(p) ((p)- '0') +#ifndef MAX +#define MAX(p,q) (((p) >= (q)) ? (p) : (q)) +#endif + +static size_t dopr(char *buffer, size_t maxlen, const char *format, va_list args) +{ + char ch; + LLONG value; + LDOUBLE fvalue; + char *strvalue; + int min; + int max; + int state; + int flags; + int cflags; + size_t currlen; + + state = DP_S_DEFAULT; + currlen = flags = cflags = min = 0; + max = -1; + ch = *format++; + + while (state != DP_S_DONE) { + if (ch == '\0') + state = DP_S_DONE; + + switch(state) { + case DP_S_DEFAULT: + if (ch == '%') + state = DP_S_FLAGS; + else + dopr_outch (buffer, &currlen, maxlen, ch); + ch = *format++; + break; + case DP_S_FLAGS: + switch (ch) { + case '-': + flags |= DP_F_MINUS; + ch = *format++; + break; + case '+': + flags |= DP_F_PLUS; + ch = *format++; + break; + case ' ': + flags |= DP_F_SPACE; + ch = *format++; + break; + case '#': + flags |= DP_F_NUM; + ch = *format++; + break; + case '0': + flags |= DP_F_ZERO; + ch = *format++; + break; + default: + state = DP_S_MIN; + break; + } + break; + case DP_S_MIN: + if (isdigit((unsigned char)ch)) { + min = 10*min + char_to_int (ch); + ch = *format++; + } else if (ch == '*') { + min = va_arg (args, int); + ch = *format++; + state = DP_S_DOT; + } else { + state = DP_S_DOT; + } + break; + case DP_S_DOT: + if (ch == '.') { + state = DP_S_MAX; + ch = *format++; + } else { + state = DP_S_MOD; + } + break; + case DP_S_MAX: + if (isdigit((unsigned char)ch)) { + if (max < 0) + max = 0; + max = 10*max + char_to_int (ch); + ch = *format++; + } else if (ch == '*') { + max = va_arg (args, int); + ch = *format++; + state = DP_S_MOD; + } else { + state = DP_S_MOD; + } + break; + case DP_S_MOD: + switch (ch) { + case 'h': + cflags = DP_C_SHORT; + ch = *format++; + break; + case 'l': + cflags = DP_C_LONG; + ch = *format++; + if (ch == 'l') { /* It's a long long */ + cflags = DP_C_LLONG; + ch = *format++; + } + break; + case 'L': + cflags = DP_C_LDOUBLE; + ch = *format++; + break; + default: + break; + } + state = DP_S_CONV; + break; + case DP_S_CONV: + switch (ch) { + case 'd': + case 'i': + if (cflags == DP_C_SHORT) + value = va_arg (args, int); + else if (cflags == DP_C_LONG) + value = va_arg (args, long int); + else if (cflags == DP_C_LLONG) + value = va_arg (args, LLONG); + else + value = va_arg (args, int); + fmtint (buffer, &currlen, maxlen, value, 10, min, max, flags); + break; + case 'o': + flags |= DP_F_UNSIGNED; + if (cflags == DP_C_SHORT) + value = va_arg (args, unsigned int); + else if (cflags == DP_C_LONG) + value = (long)va_arg (args, unsigned long int); + else if (cflags == DP_C_LLONG) + value = (long)va_arg (args, unsigned LLONG); + else + value = (long)va_arg (args, unsigned int); + fmtint (buffer, &currlen, maxlen, value, 8, min, max, flags); + break; + case 'u': + flags |= DP_F_UNSIGNED; + if (cflags == DP_C_SHORT) + value = va_arg (args, unsigned int); + else if (cflags == DP_C_LONG) + value = (long)va_arg (args, unsigned long int); + else if (cflags == DP_C_LLONG) + value = (LLONG)va_arg (args, unsigned LLONG); + else + value = (long)va_arg (args, unsigned int); + fmtint (buffer, &currlen, maxlen, value, 10, min, max, flags); + break; + case 'X': + flags |= DP_F_UP; + case 'x': + flags |= DP_F_UNSIGNED; + if (cflags == DP_C_SHORT) + value = va_arg (args, unsigned int); + else if (cflags == DP_C_LONG) + value = (long)va_arg (args, unsigned long int); + else if (cflags == DP_C_LLONG) + value = (LLONG)va_arg (args, unsigned LLONG); + else + value = (long)va_arg (args, unsigned int); + fmtint (buffer, &currlen, maxlen, value, 16, min, max, flags); + break; + case 'f': + if (cflags == DP_C_LDOUBLE) + fvalue = va_arg (args, LDOUBLE); + else + fvalue = va_arg (args, double); + /* um, floating point? */ + fmtfp (buffer, &currlen, maxlen, fvalue, min, max, flags); + break; + case 'E': + flags |= DP_F_UP; + case 'e': + if (cflags == DP_C_LDOUBLE) + fvalue = va_arg (args, LDOUBLE); + else + fvalue = va_arg (args, double); + break; + case 'G': + flags |= DP_F_UP; + case 'g': + if (cflags == DP_C_LDOUBLE) + fvalue = va_arg (args, LDOUBLE); + else + fvalue = va_arg (args, double); + break; + case 'c': + dopr_outch (buffer, &currlen, maxlen, va_arg (args, int)); + break; + case 's': + strvalue = va_arg (args, char *); + if (!strvalue) strvalue = "(NULL)"; + if (max == -1) { + max = strlen(strvalue); + } + if (min > 0 && max >= 0 && min > max) max = min; + fmtstr (buffer, &currlen, maxlen, strvalue, flags, min, max); + break; + case 'p': + strvalue = (char *)va_arg(args, void *); + fmtint (buffer, &currlen, maxlen, (long) strvalue, 16, min, max, flags); + break; + case 'n': + if (cflags == DP_C_SHORT) { + short int *num; + num = va_arg (args, short int *); + *num = currlen; + } else if (cflags == DP_C_LONG) { + long int *num; + num = va_arg (args, long int *); + *num = (long int)currlen; + } else if (cflags == DP_C_LLONG) { + LLONG *num; + num = va_arg (args, LLONG *); + *num = (LLONG)currlen; + } else { + int *num; + num = va_arg (args, int *); + *num = currlen; + } + break; + case '%': + dopr_outch (buffer, &currlen, maxlen, ch); + break; + case 'w': + /* not supported yet, treat as next char */ + ch = *format++; + break; + default: + /* Unknown, skip */ + break; + } + ch = *format++; + state = DP_S_DEFAULT; + flags = cflags = min = 0; + max = -1; + break; + case DP_S_DONE: + break; + default: + /* hmm? */ + break; /* some picky compilers need this */ + } + } + if (maxlen != 0) { + if (currlen < maxlen - 1) + buffer[currlen] = '\0'; + else if (maxlen > 0) + buffer[maxlen - 1] = '\0'; + } + + return currlen; +} + +static void fmtstr(char *buffer, size_t *currlen, size_t maxlen, + char *value, int flags, int min, int max) +{ + int padlen, strln; /* amount to pad */ + int cnt = 0; + +#ifdef DEBUG_SNPRINTF + printf("fmtstr min=%d max=%d s=[%s]\n", min, max, value); +#endif + if (value == 0) { + value = ""; + } + + for (strln = 0; value[strln]; ++strln); /* strlen */ + padlen = min - strln; + if (padlen < 0) + padlen = 0; + if (flags & DP_F_MINUS) + padlen = -padlen; /* Left Justify */ + + while ((padlen > 0) && (cnt < max)) { + dopr_outch (buffer, currlen, maxlen, ' '); + --padlen; + ++cnt; + } + while (*value && (cnt < max)) { + dopr_outch (buffer, currlen, maxlen, *value++); + ++cnt; + } + while ((padlen < 0) && (cnt < max)) { + dopr_outch (buffer, currlen, maxlen, ' '); + ++padlen; + ++cnt; + } +} + +/* Have to handle DP_F_NUM (ie 0x and 0 alternates) */ + +static void fmtint(char *buffer, size_t *currlen, size_t maxlen, + long value, int base, int min, int max, int flags) +{ + int signvalue = 0; + unsigned long uvalue; + char convert[20]; + int place = 0; + int spadlen = 0; /* amount to space pad */ + int zpadlen = 0; /* amount to zero pad */ + int caps = 0; + + if (max < 0) + max = 0; + + uvalue = value; + + if(!(flags & DP_F_UNSIGNED)) { + if( value < 0 ) { + signvalue = '-'; + uvalue = -value; + } else { + if (flags & DP_F_PLUS) /* Do a sign (+/i) */ + signvalue = '+'; + else if (flags & DP_F_SPACE) + signvalue = ' '; + } + } + + if (flags & DP_F_UP) caps = 1; /* Should characters be upper case? */ + + do { + convert[place++] = + (caps? "0123456789ABCDEF":"0123456789abcdef") + [uvalue % (unsigned)base ]; + uvalue = (uvalue / (unsigned)base ); + } while(uvalue && (place < 20)); + if (place == 20) place--; + convert[place] = 0; + + zpadlen = max - place; + spadlen = min - MAX (max, place) - (signvalue ? 1 : 0); + if (zpadlen < 0) zpadlen = 0; + if (spadlen < 0) spadlen = 0; + if (flags & DP_F_ZERO) { + zpadlen = MAX(zpadlen, spadlen); + spadlen = 0; + } + if (flags & DP_F_MINUS) + spadlen = -spadlen; /* Left Justifty */ + +#ifdef DEBUG_SNPRINTF + printf("zpad: %d, spad: %d, min: %d, max: %d, place: %d\n", + zpadlen, spadlen, min, max, place); +#endif + + /* Spaces */ + while (spadlen > 0) { + dopr_outch (buffer, currlen, maxlen, ' '); + --spadlen; + } + + /* Sign */ + if (signvalue) + dopr_outch (buffer, currlen, maxlen, signvalue); + + /* Zeros */ + if (zpadlen > 0) { + while (zpadlen > 0) { + dopr_outch (buffer, currlen, maxlen, '0'); + --zpadlen; + } + } + + /* Digits */ + while (place > 0) + dopr_outch (buffer, currlen, maxlen, convert[--place]); + + /* Left Justified spaces */ + while (spadlen < 0) { + dopr_outch (buffer, currlen, maxlen, ' '); + ++spadlen; + } +} + +static LDOUBLE abs_val(LDOUBLE value) +{ + LDOUBLE result = value; + + if (value < 0) + result = -value; + + return result; +} + +static LDOUBLE POW10(int exp) +{ + LDOUBLE result = 1; + + while (exp) { + result *= 10; + exp--; + } + + return result; +} + +static LLONG ROUND(LDOUBLE value) +{ + LLONG intpart; + + intpart = (LLONG)value; + value = value - intpart; + if (value >= 0.5) intpart++; + + return intpart; +} + +/* a replacement for modf that doesn't need the math library. Should + be portable, but slow */ +static double my_modf(double x0, double *iptr) +{ + int i; + long l; + double x = x0; + double f = 1.0; + + for (i=0;i<100;i++) { + l = (long)x; + if (l <= (x+1) && l >= (x-1)) break; + x *= 0.1; + f *= 10.0; + } + + if (i == 100) { + /* yikes! the number is beyond what we can handle. What do we do? */ + (*iptr) = 0; + return 0; + } + + if (i != 0) { + double i2; + double ret; + + ret = my_modf(x0-l*f, &i2); + (*iptr) = l*f + i2; + return ret; + } + + (*iptr) = l; + return x - (*iptr); +} + + +static void fmtfp (char *buffer, size_t *currlen, size_t maxlen, + LDOUBLE fvalue, int min, int max, int flags) +{ + int signvalue = 0; + double ufvalue; + char iconvert[311]; + char fconvert[311]; + int iplace = 0; + int fplace = 0; + int padlen = 0; /* amount to pad */ + int zpadlen = 0; + int caps = 0; + int index; + double intpart; + double fracpart; + double temp; + + /* + * AIX manpage says the default is 0, but Solaris says the default + * is 6, and sprintf on AIX defaults to 6 + */ + if (max < 0) + max = 6; + + ufvalue = abs_val (fvalue); + + if (fvalue < 0) { + signvalue = '-'; + } else { + if (flags & DP_F_PLUS) { /* Do a sign (+/i) */ + signvalue = '+'; + } else { + if (flags & DP_F_SPACE) + signvalue = ' '; + } + } + +#if 0 + if (flags & DP_F_UP) caps = 1; /* Should characters be upper case? */ +#endif + +#if 0 + if (max == 0) ufvalue += 0.5; /* if max = 0 we must round */ +#endif + + /* + * Sorry, we only support 16 digits past the decimal because of our + * conversion method + */ + if (max > 16) + max = 16; + + /* We "cheat" by converting the fractional part to integer by + * multiplying by a factor of 10 + */ + + temp = ufvalue; + my_modf(temp, &intpart); + + fracpart = ROUND((POW10(max)) * (ufvalue - intpart)); + + if (fracpart >= POW10(max)) { + intpart++; + fracpart -= POW10(max); + } + + + /* Convert integer part */ + do { + temp = intpart; + my_modf(intpart*0.1, &intpart); + temp = temp*0.1; + index = (int) ((temp -intpart +0.05)* 10.0); + /* index = (int) (((double)(temp*0.1) -intpart +0.05) *10.0); */ + /* printf ("%llf, %f, %x\n", temp, intpart, index); */ + iconvert[iplace++] = + (caps? "0123456789ABCDEF":"0123456789abcdef")[index]; + } while (intpart && (iplace < 311)); + if (iplace == 311) iplace--; + iconvert[iplace] = 0; + + /* Convert fractional part */ + if (fracpart) + { + do { + temp = fracpart; + my_modf(fracpart*0.1, &fracpart); + temp = temp*0.1; + index = (int) ((temp -fracpart +0.05)* 10.0); + /* index = (int) ((((temp/10) -fracpart) +0.05) *10); */ + /* printf ("%lf, %lf, %ld\n", temp, fracpart, index); */ + fconvert[fplace++] = + (caps? "0123456789ABCDEF":"0123456789abcdef")[index]; + } while(fracpart && (fplace < 311)); + if (fplace == 311) fplace--; + } + fconvert[fplace] = 0; + + /* -1 for decimal point, another -1 if we are printing a sign */ + padlen = min - iplace - max - 1 - ((signvalue) ? 1 : 0); + zpadlen = max - fplace; + if (zpadlen < 0) zpadlen = 0; + if (padlen < 0) + padlen = 0; + if (flags & DP_F_MINUS) + padlen = -padlen; /* Left Justifty */ + + if ((flags & DP_F_ZERO) && (padlen > 0)) { + if (signvalue) { + dopr_outch (buffer, currlen, maxlen, signvalue); + --padlen; + signvalue = 0; + } + while (padlen > 0) { + dopr_outch (buffer, currlen, maxlen, '0'); + --padlen; + } + } + while (padlen > 0) { + dopr_outch (buffer, currlen, maxlen, ' '); + --padlen; + } + if (signvalue) + dopr_outch (buffer, currlen, maxlen, signvalue); + + while (iplace > 0) + dopr_outch (buffer, currlen, maxlen, iconvert[--iplace]); + +#ifdef DEBUG_SNPRINTF + printf("fmtfp: fplace=%d zpadlen=%d\n", fplace, zpadlen); +#endif + + /* + * Decimal point. This should probably use locale to find the correct + * char to print out. + */ + if (max > 0) { + dopr_outch (buffer, currlen, maxlen, '.'); + + while (fplace > 0) + dopr_outch (buffer, currlen, maxlen, fconvert[--fplace]); + } + + while (zpadlen > 0) { + dopr_outch (buffer, currlen, maxlen, '0'); + --zpadlen; + } + + while (padlen < 0) { + dopr_outch (buffer, currlen, maxlen, ' '); + ++padlen; + } +} + +static void dopr_outch(char *buffer, size_t *currlen, size_t maxlen, char c) +{ + if (*currlen < maxlen) { + buffer[(*currlen)] = c; + } + (*currlen)++; +} + +/* yes this really must be a ||. Don't muck with this (tridge) */ +#if !defined(HAVE_VSNPRINTF) || !defined(HAVE_C99_VSNPRINTF) + int vsnprintf (char *str, size_t count, const char *fmt, va_list args) +{ + return dopr(str, count, fmt, args); +} +#endif + +/* yes this really must be a ||. Don't muck wiith this (tridge) + * + * The logic for these two is that we need our own definition if the + * OS *either* has no definition of *sprintf, or if it does have one + * that doesn't work properly according to the autoconf test. Perhaps + * these should really be smb_snprintf to avoid conflicts with buggy + * linkers? -- mbp + */ +#if !defined(HAVE_SNPRINTF) || !defined(HAVE_C99_SNPRINTF) + int snprintf(char *str,size_t count,const char *fmt,...) +{ + size_t ret; + va_list ap; + + va_start(ap, fmt); + ret = vsnprintf(str, count, fmt, ap); + va_end(ap); + return ret; +} +#endif + +#endif + +#ifndef HAVE_VASPRINTF + int vasprintf(char **ptr, const char *format, va_list ap) +{ + int ret; + + ret = vsnprintf(0, 0, format, ap); + if (ret <= 0) return ret; + + (*ptr) = (char *)malloc(ret+1); + if (!*ptr) return -1; + ret = vsnprintf(*ptr, ret+1, format, ap); + + return ret; +} +#endif + + +#ifndef HAVE_ASPRINTF + int asprintf(char **ptr, const char *format, ...) +{ + va_list ap; + int ret; + + *ptr = 0; + va_start(ap, format); + ret = vasprintf(ptr, format, ap); + va_end(ap); + + return ret; +} +#endif + +#ifndef HAVE_VSYSLOG +#ifdef HAVE_SYSLOG + void vsyslog (int facility_priority, char *format, va_list arglist) +{ + char *msg = 0; + vasprintf(&msg, format, arglist); + if (!msg) + return; + syslog(facility_priority, "%s", msg); + free(msg); +} +#endif /* HAVE_SYSLOG */ +#endif /* HAVE_VSYSLOG */ + +#ifdef TEST_SNPRINTF + + int sprintf(char *str,const char *fmt,...); + + int main (void) +{ + char buf1[1024]; + char buf2[1024]; + char *fp_fmt[] = { + "%1.1f", + "%-1.5f", + "%1.5f", + "%123.9f", + "%10.5f", + "% 10.5f", + "%+22.9f", + "%+4.9f", + "%01.3f", + "%4f", + "%3.1f", + "%3.2f", + "%.0f", + "%f", + "-16.16f", + 0 + }; + double fp_nums[] = { 6442452944.1234, -1.5, 134.21, 91340.2, 341.1234, 0203.9, 0.96, 0.996, + 0.9996, 1.996, 4.136, 0}; + char *int_fmt[] = { + "%-1.5d", + "%1.5d", + "%123.9d", + "%5.5d", + "%10.5d", + "% 10.5d", + "%+22.33d", + "%01.3d", + "%4d", + "%d", + 0 + }; + long int_nums[] = { -1, 134, 91340, 341, 0203, 0}; + char *str_fmt[] = { + "10.5s", + "5.10s", + "10.1s", + "0.10s", + "10.0s", + "1.10s", + "%s", + "%.1s", + "%.10s", + "%10s", + 0 + }; + char *str_vals[] = {"hello", "a", "", "a longer string", 0}; + int x, y; + int fail = 0; + int num = 0; + + printf ("Testing snprintf format codes against system sprintf...\n"); + + for (x = 0; fp_fmt[x] ; x++) { + for (y = 0; fp_nums[y] != 0 ; y++) { + int l1 = snprintf(0, 0, fp_fmt[x], fp_nums[y]); + int l2 = snprintf(buf1, sizeof(buf1), fp_fmt[x], fp_nums[y]); + sprintf (buf2, fp_fmt[x], fp_nums[y]); + if (strcmp (buf1, buf2)) { + printf("snprintf doesn't match Format: %s\n\tsnprintf = [%s]\n\t sprintf = [%s]\n", + fp_fmt[x], buf1, buf2); + fail++; + } + if (l1 != l2) { + printf("snprintf l1 != l2 (%d %d) %s\n", l1, l2, fp_fmt[x]); + fail++; + } + num++; + } + } + + for (x = 0; int_fmt[x] ; x++) { + for (y = 0; int_nums[y] != 0 ; y++) { + int l1 = snprintf(0, 0, int_fmt[x], int_nums[y]); + int l2 = snprintf(buf1, sizeof(buf1), int_fmt[x], int_nums[y]); + sprintf (buf2, int_fmt[x], int_nums[y]); + if (strcmp (buf1, buf2)) { + printf("snprintf doesn't match Format: %s\n\tsnprintf = [%s]\n\t sprintf = [%s]\n", + int_fmt[x], buf1, buf2); + fail++; + } + if (l1 != l2) { + printf("snprintf l1 != l2 (%d %d) %s\n", l1, l2, int_fmt[x]); + fail++; + } + num++; + } + } + + for (x = 0; str_fmt[x] ; x++) { + for (y = 0; str_vals[y] != 0 ; y++) { + int l1 = snprintf(0, 0, str_fmt[x], str_vals[y]); + int l2 = snprintf(buf1, sizeof(buf1), str_fmt[x], str_vals[y]); + sprintf (buf2, str_fmt[x], str_vals[y]); + if (strcmp (buf1, buf2)) { + printf("snprintf doesn't match Format: %s\n\tsnprintf = [%s]\n\t sprintf = [%s]\n", + str_fmt[x], buf1, buf2); + fail++; + } + if (l1 != l2) { + printf("snprintf l1 != l2 (%d %d) %s\n", l1, l2, str_fmt[x]); + fail++; + } + num++; + } + } + + printf ("%d tests failed out of %d.\n", fail, num); + + printf("seeing how many digits we support\n"); + { + double v0 = 0.12345678901234567890123456789012345678901; + for (x=0; x<100; x++) { + snprintf(buf1, sizeof(buf1), "%1.1f", v0*pow(10, x)); + sprintf(buf2, "%1.1f", v0*pow(10, x)); + if (strcmp(buf1, buf2)) { + printf("we seem to support %d digits\n", x-1); + break; + } + } + } + + return 0; +} +#endif /* SNPRINTF_TEST */ diff --git a/CCache/stats.c b/CCache/stats.c new file mode 100644 index 0000000..92bc4a8 --- /dev/null +++ b/CCache/stats.c @@ -0,0 +1,361 @@ +/* + Copyright (C) Andrew Tridgell 2002 + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. +*/ +/* + routines to handle the stats files + + the stats file is stored one per cache subdirectory to make this more + scalable + */ + +#include "ccache.h" + +extern char *stats_file; +extern char *cache_dir; + +#define STATS_VERSION 1 + +#define FLAG_NOZERO 1 /* don't zero with the -z option */ +#define FLAG_ALWAYS 2 /* always show, even if zero */ + +static struct { + enum stats stat; + char *message; + void (*fn)(unsigned ); + unsigned flags; +} stats_info[] = { + { STATS_CACHED, "cache hit ", NULL, FLAG_ALWAYS }, + { STATS_TOCACHE, "cache miss ", NULL, FLAG_ALWAYS }, + { STATS_LINK, "called for link ", NULL, 0 }, + { STATS_MULTIPLE, "multiple source files ", NULL, 0 }, + { STATS_STDOUT, "compiler produced stdout ", NULL, 0 }, + { STATS_STATUS, "compile failed ", NULL, 0 }, + { STATS_ERROR, "ccache internal error ", NULL, 0 }, + { STATS_PREPROCESSOR, "preprocessor error ", NULL, 0 }, + { STATS_COMPILER, "couldn't find the compiler ", NULL, 0 }, + { STATS_MISSING, "cache file missing ", NULL, 0 }, + { STATS_ARGS, "bad compiler arguments ", NULL, 0 }, + { STATS_NOTC, "not a C/C++ file ", NULL, 0 }, + { STATS_CONFTEST, "autoconf compile/link ", NULL, 0 }, + { STATS_UNSUPPORTED, "unsupported compiler option ", NULL, 0 }, + { STATS_OUTSTDOUT, "output to stdout ", NULL, 0 }, + { STATS_DEVICE, "output to a non-regular file ", NULL, 0 }, + { STATS_NOINPUT, "no input file ", NULL, 0 }, + { STATS_ENVIRONMMENT, "error due to bad env variable ", NULL, 0 }, + { STATS_NUMFILES, "files in cache ", NULL, FLAG_NOZERO|FLAG_ALWAYS }, + { STATS_TOTALSIZE, "cache size ", display_size , FLAG_NOZERO|FLAG_ALWAYS }, + { STATS_MAXFILES, "max files ", NULL, FLAG_NOZERO }, + { STATS_MAXSIZE, "max cache size ", display_size, FLAG_NOZERO }, + { STATS_NONE, NULL, NULL, 0 } +}; + +/* parse a stats file from a buffer - adding to the counters */ +static void parse_stats(unsigned counters[STATS_END], char *buf) +{ + int i; + char *p, *p2; + + p = buf; + for (i=0;i= (int)sizeof(buf)-1) fatal("stats too long?!"); + } + len += snprintf(buf+len, sizeof(buf)-(len+1), "\n"); + if (len >= (int)sizeof(buf)-1) fatal("stats too long?!"); + + lseek(fd, 0, SEEK_SET); + if (write(fd, buf, len) == -1) fatal("could not write stats"); +} + + +/* fill in some default stats values */ +static void stats_default(unsigned counters[STATS_END]) +{ + counters[STATS_MAXSIZE] += DEFAULT_MAXSIZE / 16; +} + +/* read in the stats from one dir and add to the counters */ +static void stats_read_fd(int fd, unsigned counters[STATS_END]) +{ + char buf[1024]; + int len; + len = read(fd, buf, sizeof(buf)-1); + if (len <= 0) { + stats_default(counters); + return; + } + buf[len] = 0; + parse_stats(counters, buf); +} + +/* update the stats counter for this compile */ +static void stats_update_size(enum stats stat, size_t size, size_t numfiles) +{ + int fd; + unsigned counters[STATS_END]; + int need_cleanup = 0; + + if (getenv("CCACHE_NOSTATS")) return; + + if (!stats_file) { + if (!cache_dir) return; + x_asprintf(&stats_file, "%s/stats", cache_dir); + } + + /* open safely to try to prevent symlink races */ + fd = safe_open(stats_file); + + /* still can't get it? don't bother ... */ + if (fd == -1) return; + + memset(counters, 0, sizeof(counters)); + + if (lock_fd(fd) != 0) return; + + /* read in the old stats */ + stats_read_fd(fd, counters); + + /* update them */ + counters[stat]++; + + /* on a cache miss we up the file count and size */ + if (stat == STATS_TOCACHE) { + counters[STATS_NUMFILES] += numfiles; + counters[STATS_TOTALSIZE] += size; + } + + /* and write them out */ + write_stats(fd, counters); + close(fd); + + /* we might need to cleanup if the cache has now got too big */ + if (counters[STATS_MAXFILES] != 0 && + counters[STATS_NUMFILES] > counters[STATS_MAXFILES]) { + need_cleanup = 1; + } + if (counters[STATS_MAXSIZE] != 0 && + counters[STATS_TOTALSIZE] > counters[STATS_MAXSIZE]) { + need_cleanup = 1; + } + + if (need_cleanup) { + char *p = dirname(stats_file); + cleanup_dir(p, counters[STATS_MAXFILES], counters[STATS_MAXSIZE]); + free(p); + } +} + +/* record a cache miss */ +void stats_tocache(size_t size, size_t numfiles) +{ + /* convert size to kilobytes */ + size = size / 1024; + + stats_update_size(STATS_TOCACHE, size, numfiles); +} + +/* update a normal stat */ +void stats_update(enum stats stat) +{ + stats_update_size(stat, 0, 0); +} + +/* read in the stats from one dir and add to the counters */ +void stats_read(const char *stats_file, unsigned counters[STATS_END]) +{ + int fd; + + fd = open(stats_file, O_RDONLY|O_BINARY); + if (fd == -1) { + stats_default(counters); + return; + } + lock_fd(fd); + stats_read_fd(fd, counters); + close(fd); +} + +/* sum and display the total stats for all cache dirs */ +void stats_summary(void) +{ + int dir, i; + unsigned counters[STATS_END]; + + memset(counters, 0, sizeof(counters)); + + /* add up the stats in each directory */ + for (dir=-1;dir<=0xF;dir++) { + char *fname; + + if (dir == -1) { + x_asprintf(&fname, "%s/stats", cache_dir); + } else { + x_asprintf(&fname, "%s/%1x/stats", cache_dir, dir); + } + + stats_read(fname, counters); + free(fname); + + /* oh what a nasty hack ... */ + if (dir == -1) { + counters[STATS_MAXSIZE] = 0; + } + + } + + printf("cache directory %s\n", cache_dir); + + /* and display them */ + for (i=0;stats_info[i].message;i++) { + enum stats stat = stats_info[i].stat; + + if (counters[stat] == 0 && + !(stats_info[i].flags & FLAG_ALWAYS)) { + continue; + } + + printf("%s ", stats_info[i].message); + if (stats_info[i].fn) { + stats_info[i].fn(counters[stat]); + printf("\n"); + } else { + printf("%8u\n", counters[stat]); + } + } +} + +/* zero all the stats structures */ +void stats_zero(void) +{ + int dir, fd; + unsigned i; + char *fname; + unsigned counters[STATS_END]; + + x_asprintf(&fname, "%s/stats", cache_dir); + unlink(fname); + free(fname); + + for (dir=0;dir<=0xF;dir++) { + x_asprintf(&fname, "%s/%1x/stats", cache_dir, dir); + fd = safe_open(fname); + if (fd == -1) { + free(fname); + continue; + } + memset(counters, 0, sizeof(counters)); + lock_fd(fd); + stats_read_fd(fd, counters); + for (i=0;stats_info[i].message;i++) { + if (!(stats_info[i].flags & FLAG_NOZERO)) { + counters[stats_info[i].stat] = 0; + } + } + write_stats(fd, counters); + close(fd); + free(fname); + } +} + + +/* set the per directory limits */ +int stats_set_limits(long maxfiles, long maxsize) +{ + int dir; + unsigned counters[STATS_END]; + + if (maxfiles != -1) { + maxfiles /= 16; + } + if (maxsize != -1) { + maxsize /= 16; + } + + if (create_dir(cache_dir) != 0) { + return 1; + } + + /* set the limits in each directory */ + for (dir=0;dir<=0xF;dir++) { + char *fname, *cdir; + int fd; + + x_asprintf(&cdir, "%s/%1x", cache_dir, dir); + if (create_dir(cdir) != 0) { + return 1; + } + x_asprintf(&fname, "%s/stats", cdir); + free(cdir); + + memset(counters, 0, sizeof(counters)); + fd = safe_open(fname); + if (fd != -1) { + lock_fd(fd); + stats_read_fd(fd, counters); + if (maxfiles != -1) { + counters[STATS_MAXFILES] = maxfiles; + } + if (maxsize != -1) { + counters[STATS_MAXSIZE] = maxsize; + } + write_stats(fd, counters); + close(fd); + } + free(fname); + } + + return 0; +} + +/* set the per directory sizes */ +void stats_set_sizes(const char *dir, size_t num_files, size_t total_size) +{ + int fd; + unsigned counters[STATS_END]; + char *stats_file; + + create_dir(dir); + x_asprintf(&stats_file, "%s/stats", dir); + + memset(counters, 0, sizeof(counters)); + + fd = safe_open(stats_file); + if (fd != -1) { + lock_fd(fd); + stats_read_fd(fd, counters); + counters[STATS_NUMFILES] = num_files; + counters[STATS_TOTALSIZE] = total_size; + write_stats(fd, counters); + close(fd); + } + + free(stats_file); +} diff --git a/CCache/test.sh b/CCache/test.sh new file mode 100755 index 0000000..9581c85 --- /dev/null +++ b/CCache/test.sh @@ -0,0 +1,452 @@ +#!/bin/sh + +# a simple test suite for ccache +# tridge@samba.org + +if test -n "$CC"; then + COMPILER="$CC" +else + COMPILER=cc +fi + +if test -n "$SWIG"; then + SWIG="$SWIG" +else + SWIG=swig +fi + +CCACHE=../ccache-swig +TESTDIR=test.$$ + +test_failed() { + reason="$1" + echo $1 + $CCACHE -s + cd .. + rm -rf $TESTDIR + echo TEST FAILED + exit 1 +} + +randcode() { + outfile="$1" + nlines=$2 + i=0; + ( + while [ $i -lt $nlines ]; do + echo "int foo$nlines$i(int x) { return x; }" + i=`expr $i + 1` + done + ) >> "$outfile" +} + +genswigcode() { + outfile="$1" + nlines=$2 + i=0; + ( + echo "%module swigtest$2;" + while [ $i -lt $nlines ]; do + echo "int foo$nlines$i(int x);" + echo "struct Bar$nlines$i { int y; };" + i=`expr $i + 1` + done + ) >> "$outfile" +} + + +getstat() { + stat="$1" + value=`$CCACHE -s | grep "$stat" | cut -c34-40` + echo $value +} + +checkstat() { + stat="$1" + expected_value="$2" + value=`getstat "$stat"` +# echo "exp: $expected_value got: $value $testname" + if [ "$expected_value" != "$value" ]; then + test_failed "SUITE: $testsuite TEST: $testname - Expected $stat to be $expected_value got $value" + fi +} + + +basetests() { + echo "starting testsuite $testsuite" + rm -rf "$CCACHE_DIR" + checkstat 'cache hit' 0 + checkstat 'cache miss' 0 + + j=1 + rm -f *.c + while [ $j -lt 32 ]; do + randcode test$j.c $j + j=`expr $j + 1` + done + + testname="BASIC" + $CCACHE_COMPILE -c test1.c + checkstat 'cache hit' 0 + checkstat 'cache miss' 1 + + testname="BASIC2" + $CCACHE_COMPILE -c test1.c + checkstat 'cache hit' 1 + checkstat 'cache miss' 1 + + testname="debug" + $CCACHE_COMPILE -c test1.c -g + checkstat 'cache hit' 1 + checkstat 'cache miss' 2 + + testname="debug2" + $CCACHE_COMPILE -c test1.c -g + checkstat 'cache hit' 2 + checkstat 'cache miss' 2 + + testname="output" + $CCACHE_COMPILE -c test1.c -o foo.o + checkstat 'cache hit' 3 + checkstat 'cache miss' 2 + + testname="link" + $CCACHE_COMPILE test1.c -o test 2> /dev/null + checkstat 'called for link' 1 + + testname="multiple" + $CCACHE_COMPILE -c test1.c test2.c + checkstat 'multiple source files' 1 + + testname="find" + $CCACHE blahblah -c test1.c 2> /dev/null + checkstat "couldn't find the compiler" 1 + + testname="bad" + $CCACHE_COMPILE -c test1.c -I 2> /dev/null + checkstat 'bad compiler arguments' 1 + + testname="c/c++" + ln -f test1.c test1.ccc + $CCACHE_COMPILE -c test1.ccc 2> /dev/null + checkstat 'not a C/C++ file' 1 + + testname="unsupported" + $CCACHE_COMPILE -M foo -c test1.c > /dev/null 2>&1 + checkstat 'unsupported compiler option' 1 + + testname="stdout" + $CCACHE echo foo -c test1.c > /dev/null + checkstat 'compiler produced stdout' 1 + + testname="non-regular" + mkdir testd + $CCACHE_COMPILE -o testd -c test1.c > /dev/null 2>&1 + rmdir testd + checkstat 'output to a non-regular file' 1 + + testname="no-input" + $CCACHE_COMPILE -c -O2 2> /dev/null + checkstat 'no input file' 1 + + + testname="CCACHE_DISABLE" + CCACHE_DISABLE=1 $CCACHE_COMPILE -c test1.c 2> /dev/null + checkstat 'cache hit' 3 + $CCACHE_COMPILE -c test1.c + checkstat 'cache hit' 4 + + testname="CCACHE_CPP2" + CCACHE_CPP2=1 $CCACHE_COMPILE -c test1.c -O -O + checkstat 'cache hit' 4 + checkstat 'cache miss' 3 + + CCACHE_CPP2=1 $CCACHE_COMPILE -c test1.c -O -O + checkstat 'cache hit' 5 + checkstat 'cache miss' 3 + + testname="CCACHE_NOSTATS" + CCACHE_NOSTATS=1 $CCACHE_COMPILE -c test1.c -O -O + checkstat 'cache hit' 5 + checkstat 'cache miss' 3 + + testname="CCACHE_RECACHE" + CCACHE_RECACHE=1 $CCACHE_COMPILE -c test1.c -O -O + checkstat 'cache hit' 5 + checkstat 'cache miss' 4 + + # strictly speaking should be 6 - RECACHE causes a double counting! + checkstat 'files in cache' 8 + $CCACHE -c > /dev/null + checkstat 'files in cache' 6 + + + testname="CCACHE_HASHDIR" + CCACHE_HASHDIR=1 $CCACHE_COMPILE -c test1.c -O -O + checkstat 'cache hit' 5 + checkstat 'cache miss' 5 + + CCACHE_HASHDIR=1 $CCACHE_COMPILE -c test1.c -O -O + checkstat 'cache hit' 6 + checkstat 'cache miss' 5 + + checkstat 'files in cache' 8 + + testname="comments" + echo '/* a silly comment */' > test1-comment.c + cat test1.c >> test1-comment.c + $CCACHE_COMPILE -c test1-comment.c + rm -f test1-comment* + checkstat 'cache hit' 6 + checkstat 'cache miss' 6 + + testname="CCACHE_UNIFY" + CCACHE_UNIFY=1 $CCACHE_COMPILE -c test1.c + checkstat 'cache hit' 6 + checkstat 'cache miss' 7 + mv test1.c test1-saved.c + echo '/* another comment */' > test1.c + cat test1-saved.c >> test1.c + CCACHE_UNIFY=1 $CCACHE_COMPILE -c test1.c + mv test1-saved.c test1.c + checkstat 'cache hit' 7 + checkstat 'cache miss' 7 + + testname="cache-size" + for f in *.c; do + $CCACHE_COMPILE -c $f + done + checkstat 'cache hit' 8 + checkstat 'cache miss' 37 + checkstat 'files in cache' 72 + $CCACHE -F 48 -c > /dev/null + if [ `getstat 'files in cache'` -gt 48 ]; then + test_failed '-F test failed' + fi + + testname="cpp call" + $CCACHE_COMPILE -c test1.c -E > test1.i + checkstat 'cache hit' 8 + checkstat 'cache miss' 37 + + testname="direct .i compile" + $CCACHE_COMPILE -c test1.c + checkstat 'cache hit' 8 + checkstat 'cache miss' 38 + + $CCACHE_COMPILE -c test1.i + checkstat 'cache hit' 9 + checkstat 'cache miss' 38 + + $CCACHE_COMPILE -c test1.i + checkstat 'cache hit' 10 + checkstat 'cache miss' 38 + + # removed these tests as some compilers (including newer versions of gcc) + # determine which language to use based on .ii/.i extension, and C++ may + # not be installed +# testname="direct .ii file" +# mv test1.i test1.ii +# $CCACHE_COMPILE -c test1.ii +# checkstat 'cache hit' 10 +# checkstat 'cache miss' 39 + +# $CCACHE_COMPILE -c test1.ii +# checkstat 'cache hit' 11 +# checkstat 'cache miss' 39 + + testname="stripc" # This test might not be portable + CCACHE_STRIPC=1 $CCACHE_COMPILE -c test1.c + checkstat 'cache hit' 10 + checkstat 'cache miss' 39 + + CCACHE_STRIPC=1 $CCACHE_COMPILE -c test1.c + checkstat 'cache hit' 11 + checkstat 'cache miss' 39 + + testname="zero-stats" + $CCACHE -z > /dev/null + checkstat 'cache hit' 0 + checkstat 'cache miss' 0 + + testname="clear" + $CCACHE -C > /dev/null + checkstat 'files in cache' 0 + + + rm -f test1.c +} + +swigtests() { + echo "starting swig testsuite $testsuite" + rm -rf "$CCACHE_DIR" + checkstat 'cache hit' 0 + checkstat 'cache miss' 0 + + j=1 + rm -f *.i + genswigcode testswig1.i 1 + + testname="BASIC" + $CCACHE_COMPILE -java testswig1.i + checkstat 'cache hit' 0 + checkstat 'cache miss' 1 + + checkstat 'files in cache' 6 + + testname="BASIC2" + $CCACHE_COMPILE -java testswig1.i + checkstat 'cache hit' 1 + checkstat 'cache miss' 1 + + testname="output" + $CCACHE_COMPILE -java testswig1.i -o foo_wrap.c + checkstat 'cache hit' 1 + checkstat 'cache miss' 2 + + testname="bad" + $CCACHE_COMPILE -java testswig1.i -I 2> /dev/null + checkstat 'bad compiler arguments' 1 + + testname="stdout" + $CCACHE_COMPILE -v -java testswig1.i > /dev/null + checkstat 'compiler produced stdout' 1 + + testname="non-regular" + mkdir testd + $CCACHE_COMPILE -o testd -java testswig1.i > /dev/null 2>&1 + rmdir testd + checkstat 'output to a non-regular file' 1 + + testname="no-input" + $CCACHE_COMPILE -java 2> /dev/null + checkstat 'no input file' 1 + + + testname="CCACHE_DISABLE" + CCACHE_DISABLE=1 $CCACHE_COMPILE -java testswig1.i 2> /dev/null + checkstat 'cache hit' 1 + $CCACHE_COMPILE -java testswig1.i + checkstat 'cache hit' 2 + + testname="CCACHE_CPP2" + CCACHE_CPP2=1 $CCACHE_COMPILE -java -O -O testswig1.i + checkstat 'cache hit' 2 + checkstat 'cache miss' 3 + + CCACHE_CPP2=1 $CCACHE_COMPILE -java -O -O testswig1.i + checkstat 'cache hit' 3 + checkstat 'cache miss' 3 + + testname="CCACHE_NOSTATS" + CCACHE_NOSTATS=1 $CCACHE_COMPILE -java -O -O testswig1.i + checkstat 'cache hit' 3 + checkstat 'cache miss' 3 + + testname="CCACHE_RECACHE" + CCACHE_RECACHE=1 $CCACHE_COMPILE -java -O -O testswig1.i + checkstat 'cache hit' 3 + checkstat 'cache miss' 4 + + # strictly speaking should be 3x6=18 instead of 4x6=24 - RECACHE causes a double counting! + checkstat 'files in cache' 24 + $CCACHE -c > /dev/null + checkstat 'files in cache' 18 + + + testname="CCACHE_HASHDIR" + CCACHE_HASHDIR=1 $CCACHE_COMPILE -java -O -O testswig1.i + checkstat 'cache hit' 3 + checkstat 'cache miss' 5 + + CCACHE_HASHDIR=1 $CCACHE_COMPILE -java -O -O testswig1.i + checkstat 'cache hit' 4 + checkstat 'cache miss' 5 + + checkstat 'files in cache' 24 + + testname="cpp call" + $CCACHE_COMPILE -java -E testswig1.i > testswig1-preproc.i + checkstat 'cache hit' 4 + checkstat 'cache miss' 5 + + testname="direct .i compile" + $CCACHE_COMPILE -java testswig1.i + checkstat 'cache hit' 5 + checkstat 'cache miss' 5 + + # No cache hit due to different input file name, -nopreprocess should not be given twice to SWIG + $CCACHE_COMPILE -java -nopreprocess testswig1-preproc.i + checkstat 'cache hit' 5 + checkstat 'cache miss' 6 + + $CCACHE_COMPILE -java -nopreprocess testswig1-preproc.i + checkstat 'cache hit' 6 + checkstat 'cache miss' 6 + + testname="stripc" + CCACHE_STRIPC=1 $CCACHE_COMPILE -java -O -O testswig1.i + checkstat 'cache hit' 7 + checkstat 'cache miss' 6 + + CCACHE_STRIPC=1 $CCACHE_COMPILE -java -O -O -O testswig1.i + checkstat 'cache hit' 7 + checkstat 'cache miss' 7 + + rm -f testswig1-preproc.i + rm -f testswig1.i +} + +###### +# main program +rm -rf $TESTDIR +mkdir $TESTDIR +cd $TESTDIR || exit 1 +CCACHE_DIR="ccache dir" # with space in directory name (like Windows default) +mkdir "$CCACHE_DIR" +export CCACHE_DIR + +testsuite="base" +CCACHE_COMPILE="$CCACHE $COMPILER" +basetests +CCACHE_COMPILE="$CCACHE $SWIG" +swigtests + +if test -z "$NOSOFTLINKSTEST"; then + testsuite="link" + ln -s $CCACHE $COMPILER + CCACHE_COMPILE="./$COMPILER" + basetests + rm "./$COMPILER" + ln -s $CCACHE $SWIG + CCACHE_COMPILE="./$SWIG" + swigtests + rm "./$SWIG" +else + echo "skipping testsuite link" +fi + +testsuite="hardlink" +CCACHE_COMPILE="env CCACHE_NOCOMPRESS=1 CCACHE_HARDLINK=1 $CCACHE $COMPILER" +basetests +CCACHE_COMPILE="env CCACHE_NOCOMPRESS=1 CCACHE_HARDLINK=1 $CCACHE $SWIG" +swigtests + +testsuite="cpp2" +CCACHE_COMPILE="env CCACHE_CPP2=1 $CCACHE $COMPILER" +basetests +CCACHE_COMPILE="env CCACHE_CPP2=1 $CCACHE $SWIG" +swigtests + +testsuite="nlevels4" +CCACHE_COMPILE="env CCACHE_NLEVELS=4 $CCACHE $COMPILER" +basetests + +testsuite="nlevels1" +CCACHE_COMPILE="env CCACHE_NLEVELS=1 $CCACHE $COMPILER" +basetests + +cd .. +rm -rf $TESTDIR +echo test done - OK +exit 0 diff --git a/CCache/unify.c b/CCache/unify.c new file mode 100644 index 0000000..a93d48a --- /dev/null +++ b/CCache/unify.c @@ -0,0 +1,307 @@ +/* + Copyright (C) Andrew Tridgell 2002 + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. +*/ +/* + C/C++ unifier + + the idea is that changes that don't affect the resulting C code + should not change the hash. This is achieved by folding white-space + and other non-semantic fluff in the input into a single unified format. + + This unifier was design to match the output of the unifier in + compilercache, which is flex based. The major difference is that + this unifier is much faster (about 2x) and more forgiving of + syntactic errors. Continuing on syntactic errors is important to + cope with C/C++ extensions in the local compiler (for example, + inline assembly systems). +*/ + +#include "ccache.h" + +static char *s_tokens[] = { + "...", ">>=", "<<=", "+=", "-=", "*=", "/=", "%=", "&=", "^=", + "|=", ">>", "<<", "++", "--", "->", "&&", "||", "<=", ">=", + "==", "!=", ";", "{", "<%", "}", "%>", ",", ":", "=", + "(", ")", "[", "<:", "]", ":>", ".", "&", "!", "~", + "-", "+", "*", "/", "%", "<", ">", "^", "|", "?", + 0 +}; + +#define C_ALPHA 1 +#define C_SPACE 2 +#define C_TOKEN 4 +#define C_QUOTE 8 +#define C_DIGIT 16 +#define C_HEX 32 +#define C_FLOAT 64 +#define C_SIGN 128 + +static struct { + unsigned char type; + unsigned char num_toks; + char *toks[7]; +} tokens[256]; + +/* build up the table used by the unifier */ +static void build_table(void) +{ + unsigned char c; + int i; + static int done; + + if (done) return; + done = 1; + + memset(tokens, 0, sizeof(tokens)); + for (c=0;c<128;c++) { + if (isalpha(c) || c == '_') tokens[c].type |= C_ALPHA; + if (isdigit(c)) tokens[c].type |= C_DIGIT; + if (isspace(c)) tokens[c].type |= C_SPACE; + if (isxdigit(c)) tokens[c].type |= C_HEX; + } + tokens['\''].type |= C_QUOTE; + tokens['"'].type |= C_QUOTE; + tokens['l'].type |= C_FLOAT; + tokens['L'].type |= C_FLOAT; + tokens['f'].type |= C_FLOAT; + tokens['F'].type |= C_FLOAT; + tokens['U'].type |= C_FLOAT; + tokens['u'].type |= C_FLOAT; + + tokens['-'].type |= C_SIGN; + tokens['+'].type |= C_SIGN; + + for (i=0;s_tokens[i];i++) { + c = s_tokens[i][0]; + tokens[c].type |= C_TOKEN; + tokens[c].toks[tokens[c].num_toks] = s_tokens[i]; + tokens[c].num_toks++; + } +} + +/* buffer up characters before hashing them */ +static void pushchar(unsigned char c) +{ + static unsigned char buf[64]; + static int len; + + if (c == 0) { + if (len > 0) { + hash_buffer((char *)buf, len); + len = 0; + } + hash_buffer(NULL, 0); + return; + } + + buf[len++] = c; + if (len == 64) { + hash_buffer((char *)buf, len); + len = 0; + } +} + +/* hash some C/C++ code after unifying */ +static void unify(unsigned char *p, size_t size) +{ + size_t ofs; + unsigned char q; + int i; + + build_table(); + + for (ofs=0; ofs 2 && p[ofs+1] == ' ' && isdigit(p[ofs+2])) { + do { + ofs++; + } while (ofs < size && p[ofs] != '\n'); + ofs++; + } else { + do { + pushchar(p[ofs]); + ofs++; + } while (ofs < size && p[ofs] != '\n'); + pushchar('\n'); + ofs++; + } + continue; + } + + if (tokens[p[ofs]].type & C_ALPHA) { + do { + pushchar(p[ofs]); + ofs++; + } while (ofs < size && + (tokens[p[ofs]].type & (C_ALPHA|C_DIGIT))); + pushchar('\n'); + continue; + } + + if (tokens[p[ofs]].type & C_DIGIT) { + do { + pushchar(p[ofs]); + ofs++; + } while (ofs < size && + ((tokens[p[ofs]].type & C_DIGIT) || p[ofs] == '.')); + if (ofs < size && (p[ofs] == 'x' || p[ofs] == 'X')) { + do { + pushchar(p[ofs]); + ofs++; + } while (ofs < size && (tokens[p[ofs]].type & C_HEX)); + } + if (ofs < size && (p[ofs] == 'E' || p[ofs] == 'e')) { + pushchar(p[ofs]); + ofs++; + while (ofs < size && + (tokens[p[ofs]].type & (C_DIGIT|C_SIGN))) { + pushchar(p[ofs]); + ofs++; + } + } + while (ofs < size && (tokens[p[ofs]].type & C_FLOAT)) { + pushchar(p[ofs]); + ofs++; + } + pushchar('\n'); + continue; + } + + if (tokens[p[ofs]].type & C_SPACE) { + do { + ofs++; + } while (ofs < size && (tokens[p[ofs]].type & C_SPACE)); + continue; + } + + if (tokens[p[ofs]].type & C_QUOTE) { + q = p[ofs]; + pushchar(p[ofs]); + do { + ofs++; + while (ofs < size-1 && p[ofs] == '\\') { + pushchar(p[ofs]); + pushchar(p[ofs+1]); + ofs+=2; + } + pushchar(p[ofs]); + } while (ofs < size && p[ofs] != q); + pushchar('\n'); + ofs++; + continue; + } + + if (tokens[p[ofs]].type & C_TOKEN) { + q = p[ofs]; + for (i=0;i= ofs+len && memcmp(&p[ofs], s, len) == 0) { + int j; + for (j=0;s[j];j++) { + pushchar(s[j]); + ofs++; + } + pushchar('\n'); + break; + } + } + if (i < tokens[q].num_toks) { + continue; + } + } + + pushchar(p[ofs]); + pushchar('\n'); + ofs++; + } + pushchar(0); +} + + +/* hash a file that consists of preprocessor output, but remove any line + number information from the hash +*/ +int unify_hash(const char *fname) +{ +#ifdef _WIN32 + HANDLE file; + HANDLE section; + DWORD filesize_low; + char *map; + int ret = -1; + + file = CreateFileA(fname, GENERIC_READ, FILE_SHARE_READ, NULL, + OPEN_EXISTING, 0, NULL); + if (file != INVALID_HANDLE_VALUE) { + filesize_low = GetFileSize(file, NULL); + if (!(filesize_low == INVALID_FILE_SIZE && GetLastError() != NO_ERROR)) { + section = CreateFileMappingA(file, NULL, PAGE_READONLY, 0, 0, NULL); + CloseHandle(file); + if (section != NULL) { + map = MapViewOfFile(section, FILE_MAP_READ, 0, 0, 0); + CloseHandle(section); + if (map != NULL) + ret = 0; + } + } + } + + if (ret == -1) { + cc_log("Failed to open preprocessor output %s\n", fname); + stats_update(STATS_PREPROCESSOR); + return -1; + } + + /* pass it through the unifier */ + unify((unsigned char *)map, filesize_low); + + UnmapViewOfFile(map); + + return 0; +#else + int fd; + struct stat st; + char *map; + + fd = open(fname, O_RDONLY|O_BINARY); + if (fd == -1 || fstat(fd, &st) != 0) { + cc_log("Failed to open preprocessor output %s\n", fname); + stats_update(STATS_PREPROCESSOR); + return -1; + } + + /* we use mmap() to make it easy to handle arbitrarily long + lines in preprocessor output. I have seen lines of over + 100k in length, so this is well worth it */ + map = mmap(NULL, st.st_size, PROT_READ, MAP_PRIVATE, fd, 0); + if (map == (char *)-1) { + cc_log("Failed to mmap %s\n", fname); + stats_update(STATS_PREPROCESSOR); + return -1; + } + close(fd); + + /* pass it through the unifier */ + unify((unsigned char *)map, st.st_size); + + munmap(map, st.st_size); + + return 0; +#endif +} + diff --git a/CCache/util.c b/CCache/util.c new file mode 100644 index 0000000..bba2324 --- /dev/null +++ b/CCache/util.c @@ -0,0 +1,884 @@ +/* + Copyright (C) Andrew Tridgell 2002 + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. +*/ + +#include "ccache.h" + +static FILE *logfile; + +/* log a message to the CCACHE_LOGFILE location */ +void cc_log(const char *format, ...) +{ + va_list ap; + extern char *cache_logfile; + + if (!cache_logfile) return; + + if (!logfile) logfile = fopen(cache_logfile, "a"); + if (!logfile) return; + + va_start(ap, format); + vfprintf(logfile, format, ap); + va_end(ap); + fflush(logfile); +} + +/* something went badly wrong! */ +void fatal(const char *msg) +{ + cc_log("FATAL: %s\n", msg); + exit(1); +} + +int safe_rename(const char* oldpath, const char* newpath) +{ + /* safe_rename is for creating entries in the cache. + + Works like rename(), but it never overwrites an existing + cache entry. This avoids corruption on NFS. */ +#ifndef _WIN32 + int status = link(oldpath, newpath); + if( status == 0 || errno == EEXIST ) +#else + int status = CreateHardLinkA(newpath, oldpath, NULL) ? 0 : -1; + if( status == 0 || GetLastError() == ERROR_ALREADY_EXISTS ) +#endif + { + return unlink( oldpath ); + } + else + { + return -1; + } +} + +#ifndef ENABLE_ZLIB +/* copy all data from one file descriptor to another */ +void copy_fd(int fd_in, int fd_out) +{ + char buf[10240]; + int n; + + while ((n = read(fd_in, buf, sizeof(buf))) > 0) { + if (write(fd_out, buf, n) != n) { + fatal("Failed to copy fd"); + } + } +} + +#ifndef HAVE_MKSTEMP +/* cheap and nasty mkstemp replacement */ +static int mkstemp(char *template) +{ + mktemp(template); + return open(template, O_RDWR | O_CREAT | O_EXCL | O_BINARY, 0600); +} +#endif + +/* move a file using rename */ +int move_file(const char *src, const char *dest) { + return safe_rename(src, dest); +} + +/* copy a file - used when hard links don't work + the copy is done via a temporary file and atomic rename +*/ +static int copy_file(const char *src, const char *dest) +{ + int fd1, fd2; + char buf[10240]; + int n; + char *tmp_name; + mode_t mask; + + x_asprintf(&tmp_name, "%s.XXXXXX", dest); + + fd1 = open(src, O_RDONLY|O_BINARY); + if (fd1 == -1) { + free(tmp_name); + return -1; + } + + fd2 = mkstemp(tmp_name); + if (fd2 == -1) { + close(fd1); + free(tmp_name); + return -1; + } + + while ((n = read(fd1, buf, sizeof(buf))) > 0) { + if (write(fd2, buf, n) != n) { + close(fd2); + close(fd1); + unlink(tmp_name); + free(tmp_name); + return -1; + } + } + + close(fd1); + + /* get perms right on the tmp file */ +#ifndef _WIN32 + mask = umask(0); + fchmod(fd2, 0666 & ~mask); + umask(mask); +#else + (void)mask; +#endif + + /* the close can fail on NFS if out of space */ + if (close(fd2) == -1) { + unlink(tmp_name); + free(tmp_name); + return -1; + } + + unlink(dest); + + if (rename(tmp_name, dest) == -1) { + unlink(tmp_name); + free(tmp_name); + return -1; + } + + free(tmp_name); + + return 0; +} + +/* copy a file to the cache */ +static int copy_file_to_cache(const char *src, const char *dest) { + return copy_file(src, dest); +} + +/* copy a file from the cache */ +static int copy_file_from_cache(const char *src, const char *dest) { + return copy_file(src, dest); +} + +#else /* ENABLE_ZLIB */ + +/* copy all data from one file descriptor to another + possibly decompressing it +*/ +void copy_fd(int fd_in, int fd_out) { + char buf[10240]; + int n; + gzFile gz_in; + + gz_in = gzdopen(dup(fd_in), "rb"); + + if (!gz_in) { + fatal("Failed to copy fd"); + } + + while ((n = gzread(gz_in, buf, sizeof(buf))) > 0) { + if (write(fd_out, buf, n) != n) { + fatal("Failed to copy fd"); + } + } +} + +static int _copy_file(const char *src, const char *dest, int mode) { + int fd_in, fd_out; + gzFile gz_in, gz_out = NULL; + char buf[10240]; + int n, ret; + char *tmp_name; + mode_t mask; + struct stat st; + + x_asprintf(&tmp_name, "%s.XXXXXX", dest); + + if (getenv("CCACHE_NOCOMPRESS")) { + mode = COPY_UNCOMPRESSED; + } + + /* open source file */ + fd_in = open(src, O_RDONLY); + if (fd_in == -1) { + return -1; + } + + gz_in = gzdopen(fd_in, "rb"); + if (!gz_in) { + close(fd_in); + return -1; + } + + /* open destination file */ + fd_out = mkstemp(tmp_name); + if (fd_out == -1) { + gzclose(gz_in); + free(tmp_name); + return -1; + } + + if (mode == COPY_TO_CACHE) { + /* The gzip file format occupies at least 20 bytes. So + it will always occupy an entire filesystem block, + even for empty files. + Since most stderr files will be empty, we turn off + compression in this case to save space. + */ + if (fstat(fd_in, &st) != 0) { + gzclose(gz_in); + close(fd_out); + free(tmp_name); + return -1; + } + if (file_size(&st) == 0) { + mode = COPY_UNCOMPRESSED; + } + } + + if (mode == COPY_TO_CACHE) { + gz_out = gzdopen(dup(fd_out), "wb"); + if (!gz_out) { + gzclose(gz_in); + close(fd_out); + free(tmp_name); + return -1; + } + } + + while ((n = gzread(gz_in, buf, sizeof(buf))) > 0) { + if (mode == COPY_TO_CACHE) { + ret = gzwrite(gz_out, buf, n); + } else { + ret = write(fd_out, buf, n); + } + if (ret != n) { + gzclose(gz_in); + if (gz_out) { + gzclose(gz_out); + } + close(fd_out); + unlink(tmp_name); + free(tmp_name); + return -1; + } + } + + gzclose(gz_in); + if (gz_out) { + gzclose(gz_out); + } + + /* get perms right on the tmp file */ + mask = umask(0); + fchmod(fd_out, 0666 & ~mask); + umask(mask); + + /* the close can fail on NFS if out of space */ + if (close(fd_out) == -1) { + unlink(tmp_name); + free(tmp_name); + return -1; + } + + unlink(dest); + + if (rename(tmp_name, dest) == -1) { + unlink(tmp_name); + free(tmp_name); + return -1; + } + + free(tmp_name); + + return 0; +} + +/* move a file to the cache, compressing it */ +int move_file(const char *src, const char *dest) { + int ret; + + ret = _copy_file(src, dest, COPY_TO_CACHE); + if (ret != -1) unlink(src); + return ret; +} + +/* copy a file to the cache, compressing it */ +static int copy_file_to_cache(const char *src, const char *dest) { + return _copy_file(src, dest, COPY_TO_CACHE); +} + +/* copy a file from the cache, decompressing it */ +static int copy_file_from_cache(const char *src, const char *dest) { + return _copy_file(src, dest, COPY_FROM_CACHE); +} +#endif /* ENABLE_ZLIB */ + +/* test if a file is zlib compressed */ +int test_if_compressed(const char *filename) { + FILE *f; + + f = fopen(filename, "rb"); + if (!f) { + return 0; + } + + /* test if file starts with 1F8B, which is zlib's + * magic number */ + if ((fgetc(f) != 0x1f) || (fgetc(f) != 0x8b)) { + fclose(f); + return 0; + } + + fclose(f); + return 1; +} + +/* copy file to the cache with error checking taking into account compression and hard linking if desired */ +int commit_to_cache(const char *src, const char *dest, int hardlink) +{ + int ret = -1; + struct stat st; + if (stat(src, &st) == 0) { + unlink(dest); + if (hardlink) { +#ifdef _WIN32 + ret = CreateHardLinkA(dest, src, NULL) ? 0 : -1; +#else + ret = link(src, dest); +#endif + } + if (ret == -1) { + ret = copy_file_to_cache(src, dest); + if (ret == -1) { + cc_log("failed to commit %s -> %s (%s)\n", src, dest, strerror(errno)); + stats_update(STATS_ERROR); + } + } + } else { + cc_log("failed to put %s in the cache (%s)\n", src, strerror(errno)); + stats_update(STATS_ERROR); + } + return ret; +} + +/* copy file out of the cache with error checking taking into account compression and hard linking if desired */ +int retrieve_from_cache(const char *src, const char *dest, int hardlink) +{ + int ret = 0; + + x_utimes(src); + + if (strcmp(dest, "/dev/null") == 0) { + ret = 0; + } else { + unlink(dest); + /* only make a hardlink if the cache file is uncompressed */ + if (hardlink && test_if_compressed(src) == 0) { +#ifdef _WIN32 + ret = CreateHardLinkA(dest, src, NULL) ? 0 : -1; +#else + ret = link(src, dest); +#endif + } else { + ret = copy_file_from_cache(src, dest); + } + } + + /* the cached file might have been deleted by some external process */ + if (ret == -1 && errno == ENOENT) { + cc_log("hashfile missing for %s\n", dest); + stats_update(STATS_MISSING); + return -1; + } + + if (ret == -1) { + ret = copy_file_from_cache(src, dest); + if (ret == -1) { + cc_log("failed to retrieve %s -> %s (%s)\n", src, dest, strerror(errno)); + stats_update(STATS_ERROR); + return -1; + } + } + return ret; +} + +/* make sure a directory exists */ +int create_dir(const char *dir) +{ + struct stat st; + if (stat(dir, &st) == 0) { + if (S_ISDIR(st.st_mode)) { + return 0; + } + errno = ENOTDIR; + return 1; + } +#ifdef _WIN32 + if (mkdir(dir) != 0 && errno != EEXIST) { + return 1; + } +#else + if (mkdir(dir, 0777) != 0 && errno != EEXIST) { + return 1; + } +#endif + return 0; +} + +char const CACHEDIR_TAG[] = + "Signature: 8a477f597d28d172789f06886806bc55\n" + "# This file is a cache directory tag created by ccache.\n" + "# For information about cache directory tags, see:\n" + "# http://www.brynosaurus.com/cachedir/\n"; + +int create_cachedirtag(const char *dir) +{ + char *filename; + struct stat st; + FILE *f; + x_asprintf(&filename, "%s/CACHEDIR.TAG", dir); + if (stat(filename, &st) == 0) { + if (S_ISREG(st.st_mode)) { + goto success; + } + errno = EEXIST; + goto error; + } + f = fopen(filename, "w"); + if (!f) goto error; + if (fwrite(CACHEDIR_TAG, sizeof(CACHEDIR_TAG)-1, 1, f) != 1) { + goto error; + } + if (fclose(f)) goto error; +success: + free(filename); + return 0; +error: + free(filename); + return 1; +} + +/* + this is like asprintf() but dies if the malloc fails + note that we use vsnprintf in a rather poor way to make this more portable +*/ +void x_asprintf(char **ptr, const char *format, ...) +{ + va_list ap; + + *ptr = NULL; + va_start(ap, format); + if (vasprintf(ptr, format, ap) == -1) { + fatal("out of memory in x_asprintf"); + } + va_end(ap); + + if (!ptr) fatal("out of memory in x_asprintf"); +} + +/* + this is like strdup() but dies if the malloc fails +*/ +char *x_strdup(const char *s) +{ + char *ret; + ret = strdup(s); + if (!ret) { + fatal("out of memory in strdup\n"); + } + return ret; +} + +/* + this is like malloc() but dies if the malloc fails +*/ +void *x_malloc(size_t size) +{ + void *ret; + ret = malloc(size); + if (!ret) { + fatal("out of memory in malloc\n"); + } + return ret; +} + +/* + this is like realloc() but dies if the malloc fails +*/ +void *x_realloc(void *ptr, size_t size) +{ + void *p2; +#if 1 + /* Avoid invalid read in memcpy below */ + p2 = realloc(ptr, size); + if (!p2) { + fatal("out of memory in x_realloc"); + } +#else + if (!ptr) return x_malloc(size); + p2 = malloc(size); + if (!p2) { + fatal("out of memory in x_realloc"); + } + if (ptr) { + /* Note invalid read as the memcpy reads beyond the memory allocated by ptr */ + memcpy(p2, ptr, size); + free(ptr); + } +#endif + return p2; +} + + +/* + revsusive directory traversal - used for cleanup + fn() is called on all files/dirs in the tree + */ +void traverse(const char *dir, void (*fn)(const char *, struct stat *)) +{ + DIR *d; + struct dirent *de; + + d = opendir(dir); + if (!d) return; + + while ((de = readdir(d))) { + char *fname; + struct stat st; + + if (strcmp(de->d_name,".") == 0) continue; + if (strcmp(de->d_name,"..") == 0) continue; + + if (strlen(de->d_name) == 0) continue; + + x_asprintf(&fname, "%s/%s", dir, de->d_name); +#ifdef _WIN32 + if (stat(fname, &st)) +#else + if (lstat(fname, &st)) +#endif + { + if (errno != ENOENT) { + perror(fname); + } + free(fname); + continue; + } + + if (S_ISDIR(st.st_mode)) { + traverse(fname, fn); + } + + fn(fname, &st); + free(fname); + } + + closedir(d); +} + + +/* return the base name of a file - caller frees */ +char *str_basename(const char *s) +{ + char *p = strrchr(s, '/'); + if (p) { + s = (p+1); + } + +#ifdef _WIN32 + p = strrchr(s, '\\'); + + if (p) { + s = (p+1); + } +#endif + + return x_strdup(s); +} + +/* return the dir name of a file - caller frees */ +char *dirname(char *s) +{ + char *p; + s = x_strdup(s); + p = strrchr(s, '/'); +#ifdef _WIN32 + p = strrchr(s, '\\'); +#endif + if (p) { + *p = 0; + } + return s; +} + +/* + http://www.ecst.csuchico.edu/~beej/guide/ipc/flock.html + http://cvs.php.net/viewvc.cgi/php-src/win32/flock.c?revision=1.2&view=markup + Should return 0 for success, >0 otherwise + */ +int lock_fd(int fd) +{ +#ifdef _WIN32 +# if 1 + return _locking(fd, _LK_NBLCK, 1); +# else + HANDLE fl = (HANDLE)_get_osfhandle(fd); + OVERLAPPED o; + memset(&o, 0, sizeof(o)); + return (LockFileEx(fl, LOCKFILE_EXCLUSIVE_LOCK, 0, 1, 0, &o)) + ? 0 : GetLastError(); +# endif +#else + struct flock fl; + int ret; + + fl.l_type = F_WRLCK; + fl.l_whence = SEEK_SET; + fl.l_start = 0; + fl.l_len = 1; + fl.l_pid = 0; + + /* not sure why we would be getting a signal here, + but one user claimed it is possible */ + do { + ret = fcntl(fd, F_SETLKW, &fl); + } while (ret == -1 && errno == EINTR); + return ret; +#endif +} + +/* return size on disk of a file */ +size_t file_size(struct stat *st) +{ +#ifdef _WIN32 + return (st->st_size + 1023) & ~1023; +#else + size_t size = st->st_blocks * 512; + if ((size_t)st->st_size > size) { + /* probably a broken stat() call ... */ + size = (st->st_size + 1023) & ~1023; + } + return size; +#endif +} + + +/* a safe open/create for read-write */ +int safe_open(const char *fname) +{ + int fd = open(fname, O_RDWR|O_BINARY); + if (fd == -1 && errno == ENOENT) { + fd = open(fname, O_RDWR|O_CREAT|O_EXCL|O_BINARY, 0666); + if (fd == -1 && errno == EEXIST) { + fd = open(fname, O_RDWR|O_BINARY); + } + } + return fd; +} + +/* display a kilobyte unsigned value in M, k or G */ +void display_size(unsigned v) +{ + if (v > 1024*1024) { + printf("%8.1f Gbytes", v/((double)(1024*1024))); + } else if (v > 1024) { + printf("%8.1f Mbytes", v/((double)(1024))); + } else { + printf("%8u Kbytes", v); + } +} + +/* return a value in multiples of 1024 give a string that can end + in K, M or G +*/ +size_t value_units(const char *s) +{ + char m; + double v = atof(s); + m = s[strlen(s)-1]; + switch (m) { + case 'G': + case 'g': + default: + v *= 1024*1024; + break; + case 'M': + case 'm': + v *= 1024; + break; + case 'K': + case 'k': + v *= 1; + break; + } + return (size_t)v; +} + + +/* + a sane realpath() function, trying to cope with stupid path limits and + a broken API +*/ +char *x_realpath(const char *path) +{ +#ifdef _WIN32 + char namebuf[MAX_PATH]; + DWORD ret; + + ret = GetFullPathNameA(path, sizeof(namebuf), namebuf, NULL); + if (ret == 0 || ret >= sizeof(namebuf)) { + return NULL; + } + + return x_strdup(namebuf); +#else + int maxlen; + char *ret, *p; +#ifdef PATH_MAX + maxlen = PATH_MAX; +#elif defined(MAXPATHLEN) + maxlen = MAXPATHLEN; +#elif defined(_PC_PATH_MAX) + maxlen = pathconf(path, _PC_PATH_MAX); +#endif + if (maxlen < 4096) maxlen = 4096; + + ret = x_malloc(maxlen); + +#if HAVE_REALPATH + p = realpath(path, ret); +#else + /* yes, there are such systems. This replacement relies on + the fact that when we call x_realpath we only care about symlinks */ + { + int len = readlink(path, ret, maxlen-1); + if (len == -1) { + free(ret); + return NULL; + } + ret[len] = 0; + p = ret; + } +#endif + if (p) { + p = x_strdup(p); + free(ret); + return p; + } + free(ret); + return NULL; +#endif +} + +/* a getcwd that will returns an allocated buffer */ +char *gnu_getcwd(void) +{ + unsigned size = 128; + + while (1) { + char *buffer = (char *)x_malloc(size); + if (getcwd(buffer, size) == buffer) { + return buffer; + } + free(buffer); + if (errno != ERANGE) { + return 0; + } + size *= 2; + } +} + +/* create an empty file */ +int create_empty_file(const char *fname) +{ + int fd; + + fd = open(fname, O_WRONLY|O_CREAT|O_TRUNC|O_EXCL|O_BINARY, 0666); + if (fd == -1) { + return -1; + } + close(fd); + return 0; +} + +/* + return current users home directory or die +*/ +const char *get_home_directory(void) +{ +#ifdef _WIN32 + static char home_path[MAX_PATH] = {0}; + HRESULT ret; + + /* we already have the path */ + if (home_path[0] != 0) { + return home_path; + } + + /* get the path to "Application Data" folder */ + ret = SHGetFolderPathA(NULL, CSIDL_APPDATA | CSIDL_FLAG_CREATE, NULL, 0, home_path); + if (SUCCEEDED(ret)) { + return home_path; + } + + fprintf(stderr, "ccache: Unable to determine home directory\n"); + return NULL; +#else + const char *p = getenv("HOME"); + if (p) { + return p; + } +#ifdef HAVE_GETPWUID + { + struct passwd *pwd = getpwuid(getuid()); + if (pwd) { + return pwd->pw_dir; + } + } +#endif + fatal("Unable to determine home directory"); + return NULL; +#endif +} + +int x_utimes(const char *filename) +{ +#ifdef HAVE_UTIMES + return utimes(filename, NULL); +#else + return utime(filename, NULL); +#endif +} + +#ifdef _WIN32 +/* perror for Win32 API calls, using GetLastError() instead of errno */ +void perror_win32(LPTSTR pszFunction) +{ + LPTSTR pszMessage; + DWORD dwLastError = GetLastError(); + + FormatMessage( FORMAT_MESSAGE_ALLOCATE_BUFFER | + FORMAT_MESSAGE_FROM_SYSTEM | + FORMAT_MESSAGE_IGNORE_INSERTS, + NULL, + dwLastError, + MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), + (LPTSTR)&pszMessage, + 0, NULL ); + + fprintf(stderr, "%s: %s\n", pszFunction, pszMessage); + LocalFree(pszMessage); +} +#endif diff --git a/CCache/web/index.html b/CCache/web/index.html new file mode 100644 index 0000000..4af8391 --- /dev/null +++ b/CCache/web/index.html @@ -0,0 +1,158 @@ + + + +ccache + + +

      ccache

      + +ccache is a compiler cache. It acts as a caching pre-processor to +C/C++ compilers, using the -E compiler switch and a hash to detect +when a compilation can be satisfied from cache. This often results in +a 5 to 10 times speedup in common compilations.

      + +The idea came from Erik Thiele wrote the original compilercache program +as a bourne shell script. ccache is a re-implementation of Erik's idea +in C with more features and better performance.

      + +

      Latest release

      + +The latest release is ccache 2.4. + +
        +
      • Added CCACHE_READONLY option +
      • Added CCACHE_TEMPDIR option +
      • fixed handling of hard-linked compilers on AIX +
      • added O_BINARY support, to try and support win32 compiles +
      • show cache directory in stats output +
      • fixed handling of HOME environment variable +
      + +See the manual page for details +on the new options.

      + +You can get this release from the download directory + +

      NOTE! This release changes the hash input slighly, so you will +probably find that you will not get any hits against your existing +cache when you upgrade. + +

      Why bother?

      + +Why bother with a compiler cache? If you ever run "make clean; make" +then you can probably benefit from ccache. It is very common for +developers to do a clean build of a project for a whole host of +reasons, and this throws away all the information from your previous +compiles.

      + +By using ccache you can get exactly the same effect as "make clean; +make" but much faster. It also helps a lot when doing RPM builds, +as RPM can make doing incremental builds tricky.

      + +I put the effort into writing ccache for 2 reasons. The first is the +Samba build farm +(http://build.samba.org/) +which constantly does clean builds of Samba on about 30 machines after each +CVS commit. On some of those machines the build took over an hour. By +using ccache we get the same effect as clean builds but about 6 times +faster.

      + +The second reason is the autobuild system I used to run for +Quantum. That system builds our whole Linux based OS from scratch +after every CVS commit to catch compilation problems quickly. Using +ccache those builds are much faster. + +

      Is it safe?

      + +Yes. The most important aspect of a compiler cache is to always +produce exactly the same output that the real compiler would +produce. The includes providing exactly the same object files and +exactly the same compiler warnings that would be produced if you use +the real compiler. The only way you should be able to tell that you +are using ccache is the speed.

      + +I have coded ccache very carefully to try to provide these guarantees. + +

      Features

      + +
        +
      • keeps statistics on hits/misses +
      • automatic cache size management +
      • can cache compiles that generate warnings +
      • easy installation +
      • very low overhead +
      • uses hard links where possible to avoid copies +
      + +

      Documentation

      + +See the manual page + + +

      Performance

      + +Here are some results for compiling Samba on my Linux laptop. I have +also included the results of using Erik's compilercache program +(version 1.0.10) for comparison.

      + + + + + + +
          ccache  compilercache
      normal 13m 4s 13m 4s
      uncached 13m 15s 15m 41s
      cached 2m 45s 4m 26s
      + +

      How to use it

      + +You can use ccache in two ways. The first is just to prefix your +compile commands with "ccache". For example, you could change the +"CC=gcc" line in your Makefile to be "CC=ccache gcc".

      + +Alternatively, you can create symbolic links from your compilers name +to ccache. This allows you to use ccache without any changes to your +build system. + +

      Download

      + +You can download the latest release from the download directory.

      + +For the bleeding edge, you can fetch ccache via CVS or +rsync. To fetch via cvs use the following command: + +

      +  cvs -d :pserver:cvs@pserver.samba.org:/cvsroot co ccache
+
      + +To fetch via rsync use this command: + +
      +  rsync -Pavz samba.org::ftp/unpacked/ccache .
+
      + +

      Related projects

      + +Here are some related programs you may find interesting + +
        +
      • distcc - a distributed compilation system +
      • cachecc1 - a gcc specific cache +
      • gocache - a cross platform compiler cache +
      +

      + +

      Mailing list

      + +

      A mailing +list is available for discussion of ccache. + + +

      + +Andrew Tridgell
      +bugs@ccache.samba.org +       + + + diff --git a/CHANGES b/CHANGES new file mode 100644 index 0000000..d942651 --- /dev/null +++ b/CHANGES @@ -0,0 +1,20309 @@ +SWIG (Simplified Wrapper and Interface Generator) + +See CHANGES.current for current version. + +Version 1.3.39 (21 March 2009) +============================== + +2009-03-19: bhy + [Python] Fix the memory leak related to Python 3 unicode and C char* conversion, + which can be shown in the following example before this fix: + + from li_cstring import * + i=0 + while True: + i += 1 + n = str(i)*10 + test3(n) + + This fix affected SWIG_AsCharPtrAndSize() so you cannot call this function with + a null alloc and non-null cptr argument in Python 3, otherwise a runtime error + will be raised. + +2009-03-18: wsfulton + [C#] std::vector wrapper improvements for .NET 2 and also providing the + necessary machinery to use the std::vector wrappers with more advanced features such + as LINQ - the C# proxy class now derives from IEnumerable<>. The default is now to + generate code requiring .NET 2 as a minimum, although the C# code can be compiled + for .NET 1 by defining the SWIG_DOTNET_1 C# preprocessor constant. See the + std_vector.i file for more details. + + *** POTENTIAL INCOMPATIBILITY *** + +2009-03-12: wsfulton + [Ruby] Fix #2676738 SWIG generated symbol name clashes. + +2009-03-01: bhy + [Python] Some fixes for Python 3.0.1 and higher support. In 3.0.1, the C API function + PyObject_Compare is removed, so PyObject_RichCompareBool is used for replacement. + Struct initilization of SwigPyObject and SwigPyObject_as_number changed to reflect + the drop of tp_compare and nb_long. + +2009-03-01: bhy + [Python] Fix SF#2583160. Now the importer in Python shadow wrapper take care of the + case that module already imported at other place. + +2009-02-28: bhy + [Python] Fix SF#2637352. Move struct declaration of SWIG_module in pyinit.swg before + the method calls, since some C compiler don't allow declaration in middle of function + body. + +2009-02-21: wsfulton + [Allegrocl] Fix seg fault wrapping some constant variable (%constant) types. + +2009-02-20: wsfulton + [CFFI] Fix seg faults when for %extend and using statements. + +2009-02-20: wsfulton + Fix SF #2605955: -co option which broke in 1.3.37. + +2009-02-20: wsfulton + New %insert("begin") section added. Also can be used as %begin. This is a new + code section reserved entirely for users and the code within the section is generated + at the top of the C/C++ wrapper file and so provides a means to put custom code + into the wrapper file before anything else that SWIG generates. + +2009-02-17: wsfulton + 'make clean-test-suite' will now run clean on ALL languages. Previously it only + ran the correctly configured languages. This way it is now possible to clean up + properly after running 'make partialcheck-test-suite'. + +2009-02-14: wsfulton + Extend attribute library support for structs/classes and the accessor functions use + pass/return by value semantics. Two new macros are available and usage is identical + to %attribute. These are %attributeval for structs/classes and %attributestring for + string classes, like std::string. See attribute.swg for more details. + +2009-02-13: wsfulton + Add support for %extend and memberin typemaps. Previously the memberin typemaps were + ignored for member variables within a %extend block. + +2009-02-12: wsfulton + Remove unnecessary temporary variable when wrapping return values that are references. + Example of generated code for wrapping: + + struct XYZ { + std::string& refReturn(); + }; + + used to be: + + std::string *result = 0 ; + ... + { + std::string &_result_ref = (arg1)->refReturn(); + result = (std::string *) &_result_ref; + } + + Now it is: + + std::string *result = 0 ; + ... + result = (std::string *) &(arg1)->refReturn(); + +2009-02-08: bhy + Change the SIZE mapped by %pybuffer_mutable_binary and %pybuffer_binary in pybuffer.i from + the length of the buffer to the number of items in the buffer. + +2009-02-08: wsfulton + Fix %feature not working for conversion operators, reported by Matt Sprague, for example: + %feature("cs:methodmodifiers") operator bool "protected"; + +2009-02-07: wsfulton + [MzScheme] Apply #2081967 configure changes for examples to build with recent PLT versions. + Also fixes Makefile errors building SWIG executable when mzscheme package is installed + (version 3.72 approx and later). + +2009-02-04: talby + [Perl] Fix SF#2564192 reported by David Kolovratnk. + SWIG_AsCharPtrAndSize() now handles "get" magic. + +Version 1.3.38 (31 January 2009) +================================ + +2009-01-31: bhy + [Python] Fix SF#2552488 reported by Gaetan Lehmann. Now %pythonprepend + and %pythonappend have correct indentation. + +2009-01-31: bhy + [Python] Fix SF#2552048 reported by Gaetan Lehmann. The parameter list + of static member function in generated proxy code should not have the + 'self' parameter. + +2009-01-29: wsfulton + Fix regression introduced in 1.3.37 where the default output directory + for target language specific files (in the absence of -outdir) was no + longer the same directory as the generated c/c++ file. + +2009-01-28: wsfulton + [Java, C#] Fix proxy class not being used when the global scope operator + was used for parameters passed by value. Reported by David Piepgrass. + +2009-01-15: wsfulton + [Perl] Fix seg fault when running with -v option, reported by John Ky. + +Version 1.3.37 (13 January 2009) +================================ + +2009-01-13: mgossage + [Lua] Added contract support for requiring that unsigned numbers are >=0 + Rewrote much of Examples/Lua/embed3. + Added a lot to the Lua documentation. + +2009-01-13: wsfulton + Fix compilation error when using directors on protected virtual overloaded + methods reported by Sam Hendley. + +2009-01-12: drjoe + [R] Fixed handling of integer arrays + +2009-01-10: drjoe + [R] Fix integer handling in r to deal correctly with signed + and unsigned issues + +2009-01-10: wsfulton + Patch #1992756 from Colin McDonald - %contract not working for classes + in namespace + +2009-01-05: olly + Mark SWIGPERL5, SWIGPHP5, and SWIGTCL8 as deprecated in the source + code and remove documentation of them. + +2008-12-30: wsfulton + Bug #2430756. All the languages now define a macro in the generated C/C++ + wrapper file indicating which language is being wrapped. The macro name is the + same as those defined when SWIG is run, eg SWIGJAVA, SWIGOCTAVE, SWIGCSHARP etc + and are listed in the "Conditional Compilation" section in the documentation. + +2008-12-23: wsfulton + [Java] Fix #2153773 - %nojavaexception was clearing the exception feature + instead of disabling it. Clearing checked Java exceptions also didn't work. + The new %clearjavaexception can be used for clearing the exception feature. + +2008-12-22: wsfulton + Fix #2432801 - Make SwigValueWrapper exception safe for when copy constructors + throw exceptions. + +2008-12-21: wsfulton + Apply patch #2440046 which fixes possible seg faults for member and global + variable char arrays when the strings are larger than the string array size. + +2008-12-20: wsfulton + The ccache compiler cache has been adapted to work with SWIG and + named ccache-swig. It now works with C/C++ compilers as well as SWIG + and can result in impressive speedups when used to recompile unchanged + code with either a C/C++ compiler or SWIG. Documentation is in CCache.html + or the installed ccache-swig man page. + +2008-12-12: wsfulton + Apply patch from Kalyanov Dmitry which fixes parsing of nested structs + containing comments. + +2008-12-12: wsfulton + Fix error message in some nested struct and %inline parsing error situations + such as unterminated strings and comments. + +2008-12-07: olly + [PHP] Fix warnings when compiling generated wrapper with GCC 4.3. + +2008-12-06: wsfulton + [PHP] Deprecate %pragma(php4). Please use %pragma(php) instead. + The following two warnings have been renamed: + WARN_PHP4_MULTIPLE_INHERITANCE -> WARN_PHP_MULTIPLE_INHERITANCE + WARN_PHP4_UNKNOWN_PRAGMA -> WARN_PHP_UNKNOWN_PRAGMA + + *** POTENTIAL INCOMPATIBILITY *** + +2008-12-04: bhy + [Python] Applied patch SF#2158938: all the SWIG symbol names started with Py + are changed, since they are inappropriate and discouraged in Python + documentation (from http://www.python.org/doc/2.5.2/api/includes.html): + + "All user visible names defined by Python.h (except those defined by + the included standard headers) have one of the prefixes "Py" or "_Py". + Names beginning with "_Py" are for internal use by the Python implementation + and should not be used by extension writers. Structure member names do + not have a reserved prefix. + + Important: user code should never define names that begin with "Py" or "_Py". + This confuses the reader, and jeopardizes the portability of the user + code to future Python versions, which may define additional names beginning + with one of these prefixes." + + Here is a brief list of what changed: + + PySwig* -> SwigPy* + PyObject_ptr -> SwigPtr_PyObject + PyObject_var -> SwigVar_PyObject + PySequence_Base, PySequence_Cont, PySequence_Ref -> + SwigPySequence_Base, SwigPySequence_Cont, SwigPySequence_Ref + PyMap* -> SwigPyMap* + + We provided a pyname_compat.i for backward compatibility. Users whose code having + these symbols and do not want to change it could simply include this file + at front of your code. A better solution is to run the converting tool on + your code, which has been put in SWIG's SVN trunk (Tools/pyname_patch.py) and + you can download it here: + https://swig.svn.sourceforge.net/svnroot/swig/trunk/Tools/pyname_patch.py + + *** POTENTIAL INCOMPATIBILITY *** + +2008-12-02: wsfulton + [Python] Apply patch #2143727 from Serge Monkewitz to fix importing base classes + when the package option is specified in %module and that module is %import'ed. + +2008-11-28: wsfulton + [UTL] Fix #2080497. Some incorrect acceptance of types in the STL, eg a double * element + passed into a vector constructor would be accepted, but the ensuing behaviour + was undefined. Now the type conversion correctly raises an exception. + +2008-11-24: wsfulton + Add -outcurrentdir option. This sets the default output directory to the current + directory instead of the path specified by the input file. This option enables + behaviour similar to c/c++ compilers. Note that this controls the output directory, + but only in the absence of the -o and/or -outdir options. + +2008-11-23: wsfulton + [ruby] Apply patch #2263850 to fix ruby/file.i ... rubyio.h filename change in + ruby 1.9. + +2008-11-23: wsfulton + Apply patch #2319790 from Johan Hake to fix shared_ptr usage in std::tr1 namespace. + +2008-11-21: wsfulton + The use of the include path to find the input file is now deprecated. + This makes the behaviour of SWIG the same as C/C++ compilers in preparation + for use with ccache. + +2008-11-16: wsfulton + Fix -nopreprocess option to: + - correctly report file names in warning and error messages. + - use the original input filename that created the preprocessed output when + determining the C++ wrapper file name (in the absence of -o). Previously + the name of the input file containing the preprocessed output was used. + +2008-11-11: wsfulton + [Java] Add patch #2152691 from MATSUURA Takanori which fixes compiles using the + Intel compiler + +2008-11-01: wsfulton + Add patch #2128249 from Anatoly Techtonik which corrects the C/C++ proxy + class being reported for Python docstrings when %rename is used. + +2008-11-01: wsfulton + Add the strip encoder patch from Anatoly Techtonik #2130016. This enables an + easy way to rename symbols by stripping a commonly used prefix in all the + function/struct names. It works in the same way as the other encoders, such as + title, lower, command etc outlined in CHANGES file dated 12/30/2005. Example + below will rename wxAnotherWidget to AnotherWidget and wxDoSomething to + DoSomething: + + %rename("%(strip:[wx])s") ""; + + struct wxAnotherWidget { + void wxDoSomething(); + }; + +2008-09-26: mutandiz + [allegrocl] + Lots of test-suite work. + - Fix ordering of wrapper output and %{ %} header output. + - Fix declarations of local vars in C wrappers. + - Fix declaration of defined constants in C wrappers. + - Fix declaration of EnumValues in C wrappers. + - add some const typemaps to allegrocl.swg + - add rename for operator bool() overloads. + +2008-09-25: olly + [PHP5] Fill in typemaps for SWIGTYPE and void * (SF#2095186). + +2008-09-22: mutandiz (Mikel Bancroft) + [allegrocl] + - Support wrapping of types whose definitions are not seen by + SWIG. They are treated as forward-referenced classes and if a + definition is not seen are treated as (* :void). + - Don't wrap the contents of unnamed namespaces. + - More code cleanup. Removed some extraneous warnings. + - start work on having the allegrocl mod pass the cpp test-suite. + +2008-09-19: olly + [PHP5] Add typemaps for long long and unsigned long long. + +2008-09-18: wsfulton + [C#] Added C# array typemaps provided by Antti Karanta. + The arrays provide a way to use MarshalAs(UnmanagedType.LPArray) + and pinning the array using 'fixed'. See arrays_csharp.i library file + for details. + +2008-09-18: wsfulton + Document the optional module attribute in the %import directive, + see Modules.html. Add a warning for Python wrappers when the + module name for an imported base class is missing, requiring the + module attribute to be added to %import, eg + + %import(module="FooModule") foo.h + +2008-09-18: olly + [PHP5] Change the default input typemap for char * to turn PHP + Null into C NULL (previously it was converted to an empty string). + The new behaviour is consistent with how the corresponding output + typemap works (SF#2025719). + + If you want to keep the old behaviour, add the following typemap + to your interface file (PHP's convert_to_string_ex() function does + the converting from PHP Null to an empty string): + + %typemap(in) char * { + convert_to_string_ex($input); + $1 = Z_STRVAL_PP($input); + } + +2008-09-18: olly + [PHP5] Fix extra code added to proxy class constructors in the case + where the only constructor takes no arguments. + +2008-09-18: olly + [PHP5] Fix wrapping of a renamed enumerated value of an enum class + member (SF#2095273). + +2008-09-17: mutandiz (Mikel Bancroft) + [allegrocl] + - Fix how forward reference typedefs are handled, so as not to conflict + with other legit typedefs. + - Don't (for now) perform an ffitype typemap lookup when trying to + when calling compose_foreign_type(). This is actually a useful thing + to do in certain cases, the test cases for which I can't currently + locate :/. It's breaking some wrapping behavior that is more commonly + seen, however. I'll readd in a more appropriate way when I can + recreate the needed test case, or a user complains (which means + they probably have a test case). + - document the -isolate command-line arg in the 'swig -help' output. + It was in the html docs, but not there. + - small amount of code cleanup, removed some unused code. + - some minor aesthetic changes. + +2008-09-12: bhy + [Python] Python 3.0 support branch merged into SWIG trunk. Thanks to + Google Summer of Code 2008 for supporting this project! By default + SWIG will generate interface files compatible with both Python 2.x + and 3.0. And there's also some Python 3 new features that can be + enabled by passing a "-py3" command line option to SWIG. These + features are: + + - Function annotation support + Also, the parameter list of proxy function will be generated, + even without the "-py3" option. However, the parameter list + will fallback to *args if the function (or method) is overloaded. + - Buffer interface support + - Abstract base class support + + For details of Python 3 support and these features, please see the + "Python 3 Support" section in the "SWIG and Python" chapter of the SWIG + documentation. + + The "-apply" command line option and support of generating codes + using apply() is removed. Since this is only required by very old + Python. + + This merge also patched SWIG's parser to solve a bug. By this patch, + SWIG features able to be correctly applied on C++ conversion operator, + such like this: + + %feature("shadow") *::operator bool %{ ... %} + +2008-09-02: richardb + [Python] Commit patch #2089149: Director exception handling mangles + returned exception. Exceptions raised by Python code in directors + are now passed through to the caller without change. Also, remove + the ": " prefix which used to be added to other director exceptions + (eg, those due to incorrect return types). + +2008-09-02: wsfulton + [Python] Commit patch #1988296 GCItem multiple module linking issue when using + directors. + +2008-09-02: wsfulton + [C#] Support for 'using' and 'fixed' blocks in the 'csin' typemap is now + possible through the use of the pre attribute and the new terminator attribute, eg + + %typemap(csin, + pre=" using (CDate temp$csinput = new CDate($csinput)) {", + terminator=" } // terminate temp$csinput using block", + ) const CDate & + "$csclassname.getCPtr(temp$csinput)" + + See CSharp.html for more info. + +2008-09-01: wsfulton + [CFFI] Commit patch #2079381 submitted by Boris Smilga - constant exprs put into + no-eval context in DEFCENUM + +2008-08-02: wuzzeb + [Chicken,Allegro] Commit Patch 2019314 + Fixes a build error in chicken, and several build errors and other errors + in Allegro CL + +2008-07-19: wsfulton + Fix building of Tcl examples/test-suite on Mac OSX reported by Gideon Simpson. + +2008-07-17: wsfulton + Fix SF #2019156 Configuring with --without-octave or --without-alllang + did not disable octave. + +2008-07-14: wsfulton + [Java, C#] Fix director typemaps for pointers so that NULL pointers are correctly + marshalled to C#/Java null in director methods. + +2008-07-04: olly + [PHP] For std_vector.i and std_map.i, rename empty() to is_empty() + since "empty" is a PHP reserved word. Based on patch from Mark Klein + in SF#1943417. + +2008-07-04: olly + [PHP] The deprecated command line option "-make" has been removed. + Searches on Google codesearch suggest that nobody is using it now + anyway. + +2008-07-04: olly + [PHP] The SWIG cdata.i library module is now supported. + +2008-07-03: olly + [PHP] The deprecated command line option "-phpfull" has been + removed. We recommend building your extension as a dynamically + loadable module. + +2008-07-02: olly + [PHP4] Support for PHP4 has been removed. The PHP developers are + no longer making new PHP4 releases, and won't even be providing + patches for critical security issues after 2008-08-08. + +2008-07-02: olly + [Python] Import the C extension differently for Python 2.6 and + later so that an implicit relative import doesn't produce a + deprecation warning for 2.6 and a failure for 2.7 and later. + Patch from Richard Boulton in SF#2008229, plus follow-up patches + from Richard and Haoyu Bai. + +Version 1.3.36 (24 June 2008) +============================= + +06/24/2008: wsfulton + Remove deprecated -c commandline option (runtime library generation). + +06/24/2008: olly + [PHP] Fix assertion failure when handling %typemap(in,numinputs=0) + (testcase ignore_parameter). + +06/24/2008: olly + [PHP] Fix segfault when wrapping a non-class function marked with + %newobject (testcase char_strings). + +06/22/2008: wsfulton + [Java] Add a way to use AttachCurrentThreadAsDaemon instead of AttachCurrentThread + in director code. Define the SWIG_JAVA_ATTACH_CURRENT_THREAD_AS_DAEMON macro, see + Lib/java/director.swg. + +06/21/2008: wsfulton + [Ruby] Fix crashing in the STL wrappers (reject! and delete_if methods) + +06/19/2008: wsfulton + [Java, C#] C# and Java keywords will be renamed instead of just issuing a warning + and then generating uncompileable code. Warning 314 gives the new name when a + keyword is found. + +06/19/2008: wsfulton + [R] Keyword handling added. R Keywords will be renamed as necessary. + Warning 314 gives the new name when a keyword is found. + +06/17/2008: mgossage + [Lua] Added missing support for bool& and bool*. Added runtest for li_typemaps testcase. + (Bug #1938142) + +06/07/2008: bhy + Added test case keyword_rename, then made the keyword renaming works properly + by fixing Swig_name_make() for a incomplete condition checking. + +06/02/2008: wsfulton + [Java, C#] Fix enum wrappers when using -noproxy. + +05/30/2008: bhy + Added std::wstring into Lib/typemaps/primtypes.swg, since it is also a primitive + type in SWIG - fixed SF #1976978. + +05/29/2008: wsfulton + [Java, C#] Fix variable wrappers when using -noproxy. + +05/29/2008: bhy + [Python] Fixed a typo of %#ifdef in Lib/python/pycontainer.swg, which is related + to -extranative SWIG option - SF #1971977. + +05/20/2008: wsfulton + New partialcheck makefile targets for partial testing of the test-suite. These + just invoke SWIG, ie no compilation and no runtime testing. It can be faster + when developing by just doing a directory diff of the files SWIG generates + against those from a previous run. Example usage from the top level directory: + + make partialcheck-test-suite + make partialcheck-java-test-suite + + This change also encompasses more flexibility in running the test-suite, eg + it is possible to prefix the command line which runs any target language test + with a tool. See the RUNTOOL, COMPILETOOL and SWIGTOOL targets in the common.mk + file and makefiles in the test-suite directory. For example it is possible to + run the runtime tests through valgrind using: + + make check RUNTOOL="valgrind --leak-check=full" + + or invoke SWIG under valgrind using: + + make check SWIGTOOL="valgrind --tool=memcheck" + +05/19/2008: drjoe + [R] Fixed define that was breaking pre-2.7. Checked in + patch from Soren Sonnenburg that creates strings in + version independent way + +05/15/2008: wsfulton + [Java] Fix variable name clash in directors - SF #1963316 reported by Tristan. + +05/14/2008: wsfulton + Add an optimisation for functions that return objects by value, reducing + the number of copies of the object that are made. Implemented using an + optional attribute in the "out" typemap called "optimal". Details in + Typemaps.html. + +05/11/2008: olly + [PHP] Check for %feature("notabstract") when generating PHP5 class + wrapper. + +05/11/2008: wsfulton + Fix SF #1943608 - $self substitution in %contract, patch submitted by + Toon Verstraelen. + +05/09/2008: olly + [PHP] Fix char * typemaps to work when applied to signed char * and + unsigned char * (uncovered by testcase apply_strings). + +05/09/2008: wsfulton + Fix wrapping of char * member variables when using allprotected mode. + Bug reported by Warren Wang. + +05/09/2008: olly + [PHP] Fix bad PHP code generated when wrapping an enum in a + namespace (uncovered by testcase arrays_scope). + +05/09/2008: olly + [PHP] SWIG now runs the PHP testsuite using PHP5, not PHP4. PHP4 + is essentially obsolete now, so we care much more about solid PHP5 + support. + +05/07/2008: wsfulton + STL fixes when using %import rather than %include and the Solaris Workshop + compiler and the Roguewave STL. + +05/07/2008: wsfulton + Fix wrapping of overloaded protected methods when using allprotected mode. + Bug reported by Warren Wang. + +05/03/2008: wsfulton + Commit patch #1956607 to add -MT support from Richard Boulton. + This patch mirrors the gcc -MT option which allows one to change the default + Makefile target being generated when generating makefiles with the -M family + of options. For example: + + $ swig -java -MM -MT overiddenname -c++ example.i + overiddenname: \ + example.i \ + example.h + +04/30/2008: mgossage + [Lua] Removed generation of _wrap_delete_XXXXX (wrappered destructor) + which was unused and causing warning with g++ -Wall. + Removed other unused warning in typemaps.i and other places. + Added Examples/lua/embed3, and run tests a few test cases. + +04/24/2008: olly + [Python] Fix generated code for IBM's C++ compiler on AIX (patch + from Goeran Uddeborg in SF#1928048). + +04/24/2008: olly + Rename BSIZE in Examples/test-suite/arrays_scope.i to BBSIZE to + avoid a clash with BSIZE defined by headers on AIX with Perl + (reported in SF#1928048). + +04/20/2008: wsfulton + Add the ability to wrap all protected members when using directors. + Previously only the virtual methods were available to the target language. + Now all protected members, (static and non-static variables, non-virtual methods + and static methods) are wrapped when using the allprotected mode. The allprotected + mode is turned on in the module declaration: + + %module(directors="1", allprotected="1") modulename + +Version 1.3.35 (7 April 2008) +============================= + +04/07/2008: wsfulton + [Lua] Add missing pointer reference typemaps + +04/06/2008: wsfulton + Fix stack overflow when using typemap warning suppression, eg + %warnfilter(SWIGWARN_TYPEMAP_CHARLEAK_MSG) + +04/05/2008: wsfulton + [Python] Fix shared_ptr typemaps so that %pythonnondynamic can be used. Also corrects + display of the proxy class type. Reported by Robert Lupton. + +04/04/2008: olly + [Python] Add %newobject reference to python memory management subsection of manual + (patch from mdbeachy in SF#1894610). + +03/27/2008: wsfulton + [Python] Fix shared_ptr typemaps where the pointer type is a templated type with + with more than one parameter. Reported by Robert Lupton. + +03/27/2008: mgossage + [Lua] Added a typemap DISOWN for SWIGTYPE* and SWIGTYPE[], and support for %delobject feature. + Added Examples/lua/owner which demonstrates the use of the memory management. + +03/26/2008: wsfulton + [Java] Apply patch #1844301 from Monty Taylor to suppress enum constructor + unused warnings. + +03/26/2008: wsfulton + [Python] Apply patch #1924524 from Casey Raymondson which ensures the + "No constructor defined" message is displayed when attempting to call a + constructor on a class that doesn't have a constructor wrapper, eg if + the C++ class is abstract. + +03/26/2008: wsfulton + [Python] Apply patch #1925702 from Casey Raymondson which removes warning 512 + for std::vector wrappers. + +03/26/2008: olly + [Python] Apply GCC 4.3 warnings patch from Philipp Thomas + (SF#1925122). + +03/21/2008: wsfulton + [Python] Thread safety patch for STL iterators from Abhinandan Jain. + +03/17/2008: mgossage + [Lua] Added %luacode feature to add source code into wrappers. + Updated documentation to document this. + Added Examples/lua/arrays to show its use (and typemaps) + +03/17/2008: olly + Fix nonportable sed usage which failed on Mac OS X (and probably + other platforms). Fixes SF#1903612. + +03/17/2008: olly + Fix memory leak in SWIG's parser (based on patch from Russell + Bryant in SF#1914023).` + +03/12/2008: wsfulton + Fix bug #1878285 - unnecessary cast for C struct creation wrappers. + +03/12/2008: wsfulton + [Python] Remove debugging info when using shared_ptr support + +03/06/2008: mgossage + [Lua] Updated documentation for Lua exceptions. + Added Examples/lua/exception and Examples/lua/embed2. + Small updates to the typemaps. + +03/04/2008: wsfulton + [Java, C#] Add char *& typemaps. + +03/04/2008: wsfulton + Fix occasional seg fault when attempting to report overloaded methods as being ignored. + +02/29/2008: wsfulton + [Perl] Fix #1904537 Swig causes a Perl warning "x used only once" in Perl 5.10 + reported by Ari Jolma + +02/29/2008: wsfulton + [Python] Add shared_ptr varin/varout typemaps for wrapping global variables. + +02/25/2008: wsfulton + Fix $wrapname to work in %exception (fixes some wrap:name assertions) + +Version 1.3.34 (27 February 2008) +================================= + +02/13/2008: wsfulton + [R] Fix wrapping of global function pointer variables. + +02/13/2008: wsfulton + Add new special variables for use within %exception: + $wrapname - language specific wrapper name + $overname - if a method is overloaded this contains the extra mangling used on + the overloaded method + $decl - the fully qualified C/C++ declaration of the method being wrapped + without the return type + $fulldecl - the fully qualified C/C++ declaration of the method being wrapped + including the return type + +02/12/2008: drjoe + [R] Now setting S4 flag in SWIG created objects. This + fixes R-SWIG for 2.6 and warning for 2.6 failure has been removed. + +02/11/2008: mgossage + [Lua] Added a patch by Torsten Landschoff to fix the unary minus issue + Ran 'astyle --style=kr -2' across lua.cxx to neaten it up + +02/10/2008: wsfulton + Bump SWIG_RUNTIME_VERSION to 4. This is because of the recently introduced API + change in the conversion functions, ie change in definition of swig_converter_func. + Anyone calling SWIG_TypeCast must pass in a valid value for the new additional + (third) parameter and then handle the newly created memory if the returned value + is set to SWIG_CAST_NEW_MEMORY else a memory leak will ensue. + +02/09/2008: wsfulton + [Python] Experimental shared_ptr typemaps added. Usage is the same as the recently + added Java and C# shared_ptr typemaps. Two macros are available, although these + may well change in a future version: + + For base classes or classes not in an inheritance chain: + SWIG_SHARED_PTR(PROXYCLASS, TYPE) + For derived classes: + SWIG_SHARED_PTR_DERIVED(PROXYCLASS, BASECLASSTYPE, TYPE) + + The PROXYCLASS is the name of the proxy class, but is only required for Java/C#. + Example usage: + + %include "boost_shared_ptr.i" + + SWIG_SHARED_PTR(Klass, Space::Klass) + SWIG_SHARED_PTR_DERIVED(KlassDerived, Space::Klass, Space::KlassDerived) + + namespace Space { + struct Klass { ... }; + struct KlassDerived : Klass { ... }; + } + + Further details to follow in future documentation, but the following features + should be noted: + + - Not restricted to boost::shared_ptr, eg std::tr1::shared_ptr can also be used. + - Available typemap groups: + (a) Typemaps for shared_ptr passed by value, reference, pointer and pointer + reference. + - (b) Typemaps for passing by raw value, raw pointer, raw reference, raw pointer + reference. + - The code being wrapped does not even have to use shared_ptr, SWIG can use + shared_ptr as the underlying storage mechanism instead of a raw pointer due to + the typemaps in group (b) above. + - No array support as shared_ptr does not support arrays. + - This works quite differently to the usual SWIG smart pointer support when + operator-> is parsed by SWIG: + - An additional smart pointer class is not generated reducing code bloat in + the wrappers. + - Using smart pointers and raw pointers can be mixed seamlessly. + - Missing constructors for the smart pointers is no longer a problem and so + separate factory type functions do not have to be written and wrapped. + - The implicit C++ shared_ptr< derived class > to shared_ptr< base class > + cast also works in the target language. This negates the necessity to write + an explicit helper cast function providing the upcast which would need + calling prior to passing a derived class to a method taking a shared_ptr to + a base class. + +02/09/2008: wsfulton + [Python] Add support for overriding the class registration function via a new + "smartptr" feature. This is a very low level of customisation most users + would never need to know. The feature will typically be used for intrusive + smart pointers along with additional typemaps. Example usage of the feature: + + %feature("smartptr", noblock=1) Foo { boost::shared_ptr< Foo > } + class Foo {}; + + The generated Foo_swigregister function will then register boost::shared < Foo > + (SWIGTYPE_p_boost__shared_ptrTFoo_t instead of SWIGTYPE_p_Foo) as the underlying + type for instantiations of Foo. + +02/09/2008: wsfulton + Features now supports the optional 'noblock' attribute for all usage of %feature. + When specified, the { } braces are removed from the feature code. This is identical + in behaviour to usage of 'noblock' in typemaps and is used when the preprocessor + is required to operate on the code in the feature and the enclosing { } braces + are not required. Example: + + #define FOO foo + %feature("smartptr", noblock="1") { FOO::bar } + + The preprocessor then reduces this as if this had been used instead: + + %feature("smartptr") "foo::bar" + +02/01/2008: olly + [Python] Fix format string bug (SF#1882220). + +01/31/2008: wsfulton + Additions to the %types directive. Now the conversion / casting code can be + overridden to some custom code in the %types directive, like so: + + %types(fromtype = totype) %{ + ... code to convert fromtype to totype and return ... + %} + + The special variable $from will be replaced by the name of the parameter of the + type being converted from. The code must return the totype cast to void *. Example: + + class Time; + class Date; + Date &Time::dateFromTime(); + + %types(Time = Date) %{ + Time *t = (Time *)$from; + Date &d = t->dateFromTime(); + return (void *) &d; + %} + + resulting in the conversion / casting code looking something like: + + static void *_p_TimeTo_p_Date(void *x) { + Time *t = (Time *)x; + Date &d = t->dateFromTime(); + return (void *) &d; + } + + This is advanced usage, please use only if you understand the runtime type system. + +01/30/2008: mgossage + Small update to documentation in Typemaps.html, to warn about use of local + variables in typemaps for multiple types. + +01/25/2008: wsfulton + [Java] Fix bug reported by Kevin Mills in ARRAYSOFCLASSES typemaps where any + changes made to an array element passed from Java to C are not reflected back + into Java. + +01/24/2008: mgossage + More updates to the configure script for detecting lua. + Also looks in /usr/include/lua* + Also changed typemaps.i not to check for NULL before freeing a pointer + +01/21/2008: wsfulton + [Python] For STL containers, SWIG no longer attempts to convert from one + STL container to another, eg from std::vector to std::vector + or std::list to std::vector or even std::vector to + std::vector as it previously did. In fact SWIG no longer attempts to + convert any SWIG wrapped C++ proxy class that is also a Python sequence, + whereas previously it would. Any non-SWIG Python sequence will still be + accepted wherever an STL container is accepted. Overloaded methods using + containers should be faster. + +01/18/2008: wsfulton + [C#] Add 'directorinattributes' and 'directoroutattributes' typemap attributes + for the imtype typemap. These should contain C# attributes which will + be generated into the C# director delegate methods. + +01/18/2008: olly + Fix handling of byte value 255 in input files on platforms where + char is signed (it was getting mapped to EOF). Fixes SF#1518219. + +01/16/2008: wsfulton + Fix template member variables wrapped by a smart pointer. Bug reported + by Robert Lupton. + +01/14/2008: mgossage + Substantial changes to configure script for detecting lua. + Code can now link to liblua.a, liblua50.a or liblua51.a + It's also a lot neater now. + +12/16/2007: wsfulton + [Perl] Backed out #1798728 - numbers can be passed to functions taking char * + +12/16/2007: wsfulton + Fix #1832613 - Templates and some typedefs involving pointers or function pointers + +12/12/2007: wsfulton + [Java] Fix #1632625 - Compilation errors on Visual C++ 6 when using directors. + +12/12/2007: wsfulton + [Perl] Fix #1798728 - numbers can be passed to functions taking char *. + +12/12/2007: wsfulton + Fix #1819847 %template with just one default template parameter + + template class Foo {...}; + %template(FooDefault) Foo<>; + +12/12/2007: mgossage + [Lua] Small correction on Lua.html + +12/09/2007: wsfulton + Apply patch #1838248 from Monty Taylor for vpath builds of SWIG. + +12/08/2007: wsfulton + [Lua] Fixes to remove gcc-4.2 warnings + +12/06/2007: wsfulton + Fix #1734415 - template template parameters with default arguments such as: + + template class t_alloc = pfc::alloc_fast > + class list_t : public list_impl_t > { ... }; + +12/04/2007: mgossage + [lua] Fix a bug in the class hierachy code, where the methods were not propagated, + if the name ordering was in a certain order. + Added new example programs (dual, embed) and runtime tests for test-suite. + +11/30/2007: wsfulton + Fix using statements using a base class method where the methods were overloaded. + Depending on the order of the using statements and method declarations, these + were previously generating uncompileable wrappers, eg: + + struct Derived : Base { + virtual void funk(); + using Base::funk; + }; + +Version 1.3.33 (November 23, 2007) +================================== + +11/21/2007: mikel + [allegrocl] omit private slot type info in the classes/types + defined on the lisp side. Fix bug in mapping of C/++ types + to lisp types. Fix typo in modules generated defpackage form. + Have std::string *'s automatically marshalled between foreign + and lisp strings. + +11/20/2007: olly + [Python] Fill in Python Dictionary functions list (patch from + Jelmer Vernooij posted to swig-devel). + +11/20/2007: beazley + Fixed a bug in the C scanner related to backslash characters. + +11/19/2007: wsfulton + [Perl] Fix broken compilation of C++ wrappers on some compilers. + +11/16/2007: olly + [Python] Don't pass Py_ssize_t for a %d printf-like format as + that's undefined behaviour when sizeof(Py_ssize_t) != sizeof(int). + +Version 1.3.32 (November 15, 2007) +================================== + +11/14/2007: wsfulton + [R] Package name and dll name is now the same as the SWIG module + name. It used to be the module name with _wrap as a suffix. The package + and dll names can be modified using the -package and -dll commandline + options. + + *** POTENTIAL INCOMPATIBILITY *** + +11/11/2007: wsfulton + [R] Add support for Windows (Visual C++ 8 tested) + +11/10/2007: olly + [php] Fix makefile generated by -make (SF#1633679). Update + documentation to mark "-make" as deprecated (none of the other + SWIG backends seem to offer such a feature, it can't realistically + generate a fully portable makefile, and the commands to build an + extension are easy enough to write for the user's preferred build + tool). Also recommend against the use of "-phpfull" (it's only + really useful when static linking, and a dynamically loadable + module is virtually always the better approach). + +11/09/2007: olly + Fix --help output to note that `export SWIG_FEATURES' is required. + +10/29/2007: wsfulton + [R] Fix seg fault on Windows + [R] Examples R scripts are now platform independent + +10/30/2007: mgossage + [lua] fixed bug in template classes which cases template_default2 + and template_specialization_defarg to fail. + Added several warning filters into the overload's test cases. + Added runtime tests for several codes. + You can now make check-lua-test-suite with no errors and only a few warnings. + +10/30/2007: olly + [guile] Fix the configure test to put GUILELINK in LIBS not LDFLAGS + (SF#1822430). + +10/30/2007: olly + [guile] Fix the guile examples on 64-bit platforms. + +10/29/2007: wsfulton + [C#] Fix member pointers on 64 bit platforms. + +10/28/2007: olly + [lua] Fix swig_lua_class instances to be static to allow multiple + SWIG wrappers to be compiled into the same executable statically. + Patch from Andreas Fredriksson (posted to the swig mailing list). + +10/28/2007: olly + [lua] Fix Examples/lua to pass SRCS for C tests rather than CXXSRCS. + The code as it was happened to work on x86, but broke on x86_64 (and + probably any other platforms which require -fPIC). + +10/28/2007: wsfulton + [Java, C#] New approach for fixing uninitialised variable usage on error in director + methods using the new templated initialisation function SwigValueInit(). + +10/28/2007: wsfulton + [Perl] Use more efficient SvPV_nolen(x) instead of SvPV(x,PL_na) if SvPV_nolen is + supported. + +10/26/2007: wuzzeb + [Chicken] Fix global variables of class member function pointers. + Other minor fixes, so all tests in the chicken test suite now pass + +10/25/2007: olly + Fix UTL typecheck macro for a function taking char[] or const + char[] (SF#1820132). + +10/22/2007: mkoeppe + [Guile] Filter out -ansi -pedantic from CFLAGS while compiling test programs for Guile + in configure. This enables running the test suite for Guile if it is installed and + usable. + +10/22/2007: mkoeppe + [Guile -scm] Fix testcases apply_signed_char and apply_strings + by adding explicit casts to the appropriate $ltype. + +10/22/2007: wsfulton + [Java, C#] Fix uninitialised variable usage on error in director methods. + +10/19/2007: wsfulton + [Java, C#] Bug #1794247 - fix generated code for derived classes when csbase or javabase + typemaps are used with the replace="1" attribute. + +10/19/2007: wsfulton + [Python] Docs updated to suggest using distutils. Patch #1796681 from Christopher Barker. + +10/19/2007: olly + [perl5] Clear errno before calls to strtol(), strtoul(), strtoll() + and strtoull() which we check errno after to avoid seeing a junk + value of errno if there isn't an error in the call. + +10/16/2007: wsfulton + Deprecate %attribute_ref and replace with %attributeref. There is just an argument + order change in order to maintain consistency with %attribute, from: + + %attribute_ref(Class, AttributeType, AccessorMethod, AttributeName) + to + %attributeref(Class, AttributeType, AttributeName, AccessorMethod) + +10/16/2007: olly + [Tcl] Fix several ocurrences of "warning: deprecated conversion + from string constant to 'char*'" from GCC 4.2 in generated C/C++ + code. + +10/16/2007: olly + [PHP] Fix many occurrences of "warning: deprecated conversion from + string constant to 'char*'" from GCC 4.2 in generated C/C++ code + when compiling with a new enough version of PHP 5 (tested with + PHP 5.2.3, but PHP 5.2.1 is probably the minimum requirement). + +10/15/2007: wsfulton + Patch #1797133 from David Piepgrass fixes %attribute when the getter has the same name + as the attribute name and no longer generate non-functional setter for read-only attributes. + +10/15/2007: olly + [Tcl] Prevent SWIG_Tcl_ConvertPtr from calling the unknown proc. + Add Examples/tcl/std_vector/ which this change fixes. Patch + is from "Cliff C" in SF#1809819. + +10/12/2007: wsfulton + [Java] Add DetachCurrentThread back in for directors. See entry dated 08/11/2006 and + search for DetachCurrentThread on the mailing lists for details. The crashes on Solaris + seem to be only present in jdk-1.4.2 and lower (jdk-1.5.0 and jdk-1.6.0 are okay), so + anyone using directors should use a recent jdk on Solaris, or define (see director.swg) + SWIG_JAVA_NO_DETACH_CURRENT_THREAD to the C++ compiler to get old behaviour. + +10/12/2007: wsfulton + [Java] Ensure the premature garbage collection prevention parameter (pgcpp) is generated + when there are C comments in the jtype and jstype typemaps. + +10/12/2007: wuzzeb + Added a testsuite entry for Bug #1735931 + +10/09/2007: olly + Automatically rerun autogen.sh if configure.in is modified. + +10/09/2007: olly + Enhance check-%-test-suite rule and friends to give a more helpful + error message if you try them for a language which doesn't exist + (e.g. "make check-php-test-suite" rather than the correct + "make check-php4-test-suite"). + +10/09/2007: olly + Add make rule to regenerate Makefile from Makefile.in if it has + changed. + +10/09/2007: olly + [php] Fix long-standing memory leak in wrapped constructors and + wrapped functions/methods which return an object. + +10/08/2007: olly + Fix Makefile.in to read check.list files correctly in a VPATH + build. + +10/07/2007: wsfulton + [C#, Java] Experimental shared_ptr typemaps added + +09/27/2007: mgossage + [lua] added more verbose error messages for incorrect typechecks. + Added a routine which checks the exact number of parameters passed to a function + (breaks operator_overloading for unary minus operator, currently disabled). + Reorganised the luatypemaps.swg to tidy it up. + Added a lot of %ignores on the operators not supported by lua. + Added support for constant member function pointers & runtest for member_pointer.i + Added first version of wchar.i + +09/25/2007: wsfulton + [C#, Java] throws typemaps for std::wstring using C# patch #1799064 from David Piepgrass + +09/24/2007: wsfulton + [Tcl] Apply #1771313 to fix bug #1650229 - fixes long long and unsigned long long + handling. + +09/20/2007: olly + [Java] Eliminate some unnecessary uses of a temporary buffer + allocated using new[]. SF#1796609. + +09/19/2007: wsfulton + [C#] The $csinput special variable can be used in the csvarin typemap where it is always + expanded to 'value'. + +09/19/2007: wsfulton + [C#] Fix bug reported by Glenn A Watson and #1795260 where the cstype typemap used the 'ref' + keyword in the typemap body, it produced uncompilable C# properties (variable wrappers). + The type for the property now correctly comes from the 'out' attribute in the cstype typemap. + +09/19/2007: wsfulton + [Java] Fix const std::wstring& typemaps + +09/19/2007: wsfulton + [Java] Ensure the premature garbage collection prevention parameter (pgcpp) is generated + where a parameter is passed by pointer reference, eg in the std::vector wrappers. The pgcpp + is also generated now when user's custom typemaps use a proxy class in the jstype typemap + and a 'long' in the jtype typemap. + +09/18/2007: olly + [php] Add typemaps for handling parameters of type std::string & + which are modified by the wrapped function. + +09/17/2007: olly + [python] Split potentially long string literals to avoid hitting + MSVC's low fixed limit on string literal length - patch from + SF#1723770, also reported as SF#1630855. + +09/17/2007: olly + [ocaml] Fix renaming of overloaded methods in the method_table - + my patch from SF#940399. + +09/17/2007: olly + [python] Simpler code for SWIG_AsVal_bool() which fixes a "strict + aliasing" warning from GCC - patch from SF#1724581 by Andrew + Baumann. + +09/17/2007: olly + [perl5] Use sv_setpvn() to set a scalar from a pointer and length + - patch from SF#174460 by "matsubaray". + +09/17/2007: olly + When wrapping C++ code, generate code which uses + std::string::assign(PTR, LEN) rather than assigning + std::string(PTR, LEN). Using assign generates more efficient code + (tested with GCC 4.1.2). + +09/07/2007: wsfulton + Fix %ignore on constructors which are not explicitly declared [SF #1777712] + +09/05/2007: wuzzeb (John Lenz) + - Change r_ltype in typesys.c to store a hashtable instead of a single value. + several very subtle bugs were being caused by multiple ltypes being mapped + to a single mangled type, mostly when using typedefed template parameters. + Now, r_ltype stores a hashtable of possible ltypes, and when generating the + type table, all the ltypes are added into the swig_type_info structure. + +08/31/2007: wsfulton + SF #1754967 from James Bigler. + - Fix bug in turning on warnings that were turned off by default. Eg 'swig -w+309' will now + turn on the normally suppressed warning 309. + + - New -Wextra commandline option which enables the extra warning numbers: + 202,309,403,512,321,322 (this is the list of warnings that have always been suppressed by + default). By specifying -Wextra, all warnings will be turned on, but unlike -Wall, + warnings can still be selectively turned on/off using %warnfilter, + #pragma SWIG nowarn or further -w commandline options, eg: + swig -Wextra -w309 + will turn on all warnings except 309. + +08/28/2007: wsfulton + - New debugging options, -debug-module and -debug-top to display the parse tree at + various stages, where is a comma separated list of stages 1-4.For example, to + display top of parse tree at stages 1 and 3: + swig -debug-top 1,3 + + - Deprecate the following options which have equivalents below: + -dump_parse_module => -debug-module 1 + -dump_module => -debug-module 4 + -dump_parse_top => -debug-top 1 + -dump_top => -debug-top 4 + + - Renamed some commandline options for naming consistency across all options: + -debug_template => -debug-template + -debug_typemap => -debug-typemap + -dump_classes => -debug-classes + -dump_tags => -debug-tags + -dump_typedef => -debug-typedef + -dump_memory => -debug-memory + +08/25/2007: olly + [PHP5] Fix handling of double or float parameters with an integer + default value. + +08/25/2007: olly + [PHP5] Generate __isset() methods for setters for PHP 5.1 and later. + +08/20/2007: wsfulton + [Java C#] Fix director bug #1776651 reported by Stephane Routelous which occurred when + the director class name is the same as the start of some other symbols used within + the director class. + +08/17/2007: wsfulton + Correct behaviour for templated methods used with %rename or %ignore and the empty + template declaration - %template(). A warning is issued if the method has not been + renamed. + +08/16/2007: mutandiz (Mikel Bancroft) + [allegrocl] Name generated cl file based on input file rather than by + module name. It was possible to end up with a mypackage.cl and a test_wrap.c + when parsing a test.i input file. Confusing. Also, include external-format + templates for :fat and :fat-le automatically to avoid these being compiled + at runtime. + +08/15/2007: efuzzyone + [cffi] Apply patch #1766076 from Leigh Smith adding support for newly introduced + in cffi :long-long and :unsigned-long-long. + +08/10/2007: wsfulton + [Java] Add documentation patch #1743573 from Jeffrey Sorensen. It contains a neat + idea with respect to better memory management by the JVM of C++ allocated memory. + +08/10/2007: wsfulton + [Perl] Apply patch #1771410 from Wade Brainerd to fix typedef XS(SwigPerlWrapper) in + perlrun.swg for ActiveState Perl build 822 and Perl 5.8.9 and 5.10 branches. + +08/10/2007: wsfulton + [Lua] const enum reference typemaps fixed. + +08/09/2007: wsfulton + [C#] Added missing support for C++ class member pointers. + +08/09/2007: wsfulton + [C#, Java] Add support for $owner in the "out" typemaps like in the the scripting + language modules. Note that $owner has always been supported in the "javaout" / "csout" + typemaps. + +08/01/2007: wsfulton + Fix smart pointer handling for classes that have templated methods within the smart + pointer type. Problem reported by craigdo at ee.washington.edu. + +07/31/2007: efuzzyone + [cffi] fixed memory access after being freed bug. thanks to Martin Percossi. + package name clos changed to cl. thanks to Ralf Mattes + +07/24/2007: wsfulton + Parallel make support added for the examples and test-suite for developers who have + more than one CPU. Now parallel make can be used for checking in addition to building + the SWIG executable. Some typical checking examples: + + make -j8 -k check + make -j4 check-java-test-suite + make -j2 check-java-examples + +07/19/2007: mgossage + Fixed bug that stopped configure working on mingw (applied dos2unix to configure.in) + +07/10/2007: mgossage + [lua] Extra compatibility with Lua 5.1 (updated SWIG_init, docs, examples, test suite) + Removed name clash for static link of multiple modules + +07/05/2007: mgossage + [lua] Fix a bug in SWIG_ALLOC_ARRAY() + improved the error messages for incorrect arguments. + Changed the output of swig_type() to use the human readable form of the type, + rather than the raw swig type. + +07/03/2007: wsfulton + [C#] Fix directors for some overloaded methods where the imtype resulted in identical + methods being generated in the C# director class, eg void foo(int *) and void foo(double *) + used to generated two of these: + + private void SwigDirectorfoo(IntPtr p) { ... } + +06/25/2007: wsfulton + [Java, C#] Some parameter name changes in std_vector.i allowing better targeting + of typemaps for method parameters (for memory management of containers of pointers). + +06/07/2007: mutandiz (Mikel Bancroft) + [allegrocl] + fix foreign-type constructor to properly look for ffitype typemap + bindings. fix inout_typemaps.i for strings. + +06/06/2007: olly + [Ruby] + Use whichever of "long" or "long long" is the same size as "void*" + to hold pointers as integers, rather than whichever matches off_t. + Fixes compilation on OS X and GCC warnings on platforms where + sizeof(void*) < sizeof(off_t) (SF patch #1731979). + +06/06/2007: olly + [PHP5] + Fix handling of a particular case involving overloaded functions + with default parameters. + +06/05/2007: mutandiz (Mikel Bancroft) + [allegrocl] + Fix case where we'd pass fully qualified identifiers + (i.e. NS1::NS2::FOO) to swig-insert-id. All namespaces + should be stripped. + + Fix bug in TypedefHandler introduced by last fix. + +06/05/2007: olly + Fix reporting of filenames in errors after %include (patch from + Leigh Smith in #1731040; also reported as #1699940). + +05/31/2007: olly + [Python] + Fix "missing initialiser" warning when compiling generated C/C++ + wrapper code with Python 2.5 with warnings enabled (patch from + bug#1727668 from Luke Moore). + +05/29/2007: olly + [Python] + Split docstrings into separate string literals at each newline when + generating C/C++ wrapper code (the C/C++ compiler will just combine + them back into a single string literal). This avoids MSVC + complaining that the strings are too long (problem reported by + Bo Peng on the mailing list). + +05/28/2007: olly + [Python] + Escape backslashes in docstrings. + +05/26/2007: olly + [Python] + Fix autodoc generation of enums to be more consistent with how the + enums are wrapped - patch #1697226 from Josh Cherry. + +05/26/2007: olly + [PHP5] + Fix wrapping of methods and functions which return a pointer to a + class (bug#1700788) and those which have overloaded forms returning + both classes and non-classes (bug#1712717, thanks to Simon + Berthiaume for the patch). + +05/25/2007: wsfulton + Fixed %rename inconsistency in conversion operators as reported by Zhong Ren. The matching + is now done on the operator name in the same way as it is done for parameters. For example: + + %rename(opABC) Space::ABC::operator ABC() const; + %rename(methodABC) Space::ABC::method(ABC a) const; + namespace Space { + class ABC { + public: + void method(ABC a) const {} + operator ABC() const { ABC a; return a; } + }; + } + + Note that qualifying the conversion operator previously may or may not have matched. + Now it definitely won't, so this will not match: + + %rename(opABC) Space::ABC::operator Space::ABC() const; + + in the same way that this does not match: + + %rename(methodABC) Space::ABC::method(Space::ABC a) const; + + The documentation has been improved with respect to %rename, namespaces and templates. + Conversion operators documentation too. + + *** POTENTIAL INCOMPATIBILITY *** + +05/16/2007: mutandiz + [allegrocl] + Fix bad generation of local var ltype's in functionWrapper(). + Try to work better with the backward order in which swig + unrolls nested class definitions. + cleaned up a little unnecessary code/debug printf's. + Remove warning when replacing $ldestructor for ff:foreign-pointer + +05/12/2007: olly + [Python] + swig -python -threads now generates C/C++ code which uses Python's + own threading abstraction (from pythread.h) rather than OS specific + code. The old code failed to compile on MS Windows. (See SF patch + tracker #1710341). + +05/04/2007: gga + [Ruby] + Changed STL renames to be global renames. This fixes + STL functions not being renamed when autorename is on. + This is a not a totally perfect work-around, but better. + Someone really needs to fix the template renaming code. + (See bug #1545634) + +05/04/2007 gga + [All] + Changed %rename("%(undercase)s") a little so that single + numbers at the end of a function are not undercased. That is: + getSomething -> get_something + get2D -> get_2d + get234 -> get_234 + BUT: + asFloat2 -> as_float2 + (Bug #1699714) + +05/03/2007: gga + [Ruby] + Made __swigtype__ => @__swigtype__ so it can be accessed + from the scripting language (and follows Ruby's official + documentation, just in case). + Made tracking => @__trackings__ for same reason. + Currently storing ivars without the @ seems valid, but + the PickAxe says this is not correct, so just in case... + +05/03/2007: gga + [Ruby] + Applied patch for -minherit bug and exception classes. + This issue should be revisited more closely, as Multiple + Inheritance in Ruby is still problematic. + (patch/bug #1604878) + +05/03/2007: gga + [Ruby] + Overloaded functions in ruby will now report to the user + the possible prototypes when the user mistypes the number or + type of a parameter. + +05/03/2007: gga + [Ruby] + Forgot to document the bug fixing of an old bug regarding + exceptions. + (bug #1458247) + +05/03/2007: gga + [Ruby] + Fixed Ruby documentation to use the proper css styles for + each section. Added autodoc section to Ruby's docs to + document the features supported by Ruby in documenting its modules. + Made rdoc documentation spit out the full name of the class + + method name. Albeit this will make the current rdoc not recognize + the method, this is still needed to disambiguate between different + classes with similar methods (rdoc was created to document the + ruby source which only contains one class per c file, unlike swig) + I have patched rdoc to make it more friendly to swig. This + patch needs to be merged in the ruby std library now. + +05/03/2007: gga + [Ruby] + Changed flag -feature to be -init_name to better reflect its + purpose and avoid confusion with -features. + +05/03/2007: gga + [Ruby] + Improved autodoc generation. + Added autodoc .swg files to Ruby library for easily adding + documentation to common Ruby methods and STL methods. + Fixed autodoc documenting of getters and setters and module. + Made test suite always generate autodocs. + +05/03/2007: gga + [Ruby] + Removed some warnings from STL and test suite. + +05/02/2007: mgossage + [Lua] Fixed issues with C++ classes and hierachies across multiple + source files. Fixed imports test case & added run test. + Added Examples/imports. + Added typename for raw lua_State* + Added documentation on native functions. + +05/02/2007: gga + [Ruby] + Docstrings are now supported. + %feature("autodoc") and %feature("docstring") are now + properly supported in Ruby. These features will generate + a _wrap.cxx file with rdoc comments in them. + +05/02/2007: gga + [Ruby] + STL files have been upgraded to follow the new swig/python + Lib/std conventions. + This means std::vector, std::set, std::map, set::multimap, + std::multiset, std::deque and std::string are now properly + supported, including their iterators, support for containing + ruby objects (swig::GC_VALUE) and several other ruby + enhancements. + std::complex, std::ios, std::iostream, std::iostreambuf and + std::sstream are now also supported. + std::wstring, std::wios, std::wiostream, std::wiostreambuf + and std::wsstream are supported verbatim with no unicode + conversion. + + std_vector.i now mimics the behavior of Ruby Arrays much more + closely, supporting slicing, shifting, unshifting, + multiple indexing and proper return values on assignment. + + COMPATABILITY NOTE: this changes the older api a little bit in + that improper indexing would previously (incorrectly) raise + exceptions. Now, nil is returned instead, following ruby's + standard Array behavior. + +05/02/2007: gga + [Ruby] + Changed the value of SWIG_TYPECHECK_BOOL to be 10000 (ie. higher + than that of all integers). + This is because Ruby allows typecasting + integers down to booleans which can make overloaded functions on + bools and integers to fail. + (bug# 1488142) + +05/02/2007: gga + [Ruby] + Fixed a subtle bug in multiple argouts that could get triggered if + the user returned two or more arguments and the first one was an + array. + +05/01/2007: gga + [Ruby] + Improved the documentation to document the new features + added, add directorin/out/argout typemaps, etc. + +05/01/2007: gga + [Ruby] + Added %initstack and %ignorestack directives for director + functions. These allow you to control whether a director + function should re-init the Ruby stack. + This is sometimes needed for an embedded Ruby where the + director method is used as a C++ callback and not called + by the user from ruby code. + Explanation: + Ruby's GC needs to be aware of the running OS stack in order to + mark any VALUE (Ruby objects) it finds there to avoid collection + of them. This allows the ruby API to be very simple and allows + you to write code like "VALUE a = sth" anywhere without needing + to do things like refcounting like python. + By default, the start of the stack is set when ruby_init() is + called. If ruby is inited within main(), as it usually is the + case with the main ruby executable, ruby will be able to calculate + its stack properly. However, when this is not possible, as when + ruby is embedded as a plugin to an application where main is not + available, ruby_init() will be called in the wrong place, and + ruby will be incorrectly tracking the stack from the function + that called ruby_init() forwards only, which can lead to + all sorts of weird crashes or to ruby thinking it has run out of + stack space incorrectly. + To avoid this, director (callback) functions can now be tagged + to try to reset the ruby stack, which will solve the issues. + NOTE: ruby1.8.6 still contains a bug in it in that its function + to reset the stack will not always do so. This bug is triggered + very rarely, when ruby is called from two very distinct places + in memory, like a branch of main() and another dso. This bug + has now been reported to ruby-core and is pending further + investigation. + (bug #1700535 and patch #1702907) + +04/30/2007: wsfulton + Fix #1707582 - Restore building from read-only source directories. + +04/30/2007: gga + [Ruby] + Ruby will now report the parameter index properly on type + errors as well as the class and value of the incorrect + argument passed. + (feature request #1699670) + +04/30/2007: gga + [Ruby] + Ruby no longer creates the free_Class function if the class + contains its own user defined free function (%freefunc). + (bug #1702882) + +04/30/2007: gga + [Ruby] + Made directors raise a ruby exception for incorrect argout + returned values if RUBY_EMBEDDED is set, instead of throwing + an actual SwigDirector exception. + This will prevent crashes when ruby is embedded and unaware + of the SwigDirector exception. + +04/30/2007: gga + [Ruby] + Removed the need for -DSWIGEXTERN. + Changed swig_ruby_trackings to be a static variable, but also + be kept within a hidden instance variable in the SWIG module. + This allows properly dealing with trackings across multiple + DSOs, which was previously broken. + (bug #1700535 and improvement to patch #1702907) + +04/29/2007: gga + [Ruby] Fixed GC memory issues with trackings that could lead + to segfaults when dealing, mainly, with static variables. + (bug #1700535 and patch #1702907) + +04/29/2007: gga + [Ruby] + Fixed String conversion using old ruby1.6 macros. Now + StringValuePtr() is used if available. This removes warnings + when converting strings with \0 in them. + (bug #1700535 and patch #1702907) + +04/29/2007: gga + [Ruby] + Fixed the argout count in directors for Ruby. Previously, + ignored or "numinputs=0" typemaps would incorrectly not get + counted towards the argout count. + (bug/patch #1545585) + +04/29/2007: gga + [Ruby] + Upgraded Ruby converter to recognize "numinputs=0". Previously, + only the old "ignore" flag was checked (which would currently + still work properly, but is deprecated). + +04/29/2007: gga + [Ruby - but should be made generic] + + %feature("numoutputs","0") added. + + This feature allows you to ignore the output of a function so + that it is not added to a list of output values + ( ie. argouts ). + This should also become a feature of %typemap(directorout) + as "numoutputs"=0, just like "numinputs"=0 exists. + + %feature("directors"=1) + + %include + + %feature("numoutputs","0") { Class::member_function1 }; + %typemap(out) MStatus { // some code, like check mstatus + // and raise exception if wrong }; + + %inline %{ + typedef int MStatus; + class Class { + + // one argument returned, but director out code added + // MStatus is discarded as a return (out) parameter. + virtual MStatus member_function1( int& OUTPUT ); + + // two arguments returned, director out code added + // MStatus is not discarded + virtual MStatus member_function2( int& OUTPUT ); + }; + %} + + +04/21/2007: olly + Fix parsing of float constants with an exponent (e.g. 1e-02f) + (bug #1699646). + +04/20/2007: olly + [Python] Fix lack of generation of docstrings when -O is used. + Also, fix generation of docstrings containing a double quote + character. Patch from Richard Boulton in bug#1700146. + +04/17/2007: wsfulton + [Java, C#] Support for adding in Java/C# code before and after the intermediary call, + specifically related to the marshalling of the proxy type to the intermediary type. + The javain/csin typemap now supports the 'pre' and 'post' attributes to achieve this. + The javain typemap also supports an optional 'pgcppname' attribute for premature garbage + collection prevention parameter naming and the csin typemap supports an optional 'cshin' + attribute for the parameter type used in a constructor helper generated when the type is used + in a constructor. Details in the Java.html and CSharp.html documentation. + +04/16/2007: olly + Don't treat `restrict' as a reserved identifier in C++ mode + (bug#1685534). + +04/16/2007: olly + [PHP5] Fix how zend_throw_exception() is called (bug #1700785). + +04/10/2007: olly + Define SWIGTEMPLATEDISAMBIGUATOR to template for aCC (reported on + swig-user that this is needed). + +04/04/2007: olly + [PHP5] If ZTS is enabled, release _globals_id in MSHUTDOWN + to avoid PHP interpreter crash on shutdown. This solution was + suggested here: http://bugs.php.net/bug.php?id=40985 + +04/03/2007: olly + [PHP4] Add missing ZTS annotations to generated C++ wrapper code + to fix compilation failures when using ZTS enabled SWIG (Linux + distributions tend to disable ZTS, but notably the Windows build + uses it by default). + +04/01/2007: efuzzyone + [CFFI] Patch #1684261: fixes handling of unsigned int literals, thanks Leigh Smith. + Also, improved documentation. + +03/30/2007: olly + Avoid generating '<:' token when using SwigValueWrapper<> on a type + which starts with '::' (patch #1690948). + +03/25/2007: wuzzeb (John Lenz) + [perl5] Add SWIG_fail to the SWIG_exception macro. Fixes a few problems reported + on the mailing list. + +03/23/2007: wsfulton + String copying patch from Josh Cherry reducing memory consumption by about 25%. + +03/21/2007: wsfulton + [Java] Apply patch #1631987 from Ulrik Peterson - bool INOUT typemaps + fail on big endian machines. + +03/16/2007: wsfulton + Fix seg fault given dodgy C++ code: namespace abc::def { } + +03/16/2007: wsfulton + [Java] Fixes so that ARRAYSOFCLASSES and ARRAYSOFENUMS in arrays_java.i can be applied + to pointer types. + +03/03/2007: olly + [PHP5] When we know the literal numeric value for a constant, use + that to initialise the const member in the PHP wrapper class. + +03/02/2007: olly + [PHP5] Fix PHP wrapper code generated for certain cases of + overloaded forms with default arguments. + +02/26/2007: efuzzyone + [CFFI] Patch #1656395: fixed hex and octal values bug, thanks to Arthur Smyles. + +02/22/2007: mgossage + [Lua] Fixed bug in typemaps which caused derived_byvalue and rname test cases to fail. + Updated derived_byvalue.i to explain how to find and fix the problem + +01/25/2007: wsfulton + Fix #1538522 and #1338527, forward templated class declarations without a + name for the templated class parameters, such as: + + template class X; + +01/23/2007: mgossage + [Lua] Patch #1640862: replaced by + Patch #1598063 Typo in typemaps.i + +01/22/2007: mgossage + [Lua] Added a lua specific carrays.i which adds the operator[] support. + modified the main code to make it not emit all the class member functions & accessors + Note: C structs are created using new_XXX() while C++ classes use XXX() (should be standardised) + Updated test case: li_carrays + Updated the documentation. + +01/12/2007: wsfulton + [Php] Add support for newfree typemaps (sometimes used by %newobject) + +01/12/2007: beazley + New command line option -macroerrors. When supplied, this will force + the C scanner/parser to report proper location information for code contained + inside SWIG macros (defined with %define). By default, SWIG merely reports + errors on the line at which a macro is used. With this option, you + can expand the error back to its source---something which may simplify + debugging. + +01/12/2007: beazley + [Internals] Major overhaul of C/C++ scanning implementation. For quite + some time, SWIG contained two completely independent C/C++ tokenizers-- + the legacy scanner in CParse/cscanner.c and a general purpose scanner + in Swig/scanner.c. SWIG still has two scanning modules, but the C parser + scanner (CParse/cscanner.c) now relies upon the general purpose + scanner found in Swig/scanner.c. As a result, it is much smaller and + less complicated. This change also makes it possible to maintain all + of the low-level C tokenizing in one central location instead of two + places as before. + + ***POTENTIAL FLAKINESS*** + This change may cause problems with accurate line number reporting + as well as error reporting more generally. I have tried to resolve this + as much as possible, but there might be some corner cases. + +01/12/2007: mgossage + [Lua] Added typemap throws for std::string*, typemap for SWIGTYPE DYNAMIC, + changed the existing throws typemap to throw a string instead of making a copy of + the object (updating a few test cases to deal with the change). + fixed test case: dynamic_casts, exception_partial_info, li_std_string, size_t + +01/03/2007: beazley + [Internals]. Use of swigkeys.c/.h variables is revoked. Please use + simple strings for attribute names. + +12/30/2006: beazley + Internal API functions HashGetAttr() and HashCheckAttr() have been revoked. + Please use Getattr() to retrieve attributes. The function Checkattr() can + be used to check attributes. Note: These functions have been revoked + because they only added a marginal performance improvement at the expense + code clarity. + +12/26/2006: mgossage + [Lua] Added more STL (more exceptions, map, size_t), + fixed test case: conversion_ns_template. + +12/21/2006: mgossage + [Lua] Update to throw errors when setting immutables, + and allowing user addition of module variables. + +12/20/2006: wsfulton + Fix typedef'd variable wrappers that use %naturalvar, eg, std::string. + +12/14/2006: wsfulton + [C#] Add std::wstring and wchar_t typemaps + +12/14/2006: olly + [php] Fix bug #1613673 (bad PHP5 code generated for getters and + setters). + +12/02/2006: wsfulton, John Lenz, Dave Beazley + Move from cvs to Subversion for source control + +11/30/2006: beazley + Cleaned up swigwarnings.swg file not to use nested macro + definitions. + +11/12/2006: wsfulton + [Java, C#] Fix for %extend to work for static member variables. + +Version 1.3.31 (November 20, 2006) +================================== + +11/12/2006: Luigi Ballabio + [Python] Alternate fix for Python exceptions bug #1578346 (the previous one broke Python + properties in modern classes) + +11/12/2006: wsfulton + -fakeversion commandline option now generates the fake version into the generated wrappers + as well as displaying it when the -version commandline option is used. + +14/11/2006: mgossage + [lua] update to typemap for object by value, to make it c89 compliant + +Version 1.3.30 (November 13, 2006) +================================== + +11/12/2006: wsfulton + [java] Remove DetachCurrentThread patch from 08/11/2006 - it causes segfaults + on some systems. + +11/12/2006: wsfulton + [python] Fix #1578346 - Python exceptions with -modern + +11/10/2006: wsfulton + Fix #1593291 - Smart pointers and inheriting from templates + +11/09/2006: wsfulton + Fix director operator pointer/reference casts - #1592173. + +11/07/2006: wsfulton + Add $self special variable for %extend methods. Please use this instead of just 'self' + as the C++ 'this' pointer. + +11/07/2006: mutandiz + [allegrocl] + allegrocl.swg: swig-defvar updated to allow specifying of + non-default foreign type (via :ftype keyword arg). + allegrocl.cxx: Specify proper access type for enum values. + +11/03/2006: wsfulton + [Java/C#] Fix const std::string& return types for directors as reported by + Mark Donselzmann + +10/29/2006: wsfulton + [Java] Remove DeleteLocalRef from end of director methods for now as it is causing a + seg fault when run on Solaris 8. + +10/29/2006: wuzzeb (John Lenz) + [Guile] Patch from Chris Shoemaker to clean up some warnings in the generated code. + +10/29/2006: wsfulton + [Java] Important fix to prevent early garbage collection of the Java proxy class + while it is being used in a native method. The finalizer could destroy the underlying + C++ object while it was being used. The problem occurs when the proxy class is no + longer strongly reachable after a native call. The problem seems to occur in + memory stress situations on some JVMs. It does not seem to occur on the + Sun client JVM up to jdk 1.5. However the 1.6 client jdk has a more aggressive garbage + collector and so the problem does occur. It does occur on the Sun server + JVMs (certainly 1.4 onwards). The fix entails passing the proxy class into the native + method in addition to the C++ pointer in the long parameter, as Java classes are not + collected when they are passed into JNI methods. The extra parameter can be suppressed + by setting the nopgcpp attribute in the jtype typemap to "1" or using the new -nopgcpp + commandline option. + + See Java.html#java_pgcpp for further details on this topic. + +10/24/2006: wsfulton + [C#] Fix smart pointer wrappers. The virtual/override/new keyword is not generated + for each method as the smart pointer class does not mirror the underlying pointer + class inheritance hierarchy. SF #1496535 + +10/24/2006: mgossage + [lua] added support for native methods & member function pointers. + fixed test cases arrays_dimensionless & cpp_basic. Added new example (functor). + tidied up a little of the code (around classHandler). + +10/17/2006: wsfulton + [C#, Java] directorout typemap changes to fall in line with the other director + languages. $result is now used where $1 used to be used. Please change your typemaps + if you have a custom directorout typemap. + +10/18/2006: wsfulton + Some fixes for applying the char array typemaps to unsigned char arrays. + +10/17/2006: wsfulton + [C#, Java] Add in const size_t& and const std::size_t& typemaps. + +10/15/2006: efuzzyone + [CFFI] Suppress generating defctype for enums, thanks to Arthur Smyles. Patch 1560983. + +10/14/2006: wuzzeb (John Lenz) + [Chicken] Minor fix to make SWIG work with the (as yet unreleased) chicken 2.5 + + [Guile,Chicken] Fix SF Bug 1573892. Added an ext_test to the test suite to test + this bug, but this test can not really be made generic because the external code must + plug into the target language interpreter directly. + See Examples/test-suite/chicken/ext_test.i and ext_test_external.cxx + + Added a %.externaltest to common.mk, and any interested language modules can + copy and slightly modify either the chicken or the guile ext_test.i + +10/14/2006: mgossage + [Lua] added OUTPUT& for all number types, added a long long type + fixed several test cases. + update: changed typemaps to use SWIG_ConvertPtr rather than SWIG_MustGetPointer + started spliting lua.swg into smaller parts to make it neater + +10/13/2006: wsfulton + [C#, Java] Marginally better support for multiple inheritance only in that you can + control what the base class is. This is done using the new 'replace' attribute in the + javabase/csbase typemap, eg in the following, 'Me' will be the base class, + no matter what Foo is really derived from in the C++ layer. + + %typemap(javabase, replace="1") Foo "Me"; + %typemap(csbase, replace="1") Foo "Me"; + + Previously it was not possible for the javabase/csbase typemaps to override the C++ base. + +10/12/2006: wsfulton + [Java] Remove potential race condition on the proxy class' delete() method + (it is now a synchronized method, but is now customisable by changing the + methodmodifiers attribute in the the javadestruct or javadestruct_derived typemap) + + [C#] Remove potential race condition on the proxy class' Dispose() method, + similar to Java's delete() above. + + *** POTENTIAL INCOMPATIBILITY *** + +10/12/2006: wsfulton + [Ruby, Python] Remove redundant director code in %extend methods (%extend + methods cannot be director methods) + +10/12/2006: wsfulton + [Ruby, Python] Fix #1505594 - director objects not returned as director objects + in %extend methods. + +10/11/2006: wsfulton + [Java] Fix #1238798 - Directors using unsigned long long or any other type + marshalled across the JNI boundary using a Java class (where the jni typemap + contains jobject). + +10/06/2006: wsfulton + Fix #1162194 - #include/%include within a structure + +10/06/2006: wsfulton + Fix #1450661, string truncation in String_seek truncating Java/C# enums. + +10/06/2006: mgossage + [Lua] Fix #1569587. The name is now correct. + +10/04/2006: wsfulton + Director fixes for virtual conversion operators + +10/04/2006: olly + [php] Fix #1569587 for PHP. Don't use sizeof() except with string + literals. Change some "//" comments to "/* */" for portability. + +10/04/2006: mgossage + [Lua] Partial Fix #1569587. The type is now correct, but the name is still not correct. + +10/03/2006: wsfulton + [Ruby] Fix #1527885 - Overloaded director virtual methods sometimes produced + uncompileable code when used with the director:except feature. + +10/03/2006: wsfulton + Directors: Directors are output in the order in which they are declared in + the C++ class rather than in some pseudo-random order. + +10/03/2006: mmatus + Fix #1486281 and #1471039. + +10/03/2006: olly + [Perl] Fix for handling strings with zero bytes from Stephen Hutsal. + +09/30/2006: efuzzyone + [CFFI] Bitfield support and vararg support due to Arthur Smyles. + C expression to Lisp conversion, thanks to Arthur Smyles for the initial + idea, it now supports conversion for a whole range of C expressions. + +09/28/2006: wsfulton + Fix #1508327 - Overloaded methods are hidden when using -fvirtual optimisation. + Overloaded methods are no longer candidates for elimination - this mimics + C++ behaviour where all overloaded methods must be defined and implemented + in a derived class in order for them to be available. + +09/25/2006: wsfulton + [Ruby, Python, Ocaml] Fix #1505591 Throwing exceptions in extended directors + +09/25/2006: wsfulton + Fix #1056100 - virtual operators. + +09/24/2006: olly + Don't accidentally create a "<:" token (which is the same as "[" in C++). + Fixes bug # 1521788. + +09/23/2006: olly + [Ruby] Support building with recent versions of the Ruby 1.9 + development branch. Fixes bug #1560092. + +09/23/2006: olly + Templates can now be instantiated using negative numbers and + constant expressions, e.g.: + + template class x {}; + %template(x_minus1) x<-1>; + %template(x_1plus2) x<1+2>; + + Also, constant expressions can now include comparisons (>, <, >=, + <=, !=, ==), modulus (%), and ternary conditionals (a ? b : c). + + Fixes bugs #646275, #925555, #956282, #994301. + +09/22/2006: wsfulton + Fix %ignore on director methods - Bugs #1546254, #1543533 + +09/20/2006: wsfulton + Fix %ignore on director constructors + +09/20/2006: wsfulton + Fix seg faults and asserts when director methods are ignored (#1543533) + +09/20/2006: wsfulton + Fix out of source builds - bug #1544718 + +09/20/2006: olly + Treat a nested class definition as a forward declaration rather + than ignoring it completely, so that we generate correct code for + passing opaque pointers to the nested class (fixes SF bug #909387). + +09/20/2006: olly + *** POTENTIAL INCOMPATIBILITY *** + [php] Overload resolution now works. However to allow this, SWIG + generated wrappers no longer coerce PHP types (which reverts a change + made in 1.3.26). So for example, if a method takes a string, you + can no longer pass a number without explicitly converting it to a + string in PHP using: (string)x + +09/18/2006: mgossage + [ALL] fix on swiginit.swg, has been reported to crash on several test cases + found and fixed problem in imports under python (mingw) + +09/16/2006: wsfulton + [Python] Patch from Michal Marek for Python 2.5 to fix 64 bit array indexes on + 64 bit machines. + +09/13/2006: wsfulton + The explicitcall feature has been scrapped. This feature was introduced primarily + to solve recursive director method calls. Director upcall improvements made instead: + + [Python, Ruby, Ocaml] The swig_up flag is no longer used. The required mutexes + wrapping this flag are also no longer needed. The recursive calls going from C++ + to the target language and back again etc are now avoided by a subtlely different + approach. Instead of using the swig_up flag in each director method to indicate + whether the explicit C++ call to the appropriate base class method or a normal + polymorphic C++ call should be made, the new approach makes one of these calls + directly from the wrapper method. + + [Java, C#] The recursive call problem when calling a C++ base class method from + Java/C# is now fixed. The implementation is slightly different to the other languages + as the detection as to whether the explicit call or a normal polymorphic call is made + in the Java/C# layer rather than in the C++ layer. + +09/11/2006: mgossage + [ALL] updated swiginit.swg to allow multiple interpreters to use multiple + swig modules at once. This has been tested in Lua (mingw & linux), + perl5 & python (linux) only. + +09/11/2006: mgossage + [lua] added support for passing function pointers as well as native lua object + into wrappered function. + Added example funcptr3 to demonstrate this feature + +09/05/2006: olly + [php] Rename ErrorCode and ErrorMsg #define-s to SWIG_ErrorCode + and SWIG_ErrorMsg to avoid clashes with code the user might be + wrapping (patch from Darren Warner in SF bug #1466086). Any + user typemaps which use ErrorCode and/or ErrorMsg directly will + need adjusting - you can easily fix them to work with both old + and new SWIG by changing to use SWIG_ErrorMsg and adding: + + #ifndef SWIG_ErrorMsg + #define SWIG_ErrorMsg() ErrorMsg() + #endif + +08/29/2006: olly + [php] Move constant initialisation from RINIT to MINIT to fix a + warning when using Apache and mod_php. We only need to create + PHP constants once when we're first initialised, not for every HTTP + request. + +08/21/2006: mgossage + [Lua] + Bugfix #1542466 added code to allow mapping Lua nil's <-> C/C++ NULL's + updated various typemaps to work correctly with the changes + added voidtest_runme.lua to show the features working + +08/19/2006: wuzzeb (John Lenz) + [Guile] Add feature:constasvar to export constants as variables instead of functions + that return the constant value. + +08/11/2006: wsfulton + [Java] DetachCurrentThread calls have been added so that natively created threads + no longer prevent the JVM from exiting. Bug reported by Thomas Dudziak and + Paul Noll. + +08/10/2006: wsfulton + [C#] Fix director protected methods so they work + +07/25/2006: mutandiz + [allegrocl] + more additions to std::string, some tweaks and small bug fixes + -nocwrap mode. + +07/21/2006: mgossage + [Lua] + Bugfix #1526022 pdated std::string to support strings with '\0' inside them + updated typemaps.i to add support for pointer to pointers + +07/19/2006: mutandiz + [allegrocl] + - Add std_string.i support. + - Add newobject patch submitted by mkoeppe (thanks!) + - Fix type name mismatch issue for nested type definitions. + specifically typedefs in templated class defns. + +07/18/2006: mgossage + Bugfix #1522858 + updated lua.cxx to support -external-runtime command + +07/14/2006: wuzzeb (John Lenz) + Increment the SWIG_RUNTIME_VERSION to 3, because of the + addition of the owndata member in swig_type_info. + Reported by: Prabhu Ramachandran + +07/05/2006: wsfulton + Search path fixes: + - Fix search path for library files to behave as documented in Library.html. + - Fix mingw/msys builds which did not find the SWIG library when installed. + - Windows builds also output the mingw/msys install location when running + swig -swiglib. + - The non-existent and undocumented config directory in the search path has + been removed. + +07/05/2006: wsfulton + Fix $symname special variable expansion. + +07/04/2006: wuzzeb (John Lenz) + [Chicken] + Add %feature("constasvar"), which instead of exporting a constant as a + scheme function, exports the constant as a scheme variable. Update the + documentation as well. + +07/04/2006: wsfulton + [See entry of 09/13/2006 - explicitcall feature and documentation to it removed] + New explicitcall feature which generates additional wrappers for virtual methods + that call the method explicitly, not relying on polymorphism to make the method + call. The feature is a feature flag and is enabled like any other feature flag. + It also recognises an attribute, "suffix" for mangling the feature name, see + SWIGPlus.html#SWIGPlus_explicitcall documentation for more details. + + [Java, C#] + The explicitcall feature is also a workaround for solving the recursive calls + problem when a director method makes a call to a base class method. See + Java.html#java_directors_explicitcall for updated documentation. + +06/28/2006: joe (Joseph Wang) + [r] Initial support for R + +06/20/2006: wuzzeb (John Lenz) + [Chicken] + Minor fixes to get apply_strings.i testsuite to pass + Remove integers_runme.scm from the testsuite, because SWIG and Chicken does + handle overflows. + +06/19/2005: olly + [php] Add support for generating PHP5 class wrappers for C++ + classes (use "swig -php5"). + +06/17/2006: olly + [php] Added some missing keywords to the PHP4 keyword list, and + fixed __LINE__ and __FILE__ which were in the wrong category. + Also added all the keywords new in PHP5, and added comments + noting the PHP4 keywords which aren't keywords in PHP5. + +06/17/2006: olly + [php] Don't segfault if PHP Null is passed as this pointer (e.g. + Class_method(Null)) - give a PHP Error instead. + +06/15/2006: mutandiz + [allegrocl] + Add initial support for std::list container class. + Fix a few bugs in helper functions. + +05/13/2006: wsfulton + [Java] Replace JNIEXPORT with SWIGEXPORT, thereby enabling the possibility + of using gcc -fvisibility=hidden for potentially smaller faster loading wrappers. + +05/13/2006: wsfulton + Fix for Makefiles for autoconf-2.60 beta + +05/13/2006: wsfulton + Vladimir Menshakov patch for compiling wrappers with python-2.5 alpha. + +05/12/2006: wsfulton + Fix buffer overflow error when using large %feature(docstring) reported + by Joseph Winston. + +05/12/2006: wsfulton + [Perl] Operator overload fix from Daniel Moore. + +05/25/2006: mutandiz + [allegrocl] + Fix bug in generation of CLOS type declarations for unions + and equivalent types. + +05/24/2006: mutandiz + [allegrocl] + Don't require a full class definition to generate a CLOS wrapper. + +05/20/2006: olly + [php] GCC Visibility support now works with PHP. + +05/19/2006: olly + [php] Removed support for -dlname (use -module instead). Fixed + naming of PHP extension module to be consistent with PHP + conventions (no "php_" prefix on Unix; on PHP >= 4.3.0, handle Unix + platforms which use something other than ".so" as the extension.) + +05/13/2006: wsfulton + [C#] Director support added + +05/07/2006: olly + [php] Don't segfault if PHP Null is passed where a C++ reference + is wanted. + +05/05/2006: olly + [php] Fix wrappers generated for global 'char' variables to not + include a terminating zero byte in the PHP string. + +05/03/2006: wsfulton + Modify typemaps so that char * can be applied to unsigned char * or signed char * + types and visa versa. + +05/03/2006: efuzzyone + [cffi]Thanks to Luke J Crook for this idea. + - a struct/enum/union is replaced with :pointer only if + that slot is actually a pointer to that type. So,: + struct a_struct { int x; } and + struct b_struct { a_struct struct_1; }; + will be converted as: + (cffi:defcstruct b_struct + (struct_1 a_struct)) + - Other minor fixes in lispifying names. + +05/02/2006: wsfulton + Fix possible redefinition of _CRT_SECURE_NO_DEPRECATE for VC++. + +04/14/2006: efuzzyone + [cffi] + Thanks to Thomas Weidner for the patch. + - when feature export is set (export 'foo) is + generated for every symbol + - when feature inline is set (declaim (inline foo)) is + generated before every function definition + - when feature intern_function is set + #.(value-of-intern-function "name" "nodeType" package) + is emitted instead of the plain symbol. A sample swig-lispify + is provided. + - every symbol is prefixed by it's package. + +04/13/2006: efuzzyone + [cffi] + Fixed the generation of wrappers for global variables. + Added the option [no]swig-lisp which turns on/off generation + of code for swig helper lisp macro, functions, etc. + +Version 1.3.29 (March 21, 2006) +=============================== + +04/05/2006: mutandiz + [allegrocl] + Fix output typemap of char so it produces a character instead + of an integer. Also adds input/output typemaps for 'char *'. + + add command-line argument -isolate to generate an interface + file that won't interfere with other SWIG generated files that + may be used in the same application. + +03/20/2005: mutandiz + [allegrocl] + More tweaks to INPUT/OUTPUT typemaps for bool. + + Fix constantWrapper for char and string literals. + + find-definition keybindings should work in ELI/SLIME. + Output (in-package ) to lisp wrapper + instead of (in-package #.*swig-module-name*). + + slight rework of multiple return values. + + doc updates. + +03/17/2005: mutandiz + [allegrocl] + mangle names of constants generated via constantWrapper. + + When using OUTPUT typemaps and the function has a non-void + return value, it should be first in the values-list, followed + by the OUTPUT mapped values. + + Fix bug with boolean parameters, which needed to be + passed in as int values, rather than T or NIL. + +03/15/2006: mutandiz + [allegrocl] + Generate wrappers for constants when in C++ or -cwrap mode. + Make -cwrap the default, since it is most correct. Users + can use the -nocwrap option to avoid the creation of a .cxx + file when interfacing to C code. + + When in -nocwrap mode, improve the handling of converting + infix literals to prefix notation for lisp. This is very + basic and not likely to be improved upon since this only + applies to the -nocwrap case. Literals we can't figure out + will result in a warning and be included in the generated + code. + + validIdentifier now more closely approximates what may be + a legal common lisp symbol. + + Fix typemap error in allegrocl.swg + +03/12/2006: mutandiz + [allegrocl] + fix up INPUT/OUTPUT typemaps for bool. + Generate c++ style wrapper functions for struct/union members + when -cwrap option specified. + +03/10/2006: mutandiz + [allegrocl] + Fix bug in C wrapper generation introduced by last allegrocl + commit. + +03/10/2006: wsfulton + [Java] + Commit #1447337 - Delete LocalRefs at the end of director methods to fix potential leak + +03/10/2006: wsfulton + Fix #1444949 - configure does not honor --program-prefix. + Removed non-standard configure option --with-release-suffix. Fix the autoconf standard + options --program-prefix and --program-suffix which were being shown in the help, + but were being ignored. Use --program-suffix instead of --with-release-suffix now. + +03/10/2006: wsfulton + [Java] + Fix #1446319 with patch from andreasth - more than one wstring parameter in director methods + +03/07/2006: mkoeppe + [Guile] + Fix for module names containing a "-" in non-"shadow" mode. + Patch from Aaron VanDevender (#1441474). + +03/04/2006: mmatus + - Add -O to the main program, which now enables -fastdispatch + + [Python] + + - Add the -fastinit option to enable faster __init__ + methods. Setting 'this' as 'self.this.append(this)' in the python + code confuses PyLucene. Now the initialization is done in the + the C++ side, as reported by Andi and Robin. + + - Add the -fastquery option to enable faster SWIG_TypeQuery via a + python dict cache, as proposed by Andi Vajda + + - Avoid to call PyObject_GetAttr inside SWIG_Python_GetSwigThis, + since this confuses PyLucene, as reported by Andi Vajda. + +03/02/2006: wsfulton + [Java] + Removed extra (void *) cast when casting pointers to and from jlong as this + was suppressing gcc's "dereferencing type-punned pointer will break strict-aliasing rules" + warning. This warning could be ignored in versions of gcc prior to 4.0, but now the + warning is useful as gcc -O2 and higher optimisation levels includes -fstrict-aliasing which + generates code that doesn't work with these casts. The assignment is simply never made. + Please use -fno-strict-aliasing to both suppress the warning and fix the bad assembly + code generated. Note that the warning is only generated by the C compiler, but not + the C++ compiler, yet the C++ compiler will also generate broken code. Alternatively use + -Wno-strict-aliasing to suppress the warning for gcc-3.x. The typemaps affected + are the "in" and "out" typemaps in java.swg and arrays_java.swg. Users ought to fix + their own typemaps to do the same. Note that removal of the void * cast simply prevents + suppression of the warning for the C compiler and nothing else. Typical change: + + From: + %typemap(in) SWIGTYPE * %{ $1 = *($&1_ltype)(void *)&$input; %} + To: + %typemap(in) SWIGTYPE * %{ $1 = *($&1_ltype)&$input; %} + + From: + %typemap(out) SWIGTYPE * %{ *($&1_ltype)(void *)&$result = $1; %} + To: + %typemap(out) SWIGTYPE * %{ *($&1_ltype)&$result = $1; %} + +03/02/2006: mkoeppe + [Guile -scm] + Add typemaps for "long long"; whether the generated code compiles, however, depends + on the version and configuration of Guile. + +03/02/2006: wsfulton + [C#] + Add support for inner exceptions. If any of the delegates are called which construct + a pending exception and there is already a pending exception, it will create the new + exception with the pending exception as an inner exception. + +03/02/2006: wsfulton + [Php] + Added support for Php5 exceptions if compiling against Php5 (patch from Olly Betts). + +03/01/2006: mmatus + Use the GCC visibility attribute in SWIGEXPORT. + + Now you can compile (with gcc 3.4 or later) using + CFLAGS="-fvisibility=hidden". + + Check the difference for the 'std_containers.i' python + test case: + + Sizes: + + 3305432 _std_containers.so + 2383992 _std_containers.so.hidden + + Exported symbols (nm -D .so | wc -l): + + 6146 _std_containers.so + 174 _std_containers.so.hidden + + Excecution times: + + real 0m0.050s user 0m0.039s sys 0m0.005s _std_containers.so + real 0m0.039s user 0m0.026s sys 0m0.007s _std_containers.so.hidden + + Read http://gcc.gnu.org/wiki/Visibility for more details. + + +02/27/2006: mutandiz + [allegrocl] + Add support for INPUT, OUTPUT, and INOUT typemaps. + For OUTPUT variables, the lisp wrapper returns multiple + values. + +02/26/2006: mmatus + + [Ruby] add argcargv.i library file. + + Use it as follow: + + %include argcargv.i + + %apply (int ARGC, char **ARGV) { (size_t argc, const char **argv) } + + %inline { + int mainApp(size_t argc, const char **argv) + { + return argc; + } + } + + then in the ruby side: + + args = ["asdf", "asdf2"] + n = mainApp(args); + + + This is the similar to the python version Lib/python/argcargv.i + +02/24/2006: mgossage + + Small update Lua documents on troubleshooting problems + +02/22/2006: mmatus + + Fix all the errors reported for 1.3.28. + - fix bug #1158178 + - fix bug #1060789 + - fix bug #1263457 + - fix 'const char*&' typemap in the UTL, reported by Geoff Hutchison + - fixes for python 2.1 and the runtime library + - fix copyctor + template bug #1432125 + - fix [ 1432152 ] %rename friend operators in namespace + - fix gcc warning reported by R. Bernstein + - avoid assert when finding a recursive scope inheritance, + emit a warning in the worst case, reported by Nitro + - fix premature object deletion reported by Paul in tcl3d + - fix warning reported by Nitro in VC7 + - more fixes for old Solaris compiler + - fix for python 2.3 and gc_refs issue reported by Luigi + - fix fastproxy for methods using kwargs + - fix overload + protected member issue reported by Colin McDonald + - fix seterrormsg as reported by Colin McDonald + - fix directors, now the test-suite runs again using -directors + - fix for friend operator and Visual studio and bug 1432152 + - fix bug #1435090 + - fix using + %extend as reported by William + - fix bug #1094964 + - fix for Py_NotImplemented as reported by Olly and Amaury + - fix nested namespace issue reported by Charlie + + and also: + + - allow director protected members by default + - delete extra new lines in swigmacros[UTL] + - cosmetic for generated python code + - add the factory.i library for UTL + - add swigregister proxy method and move __repr__ to a + single global module [python] + +02/22/2006: mmatus + + When using directors, now swig will emit all the virtual + protected methods by default. + + In previous releases, you needed to use the 'dirprot' + option to acheive the same. + + If you want, you can disable the new default behaviour, + use the 'nodirprot' option: + + swig -nodirprot ... + + and/or the %nodirector feature for specific methods, i.e.: + + %nodirector Foo::bar; + + struct Foo { + virtual ~Foo(); + + protected: + virtual void bar(); + }; + + + As before, pure abstract protected members are allways + emitted, independent of the 'dirprot/nodirprot' options. + + +02/22/2006: mmatus + Add the factory.i library for languages using the UTL (python,tcl,ruby,perl). + + factory.i implements a more natural wrap for factory methods. + + For example, if you have: + + ---- geometry.h -------- + struct Geometry { + enum GeomType{ + POINT, + CIRCLE + }; + + virtual ~Geometry() {} + virtual int draw() = 0; + + // + // Factory method for all the Geometry objects + // + static Geometry *create(GeomType i); + }; + + struct Point : Geometry { + int draw() { return 1; } + double width() { return 1.0; } + }; + + struct Circle : Geometry { + int draw() { return 2; } + double radius() { return 1.5; } + }; + + // + // Factory method for all the Geometry objects + // + Geometry *Geometry::create(GeomType type) { + switch (type) { + case POINT: return new Point(); + case CIRCLE: return new Circle(); + default: return 0; + } + } + ---- geometry.h -------- + + + You can use the %factory with the Geometry::create method as follows: + + %newobject Geometry::create; + %factory(Geometry *Geometry::create, Point, Circle); + %include "geometry.h" + + and Geometry::create will return a 'Point' or 'Circle' instance + instead of the plain 'Geometry' type. For example, in python: + + circle = Geometry.create(Geometry.CIRCLE) + r = circle.radius() + + where 'circle' now is a Circle proxy instance. + + +02/17/2006: mkoeppe + [MzScheme] Typemaps for all integral types now accept the full range of integral + values, and they signal an error when a value outside the valid range is passed. + [Guile] Typemaps for all integral types now signal an error when a value outside + the valid range is passed. + +02/13/2006: mgossage + [Documents] updated the extending documents to give a skeleton swigging code + with a few typemaps. + [Lua] added an extra typemap for void* [in], so a function which requires a void* + can take any kind of pointer + +Version 1.3.28 (February 12, 2006) +================================== + +02/11/2006: mmatus + Fix many issues with line counting and error reports. + +02/11/2006: mmatus + [Python] Better static data member support, if you have + + struct Foo { + static int bar; + }; + + then now is valid to access the static data member, ie: + + f = Foo() + f.bar = 3 + + just as in C++. + + +02/11/2006: wsfulton + [Perl] + Fixed code generation to work again with old versions of Perl + (5.004 and later tested) + +02/04/2006: mmatus + [Python] Add the %extend_smart_pointer() directive to extend + SWIG smart pointer support in python. + + For example, if you have a smart pointer as: + + template class RCPtr { + public: + ... + RCPtr(Type *p); + Type * operator->() const; + ... + }; + + you use the %extend_smart_pointer directive as: + + %extend_smart_pointer(RCPtr); + %template(RCPtr_A) RCPtr; + + then, if you have something like: + + RCPtr make_ptr(); + int foo(A *); + + you can do the following: + + a = make_ptr(); + b = foo(a); + + ie, swig will accept a RCPtr object where a 'A *' is + expected. + + Also, when using vectors + + %extend_smart_pointer(RCPtr); + %template(RCPtr_A) RCPtr; + %template(vector_A) std::vector >; + + you can type + + a = A(); + v = vector_A(2) + v[0] = a + + ie, an 'A *' object is accepted, via implicit conversion, + where a RCPtr object is expected. Additionally + + x = v[0] + + returns (and sets 'x' as) a copy of v[0], making reference + counting possible and consistent. + + %extend_smart_pointer is just a collections of new/old + tricks, including %typemaps and the new %implicitconv + directive. + +02/02/2006: mgossage + bugfix #1356577, changed double=>lua_number in a few places. + added the std::pair wrapping + +01/30/2006: wsfulton + std::string and std::wstring member variables and global variables now use + %naturalvar by default, meaning they will now be wrapped as expected in all languages. + Previously these were wrapped as a pointer rather than a target language string. + It is no longer necessary to add the following workaround to wrap these as strings: + + %apply const std::string & { std::string *} + + *** POTENTIAL INCOMPATIBILITY *** + +01/28/2006: mkoeppe + [Guile -scm] + Add typemaps for handling of member function pointers. + +01/24/2006: mmatus + - Better support for the %naturalvar directive, now it + works with the scripting languages as well as + Java/C#. + + Now, it can also be applied to class types: + + %naturalvar std::string; + %include + + that will tell swig to use the the 'natural' wrapping + mechanism to all std::string global and member + variables. + + - Add support for the %allowexcept feature along the + scripting languages, which allows the %exception feature + to be applied to the variable access methods. Also, add + the %exceptionvar directive to specify a distintic + exception mechanism only for variables. + + + - Add more docs for the %delobject directive to mark a method as a + destructor, 'disowning' the first argument. For example: + + %newobject create_foo; + %delobject destroy_foo; + + Foo *create_foo() { return new Foo(); } + void destroy_foo(Foo *foo) { delete foo; } + + or in a member method as: + + %delobject Foo::destroy; + + class Foo { + public: + void destroy() { delete this;} + + private: + ~Foo(); + }; + + +01/24/2006: mgossage + [Lua] + - Removed the type swig_lua_command_info & replace with luaL_reg + (which then broke the code), fixed this + - added an additional cast in the typemaps for enum's + due to the issue that VC.Net will not allow casting of + a double to an enum directly. Therefore cast to int then to enum + (thanks to Jason Rego for this observation) + +01/16/2006: mmatus (Change disabled... will be back in CVS soon) + Add initial support for regexp via the external library + RxSpencer. SWIG doesn't require this library to compile + and/or run. But if you specify --with-rxspencer, and the + library is found during installation, then swig will use + it in three places: + + - In %renames rules, via the new rxsmatch rules, for example: + + %rename("%(lowercase)",rxsmatch$name="GSL_.*") ""; + %rename("%(lowercase)",rxsmatch$nodeType="enum GSL_.*") ""; + + rxsmatch is similar to the match rule, it just uses + the RxSpencer regexp library to decide if there is a + match with the provided regexp. As with the match + rule, you can also use the negate rule notrxsmatch. + + - In the %rename target name via the rxstarget option, for example: + + %rename("%(lowercase)",rxstarget=1) "GSL_.*"; + + where the target name "GSL.*" is now understood as a + regexp to be matched. + + - In the new encoder "rxspencer", which looks like: + + %(rxspencer:[regexp][replace])s + + where "regexp" is the regular expression and "replace" + is a string used as a replacement, where the @0,@1,...,@9 + pseudo arguments are used to represent the + corresponding matching items in the reg expression. + + For example: + + %(rxspencer:[GSL.*][@0])s <- Hello -> + %(rxspencer:[GSL.*][@0])s <- GSLHello -> GSLHello + %(rxspencer:[GSL(.*)][@1])s <- GSLHello -> Hello + %(rxspencer:[GSL(.*)][gsl@1])s <- GSLHello -> gslHello + + Another example could be: + + %rename("%(lowercase)s",sourcefmt="%(rxspencer:[GSL_(.*)][@1])s",%$isfunction) ""; + + which take out the prefix "GSL_" and returns all the + function names in lower cases, as following: + + void GSL_Hello(); -> hello(); + void GSL_Hi(); -> hi(); + const int GSL_MAX; -> GSL_MAX; // no change, is not a function + + We use the RxSpencer as an initial test bed to + implemention while we decide which library will be + finally added to swig. + + You can obtain the RxSpencer library from + + http://arglist.com/regex (Unix) + + or + + http://gnuwin32.sourceforge.net/packages.html (Windows) + + Once installed, use "man rxspencer" to get more info + about the regexp format, or just google rxspencer. + + Since now you can enable the rxsmatch rules (see above), + the simple or '|' support for the match rules + (01/12/2006: mmatus) is disabled. Still, if you have + problems with the rxspencer library, you can re-enable + the simple 'match or' support using + -DSWIG_USE_SIMPLE_MATCHOR. + + +01/16/2006: mmatus + Change the %rename predicates to use the prefix '%$', as in: + + %rename("%(utitle)s",%$isfunction,%$ismember) ""; + + to avoid clashings with other swig macros/directives. + +01/14/2006: cfisavage + [Ruby] + Added support for Ruby bang! methods via a new %bang feature. + Bang methods end in exclamation points and indicate that the + object being processed will be modified in-place as + opposed to being copied. + +01/12/2006: cfisavage + [Ruby] + Updated the Ruby module to automatically convert + method names to lower_case_with_underscores using the + new %rename functionality. + +01/12/2006: mmatus + - Add aliases for 'case' encoders used with %rename/%namewarn + + %(uppercase)s hello_world -> HELLO_WORLD + %(lowercase)s HelloWorld -> helloworld + %(camelcase)s hello_world -> HelloWorld + %(undercase)s HelloWorld -> hello_world + + +01/12/2006: mmatus + - Add the -dump_parse_module and -dump_parse_top options, + which are similar to -dump_module and -dump_top, but they + dump the node trees just after parsing, showing only the + attributes visible at the parsing stage, and not the added + later in typemap.cxx, allocate.cxx, lang.cxx or elsewhere. + + Besides debugging porpuses, these options are very useful + if you plan to use %rename in an "advance way", since it + shows only and all the node's attributes you can use + inside the match rules. + + +01/12/2006: mmatus + - Add predicates to %rename, so, you don't need to + remember, for example, how to match a member function. + + Now it is easy, for example to use the 'utitle' encoder + in all the member methods, you type: + + %rename("%(utitle)s",%isfunction,%ismember) ""; + + or to ignore all the enumitems in a given class: + + %rename("$ignore", %isenumitem, %classname="MyClass") ""; + + Available predicates are (see swig.swg): + + %isenum + %isenumitem + %isaccess + %isclass + %isextend + %isextend + %isconstructor + %isdestructor + %isnamespace + %istemplate + %isconstant + + %isunion + %isfunction + %isvariable + %isimmutable + + %isstatic + %isfriend + %istypedef + %isvirtual + %isexplicit + %isextern + + %ismember + %isglobal + %innamespace + + %ispublic + %isprotected + %isprivate + + %classname + + These predicates correspond to specific 'match' + declarations, which sometimes are not as evident as the + predicates names. + + + - Add the or '|' operation in %rename match, for + example to capitalize all the constants (%constant or + const cdecl): + + %rename("%(upper)s",match="cdecl|constant",%isimmutable) ""; + + + +01/12/2006: mgossage + - Partial fixed of errors under C89, bug #1356574 + (converted C++ style comments to C style) + - Added patches from neomantra@users.sf.net #1379988 and #1388343 + missing a 'return' statement for error conditions + also updated the %init block bug #1356586 + +01/10/2006: mmatus + - Add the 'utitle' encoder, as an example of how to add + your own encoder. I added the encoder method in misc.c + but developers can add others, the same way, inside any + target language. + + Well, 'utitle' is the reverse of 'ctitle', ie: + + %rename("%(ctitle)s") camel_case; -> CamelCase; + %rename("%(utitle)s") CamelCase; -> camel_case; + + +01/10/2006: cfisavage + [Ruby] + Updated Ruby Exception handling. Classes that are specified in throws clauses, + or are marked as %exceptionclass, are now inherited from rb_eRuntimeError. + This allows instances of these classes to be returned to Ruby as exceptions. + Thus if a C++ method throws an instance of MyException, the calling Ruby + method will get back a MyException object. To see an example, + look at ruby/examples/exception_class. + +01/10/2006: mmatus + + - Add the %catches directive, which complements the %exception + directive in a more automatic way. For example, if you have + + int foo() throw(E1); + + swig generates the proper try/catch code to dispatch E1. + + But if you have: + + + int barfoo(int i) { + if (i == 1) { + throw E1(); + } else { + throw E2(); + } + return 0; + } + + ie, where there is no explicit exception specification in the decl, you + end up doing: + + %exception barfoo { + try { + $action + } catch(E1) { ... } + } catch(E2) { ... } + } + + which is very tedious. Well, the %catches directive defines + the list of exceptions to catch, and from swig: + + %catches(E1,E2) barfoo(int i); + int barfoo(int i); + + is equivalent to + + int barfoo(int i) throw(E1,E2); + + Note, however, that the %catches list doesn't have to + correspond to the C++ exception specification. For example, if you + have: + + struct E {}; + struct E1 : E {}; + struct E2 : E {}; + + int barfoo(int i) throw(E1,E2); + + you can define + + %catches(E) barfoo(int i); + + and swig will generate an action code equivalent to + + try { + $action + } catch(E &_e) { + ; + } + + Of course, you still have to satisfy the C++ restrictions, + and the catches list must be compatible (not the same) + as the original list of types in the exception specification. + + Also, you can now specify that you want to catch the + unknown exception '...', for example: + + %catches(E1,E2,...) barfoo(int); + + In any case, the %catches directive will emit the + code to convert into the target language error/exception + using the 'throws' typemap. + + For the '...' case to work, you need to + write the proper typemap in your target language. In the + UTL, this looks like: + + %typemap(throws) (...) { + SWIG_exception(SWIG_RuntimeError,"unknown exception"); + } + +01/09/2006: mutandiz + [Allegrocl] + + Fixes a number of SEGVs primarily in the handling of + various anonymous types. Found in a pass through the + swig test-suite. Still more to do here, but this is a + good checkpoint. + + Adds -cwrap and -nocwrap as an allegrocl specific + command-line argument. Controls generating of a C + wrapper file when wrapping C code. By default only a + lisp file is created for C code wrapping. + + Doc updates for the command-line arguments and fixes as + pointed out on swig-devel + +01/05/2006: wsfulton + [Java] Fix unsigned long long and const unsigned long long & typemaps + - Bug #1398394 with patch from Dries Decock + +01/06/2006: mmatus + Add 'named' warning codes, now in addition to: + + %warnfilter(813); + + you can use + + %warnfilter(SWIGWARN_JAVA_MULTIPLE_INHERITANCE); + + just use the same code name found in Source/Include/swigwarn.h + plus the 'SWIG' prefix. + + If a developer adds a new warning code, the Lib/swigwarn.swg file + will be generated when running the top level make. + +01/05/2006: cfisavage + [Ruby] + Reimplemented object tracking for Ruby. The new implementation works + by expanding the swig_class structure for Ruby by adding a trackObjects + field. This field can be set/unset via %trackobjects as explained + in the Ruby documentation. The new implementation is more robust + and takes less code to implement. + +01/05/2006: wsfulton + Fix for %extend and static const integral types, eg: + + class Foo { + public: + %extend { + static const int bar = 42; + } + }; + +12/30/2005: mmatus + + - Add info for old and new debug options: + + -dump_top - Print information of the entire node tree, including system nodes + -dump_module - Print information of the module node tree, avoiding system nodes + -dump_classes - Print information about the classes found in the interface + -dump_typedef - Print information about the types and typedefs found in the interface + -dump_tags - Print information about the tags found in the interface + -debug_typemap - Print information for debugging typemaps + -debug_template - Print information for debugging templates + + - Add the fakeversion. If you have a project that uses + configure/setup.py, or another automatic building system + and requires a specific swig version, let say 1.3.22 + you can use: + + SWIG_FEATURES="-fakeversion 1.3.22" + + or + + swig -fakeversion 1.3.22 + + and then swig -version will report 1.3.22 instead of the + current version. + + Typical use would be + + SWIG_FEATURES="-fakeversion 1.3.22" ./configure + +12/30/2005: mmatus + + - Add option/format support to %rename and %namewarn. + Now %namewarn can force renaming, for example: + + %namewarn("314: import is a keyword",rename="_%s") "import"; + + and rename can also support format forms: + + %rename("swig_%s") import; + + Now, since the format is processed via swig Printf, you + can use encoders as follows: + + %rename("%(title)s") import; -> Import + %rename("%(upper)s") import; -> IMPORT + %rename("%(lower)s") Import; -> import + %rename("%(ctitle)s") camel_case; -> CamelCase + + This will allow us to add more encoders, as the + expected one for regular expressions. + + - Add the above 'ctitle' encoder, which does the camel case: + + camel_case -> CamelCase + + - Also, while we get the regexp support, add the 'command' encoder, + you can use it as follows + + %rename("%(command:sed -e 's/\([a-z]\)/\U\\1/' <<< )s") import; + + then swig will popen the command + + "sed -e 's/\([a-z]\)/\U\\1/' <<< import" + + see below for anonymous renames for better examples. + + - The rename directive now also allows: + + - simple match: only apply the rename if a type match + happen, for example + + %rename(%(title)s,match="enumitem") hello; + + enum Hello { + hi, hello -> hi, Hello + }; + int hello() -> hello; + + - extended match: only apply the rename if the 'extended attribute' match + occurred, for example: + + // same as simple match + %rename(%(title)s,match$nodeType="enumitem") hello; + + enum Hello { + hi, hello -> hi, Hello + }; + + Note that the symbol '$' is used to define the attribute name in + a 'recursive' way, for example: + + // match only hello in 'enum Hello' + %rename(%(title)s,match$parentNode$type="enum Hello") hello; + + enum Hello { + hi, hello -> hi, Hello // match + }; + + enum Hi { + hi, hello -> hi, hello // no match + }; + + here, for Hello::hi, the "parentNode" is "Hello", and its "type" + is "enum Hello". + + + - Anonymous renames: you can use 'anonymous' rename directives, for example: + + // rename all the enum items in Hello + %rename(%(title)s,match$parentNode$type="enum Hello") ""; + + enum Hello { + hi, hello -> Hi, Hello // match both + }; + + enum Hi { + hi, hello -> hi, hello // no match + }; + + // rename all the enum items + %rename(%(title)s,match$nodeType="enumitem") ""; + + // rename all the items in given command (sloooow, but...) + %rename(%(command:)s) ""; + + + Anonymous renames with commands can be very powerful, since you + can 'outsource' all the renaming mechanism (or part of it) to an + external program: + + // Uppercase all (and only) the names that start with 'i' + %rename("%(command:awk '/^i/{print toupper($1)}' <<<)s") ""; + + int imported() -> IMPORTED; + int hello() -> hello + + Note that if the 'command' encoder returns an empty string, swig + understands that no rename is necessary. + + Also note that %rename 'passes' the matched name. For example, in + this case + + namespace ns1 { + int foo(); + } + + namespace ns2 { + int bar(); + } + + the external program only receives "foo" and "bar". If needed, + however, you can request the 'fullname' + + %rename("%(command:awk 'awk '/ns1::/{l=split($1,a,"::"); print toupper(a[l])}'' <<<)s",fullname=1) ""; + + ns1::foo -> FOO + ns2::bar -> bar + + - Mixing encoders and matching: of course, you can do mix commands + and match fields, for example: + + %rename("%()",match="cdecl") ""; + %rename("%()",match="enumitem") ""; + %rename("%()",match="enumitem", + match$parentNode$parentNode$nodeType="class") ""; + + Use "swig -dump_parse_module" to see the attribute names you can use to + match a specific case. + + - 'sourcefmt' and 'targetfmt': sometimes you need to + process the 'source' name before comparing, for example + + %namewarn("314: empty is a keyword",sourcefmt="%(lower)s") "empty"; + + then if you have + + int Empty(); // "Empty" is the source + + you will get the keyword warning since 'Empty' will be + lower cased, via the sourcefmt="%(lower)s" option, + before been compared to the 'target' "empty". + + There is an additional 'targetfmt' option to process the + 'target' before comparing. + + - complementing 'match': you can use 'notmatch', for example + + %namewarn("314: empty is a keyword",sourcefmt="%(lower)s",notmatch="namespace") "empty"; + + here, the name warning will be applied to all the symbols except namespaces. + + +12/30/2005: mmatus + + - Add initial support for gcj and Java -> mechanism. + + See examples in: + + Examples/python/java + Examples/ruby/java + Examples/tcl/java + + to see how to use gcj+swig to export java classes into + python/ruby/tcl. + + The idea is to put all the common code for gcj inside + + Lib/gcj + + and localize specific types such as jstring, as can be found + in + + Lib/python/jstring.i + Lib/ruby/jstring.i + Lib/tcl/jstring.i + + Using the UTL, this is very easy, and the perl version for + jstring.i will be next. + + +12/29/2005: mmatus + - Add the copyctor feature/directive/option to enable the automatic + generation of copy constructors. Use as in: + + %copyctor A; + + struct A { + + }; + + then this will work + + a1 = A(); + a2 = A(a1); + + Also, since it is a feature, if you just type + + %copyctor; + + that will enable the automatic generation for all the + classes. It is also equivalent to + + swig -copyctor -c++ ... + + Notes: + + 1.- The feature only works in C++ mode. + + 2.- The automatic creation of the copy constructor will + usually produce overloading. Hence, if the target + language doesn't support overloading, a special name + will be used (A_copy). + + 3.- For the overloading reasons above, it is probably not + a good idea to use the flag when, for example, you are + using keywords in Python. + + 4.- The copyctor automatic mechanism follows more or less + the same rules as the default constructor mechanism, + i.e., a copy constructor will not be added if the + class is abstract or if there is a pertinent non-public + copy ctor in the class or its hierarchy. + + Hence, it might be necessary for you to complete the + class declaration with the proper non-public copy ctor + to avoid a wrong constructor addition. + + - Fix features/rename for templates ctor/dtor and other + things around while adding the copyctor mechanism. + + +12/27/2005: mmatus + - Add the 'match' option to typemaps. Assume you have: + + %typemap(in) SWIGTYPE * (int res) {..} + %typemap(freearg) SWIGTYPE * { if (res$argnum) ...} + + then if you do + + %typemap(in) A * {...} + + swig will 'overload the 'in' typemap, but the 'freearg' + typemap will be also applied, even when this is wrong. The old + solutions is to write: + + %typemap(in) A * {...} + %typemap(freeag) A * ""; + + overload 'freearg' with an empty definition. + + The problem is, however, there is no way to know you need + to do that until you start getting broken C++ code, or + worse, broken runtime code. + + The same applies to the infamous 'typecheck' typemap, + which always confuses people, since the first thing you do + is to just write the 'in' typemap. + + The 'match' option solves the problem, and if instead you write: + + %typemap(in) SWIGTYPE * (int res) {..} + %typemap(freearg,match="in") SWIGTYPE * { if (res$argnum) ...} + %typemap(typecheck,match="in",precedence...) SWIGTYPE * {...} + + it will tell swig to apply the 'freearg/typecheck' + typemaps only if they 'match' the type of the 'in' + typemap. The same can be done with other typemaps as: + + %typemap(directorout) SWIGTYPE * {...} + %typemap(directorfree,match="directorout") SWIGTYPE * {...} + + +12/27/2005: mmatus + - Add the 'naturalvar' option/mode/feature to treat member + variables in a more natural way, ie, similar to the global + variable behavior. + + You can use it in a global way via the command line + + swig -naturalvar ... + + or the module mode option + + %module(naturalvar=1) + + both forms make swig treat all the member variables in the + same way it treats global variables. + + Also, you can use it in a case by case approach for + specific member variables using the directive form: + + %naturalvar Bar::s; + + Then, in the following case for example: + + std::string s; + struct Bar { + std::string s; + }; + + you can do: + + b = Bar() + b.s ="hello" + cvar.s = "hello" + + if (b.s != cvar.s): + raise RuntimeError + + + This is valid for all the languages, and the + implementation is based on forcing the use of the + const SWIGTYPE& (C++)/SWIGTYPE (C) typemaps for the + get/set methods instead of the SWIGTYPE * typemaps. + Hence, for 'naturalvar' to work, each target language + must implement 'typemap(in/out) const Type&' properly. + + The 'naturalvar' option replaces or makes workarounds such as: + + %apply const std::string & { std::string *} + + unnecessary. + + Note1: If your interface has other kinds of workarounds to + deal with the old 'unnatural' way to deal with member + variables (returning/expecting pointers), the + 'naturalvar' option could break them. + + Note2: the option has no effect on unnamed types, such + as unnamed nested unions. + + +12/27/2005: mmatus + - Add more 'expressive' result states for the typemap + libraries. + + In the past, for scripting languages, you would do checking something like: + + if (ConvertPtr(obj,&vptr,ty,flags) != -1) { + // success + } else { + // error + } + + Now the result state can carry more information, + including: + + - Error state: like the old -1/0, but with error codes from swigerrors.swg. + + int res = ConvertPtr(obj,&vptr,ty,flags); + if (SWIG_IsOK(res)) { + // success code + } else { + SWIG_Error(res); // res carries the error code + } + + - Cast rank: when returning a simple successful + conversion, you just return SWIG_OK, but if you need + to do a 'cast', you can add the casting rank, ie: + + if (PyFloat_Check(obj)) { + value = PyFloat_AsDouble(obj); + return SWIG_OK; + } else if (PyInt_Check(obj)) { + value = (double) PyInt_AsLong(obj); + return SWIG_AddCast(SWIG_OK); + } + + later, the casting rank is used to properly dispatch + the overloaded function, for example. This of course + requires your language to support and use the new + dispatch cast/rank mechanism (Now mainly supported in + perl and python, and easily expandable to ruby and tcl). + + - [UTL] Add support for the new 'expressive' result states. + +12/27/2005: mmatus + - Add support for the C++ implicit conversion mechanism, which + required some modifications in parser.y (to recognize + 'explicit') and overload.cxx (to replace $implicitconv as + needed). + + Still, real support in each target language requires each + target language to be modified. Python provides an example, + see below. + + + - Add support for native C++ implicit conversions, ie, if you + have + + %implicitconv A; + + struct A { + int ii; + A() {ii = 1;} + A(int) {ii = 2;} + A(double) {ii = 3;} + explicit A(char *s) {ii = 4;} + }; + + int get(const A& a) {return a.ii;} + + you can call: + + a = A() + ai = A(1) + ad = A(1.0) + as = A("hello") + + # old forms + get(a) -> 1 + get(ai) -> 2 + get(ad) -> 3 + get(as) -> 4 + + #implicit conversions + get(1) -> 2 + get(1.0) -> 3 + get("hello") -> Error, explicit constructor + + Also, as in C++, now implicit conversions are supported in + variable assigments, and if you have: + + A ga; + struct Bar { + A a; + }; + + you can do: + + cvar.ga = A(1) + cvar.ga = 1 + cvar.ga = 1.0 + cvar.ga = A("hello") + cvar.ga = "hello" -> error, explicit constructor + + b = Bar() + b.a = A("hello") + b.a = 1 + b.a = 1.0 + b.a = "hello" -> error, explicit constructor + + Note that the last case, assigning a member var directly, + also requires the 'naturalvar' option. + + This support now makes the old '%implicit' macro, which + was found in 'implicit.i' and it was fragile in many ways, + obsolete, and you should use the new '%implicitconv' + directive instead. + + Note that we follow the C++ conventions, ie, in the + following the implicit conversion is allowed: + + int get(A a) {return a.ii;} + int get(const A& a) {return a.ii;} + + but not in these cases: + + int get(A *a) {return a->ii;} + int get(A& a) {return a.ii;} + + Also, it works for director methods that return a by value + result, ie, the following will work: + + virtual A get_a() = 0; + + def get_a(self): + return 1 + + but not in this case: + + virtual const A& get_a() = 0; + virtual A& get_a() = 0; + virtual A* get_a() = 0; + + Notes: + + - the implicitconv mechanism is implemented by directly + calling/dispatching the python constructor, triggering a + call to the __init__method. Hence, if you expanded the + __init__ method, like in: + + class A: + def __init__(self,args): + + + + then 'my code' will also be executed. + + - Since the %implicitconv directive is a SWIG feature, if you type: + + %implicitconv; + + that will enable implicit conversion for all the classes in + your module. + + But if you are worried about performance, maybe that will be + too much, especially if you have overloaded methods, since + to resolve the dispatching problem, python will efectively + try to call all the implicit constructors as needed. + + - For the same reason, it is highly recommended that you use + the new 'castmode' when mixing implicit conversion and + overloading. + + - [python] The %implicit directive is declared obsolete, and + you should use %implicitconv instead. If you include + the implicit.i file, a warning will remind you of this. + + Note: Since %implicit is fragile, just replacing it by + %implicitconv could lead to different behavior. Hence, we + don't automatically switch from to the other, and the user + must migrate to the new %implicitconv directive manually. + + +12/26/2005: wsfulton + [C#] + Modify std::vector wrappers to use std::vector::value_type as this is + closer to the real STL declarations for some methods, eg for push_back(). + Fixes some compilation errors for some compilers eg when the templated + type is a pointer. + + [Java] + std::vector improvements - a few more methods are wrapped and specializations are + no longer required. The specialize_std_vector macro is no longer needed (a + warning is issued if an attempt is made to use it). + +12/26/2005: wsfulton + [Java, C#] + Add in pointer reference typemaps. This also enables one to easily wrap + std::vector where T is a pointer. + +12/24/2005: efuzzyone + [CFFI] The cffi module for SWIG: + - Fully supports C, but provides limited supports for C++, in + particular C++ support for templates and overloading needs to + be worked upon. + +12/23/2005: mmatus + [python] Add the castmode that allows the python + type casting to occur. + + For example, if you have 'int foo(int)', now + + class Ai(): + def __init__(self,x): + self.x = x + def __int__(self): + return self.x + + foo(1) // Ok + foo(1.0) // Ok + foo(1.3) // Error + a = Ai(4) + foo(ai) // Ok + + The castmode, which can be enabled either with the + '-castmode' option or the %module("castmode") option, uses + the new cast/rank dispatch mechanism. Hence, now if you + have 'int foo(int); int foo(double);', the following works + as expected: + + foo(1) -> foo(int) + foo(1.0) -> foo(double) + ai = Ai(4) + foo(ai) -> foo(int) + + Note1: the 'castmode' could disrupt some specialized + typemaps. In particular, the "implicit.i" library seems to + have problem with the castmode. But besides that one, the + entire test-suite compiles fine with and without the + castmode. + + Note2: the cast mode can't be combined with the fast + dispatch mode, ie, the -fastdispatch option has no effect + when the cast mode is selected. The penalties, however, + are minimum since the cast dispatch code is already based + on the same fast dispatch mechanism. + + See the file overload_dispatch_cast_runme.py file for + new cases and examples. + +12/22/2005: mmatus + Add the cast and rank mechanism to dispatch overloading + functions. The UTF supports it now, but for each language + it must be decided how to implement and/or when to use it. + + [perl] Now perl uses the new cast and rank dispatch + mechanism, which solves all the past problems known + in perl, such as the old '+ 1' problem: + + int foo(int); + + $n = 1 + $n = $n + 1 + $r = foo(n) + + also works: + + foo(1); + foo("1"); + foo(1.0); + foo("1.0"); + + but fails + + foo("l"); + + and when overloading foo(int) and foo(double); + + foo(1) -> foo(int) + foo(1.0) -> foo(double) + foo("1") -> foo(int) + foo("1.0") -> foo(double) + foo("l") -> error + foo($n) -> foo(int) for good perl versions + foo($n) -> foo(double) for old bad perl versions + + when overloading foo(int), foo(char*) and foo(double): + + foo(1) -> foo(int) + foo(1.0) -> foo(double) + foo("1") -> foo(char*) + foo("1.0") -> foo(char*) + foo("l") -> foo(char*) + + Note: In perl the old dispatch mechanism was broken, + so, we don't provide an option to enable the old one + since, again, it was really really broken. + + See 'overload_simple_runme.pl' for more cases and tests. + + PS: all the old known issues are declared resolved, any + new "problem" that could be discovered is declared, + a priori, as "features" of the new dispatch mechanism + (until we find another solution at least). + + + *** POTENTIAL INCOMPATIBILITY *** + + As with the introduction of the UTF, some things could + now start to work as expected, and people used to deal or + workaround previous bugs related to the dispatch + mechanism, could see now a difference in perl behavior. + +12/21/2005: mmatus + - The '-nodefault' flag (pragma and feature) now generates + a warning, and recommends to use the explicit + -nodefaultctor and -nodefaultdtor options. + + The reason to split the 'nodefault' behavior is that, in + general, ignoring the default destructor generates memory + leaks in the target language. Hence, is too risky just to + disable both the default constructor and destructor + at the same time. + + If you need to disable the default destructor, it is + also recommended you use the directive form: + + %nodefaultdtor MyVerySpecialClass; + + for specific classes, and always avoid using the global + -nodefault and -nodefaultdtor options. + +12/21/2005: wsfulton + [Java, C#] + Fix incorrect code generation when the intermediary classname is changed + in the module directive from its default. For example: + + %module(jniclassname="myimclassnewname") "mymodule" // Java + %module(imclassname="myimclassnewname") "mymodule" // C# + + Add in new special variable $imclassname. See docs. + +12/17/2005: mmatus + [Python] + - Add the -aliasobj0/-noaliasobj0 options to use with + -fastunpack and/or -O and old typemaps that use 'obj0' + directly. + + So, if you compile your code using -O and get errors about + the undeclared 'obj0' variable, run again using + + swig -O -aliasobj0 -python .... + + For new typemaps, never use 'obj0' directly, if needed, + use the '$self' name that will be properly expanded to + 'obj0' (nofastunpack) or 'swig_obj[0]' (fastunpack). + + If you have no idea what I am talking about, better, that + means you have no typemap with this problem. + + +12/14/2005: mmatus + [Python] + - Add the -fastunpack/-nofastunpack options to enable/disable + the use of the internal UnpackTuple method, instead of + calling the one from the python C API. + + The option -O now also implies -fastunpack. + + +12/11/2005: mmatus + [Python] + - Add the -proxydel/-noproxydel options to enable/disable + the generation of proxy/shadow __del__ methods, even + when now they are redundant, since they are empty. + However, old interfaces could rely on calling them. + + The default behavior is to generate the __del__ methods + as in 1.3.27 or older swig versions. + + The option -O now also implies -noproxydel. + +12/10/2005: mmatus + [UTF] + - Fix unneccessary calls to SWIG_TypeQuery for 'char *' + and 'wchar_t *', problem found by Clay Culver while + profiling the PyOgre project. + + + [Python] + - Add the -dirvtable/-nodirvtable to enable/disable + a pseudo virtual table used for directors, avoiding + the need to resolve the python method at each call. + + - Add the -safecstrings/-nosafecstrings options to + enable/disable the use of safe conversions from PyString + to char *. Python requires you to never change the internal + buffer directly, and hence 'safectrings' warranties that + but returning a copy of the internal python string buffer. + + The default, as in previous releases, is to return a + pointer to the buffer (nosafecstrings), so, it is the user's + responsibility to avoid its modification. + + - Add the -O option to enable all the optimization options + at once, initially equivalent to + + -modern -fastdispatch -dirvtable -nosafecstrings -fvirtual + +12/08/2005: mmatus + + - Add the -fastdispatch option (fastdispatch feature). This + enables the "fast dispatch" mechanism for overloaded + methods provided by Salvador Fandi~no Garc'ia (#930586). + + The resulting code is smaller and faster since less type + checking is performed. However, the error messages you + get when the overloading is not resolved could be + different from what the traditional method returns. + + With the old method you always get an error such as + + "No matching function for overloaded ..." + + with the new method you can also get errors such as + + "Type error in argument 1 of type ..." + + See bug report #930586 for more details. + + So, this optimization must be explicitly enabled by users. + + The new mechanism can be used as: + + swig -fastdispatch + + or using the feature form + + %feature("fastdispatch") method; + or + %fastdispatch method; + + +12/06/2005: mmatus + + - Several memory and speed improvements, specially for + templates. Now swig is up to 20 faster than before for + large template interfaces, such as the std_containers.i + and template_matrix.i files in the python test-suite. + + Memory footprint is also reduced in consideration of small + pcs/architectures. + + - add commandline options -cpperraswarn and -nocpperraswarn" to force + the swig preprocessor to treat the #error directive as a #warning. + + the pragmas + + #pragma SWIG cpperraswarn=1 + #pragma SWIG cpperraswarn=0 + + are equivalent to the command line options, respectively. + + +12/06/2005: mmatus + [Python] The generated code is now more portable, especially + for Windows. Following + + http://www.python.org/doc/faq/windows.html + + Py_None is never accessed as a structure, plus other + tricks mentioned there. + +12/06/2005: mmatus + [Python] Added initial support for threads based in the + proposal by Joseph Winston. + + The user interface is as follows: + + 1.- the module thread support is enable via the "threads" module + option, i.e. + + %module("threads"=1) + + 2.- Equivalent to that, is the new '-threads' swig option + + swig -threads -python ... + + 3.- You can partially disable thread support for a given + method using: + + %feature("nothread") method; + or + %nothread method; + + also, you can disable sections of the thread support, + for example + + %feature("nothreadblock") method; + or + %nothreadblock method; + + %feature("nothreadallow") method; + or + %nothreadallow method; + + the first disables the C++/python thread protection, and the + second disables the python/C++ thread protection. + + 4.- The current thread support is based in the PyGIL + extension present in python version 2.3 or later, but + you can provide the thread code for older versions by + defining the macros in pythreads.swg. + + If you get a working implementation for older versions, + please send us a patch. + + For the curious about performance, here are some numbers + for the profiletest.i test, which is used to check the speed + of the wrapped code: + + nothread 9.6s (no thread code) + nothreadblock 12.2s (only 'allow' code) + nothreadallow 13.6s (only 'block' code) + full thread 15.5s ('allow' + 'block' code) + + i.e., full thread code decreases the wrapping performance by + around 60%. If that is important to your application, you + can tune each method using the different 'nothread', + 'nothreadblock' or 'nothreadallow' features as + needed. Note that for some methods deactivating the + 'thread block' or 'thread allow' code is not an option, + so, be careful. + + +11/26/2005: wsfulton + SWIG library files use system angle brackets everywhere for %include, eg + %include "std_common.i" + becomes + %include + +11/26/2005: wsfulton + [Java, C#] + Typesafe enums and proper enums have an extra constructor so that enum item values that + are initialised by another enum item value can be wrapped without having to use %javaconstvalue/ + %csconstvalue for when using %javaconst(1)/%csconst(1). Suggestion by + Bob Marinier/Douglas Pearson. + For example: + + typedef enum + { + xyz, + last = xyz + } repeat; + +11/21/2005: mmatus + [ruby + python] + + Fixes for directors + pointers. This is an ugly problem without an easy + solution. Before we identified this case as problematic: + + virtual const MyClass& my_method(); + + but it turns out that all the cases where a pointer, array or + reference is returned, are problematic, even for + primitive types (as int, double, char*, etc). + + To try to fix the issue, a new typemap was added, + 'directorfree', which is used to 'free' the resources + allocated during the 'directorout' phase. At the same + time, a primitive garbage collector engine was added to + deal with orphaned addresses, when needed. + + The situation is much better now, but still it is possible to have + memory exhaustation if recursion is used. + + So, still you need to avoid returning pointers, arrays or + references when using director methods. + + - Added stdint.i - typemaps for latest C99 integral types found in stdint.h. + +11/14/2005: wsfulton + More types added to windows.i, eg UINT8, WORD, BYTE etc. + Including windows.i will also enable SWIG to parse the __declspec Microsoft + extension, eg __declspec(dllimport). Also other Windows calling conventions + such as __stdcall. + +11/10/2005: wsfulton + New library file for Windows - windows.i. This file will contain useful type + information for users who include windows.h. Initial support is for the + non ISO integral types: __int8, __int16, __int32, __int64 and unsigned versions. + The unsigned versions previously could not be parsed by SWIG. SF #872013. + +11/09/2005: wsfulton + [Java, C#] Portability warning for files which will overwrite each other on case + insensitive file systems such as FAT32/NTFS. This will occur, for example, when two + class names are the same barring case. The warning is issued on all platforms and + can be suppressed with the usual warning suppression techniques. SF bug #1084507. + +11/09/2005: wsfulton + ./configure --with-python --with-ruby --with-perl5 etc enable these languages, + ie the --with-xxxx options, where no path is specified, work the same as if + the option was not specified at all. Based on patches #1335042 #1329048 #1329047. + +11/09/2005: dancy + + [Allegrocl] + Add C++ support to the Allegrocl module. Further + enhances the C support as well. Some of the + features: + + - MUCH better generation of foreign types based on + the C/C++ types for use in defining the FFI on + the lisp side. We don't pass everything as a (* :void) + any longer. + + - Uses typemaps for better control of type conversions + and code generation in the generated lisp and c++ wrapper + code. + + - CLOS wrapping of pointers returned from foreign space + makes it easier to differentiate pointers in user code. + The wrapping objects can be passed directly to FF calls. + + - Defun wrapping of FF calls, allowing for more lispy + interface. Conversion, GCing, of lisp objects to + foreign objects can be done in the wrapping defun via + the use of typemaps. + + - overload dispatching implemented on the lisp side + using generic functions. + + - Templates and synonymous types supported. + +11/07/2005: mmatus + + [Python] Adding proper support for multi-inheritance in + the python side, ie, if you have two C++ wrapped class, Foo + and Bar, now: + + class MyPythonClass(Foo,Bar): + .... + + will properly work, even with directors, and the + deallocation of Foo.this and Bar.this will follow + correctly. Before, a class could only have one 'this' + instance (unlike C++), only the last base class was + properly deleted, or detected with directors. + + Now 'self.this' can be a list, which will contain the C++ + instance pointers for all the base classes. + + Also, swig.this is responsible for deallocating the C++ + instance(s), and the __del__ method is not emitted unless + the user preppend/append some code to it. + + - Swig can now detect memory leaks, ie, if you still + don't use proxy/shadow classes, and type something like + + import _example + f = _example.new_Foo() + + and forget to call _example.delete_Foo(f), then swig will + tell you that there is a memory leak. + + Otherwise, if you always use the proxy classes, you probably + you will never ever see this warning unless there is + something wrong inside the swig wrapping code. + + + *** POTENTIAL INCOMPATIBILITY *** + + If you overloaded the __del__ method, and call the base + one without a try block, as in + + class MyClass(SwigClass): + + def __del__(self): + + SwigClass.__del__(self) + + python could complain that the method SwigClass.__del__ is + undefined. Try to use instead: + + def __del__(self): + + try: SwigClass.__del__(self) + except: pass + + or simply + + def __del__(self): + + +11/02/2005: mmatus + + [Python] Adding more fun to STL/STD containers, now you + can do + + %template(pyset) std::set; + %template(pyvector) std::vector; + %template() std::pair; + %template(pyvector) std::map; + .... + + The same applies to std::list, std::deque, std::multiset, etc. + + Then, at the python side you can do now: + + # C++ std::vector as native python sequence + v = pyvector([1,"hello",(1,2)]) + print v[1] + >> 'hello' + print v[2] + >> (1,2) + + # C++ std::set as native python sequence + s = pyset() + s.insert((1,2)) + s.insert(1) + s.insert("hello") + sum=() + for i in s: + sum +=(i,) + print sum + >>> (1, 'hello', (1, 2)) + + # C++ std::map as native python sequence + m = pymap() + m["foo"] = "hello" + m[1] = (1,2) + pm = {} + for k in m: + pm[k] = m[k] + print pm + >>> {1: (1, 2), 'foo': 'hello'} + + ie, the STD/STL containers work as real native python + container, with arbitrary item types and so. + + But since normal C++ containers do not properly ref/unref + their items, you should use the safer versions: + + %template(pyset) std::set; + %template(pyvector) std::vector; + %template() std::pair; + %template(pyvector) std::map; + .... + + where swig::PyObject_ptr is a PyObject * envelope class provided + to safely incref/decref the python object. + + So, now you can use all the STL/STD containers as native + Python containers. + + Note 1: std::map, std::set and the other 'ordered' + containers will properly use PyObject_Compare for sorting, + when needed. + + Note 2: all the STL/STD containers have a limit size of + SIZE_MAX, ie, you can have manage containers larger than + INT_MAX, the python limit. + + +11/02/2005: mmatus + + [Python] + - add 'iterator()' method for all sequences and additionally + 'key_iterator()' for maps. + + 'iterator()' will always return the native C++ iterator. + Additionally, in maps, 'key_iterator()' will return a python + iterator using only the map keys. + + In general the sequence method __iter__ will call + 'iterator()', returning the native C++ iterator, but in + maps it will call 'key_iterator()', maintaining + backward compatibility. + + Hence, for std::maps, you can play then with the native + C++ iterator, which value is a (key, value) pair, by + calling map.iterator(), as with map.begin(), map.end(), etc. + + The difference is that map.iterator() returns a safe + 'closed' iterator, while map.begin() and map.end() are + 'open' iterators. + + A 'closed' iterator knows the begin and the end of the + sequence, and it never can seg. fault. An 'open' + iterator, as in C++, can seg. fault at the C++ side. + + # a closed iterator is safe in the following example. + # the next() method will throw a StopIteration + # exception as needed + + i = seq.iterator() + try: + while True: + sum += i.next() + except: pass + + # an open iterator always need to be checked, + # or it will crash at the C++ side + + current = seq.begin() + end = seq.end() + while (current != end): + sum += current.next() + + + [Python] + - Finally, when we call + + f = Foo() + + the construction is 'one-way'. Before construction was done + something like + + Foo() (python) -> _new_Foo() (C++) + new_Foo() (C++) -> FooPtr() (python) + FooPtr() (python) -> Foo() (python) + + and returning a pointer was done like + + NewPointerObj() (C++) -> FooPtr() (python) + FooPtr(python) -> Foo() (python) + + + ie, we when going back and forward between the C++ and + python side. + + Now since there is no FooPtr the construction process is + + Foo() (python) -> _new_Foo() (C++) + _new_Foo() (C++) -> NewPointerObj() (C++) (no shadow class) + + and returning a pointer is done + + NewPointerObj() (C++) (with shadow class) -> NewInstaceObj() (C++) + + where NewInstanceObj creates a new instance without + calling __init__ and it doesn't go 'back' to python, is + 'pure' C API. + + - With this change, and the other ones in the + PySwigObject type, which now carries the thisown and + swig_type_info pointer, the generated code should be as + fast as boost::Python and/or the other python wrappers + based in pure Python/C API calls. + + As a reference, the profiletest_runme.py example, which + does a simple call function many times, such as this code: + + import profiletest + + a = profiletest.A() + b = profiletest.B() + for i in range(0,1000000) + a = b.fn(a) + + + where fn is defined as 'A* B::fn(A *a) {return a;}', + produces the following times + + nomodern modern + swig-1.3.26 19.70s 5.98s + swig-CVS 0.99s 0.98s + + + Clearly, there is a large improvement for the python + 'nomodern' mode. Still, the 'modern' mode is around + 6 times faster than before. For the same test, but + using the non-shadow version of the module, we get + + _profiletest (non-shadow) + swig-1.3.26 0.80s + swig-CVS 0.60s + + Hence, now for practical purposes, the proxy overhead + is insignificant. + + Note that the performance numbers we are showing is for + a simple module (two types) and a simple function (one + argument). For real situations, for modules with many + more types and/or functions with many more parameters, + you will see even better results. + + +10/31/2005: mmatus + [Python] + + - Finally, no more ClassPtr proxy classes. You will see + only a clean Class proxy class in the .py file. + + - No more 'real' thisown attribute either, the PySwigObject now + carries the ownership info. + + You can also do something like + + print self.this.own() + >>> True + + self.this.disown() + self.this.own(0) + print self.this.own() + >>> False + + self.this.acquire() + self.this.own(1) + print self.this.own() + >>> True + + Still the old way, + + print self.thisown + >>> True + + self.thisown = 0 + print self.thisown + >>> False + + self.thisown = 1 + print self.thisown + >>> True + + is supported, and python dispatches the proper method + calls as needed. + + + - Support for iterators in STL/STD containers, for example, if you have + + %template std::set; + + you can use the C++ iterators as: + + s = set_string() + + s.append("c") + s.append("a") + s.append("b") + + b = s.begin() + e = s.end() + sum = "" + while (b != e): + sum += b.next() + print sum + + >>> "abc" + + advance the iterator as in C++ + + current = s.begin() + current += 1 + print current.value() + >>> "b" + + now using the reverse operators + + b = s.rbegin() + e = s.rend() + sum = "" + while (b != e): + sum += b.next() + print sum + + >>> "cba" + + or the 'previous' method + + b = s.begin() + e = s.end() + sum = "" + while (b != e): + sum += e.previous() + print sum + + >>> "cba" + + or just as in a python fashion + + for i in s: + sum += i + + Note 1: Iterators in C++ are very powerful, but + dangerous too. And in python you can shoot yourself in the foot + just like in C++, so, be careful. + + Note 2: the iterators are 'light', ie, they do not + convert sequence elements until you request to do so, via + next(), value() or previous(). If you just increment/decrement one + no conversion is performed, for example: + + + b = s.begin() + b += 1 + b.incr() + b.incr(2) + b.decr(2) + b.decr() + b -= 1 + + only the iterator is modified, and not value wrapper + is generated. Other typical C++ operations are also + available, such as: + + print s.end() - s.begin() + >>> 3 + f = s.begin() + 1 + print f.value() + >>> "b" + l = s.end() - 1 + print l.value() + >>> "c" + + etc. Of course, the 'find', 'insert', 'erase', and + so on methods also supports iterators now, ie: + + i = s.begin() + i += 1 + s.erase(i) + for i in s: + sum += i + print sum + >>> "ac" + + *** POTENTIAL INCOMPATIBILITY *** + + There is no more 'thisown' attribute. If you use it, python + will translate the following code as follows: + + if (self.thisown): ==> if (self.this.own()): + self.thisown = 1 ==> self.this.own(1) + self.thisown = 0 ==> self.this.own(0) + + Still, maybe in some unusual cases the translation will not be + 100% correct, so if you have a problem, please report it + and/or use the new 'self.this.own()' accessor. + + + *** POTENTIAL INCOMPATIBILITY *** + + There is no more ClassPtr classes in the python code. Hence, + if in the past you needed to resort to some kind of trickery + with them, or overcome their presence, it is no longer + required, but the extra code you added could now break + things. + + If needed, you can use the option -classptr, i.e., + + swig -classptr -python ... + + to generate the old ClassPtr classes. + + +10/30/2005: mkoeppe + [Guile] Make declared and defined linkage of SWIG_init consistent. + Reported by Steven G. Johnson (SF patch 1315498). + +10/26/2005: mmatus + + - Added the attribute.i file to the global library director. + Now it can be used from other languages that do not use + the unified typemap library as well. + + So, if you have something like: + + %include attribute.i + + %attribute(A, int, a, get_a, set_a); + + struct A + { + int get_a() const; + void set_a(int aa); + }; + + %attribute_ref(B, int, c); + + struct B + { + int& c(); + }; + + then in the target language the 'A.a' and 'B.c' attributes will + be visible, ie, you can access them as plain variables: + + f = A() + f.a = 3 + g = B() + g.c = 3 + + h = f.a + g.c + + and the proper get/set methods will be dispatched. See + attribute.i for more info. + + - More cleanups around and adding more test-cases. The + DISOWN typemap now is tested and working in all the + languages that use the unified typemap library, ie, tcl, + ruby, perl and python. + + +10/25/2005: mmatus + + - Perl, complete the DISOWN typemap. + + - added the attribute.i file to the unified typemap + library (before was only usable from python). + + - unify the names for the setter and getter methods in + perl,tcl,ruby and python, so, the attribute.i library + can work across them. + + - see the li_attribute.i test-case or the library file + + Lib/typemaps/attribute.swg + + for more info about how to use it. + + + + +10/24/2005: mmatus + + - Perl now uses the unified typemap library. + + - Changes in ruby to use the $track option in typemaps. + + - Changes in the unified typemap library to follow the + convention that all macros that are not used in the + C/C++ side starts with %, such as + + %delete + %new_array + + etc. + + - Documenting fragments, see fragments.swg. + + - Cleaner way to use the unified typemap library, include + just . + + Check some of the supported languages: perl, tcl, ruby, + python. + + Always start with the head file, such as + + python/python.swg + tcl/tcl8.swg + ruby/ruby.swg + perl5/perl5.swg + + and the principal file that invokes the unified library, such as + + python/pytypemaps.swg + tcl/tcltypemaps.swg + ruby/rubytypemaps.swg + perl/perltypemaps.swg + + The file that provide the specialization for each + language are the one that provides the basic types: + + python/pyprimtypes.swg + ruby/rubyprimtypes.swg + tcl/tclprimtypes.swg + perl5/perlprimtypes.swg + + and the string manipulation: + + python/pystrings.swg + ruby/rubystrings.swg + tcl/tclstrings.swg + perl5/perlstrings.swg + + + The rest of the files, such as carray.i, are mostly one + line files that include the proper typemap library + version. + + *** POTENTIAL INCOMPATIBILITY in Perl *** + + Some missing/wrong typemaps could start working properly, + and change the old expected behavior in Perl. + +10/23/2005: wuzzeb + Chicken: + + pointers to member functions finally work properly + + add test of member function pointers to cpp_basic.i + +10/20/2005: dancy + [allegrocl] Added C++ support. Large update, many changes. See + newly added Allegro Common Lisp section in lisp.html + +10/20/2005: mmatus + Ruby, Tcl, Python: + + - Uniform way to fail (label fail:), now finally + SWIG_exception works across the three languages and all + the typemaps. + + - Add proper cleanup code to ruby + + - More valgrind fixes + + - Simplify the inline use, it seems a small interface of + 20,000 lines (plus many many templates) can break + gcc -O3 easily. + + - Finalize the typemaps library. All the old *.i files + (carray.i, cpointer.i, exception.i) had been implemented + in the new typemaps library. + + +10/19/2005: wuzzeb + Update the Runtime Typemap documentation in Typemaps.html + +10/18/2005: wuzzeb + Chicken: + - Correctly handle %ignored classes + - Correctly convert long, long long, unsigned long, etc + to chicken primitives. (Thanks to Felix Winkelmann) + - Using argout parameters when the return value was a + wrapped pointer caused a memory corruption. The chicken + garbage collector moved a pointer out from under us. + This is now fixed by running all the proxy creation + functions as continuations after the wrapper function + returns. As part of this, we no longer need the + chickenfastproxy flag on output typemaps. + - using -proxy and -nocollection together works now + Before, it was not exporting the destructor in the proxy + wrapper. + +10/18/2005: mmatus + + Added the Unified Typemap Library (UTL). It unifies the typemaps for + + python, ruby, tcl + + and in the process, fixes several problems in each of the three + languages to work in a "canonical" way now established in + the typemap library + + SWIG/Lib/typempas + + The current status of the unification is that everything + compiles and runs inside the test-suite and examples + directories. And for the first time we have three + languages than pass the primitive_types.i case. + + Also, we have a uniform way to treat the errors, for example + if you do something like + + >>> from primitive_types import * + >>> print val_uchar(10) + 10 + >>> print val_uchar(1000) + Traceback (most recent call last): + File "", line 1, in ? + OverflowError: in argument 1 of type 'unsigned char' + + you get the same exception in all the three languages. + + And well, many more good things will come from this + unification, for example, proper support of the STL/STD classes + for all the languages, and hopefully, we can keep + adding other languages. + + The hardest part, writing a common typemap library + that suites the three different languages, is done, + and adding another language should now be easy. + + Still the global unification is not complete, the STL/STD + part is next, and probably as well as adding one or two more + languages. + + If you are curious, look at the python, ruby and/or tcl + directories to see what is needed to support the new + common typemaps library. Still, the final way to + integrate a new language could change as we move to + integrate the STD/STL. + + *** POTENTIAL INCOMPATIBILITY in Ruby/Tcl *** + + Some missing/wrong typemaps could start working properly, + and change the old behavior, specially in ruby and tcl. + +Version 1.3.27 (October 15, 2005) +================================= + +10/15/2005: wsfulton + [Java] Fix for typesafe enum wrapping so that it is possible to + overload a method with 2 different enum types. + +10/15/2005: wsfulton + Fix for %feature("immutable","0") attempting to generate setters + for constants. + + Restored %immutable and %makedefault to clear the feature as it + behaved in SWIG-1.3.25 and earlier. + +10/14/2005: mmatus + Fix bug in anonymous typedef structures which was leading to + strange behaviour. + +10/13/2005: mmatus + Several minor changes: + + - Improve the wchar_t type support + - Add a warning for when you define the 'in' typemap but + you don't define the 'typecheck' one. Very common mistake. + - Add proper default rule for function pointers, now you + can define a typemap such as: + + %typemap(in) SWIGTYPE ((*)(ANY)) {...} + + That will apply to all the pointer to functions. The + rule in C++ also apply to the function 'reference', ie, + in both cases + + typedef int (*fptr)(int a); + typedef int (func)(int a); + + This was needed since it seems to be 'illegal' in C++ to + do something like: + + void *ptr = static_cast(fptr); + + and probably, as for member functions, it is not + warrantied that the pointer sizes will match. + + - Add the #error/#warning directives to swig's cpp. + + - Add the noblock option for typemaps, which is used as + follows: supposed you a typemap, like this + + + %typemap(in,noblock=1) Hello { + .... + } + + then the typemap will be inserted without the block + imposed by the brackets, similar to + + %typemap(in) Hello "..."; + + So, why you don't just use the quote style?, because: + + 1.- The quote style doesn't get preprocessed, for example + + %typemap(in) Hello "$1= SWIG_macro($1);"; + + here, SWIG_macro doesn't get expanded + + 2.- Inside a quote typemap, you have to use + quotes carefully + + %typemap(in) Hello "$1 = \"hello\" "; + + 3.- You can't make emacs and/or other editors + to indent inside a string!. + + + So, why do you want to remove the block?, because an extra + block when not needed (no local variables in it): + + 1.- makes the code harder to read + 2.- makes the code larger + 3.- or in short, for the same reason we have the quote style. + +Version 1.3.26 (October 9, 2005) +================================ + +10/08/2005: wsfulton + [Php] Added 'throws' typemaps. + +10/08/2005: wsfulton + Fixes for languages that don't support multiple inheritance. The + first non-ignored class in the public base class list is used for inheritance. + by the proxy class. Previously, if the first class in the list was ignored, then + the proxy class wouldn't have any base classes. + +10/07/2005: mmatus + Update more features to follow new convention, including: + + callback + ref/unref + except + + All of them use not only the feature as a flag, but also + as code value. To deal with those features, we use now + GetFlagAttr, which is similar to GetFlag, but instead or + returning 1 or 0, it returns the attr value, if happens + to be different of "0" of course. + + Now there are also more uniform directive names for the + ones based in features, for example, for the old + %newobject directive now we have tree directives defined: + + + #define %newobject %feature("new") + #define %nonewobject %feature("new","0") + #define %clearnewobject %feature("new","") + + and so on for all the other feature directives. + + *** POTENTIAL INCOMPATIBILITY *** + +09/30/2005: wsfulton + Subtle change to some features. Previously it was not possible to disable many + features once they had been enabled. This was for most features that behave as + flags. These features now work as follows: + + %feature("name") // enables the feature + %feature("name", "1") // enables the feature + %feature("name", "0") // disables the feature + %feature("name", "") // clears the feature + + In fact any non-empty value other than "0" will enable the feature (like C boolean logic). + Previously "1", "0" or any other non-empty value would enable the feature and it would + only be possible to disable the feature by clearing it (assuming there was no global enable). + + The following features are affected: + + allowexcept + compactdefaultargs + classic (Python) + cs:const (C#) + director + exceptionclass (Python) + ignore + immutable + java:const (Java) + java:downcast (Java) + kwargs + modern (Python) + new + noautodoc (Python) + nodefault + nodirector + noref + notabstract + nounref + novaluewrapper + python:maybecall (Python) + python:nondynamic (Python) + modula3:multiretval (Modula3) + predicate (Ruby) + trackobjects (Ruby) + valuewrapper + + It is now possible, for example to ignore all methods/classes in a header file, except for a + few targetted methods, for example: + + %feature("ignore"); // ignore all methods/classes + %feature("ignore","0") some_function(int, double); // do not ignore this function + %feature("ignore","0") SomeClass; // do not ignore this Class + %feature("ignore","0") SomeClass::method; // do not ignore this method + %include "bigheader.h" + + Removed %pythondynamic - it never worked properly. Use %pythonnondynamic instead. + Removed %feature("nokwargs") - it wasn't fully implemented - use %feature("kwargs","0") instead. + + *** POTENTIAL INCOMPATIBILITY *** + +09/25/2005: mkoeppe + [Guile] Add "throws" typemaps. + +09/24/2005: cfisavage + [Ruby] Adds new %trackobjects functionality that maps C++ objects to + Ruby objects. This functionality makes it much easier to implement + mark functions for the garbage collector. For more information + refer to the update documentation and examples. + +09/20/2005: wsfulton + [Perl] Patch 1116431 from Josh Cherry. Fixes non member functions inadvertently + being called instead of member functions. + +09/20/2005: wsfulton + [Lua] Patch from Mark Gossage to add support for Lua-5.1, std::string, + std::vector, std::exception and documentation. + +09/14/2005: mmatus + [Python] Add -nocppcast. Now the default behavior is to + always use the cppcast operators. Before that was the case + only when you used the -cppcast option. + + If this seems to break your code... your welcome!, it + means it was broken before, and you never notice. + + If you thing the error is due to one of the SWIG typemaps, + send us an example. + + Use -nocppcast only with very old C++ compilers that + do not support the cppcast operations. + + So, here applies: + + This change doesn't break compatibility, it was broken before. + +09/13/2005: wsfulton + [Java] Fix for director methods when a class is passed by value as a + parameter. + +09/11/2005: mmatus + Adding the module option to the %import directive. Now you + can use it as + + %import(module="BigModule") foo.i + + where subfile could (or not) define the module name via + the %module directive. The module option take precedence + and it has the same effects than having the directive + + %module BigModule + + inside the imported file foo.i. + + You can use the option in mainly two cases: + + 1.- You used the -module option when you generated the + module to be imported, and hence the module name in + the imported %module directive is not really useful. + + 2.- The module you want to import is very large, and it + has several .i/.h files. Then, if you just one to + import a class or so from the module, says 'foo', and + not the entire module via importing the main + BigModule.i file, then you just do: + + %import(module="BigModule") foo.h + + or + + %import(module="BigModule") foo.i + + where foo.i contains the 'foo' declaration and maybe a + couple of extra %include directives, as needed. + + +09/11/2005: mmatus + Fix bug #1282637, about the -module option not having effect + in places where it was needed. + +09/11/2005: wsfulton + When wrapping variables, ensure that none of the typemaps used for the + set wrappers are used when generating the get wrappers. I doubt this was a + problem for any languages except for the recently introduced null attribute + in the out typemap (C# only). + +09/08/2005: wsfulton + More descriptive error messages when files fail to open. + +09/06/2005: mmatus + + Allow a %define a macro inside another %define macro, for example + + %define hello(name, Type) + %define name ## a(Type) + %typemap(in) Type "hello;"; + %enddef + %enddef + + To learn how to use this new features in your own typemaps library, see + python/cstring.i, python/cwstring.i and python/cwstrbase.i. + + [Python] Normalize the cstring.i implementation to use fragments, and add + cwstring.i, which implements the same typemaps but for wchar_t strings. + + [Python] Bug fixed: 1247477, 1245591, 1249878 and others. + +08/18/2005: wsfulton + [Ruby] Implement support for SWIGTYPE* DISOWN typemap (like in Python) for + better control of memory management, eg when adding an object created in Ruby + to a C++ container. Patch #1261692 from Charlie Savage. + +08/18/2005: wsfulton + [Tcl] 64 bit platform fixes for the varargs handling in SWIG_GetArgs. This is an + improved fix for bug #1011604 as suggested by Jeremy Lin. + +08/18/2005: wsfulton + [Tcl] Bug #1240469 - %newobject support for Tcl. Patch from Bob Marinier. + +08/16/2005: wsfulton + [Perl] Bug #1254494 - Fix for global namespace pollution by perl header files + (bool define) prevented STL headers from being used on some systems, eg + Windows with Visual Studio. + +08/16/2005: wsfulton + [Java] Bug #1240937 - Redefinition of __int64 typedef for Intel compilers. + +08/15/2005: wsfulton + [Xml] Bug #1251832 - C++ template may generate invalid XML file + +08/15/2005: wsfulton + [Lua] Support added for Lua. Patch #1242772 from Mark Gossage. + It supports most C/C++ features (functions, struct, classes, arrays, pointers, + exceptions), as well as lots of documentation and a few test cases & examples. + +08/14/2005: wsfulton + [Xml] Fix incorrect xml escaping in base class name when base class is a template. + +08/13/2005: efuzzyone + [CLISP] Added support for handling enums. Does not adds the return type declaration + to the function definition, if a function returns void. + +08/09/2005: mkoeppe + New language module, Common Lisp with UFFI, from Utz-Uwe Haus. + +08/09/2005: mkoeppe + Fix the Lisp s-expression output module; it no longer complains about "unknown targets". + +07/27/2005: wsfulton + Modifications to STL wrappers so that it is possible for a user's %exception directive + to be applied to the STL wrapper methods. Previously the following global %exception + directive would not be used on the wrapper methods: + + %exception { + try { + $action + } catch (...) { + // handle uncaught exceptions + } + } + + This has been implemented by replacing %exception directives for specific STL wrapper + methods with an exception specification declared on the wrapper methods. throws typemaps + are now supplied for handling the STL exception specification. These can also be easily + overridden, for example the std::out_of_range exception, which is used a lot in the STL + wrappers, can be customised easily: + + %include "std_vector.i" + %typemap(throws) std::out_of_range { + // custom exception handler + } + %template(VectInt) std::vector; + +07/22/2005: efuzzyone + [CLISP] The clisp module for SWIG: + - It can only handle C, clisp currently does not supports ffi bindings to C++. + - It has two options, (a) -extern-all this will generate wrappers for all functions + and variablestions, (b) -generate-typedef this will generate wrappers "def-c-type" + wrappers for typedefs + - Can handle pointers to functions, complex types such as n-dimensional arrays of + pointers of depth d + - Generates wrappers for constants as well as variables + - Correctly distinguishes between the declaration of variables in structures and functions + - Creates a defpackage "declaration" with the module name as the package name, the created + package exports both functions and variables + - tries to guess when should a pointer variable be declared as c-ptr or c-pointer + +07/22/2005: wsfulton + [C#] Changes to support C# structs returned by value. The changes required are: + - Using an optional 'null' attribute in the out typemap. If this attribute is specified, + then it is used for the $null special variable substitution. + - The ctype used in the C/C++ wrappers is no longer initialised to 0 on declaration. + Both of these changes fix the situations where an attempt was made to assign 0 to the + returned struct. Marshalling structs as value types still requires user defined typemaps. + See documentation for an example. + +07/22/2005: wsfulton + [C#, Java] Fix SWIG_exception usage to work with compilers that don't support empty macro + arguments. Unfortunately this fix will stop usage of SWIG_exception being used within typemaps + that use "" or %{ %} delimiters, but continues to work with typemaps using {} delimiters. + Please use the SWIG_CSharpSetPendingExceptionArgument or SWIG_JavaThrowException methods instead + as SWIG_exception is really intended as a platform independent macro for the SWIG library writers. + +07/16/2005: mkoeppe + [Allegro CL] Use specific foreign types rather than (* :void). + Use *swig-identifier-converter*. + +06/27/2005: wsfulton + Functions declared as 'extern' no longer have an additional function declaration added to the + wrapper files. There are some cases where SWIG does not get this right, eg bug #1205859 (extern + functions with default arguments declared in a namespace). Also SWIG cannot get non-standard + calling conventions correct, eg Windows calling conventions are usually handled like this: + + %{ + #define DLLIMPORT __declspec(dllimport) + #define STDCALL __stdcall + %} + #define DLLIMPORT + #define STDCALL + %inline %{ + DLLIMPORT extern STDCALL void function(int); + %} + + SWIG incorrectly generates: + + extern void function(int); + + To which there is no solution as SWIG doesn't handle non-standard calling conventions. The extra + 'extern' function that SWIG generates is superfluous unless a user has forgotten to add the function + declaration into the wrappers. + + The -noextern commandline argument is now redundant and a new commandline argument -addextern can + be used to obtain the original behaviour. This shouldn't be necessary unless the header file + containing the function declaration was inadvertently not added to the wrappers. To fix this + add the function declaration into your wrappers, For example, replace: + + extern void foo(int); + + with: + + %inline %{ + extern void foo(int); + %} + + *** POTENTIAL INCOMPATIBILITY *** + +06/22/2005: wsfulton + [C#, Java, Modula3, Ocaml] + The intermediary function names have been changed when wrapping variables to + match the other language modules so that %extend for a member variable works + uniformly across all language modules, eg: + + %extend ExtendMe { + Var; + }; + + %{ + void ExtendMe_Var_set(ExtendMe *, double) {...} + double ExtendMe_Var_get(ExtendMe *) {...} + %} + + The methods implementing the get/set used to be: + + %{ + void set_ExtendMe_Var(ExtendMe *, double) {...} + double get_ExtendMe_Var(ExtendMe *) {...} + %} + + This also changes the name of variable wrapper functions when using -noproxy. + The original names can be generated with the -oldvarnames commandline option. + + *** POTENTIAL INCOMPATIBILITY *** + +Version 1.3.25 (June 11, 2005) +============================== + +06/11/2006: mkoeppe + [Guile] Fix handling of anonymous-enum variables. + +06/10/2005: mkoeppe + [Guile] Fix for function arguments that are passed by + copy-of-value. Fix for global "const char *" variables. + Fix testcases arrays_dimensionless, arrays_global. + +06/08/2005: wsfulton + Fix for when a base class defines a symbol as a member variable and a derived class defines + the same symbol as a member method. + +06/08/2005: wsfulton + [C#] More fixes for virtual/new/override modifiers - when a method has protected access + in base and public access in derived class. + +06/02/2005: wsfulton + Fix #1066363 - Follow convention of release tarball name matching directory name. + +06/02/2005: wsfulton + [C#, Java] Fix #1211353 - typesafe enums (and Java proper enums) wrappers when enum value + is negative. + +05/27/2005: wsfulton + Modernised and tidied up Windows macros --> SWIGEXPORT, SWIGSTDCALL. They can be overridden + by users via -D compiler directives if need be. + +05/26/2005: wsfulton + %csmethodmodifiers can be applied to variables as well as methods now. + + In addition to the default 'public' modifier that SWIG generates, %csmethodmodifiers will also + replace the virtual/new/override modifiers that SWIG thinks is appropriate. This feature is + useful for some obscure cases where SWIG might get the modifiers incorrect, for example + with multiple inheritance and overriding a method in the base class. + + *** POTENTIAL INCOMPATIBILITY FOR C# MODULE *** + +05/25/2005: wsfulton + Added missing constructors to std::pair wrappers (std_pair.i) for all languages. + +05/25/2005: wsfulton + [C#] Added std::pair wrappers in std_pair.i + +05/25/2005: wsfulton + [C#] The C# 'new' and 'override' modifiers will be generated when a C++ class inherits methods + via a C++ 'using' declaration. + +05/25/2005: wsfulton + Fix for exception specifications previously being ignored in classes that inherited methods + from 'using' declarations, eg calls to Derived::bar below will convert C++ exceptions into + a target language exception/error, like it always has done for Base::Bar. + + class Base { + virtual bar() throw (std::string); + }; + class Derived : public Base { + using Base::bar; + }; + +05/23/2005: wsfulton + Fixes for detecting virtual methods in %extend for the -fvirtual option and C# override and new + method modifiers. + +05/23/2005: wsfulton + [C#] The 'new' modifier is now generated on the proxy method when a method in a derived + class is not polymorphic and the same method exists in the derived class (ie it hides + the base class' non-virtual method). + +05/23/2005: wsfulton + [Java, C#] Fixes to detection of covariant return types - when the class hierarchy is more + than 2 classes deep. + +05/21/2005: wsfulton + [Java] std::wstring typemaps moved from std_string.i to std_wstring.i + +05/21/2005: wsfulton + Fix for crash in DohStrstr, bug #1190921 + +05/21/2005: wsfulton + [TCL] Fix for methods with similar names when showing list of names on error - bug #1191828. + Patch from Jeroen Dobbelaere. + +05/21/2005: wsfulton + [TCL] long long overloading fix - bug #1191835, patch from Jeroen Dobbelaere. + +05/21/2005: wsfulton + Fix bug #1196755 to remove debug from swigtcl8.swg. + +05/19/2005: wsfulton + [C# and -fvirtual option] Fix for the override key not being generated in the derived class when a + virtual method's return type was a typedef in either the base or derived class. Also ensures the + method is eliminated when using the -fvirtual option. For example, Derived.method now has the C# + override keyword generated: + + typedef int* IntegerPtr; + + struct Base { + virtual IntegerPtr method(); + }; + + struct Derived : Base { + int * method() const; + }; + + [C#] Fix for the override key being incorrectly generated for virtual methods when a base class + is ignored with %ignore. + +05/13/2005: wsfulton + [Java] Fixes to remove "dereferencing type-punned pointer will break strict-aliasing rules" + warnings in C wrappers when compiling C code with 'gcc -Wall -fstrict-aliasing'. Patch from + Michael Cahill. This modifies many of the casts slightly, for example + arg1 = *(DB_ENV **)&jarg1; + to + arg1 = *(DB_ENV **)(void *)&jarg1; + +05/12/2005: wsfulton + [C#] Support for C# attributes. C# attributes can be generated: + 1) On a C/C++ type basis by specifying an inattributes and/or outattributes typemap attribute + in the imtype or cstype typemaps (for C# return type or C# parameter type attributes). + 2) On a wrapped method or variable by specifying a csattributes feature (%feature). + 3) On a wrapped proxy class or enum by specifying a csattributes typemap. + + Examples are in the C# documentation (CSharp.html). + +04/29/2005: wsfulton + New configure option to turn off the default maximum compiler warning as + they couldn't be removed even when overriding CFLAGS and CXXFLAGS with configure + (./configure CFLAGS= CXXFLAGS=). To turn the maximum warnings off, run: + + ./configure --without-maximum-compile-warnings + +04/28/2005: wsfulton + Patch from Scott Michel which reworks the Java constructor and finalize/destructor typemaps, + for directors to reduce the number of overall Java typemaps. Added the director_take and + director_release typemaps to emulate other modules' __disown__ functionality. + + *** POTENTIAL INCOMPATIBILITY FOR JAVA DIRECTORS *** + +04/28/2005: wsfulton + [C#] Fixed problems due to the over eager garbage collector. Occasionally the + garbage collector would collect a C# proxy class instance while it was being used + in unmanaged code if the object was passed as a parameter to a wrapped function. + Needless to say this caused havoc as the C# proxy class calls the C++ destructor + when it is collected. Proxy classes and type wrapper classes now use a HandleRef, + which holds an IntPtr, instead of a plain IntPtr to marshal the C++ pointer to unmanaged + code. There doesn't appear to be any performance degradation as a result of this + modification. + + The changes are in the proxy and type wrapper classes. The swigCPtr is now of type HandleRef + instead of IntPtr and consequently the getCPtr method return type has also changed. The net + effect is that any custom written typemaps might have to be modified to suite. Affected users + should note that the implementation uses the new 'out' attribute in the imtype typemap as the + input type is now a HandleRef and the output type is still an IntPtr. + + *** POTENTIAL INCOMPATIBILITY FOR C# MODULE *** + +04/28/2005: wsfulton + [C#] Support for asymmetric type marshalling added. Sometimes the output type needs to be + different to the input type. Support for this comes in the form of a new optional 'out' + attribute for the ctype, imtype and cstype typemaps. If this typemap attribute is not + specified, then the type used for both input and output is the type specified in the + typemap, as has always previously been the case. If this typemap attribute is specified, + then the type specified in the attribute is used for output types and the type specified + in the typemap itself is used for the input type. An output type is a return value from + a wrapped method or wrapped constant and an input type is a parameter in a wrapped method. + + An example shows that char * could be marshalled in different ways, + + %typemap(imtype, out="IntPtr") char * "string" + char * function(char *); + + The output type is thus IntPtr and the input type is string. The resulting intermediary C# code is: + + public static extern IntPtr function(string jarg1); + +04/22/2005: mkoeppe (Matthias Koeppe) + [Guile] Fix generation of "define-method" for methods of + classes with a constructor. Reported by Luigi Ballabio. + +04/15/2005: wuzzeb (John Lenz) + [Chicken] + For wrapped functions that return multiple values (using argout), + SWIG CHICKEN now returns them as multiple values instead of as + a list. They can then be accessed using (call-with-values). + +04/14/2005: wuzzeb (John Lenz) + [Chicken] + + Added a whole bunch of new _runme scripts into the chicken test + suite. Also fix some bugs these new scripts turned up. + + + Added optimization when returning a wrapped proxy class. Before, + a minor garbage collection was invoked every time a function returned. + + + All the chicken Examples should now run correctly + +04/14/2005: wsfulton + [C#] More fixes for typemap matching when wrapping variables, in particular + std::string, so that std::string variables can be easily marshalled with + a C# string property using: + + %include "std_string.i" + %apply const std::string & { std::string *variable_name }; + std::string variable_name; + + (Recall that all class variables are wrapped using pointers) + +04/05/2005: wuzzeb (John Lenz) + [Chicken] + + Added Examples/chicken/egg, an example on how to build a chicken + extension library in the form of an egg. Also updated the + documentation on the different linking options. + + + chicken test-suite now has support to check SWIG with the -proxy + argument if there exists a _proxy_runme.ss file. + + + More fixes for overloaded functions and -proxy + +03/31/2005: wsfulton + Turned on extra template features for all languages which were + previously only available to Python. + + This enables typemaps defined within a templated class to be used as + expected. Requires %template on the templated class, %template() will + also pick up the typemaps. Example: + + template struct Foo { + ... + %typemap(in) Foo "in typemap for Foo " + or + %typemap(in) Foo "in typemap for Foo " + }; + + %template(Foo_i) Foo; + %template() Foo; + + will generate the proper 'in' typemaps wherever Foo and Foo + are used. + +03/30/2005: mkoeppe (Matthias Koeppe) + [MzScheme] Patch from Hans Oesterholt for supporting MzScheme 30x. + +03/29/2005: wuzzeb (John Lenz) + [Chicken] + + Reallow older versions of chicken (1.40 to 1.89) by passing -nocollection + argument to SWIG + + %import now works correctly with tinyclos. (declare (uses ...)) will be + exported correctly. + + TinyCLOS proxy classes now work correctly with overloaded functions + and constructors. + +03/29/2005: wsfulton + [Java] Patch from Scott Michel for directorout typemaps. Java directors + require the directorout typemaps like the other languages now. The new + typemaps provide fixes for methods where the return type is returned + by reference (this cannot automatically be made thread safe though). + +03/22/2005: wsfulton + Enum casting fixes. Visual C++ didn't like the C type casting SWIG produced + when wrapping C++ enum references, as reported by Admire Kandawasvika. + +03/21/2005: wsfulton + [Perl] SF #1124490. Fix Perl macro clashes when using Visual Studio's STL string, + so now projects can #include . + +03/21/2005: wsfulton + Fixed %varargs which got broken with the recent default argument changes. + Also works for Java and C# for the first time now. + +03/17/2005: wuzzeb (John Lenz) + [Chicken] + + Fix a whole bunch of bugs in the chicken module. The entire + test suite now compiles, with the exception of the tests that require + std_vector.i, std_deque.i, and so on, which chicken does not have yet. + + + Add support for %exception and %typemap(exceptions). Exceptions are + thrown with a call to (abort) and can be handled by (handle-exceptions) + +03/15/2005: wsfulton + [Java] Patch from Scott Michel for directors. Modifications to the typemaps + giving users fine control over memory ownership and lifetime of director classes. + Director classes no longer live forever by default as they are now collectable + by the GC. + +03/15/2005: wuzzeb (John Lenz) + [Chicken] Add support for adding finalizers garbage collected objects. + Functions that return new objects should be marked with %newobject and + input arguments which consume (or take ownership) of a pointer should + be marked with the DISOWN typemap. + + Also add support for correctly checking the number of arguments passed + to a function, and raising an error if the wrong number are passed. + +03/14/2005: wuzzeb (John Lenz) + Add --without-alllang option to configure.in, which is the same as + passing all the --without-python --without-perl5 etc... that Matthias added. + +03/09/2005: wsfulton + [Php] Memory leak fix for functions returning classes/structs by value. + +03/08/2005: wsfulton + [Perl] Fix for Perl incorrectly taking memory ownership for return types that + are typedefs to a struct/class pointer. Reported by Josh Cherry. + +03/07/2005: wsfulton + [C#] Various exception changes for the std::vector wrappers. These now more + accurately mirror the same exceptions that System.Collections.ArrayList throw. + +03/07/2005: wsfulton + [C#] Fix undefined behaviour after any of the std::vector methods + throw an exception. + +03/07/2005: wsfulton + [C#] When null is passed for a C++ reference or value parameter, the + exception thrown has been corrected to an ArgumentNullException instead + of NullReferenceException as recommended in the .NET Framework documentation. + + The default throws typemaps turn a C++ exception into an ApplicationException, + not a SystemException now. + +03/07/2005: wsfulton + [C#] Numerous changes in C# exception handling have been made over the past + few weeks. A summary follows: + + The way in which C++ exceptions are mapped to C# exceptions is quite different. + The change is to fix C# exceptions so that the C++ exception stack is correctly + unwound as previously C++ exceptions were being thrown across the C PInvoke layer + into the managed world. + + New typemap attributes (canthrow and excode) have been introduced to control the + mapping of C++ to C# exceptions. Essentially a callback into the unmanaged world + is made to set a pending exception. The exception to throw is stored in thread local + storage (so the approach is thread-safe). The typemaps are expected to return + from unmanaged code as soon as the pending exception is set. Any pending exceptions + are checked for and thrown once managed code starts executing. There should + be minimal impact on execution speed during normal behaviour. Full details will be + documented in CSharp.html. + + The SWIG_CSharpThrowException() function has been removed and replaced with the + SWIG_CSharpSetPendingExceptionArgument() and SWIG_CSharpSetPendingException() + functions. The original name has been deliberately changed to break old code as + the old approach was somewhat flawed. Any user defined exceptions that follow the + same pattern as the old approach should also be fixed. + + Numerous new .NET framework exceptions are now available for easy throwing from + unmanaged code. The complete list is: + + ApplicationException, ArithmeticException, DivideByZeroException, + IndexOutOfRangeException, InvalidOperationException, IOException, + NullReferenceException, OutOfMemoryException, OverflowException, + SystemException, ArgumentException, ArgumentNullException and + ArgumentOutOfRangeException. + + *** POTENTIAL INCOMPATIBILITY FOR C# MODULE *** + +05/05/2005: mmatus + + Fix several memory leaks around. Even when we survive knowning + swig is a memory leak factory, it was a little out of + control. To run std_containers.i in the python test-suite, + swig was using ~260MB, now it uses 'only' ~40MB, which is + the same ammount that g++ uses, so, is not that bad. + In the process, I found a couple of extra Deletes, which + in some cases could trigger seg. faults and/or + DOH/asserts. + + [python] Better support for directors + exception. More + verbose errors and added an unexpected exception handler. + + [python] Fix memory leak for the + + std::vector > + + case,reported by Bo Peng. + + [python] Fix SwigPyObject compare problem reporte by + Cameron Patrick. + + [python] Fix several warnings in the generated code + for gnu-gcc, Intel and VC7.1 compilers. + + +02/25/2005: wuzzeb (John Lenz) + Update documentation to use CSS and
      instead of
      + I used a script to convert the docs, and it set all the box classes + to be "code". There are actually 4 different classes, + "shell", "code", "targetlang", and "diagram". We need to go through + and convert the divs depending on what they contain. + +02/23/2005: mmatus + + [Python] Added option -nortti to disable the use of native + C++ RTTI with directors (dynamic_cast<> is not used). + + Add more code for directors to detect and report errors in + the python side. + + Extend the use of SWIGINTERN whenever is possible. + + Remove template warnings reported by VC7.1. + + Remove warnings reported by gcc/g++. Finally you can + compile using + + g++ -W -Wall -c mymodule_wrap.cxx + + and no spurious errors will be generated in the wrapper + code. + +02/23/2005: wuzzeb (John Lenz) + Added -external-runtime argument. This argument is used to dump + out all the code needed for external access to the runtime system, + and it replaces including the files directly. This change adds + two new virtual functions to the Language class, which are used + to find the language specific runtime code. I also updated + all languages that use the runtime to implement these two functions. + +02/22/2005: mmatus + Fix %template + private error SF#1099976. + +02/21/2005: mmatus + + Fix swigrun.swg warnings reported when using "gcc -W -Wall" + (static/inline not used in front of a function + declaration), and add SWIGUNUSED attribute to avoid + unused warnings elsewhere. + + Fix unused variable warnings. + + [Python] Use new SWIGUNUSED attribute to avoid warnings in + SWIGINTERN methods. + + [Python] Fix PyOS_snprintf for python versions < 2.2 (SF #1104919). + + [Python] Fix map/multimap to allow empty maps (reported by + Philippe Hetroy). + + [Docs] Add some documentation to Python.html and + SWIGPlus.html, including for example the fact that + 'friends' are now supported. + +02/21/2005: wsfulton + [PHP] Patch from Olly Betts, so that wrappers compile with Zend thread safety enabled. + +02/17/2005: wsfulton + Memory leak fix in some of the scripting language modules when using default + arguments in constructors. The scripting language was not taking ownership of the + C++ object memory when any of the constructors that use default arguments was called. + +02/16/2005: wsfulton + SF #1115055: Failed make install. Patch from Rob Stone. + +02/16/2005: wsfulton + [Java] SF #1123416 from Paul Moore. Correct memory allocation for STRINGARRAY + typemaps in various.i. + +02/15/2005: wsfulton + Disabled typemap search changes for now (see entry 19/12/2004). It breaks + old typemaps, lengthens the execution time by about 25% and introduces + inconsistencies. + +02/15/2005: wsfulton + swig -help follows other software by printing to stdout instead of stderr now. + swig -version also displays to stdout instead of stderr now. + Behaviour reported by Torsten Landschoff. + +02/15/2005: wsfulton + [Ruby] Fix for the less commonly used ordering of %include and #include, so + that the generated code compiles. Bug reported by reported by Max Bowsher. + %include foo.h + %{ + #include foo.h + %} + +02/15/2005: wsfulton + [C#, Java] SWIG_exception macro will now return from unmanaged code / native code + as soon as it is called. Fixes possible JVM crashes and other code unexpectedly + being executed. Note SWIG_exception is only occasionally used by SWIG library + writers, and is best avoided by SWIG users. + +02/15/2005: wsfulton + [C#, Java] Typemaps can now be targeted at global variable names + and static member variable names. Previously the typemaps for + the setters were ignored, for example: + + %typemap(in) int globalint "..." + int globalint; + +02/13/2005: mkoeppe (Matthias Koeppe) + [Guile] Add %typecheck for SWIGTYPE, add %typecheck for ptrdiff_t, fix + typemaps for size_t. + + [Pike] Merge patch from Torsten Landschoff for improved Pike configuration. + +02/12/2005: mkoeppe (Matthias Koeppe) + New configure switches --without-tcl, --without-python etc. allow to + disable the search for installed languages. + +01/31/2005: wuzzeb (John Lenz) + - Add DohSortList to DOH + + - Improve the runtime type system: + + Speed. Type loading is now O(n log n) instead of O(N^2), which + for large modules is a huge improvement. + + A whole bunch of functions in swigrun.swg no longer need the + swig_type_list_handle passed to them. The only one left is + TypeQuery. This also makes runtime.swg a lot smaller. + + Split up swig_type_info structure into two structures + (swig_type_info and swig_cast_info) + + Store a pointer to a swig_type_info rather than just the type + name string in the linked list of casts. First off, this makes + the guile module a little faster, and second, the + SWIG_TypeClientData() function is faster too. + + Add the idea of a module into the type system. Before, all the + types were stored in one huge linked list. Now, another level is + added, and the type system stores a linked list of modules, each + of which stores an array of types associated with it. + + For more information of how the runtime type system now works, + please see Doc/Manual/typemaps.html and Doc/Devel/runtime.txt + + - Update all language modules to use the new type system. The changes + to each language module are minor. All languages are now able to + use runtime.swg for external access to the type system. Before + only python and perl did. + + - [guile, mzscheme, ocaml, and php4] These languages opened up the + init function inside the .cxx code, and any code in the .swg files + in the init section was inside this function. This was a problem + for swiginit.swg, which needs to be inserted before the SWIG_init + function is opened. Thus I changed these languages to be like + python or perl, where the init function is declared in the .swg + file. + + - [Ruby] Instead of moving the init function to the .swg file, I + added a new section initbeforefunc, and then added + %insert(initbeforefunc) "swiginit.swg" + + - [MzScheme] Fix enums and fix Examples/Makefile.in so that if + multiple -I arguments are specified in the INCLUDES variable, each + gets a ++ccf. + + - [Guile GH] Update Guile GH to use the new type system. See + Doc/Manual/Guile.html for how smobs are now used. + +01/11/2005: wsfulton + [C#] New typemap called 'csconstruct'. The code in this typemaps was previously hard + coded and could not be customised by a user. This typemap contains the code that is + generated into a proxy class's constructor. + + [Java] New typemap called 'javaconstruct'. The code in this typemaps was previously hard + coded and could not be customised by a user. This typemap contains the code that is + generated into a proxy class's constructor. Another typemap named 'javaconstruct_director' + is used instead when the proxy class is a director class. + + [C#, Java] If a C++ class did not have a default constructor, a protected default constructor + was automatically generated by SWIG. This seems is unnecessary and has been removed + and thereby giving the user almost complete control over the generated code along with the + new typemaps above. + +19/12/2004: mmatus + [Disabled, see entry 02/15/2004] + - Fix typemap search, now the "out" typemap search is done as follows + + int *Foo::foo(int bar) -> int *Foo::foo(int bar) + -> int *Foo::foo + -> int *foo(int bar) + -> int *foo + -> int * + + then, now you can be more specific, and define + + /* apply only for 'Foo::foo' method */ + %typemap(out) int * Foo::foo(int *bar) ...; + + /* apply for all 'foo' functions/methods */ + %typemap(out) int * foo(int *bar) ...; + + %inline { + struct Foo { + int *foo(int *bar); + }; + } + + +15/12/2004: mmatus + - More fixes for templates and template default args. + See template_default.i for scary cases that now are + supported, besides the already ugly STL/std cases. + + - Cosmetics and more use of 'const' where it was implicit. + - Other fixes for OSS, which is now working again with 1.3.25. + +Version 1.3.24 (December 14, 2004) +================================== + +12/12/2004: wuzzeb (John Lenz) + [Chicken] Fix a bunch of bugs relating to -proxy support + + non-class variables now export properly using -proxy + + static member functions now export properly using -proxy + + member class variables now export properly using -proxy + + added a -nounit argument, which does not export the (declare (unit ...)) + + correctly install swigclosprefix.scm + + constants (enums, defines) now correcly export when using -proxy + +12/11/2004: wsfulton + configure fix for when more than one version of jni_md.h is found + in the Java include directory (was generating lots of sed error + messages). + +12/08/2004: wsfulton + [Java] Fixes to arrays_java.i so that one can apply the array + typemaps to functions taking pointers as input, eg + + %include "arrays_java.i" + %apply int[] {int*}; + void foo(int *a); + +12/05/2004: wsfulton + [Java] Director mods contributed by Scott Michel. New typemaps + directordisconnect and directordisconnect_derived for the + swigDirectorDisconnect() method. Also fix to get the javapackage + typemap working again. + +12/05/2004: mmatus + - Finishing the fixes for templates + default template + args + specializations. + + - [Python] Now we use the new templates + default template + args in the std/STL library. That means the internal + swig files are getting uglier since we now support the + original declarations: + + template > + class vector { + .... + }; + + template, + class _Alloc = std::allocator > > + class map { + .... + }; + + and the user can use the %template directive as + + %template() std::vector; + %template() std::vector >; + %template() std::vector >; + + Now we are closer to the cleaning/rewriting of the + python std/STL support, such that we recover support for + MSVC++ 6.0, and we can add support for other languages + too. + + +12/02/2004: wsfulton + [Java] Fix for directors when wrapping methods using a member enum + and typesafe/proper enums enabled. + +12/01/2004: mmatus + - Fix typemaps to work with templates and default template + args, ie + + template + struct Foo { + }; + + %typemap(in) Foo *{...} + %typemap(out) Foo *{...} + + Foo * foo( Foo *f1, Foo *f2); + + now 'f1', 'f2' and the return value resolve the provided + typemaps properly. + + This is highly needed for proper STL support, see new + std_basic_string.i, std_sstream.i, etc. + + - Added std_sstream.i, and fix std_basic_string.i to use + the new typemaps + template def. arg mechanism. Also, + added the needed std_alloc.i. Now, all the containers + can be modified to support std::allocator, like in: + + template > + class vector { + public: + .... + }; + + This change is only completed by now for basic_string. + + - Fix for smart pointers + members + extensions: + + %extend Foo { + int extension(int i, int j) { return i; } + int extension() { return 1; } + } + + %inline %{ + + class Foo { + public: + int y; + static const int z; + }; + + class Bar { + Foo *f; + public: + Bar(Foo *f) : f(f) { } + Foo *operator->() { + return f; + } + }; + + now you can + + f = Foo() + f.y = 3 + a = f.z + f->extension() + + b = Bar(f) + b.y = 3 + a = b.z + b->extension() + + - Other small errors fixes, mostly python. + +11/25/2004: wsfulton + [Java] Numerous director bug fixes so that the correct java types + and canonicalized types in the JNI code are emitted. Use of the + $javaclassname special variables in the director typemaps now + consistent with the non-director typemaps. The types used for + typemap lookups are also corrected in a few places. If you + previously had your own director typemaps, ensure they are using the + correct C++ type. + + *** POTENTIAL INCOMPATIBILITY FOR JAVA DIRECTORS *** + +11/25/2004: wsfulton + const enum SWIGTYPE & typemaps added. These wrap const enum references + as if they were passed by value. Const enum references thus work the + same as const reference primitive types such as const double &, + const int & etc. Typemaps added for Java, C#, Ruby, Tcl, Perl and Pike. + +11/25/2004: wsfulton + [Java, C#] New special variable: $*javaclassname, similar to $javaclassname + and $&javaclassname. The new one removes a pointer from the C type before + obtaining the Java class name. One or more of $javaclassname, + $&javaclassname or $*javaclassname may now appear in a typemap. Likewise for + C# using csclassname instead of javaclassname. + +11/25/2004: wsfulton + The last vestiges of enums being handled as integers removed from the + internals. The wrapper methods use the enum type rather than an int + now. The net result is added type safety for enums when handled as + pointers, references etc. Previously in situations such as a method + taking a pointer to an enum, a pointer to an int or a pointer to an + enum of some other type could inadvertantly be passed to the method. + This is now fixed as the descriptor for an enum is no longer based on + an int, but the enum type instead. Anonymous enums are still handled + as integers. + + The consequence for scripting language users in correct usage of enums + should not be noticeable. There is no change for any of the languages + where enums are passed by value - most of the scripting languages will + still accept an integer for an enum value and the strongly typed + languages still use either typesafe enums, integers or proper enums + depending on what the user configures. For Java and C# users a change + in the typewrapper class name has occurred (for enum pointers, + references etc). For example: + + enum Numbers { one=1, two }; + enum Numbers* number(); + + In Java and C# this must now be coded as + + SWIGTYPE_p_Numbers n = modulename.number(); + + rather than + + SWIGTYPE_p_int n = modulename.number(); + + *** POTENTIAL INCOMPATIBILITY *** + +11/21/2004: wsfulton/mmatus + Added missing deprecated warning for %name and remove remaining %name + usage in the SWIG libraries. + +11/21/04: mmatus + - [Python] Adding the PySwigObject to be used for carrying + the instance C/C++ pointers. This is used instead of + string and PyCObjects. + + The new PySwigObject is even safer than PyCObject, and + more friendly than plain strings: + + now you can do + + print a.this + + + print str(a.this) + _00691608_p_A + + print long(a.this) + 135686400 + + print "%s 0x%x" % (a.this, a.this) + _00691608_p_A 0x8166900 + + the last one is very useful when debugging the C/C++ + side, since is the pointer value you will usually get + from the debugger. + + Also, if you have some old code that uses the string + representation "_00691608_p_A", you can use it now again + using 'str(ptr)', or by calling 'str = PyObject_Str(obj)' + in the C/C++ side. + + This change is mainly for nostalgic swig users that miss + the string representation, but also allows to say again + + if a.this == b.this: + return "a is b" + + and well, since the change were really simple, maybe in + the future we will be able to do + + next = a.this + 1 + + or add native python iteration over native C/C++ arrays, + ie, no need to create/copy new tuples when returning and + array or vector. + + Also, a PySwigPacked object was adding to carry a member + method pointer, but this is probably a temporal solution + until a more general object for methods is added. + + Be aware that to simplify maintaining and compatibility + with other tools, the old string and PyCObjects + representation could disappear very soon, and the + SWIG_COBJECTS_TYPES or SWIG_NO_OBJECT_TYPES macros will + have no effect at compilation time. Still, the three + mechanisms are present in the code just for testing, + debugging and comparison purposes. + +11/21/04: mmatus + + - [Python] Adding back support for using the swig runtime code + inside the user code. We just allow the user to include + the minimal code needed to implement the runtime + mechanism statically, just as in done in the swig + modules. + + To use the swig runtime code, for example with python, + the user needs include the following: + + #include // or using your favorite language + #include + #include // or using your favorite language + #include + + the files swigrun.swg, pyrun.swg and runtime.swg can + be checked out by using swig -co, or they can simply + be found by adding the swig lib directory to the + compiler include directory list, for example + + SWIGLIB=`swig -swiglib` + c++ -I${SWIGLIB} .. + + of better, using the CPPFLAGS, but that depends on your + environment. + + This change can be ported to the other languages too, + you just need to isolate the needed runtime code in + a single file like 'pyrun.swg', and provide the + SWIG_Runtime_GetTypeList() method. Look at the + Lib/python/pyrun.swg file and the Examples/python/swigrun + example. + +11/15/04: mmatus + - Fix mixed_types.i + gcc-3.4, ie, arrays + references + + typedefs + + - Fix multidim arrays + typedefs,ie + + typedef char character[1]; + typedef character word[64]; + + - Process protected/private bases in the same way before + we process protected/private members, ie, we check + for constructors, operator new, virtual members, etc. + + - Fix Ruby/Java to work (or ignore) multi-inheritance + + directors. Allow other languages to define if it is + supported or not. + + - Now you can run + + SWIG_FEATURES="-directors -dirprot" + make check-ruby-test-suite + make check-python-test-suite + make check-java-test-suite + make check-ocaml-test-suite + + and you will get only 'real' errors. ruby and python + compile with no errors, java shows some problems. + +Version 1.3.23 (November 11, 2004) +================================== + +11/05/2004: wsfulton + Patch #982753 from Fabrice Salvaire: Adds dependencies generation for + constructing makefiles. New command line options -MF -MD -MMD to work + with the current options -M and -MM. These options are named the same + and work the same as in gcc. + +11/05/2004: wsfulton + %ignore/%rename changes for methods with default arguments to mirror + %feature behaviour. See previous entry. + + *** POTENTIAL INCOMPATIBILITY *** + +11/04/2004: wsfulton + %feature improvements for fine tuning when wrapping methods with + default arguments. Any %feature targeting a method with default arguments + will apply to all the extra overloaded methods that SWIG generates if the + default arguments are specified in the feature. If the default arguments are + not specified in the feature, then the feature will match that exact + wrapper method only and not the extra overloaded methods that SWIG generates. + For example: + + %feature("except") void hello(int i=0, double d=0.0); + void hello(int i=0, double d=0.0); + + will apply the feature to all three wrapper methods, that is: + + void hello(int i, double d); + void hello(int i); + void hello(); + + If the default arguments are not specified in the feature: + + %feature("except") void hello(int i, double d); + void hello(int i=0, double d=0.0); + + then the feature will only apply to this wrapper method: + + void hello(int i, double d); + + and not these wrapper methods: + + void hello(int i); + void hello(); + + This has been introduced to make %feature more powerful to ease the migration + to new default arguments wrapping approach. + + *** POTENTIAL INCOMPATIBILITY *** + + If you previously had a %feature and didn't specify the default arguments, + you will have to add them in now or you can obtain the original behaviour + by using %feature("compactdefaultargs"). + +11/04/2004: wsfulton + [C#] Typemaps for std::vector added into std_vector.i. The proxy classes + generated are modelled on the .NET ArrayList class. This isn't quite + ready for general consumption yet, but will work with vectors of primitive + types and some classes. + +10/3/2004: wuzzeb (John Lenz) + [GUILE] The -scm interface is now the default. The old GH interface can + still be enabled by passing -gh to SWIG. + +10/2/2004: mmatus + + - More fixes for namespace + class declarations. + As an extra bonus, we get %template support for static/members class + methods, ie, now you can say: + + namespace space { + struct A + { + template + static void fooT(Y y) { } + }; + } + + struct B + { + template + void barT(Y y) {} + }; + + %template(foo) space::A::fooT; + %template(foo) space::A::fooT; + %template(foo) space::A::fooT; + + %template(bar) B::barT; + %template(bar) B::barT; + %template(bar) B::barT; + + and call + + A.foo(1) + b = B() + b.bar(1) + + note the the methods are emitted inside the classes, + and hence, the %template name refers to the 'member' + method name, not a global namespace name. + +10/31/2004: mmatus + - Solve namespace + class declarations, as in + + namespace foo { + struct Bar; + struct Foo { + }; + } + + struct foo::Bar : Foo { + }; + + see namespace_class.i for more examples. + + - Fix %template directive to properly use namespaces, + including the case: + + namespace one + { + template + struct Ptr {}; + } + + namespace one + { + struct Obj1 {}; + typedef Ptr Obj1_ptr; + %template(Obj1_ptr) Ptr; + } + + namespace two + { + struct Obj2 {}; + typedef one::Ptr Obj2_ptr; + %template(Obj2_ptr) one::Ptr; + } + + this is done by using the namespace name 'one' to create + a namespace node to emit the template instantiation, + just as before, but the template parameters are resolved + and qualified in the current namespace ('one' or 'two'). + This is same way that typedef works. + + This resolve the smart_pointer_namespace2.i case, and at + the same time, several other ones where before swig was + generating the + + "Can't instantiate template 'xx' inside namespace 'yy'" + + error message. In fact, that error doesn't exist + anymore. You can only get an error if you use a bad + namespace name or so. + +10/30/2004: mmatus + - [ruby] Directors fixes: + - enums and std::strings are working now (several + reports in bug track system) + - added patch 1025861 for director + exceptions + + *** Attention ***: ruby with directors + protected + members work with version 1.7+. Older versions seems to + have a broken signature for'rb_protect'. + + If you need to use an old version, look at + + http://excruby.sourceforge.net/docs/html/ruby__hacks_8hpp-source.html + for workarounds. + + - [ruby] Fix memory allocation problem in typemap (bug 1037259) + + - [tcl] Fix (enums|constants) + namespace option + (reported by jason.m.surprise@intel.com). + + - [perl] Add patch 962168 for multiple inheretance + + - Fix 'defined' as variable name. + +10/29/2004: wsfulton + Seg fault fix for global scope operator used for friend methods: + + class B { + friend void ::globalscope(); + ... + }; + +10/28/2004:mmatus + - Added module and swig option "templatereduce" to force swig + to reduce any type needed with templates, ie, in these cases + + %module("templatereduce") test + + template struct A { }; + + typedef int Int; + %template(A_Int) A ==> %template(A_Int) A + + typedef B* Bp; + %template(A_Bp) A ==> %template(A_Bp) A + + swig reduces the types Int and Bp to their primitives + int and B*. This is closer to the usual compiler + resolution mechanism, and it is really needed sometimes + when you mix templates + typedefs + specializations. + + Don't use it if you don't have any problem already, + since the type reduction can interfere with some + user typemaps, specially if you defined something like + + typedef int Int; + %typemap(in) Int ...; + + in this case, when you use the "templatereduce" option, + swig will ignore the user typemap, since the "typedef int Int" + will take precedence, and the usual "int" typemap will be + applied. + + Note that the previous case is not common, and should be + avoided, ie, is not recommended to use a typedef and a + typemap at the same time, specially if you are going to + use templates + specializations. + + - Directors: + + virtual destructor is always emitted now, this doesn't + cause any harm, and could solve some nasty and + mysterious errors, like the one mentioned by Scott. + + also the destructor is not in-lined, so, that can solve + some other mysterious errors when mixing directors + + imports + embedded applications + some specific compilers. + +10/27/2004: wsfulton + [C#] typemaps.i library file with INPUT, OUTPUT and INOUT typemaps added. + +10/27/2004: wsfulton + [Java] std::wstring typemap fixes in std_string.i from Russell Keith-Magee. + +10/25/2004: mmatus + + - Using + namespace is working now (using_namespace.i). + + - Derived + nested classes is working now + (deriver_nested.i), but of course, we are still waiting + for the nested class support. + + - Directors: + - unnamed parameters support, + + - protected constructor support (automatic and with + dirprot mode), + + - detection of really needed protected declarations + (members and constructors) now is done automatically. + Even if you don't use the 'dirprot' mode, swig will + wrap what is minimally needed (and protected) for the + code to compile. + + what is public, as usual, is always wrapped, and if + you use the 'dirport' + + + - Final fixes for the OSS to compile with SWIG 1.3.23 (my + very very ugly C++ + templates + everything mounters wrap). + +10/25/2004: wsfulton + [C#] New commandline option -dllimport. This enables one to specify + the name of the DLL for the DllImport attribute. Normally this name + comes from the module name, so now it is possible to override this: + + swig -csharp -dllimport xyz example.i + + will generate for all the wrapped PInvoke methods: + + [DllImport("xyz", EntryPoint="...")] + public static extern ... + + The wrappers from many different SWIG invocations can thus be compiled + into one DLL. + + A new special variable $dllimport can also be used in typemaps, pragmas, + features etc. This will get translated into the value specified by -dllimport + if specified, otherwise the module name. + +10/22/2004: wsfulton + [Java] Patch #1049496 from Scott Michel fixes directors methods with + enums when wrapped with typesafe or proper Java enums. + +10/21/2004: wsfulton + Fixes for default arguments in director constructors (Python, Ruby, Ocaml). + +10/21/2004: mmatus + - [Python] Add the '-cpluscast' option to enable the 'new' + C++ casting operators, such as 'static_cast', inside the + typemaps. By default swig use the old C cast style, even + when parsing C++. + + - [Python] Add the '-new_vwm' option to enable the new + SwigValueWrapper mode. Now this is mainly for testing + that the typemaps are really safe for any future + solution, but you can use it if you have a very strange + error with default cosntructors missing + %apply + + %typemap, and if everything else fails (see + valuwrapper_opaque.i for alternative and current + solutions). If you are a user that don't know what is + SwigValueWrapper, don't even try it. + + - [Python] Add the '-noh' option to be used with directors + and when you prefer to disable the generation of the + director header file. If not used, swig will work as + usual generating both the wrap.cxx and wrap.h files. If + you use it, swig will only generate wrap.cxx. + +10/21/2004: wuzzeb (John Lenz) + - If you define SWIG_TYPE_TABLE when compiling a wrapper file, + the runtime types will be stored in the given type table name. + Using this, you can seperate different modules to share their + own type systems. -DSWIG_TYPE_TABLE=Mytable + + - [Python] If you define SWIG_STATIC_RUNTIME then the type information + will be static to this wrapper. Nothing will be shared with any + other modules + + - [Python] If you define SWIG_LINK_RUNTIME, then instead of using + the new way of sharing type information, the wrapper will expect + to be linked against the Lib/linkruntime.c file. Any modules compiled + with SWIG_LINK_RUNTIME and linked against linkruntime.c will all + share type information. + +10/20/2004: mmatus + - [Python] Initial fix for python/import example. Please + update the Makefile (autoconf, configure, etc, expert), + since now probably is only working with g++, icc and a + few other compilers that have the -shared option. + + We need to create additional shared libraries for the + virtual destructors. Old and usually forgotten C++ + requirement. + + Same fix need to be used in perl, I think. + + - [Python] Fix generation of header file for directors, + now directors.swg is also included, so, it can be really + used from C++, and it solves some problem with compiler + that require that, even with the simple swig inclusion. + + - [Python] Reordering the methods and moving some bodies + outside the class declaration. This is needed due to + some gcc-2.96 internal compiler errors. It seems the + PYTHON class is getting too large to been declared and + defined at the same time. + + - Add the -oh option to change the output header file name + if needed: + + swig -c++ -python test.i -o test.CC -oh test.HH + + this is mainly needed when using directors, and if the + current default header file name is not good for you, + which is generated as follow: + + swig -c++ -python test.i => test_wrap.h + swig -c++ -python test.i -o test.CC => test.h + + +10/20/2004: wsfulton + 1) Compact default arguments feature added. This feature allows one + to use the default argument code generation that was used in + SWIG-1.3.22 and earlier versions. It produces more compact wrappers + as only one wrapper method is generated for any method with default + arguments. So the advantage is it generates less code but has the + original limitations, like it it does not work with all default arguments + and default arguments cannot be taken advantage of in the strongly typed + languages (C# and Java). It is implemented via the usual %feature mechanism: + + %feature("compactdefaultargs"); + + 2) Keyword arguments (kwargs) are working again for default arguments + in the languages that support it, ie, Python and Ruby. The new default + argument wrapping approach using overloaded methods cannot support kwargs + so the compact default argument feature is automatically turned on when + kwargs are specified, by %feature("kwargs"). + + 3) Compact default arguments are also automatically turned on when wrapping + C (not C++) code. This is to support the bizarre notion of default arguments + for C code. + +10/20/2004: wsfulton + Overloaded templated functions in namespaces also working now. + Templated functions with default arguments in namespaces too. + +10/19/2004: mmatus + + - Allow to disable the new SwigValueWrapper mechanism, + if you add the following line in your language main. + + /* Turn on safe value wrapper use mode */ + Swig_value_wrapper_mode(1); + + + Now is only active in python. All the other languages + are using the old resolution, but they can also use the + "valuewrapper"/"novaluewrapper" features to fix some + of the old broken cases. Note, however, that not all + the broken cases can be solved in that way. + + The new mechanism seems to be working fine in perl, ruby + and tcl, but failing in some typemaps in java. + + Hence, is upto the language maintainer to test it, and + decide to enable it or not. + + Look at the valuewrapper_opaque.i for examples. + + - Fix more SwigValueWrapper cases when the new mechanism + is active. Now it also check for local typemap + variables, see valuewrapper_opaque.i for an example when + this is needed. But again, this extra checking will only + be activated when using the new value wrapper mode. + + - [Python] Fix variable wrapping of classes with private + assign operators. It should be easy to fix in all the + other modules, instead of checking + + if (!Getattr(n,"immutable")) ... + + you need to verify + + if (is_assignable(n)) ... + + Look at the private_assign.i for an example. + +10/18/2004: mmatus + - %features "director"/"nodirector" now work as expected. + - General fixes in %feature to resolve function decl + properly, + + %feature("hello") foo(); + char foo() -> f() // was working + char *foo() -> f().p // it wasn't + + + - Template + specialization + default template args now is + working, (don't confuse with template + default arg + values, that was solved before), now this ugly case is + working: + + template > + struct Vector + { + Vector(T a){} + }; + + template <> + struct Vector + { + Vector(){} + int foo() { return 0; } + }; + + %template(V_c) Vector >; + %template(V_i) Vector; // picks Vector > + %template(V_d) Vector; // picks the specialization + + this is needed for automatic STL support (later will + be). + + - Fix the template + typedef errors in test-suite, which + probably will fix another group of strange template + + namespaces + typedefs errors. + + - %warnfilter is working better now, parser.y tries to use + them when needed. + + - **** New default type resolution method (stype.c) ***** + + It preserves the original mixed types, then it goes + 'backward' first deleting the qualifier, then the inner + types, for example: + + typedef A *Aptr; + const Aptr&; + r.q(const).Aptr -> r.q(const).p.SWIGTYPE + r.q(const).p.SWIGTYPE -> r.p.SWIGTYPE + r.p.SWIGTYPE -> r.SWIGTYPE + r.SWIGTYPE -> SWIGTYPE + + enum Hello {}; + const Hello& hi; + r.q(const).Hello -> r.q(const).enum SWIGTYPE + r.q(const).enum SWIGTYPE -> r.enum SWIGTYPE + r.enum SWIGTYPE -> r.SWIGTYPE + r.SWIGTYPE -> SWIGTYPE + + int a[2][4]; + a(2).a(4).int -> a(ANY).a(ANY).SWIGTYPE + a(ANY).a(ANY).SWIGTYPE -> a(ANY).a().SWIGTYPE + a(ANY).a().SWIGTYPE -> a(ANY).p.SWIGTYPE + a(ANY).p.SWIGTYPE -> a(ANY).SWIGTYPE + a(ANY).SWIGTYPE -> a().SWIGTYPE + a().SWIGTYPE -> p.SWIGTYPE + p.SWIGTYPE -> SWIGTYPE + + before it always stops after finding ref/pointer/enum/array/etc. + + Now, then, you can define (use and apply) 'higher' typemaps such as: + + %typemap(in) SWIGTYPE* const& + %typemap(out) char FIXSIZE[ANY] + %typemap(in) SWIGTYPE* const& + %typemap(in) const enum SWIGTYPE& + %typemap(in) SWIGTYPE[ANY][ANY] + %typemap(in) const char (&)[ANY] + + It is possible with this change that previous typemaps + that were defined (but ignored), now will start to work. + + Also, it is necessary check for the '%typemap(varin) SWIGTYPE[]', + before it was usually not defined (but char[] was), + and that can produce some inconsistencies. + + *** POTENTIAL INCOMPATIBILITY *** + + This change was needed for STL, since std::vector + std::vector, etc, will always generate methods that + mix const references with the vector type. + + Now that is working, all the std::container + specialization will not be needed anymore, well, in + theory. + + In the practice, everythin is working as before until + the proper mixed types are defined and the libraries + simplified to use them. + + - Change the behavior of extern "java"/"fortran"/"etc", + now swig produces a warning, and use extern "C" instead. + The warning can also be disable with the "-w 313" flag. + (WARN_PARSE_UNDEFINED_EXTERN). + + - SwigValueWrapper is now more selective (lang.cxx). + + [Perl/Tcl] + - Fix some typemaps (perl/tcl) to work properly with + SwigValueWrapper. This was not a problem with + SwigValueWrapper, but with the typemaps that now are + safe to use with %apply. + + [Python] + + - Fix %callback/%pythoncallback work now as before after + the def args changes. Also, %callback now is an alias + for %pythoncallback, so, they do the same. + + [Python/Ruby] + - %callback is more usable and uniform: + + %callback("%s_cb") foo(); // for both, python/ruby + %callback("%s_cb"); // for both, python/ruby + %callback(1) foo(); // only in python. + +10/17/2004: arty + [OCAML] + - Tweak to enum typing for soundness in the presence of multiple + modules. + - global functions are now unambiguous in multiple loaded modules. + - Fixed test case code to build multimodule test cases correctly. + - There is no way to share overload resolution across modules + because of soundness issues. If the user wants to call some + function foo from an arbitrary module bar, they will have to + use Bar._foo to call it correctly. Later I will fix the + camlp4 module to do something clever in this case. + - Promided performance overhaul of class mechanism. + - Removed symbol hack for ocaml-3.07 and below which is not needed + for ocaml-3.08 and above. + +10/16/2004: wuzzeb (John Lenz) + [CHICKEN] + - Completly change how chicken.cxx handles CLOS and generic code. + chicken no longer exports -clos.scm and -generic.scm. The clos + code is exported directly into the module.scm file if -proxy is passed. + - The code now always exports a unit. Running the test-suite is now + majorly broken, and needs to be fixed. + - CLOS now generates virtual slots for member variables similar to how + GOOPS support works in the guile module. + - chicken no longer prefixes symbols by the module name, and no longer + forces all names to lower case. It now has -useclassprefix and -closprefix + similar to how guile handles GOOPS names. + +10/16/2004: wsfulton + Templated functions with default arguments working with new default argument + wrapping approach. The new approach no longer fails with the following default + argument pattern (previously failed with some primitive types, like + unsigned primitive types): + + template int foo(const T& u = T()); + %template(foo) foo; + + This relies on the templated function overloading support just added, so all + the combinations of overloading by template parameters and normal parameters + as well as overloading with default parameters works. + +10/16/2004: wsfulton + Added support for the large range of templated function overloading that C++ + supports. + + - Overloaded templated functions, eg + + template int overload(T t); + template int overload(T t, const T &r); + + - Fixes where the templated type is not used in the parameter list, eg + + template void xyz(); + template<> void xyz(); + + - Fixes for overloading of plain functions by a templated function: + + void abc(double d); + template void abc(T t); + + - Overloading by templated parameters fixed: + + template void foo(T t) {} + template void foo(T t, U u) {} + + %template(foo) foo; + + - All combinations of the above also working including specializations, eg: + + void abc(double d); + template void abc(T t); + template<> void abc(double t); + template<> void abc(int t); + +10/16/2004: wuzzeb (John Lenz) + - Remove the ability to share type information by using c linking. + All type sharing happens through a global variable in the target language. + + Remove SWIG_NOIMPORT, SWIG_RUNTIME, and related defines. + + Depreciate -runtime, -noruntime command line options + + Update test-suite common.mk to correctly build multicpptest + + Remove reference to precommon.swg + + Update the guile_gh interface to share data by a global var instead + of c linkage. + + - Remove Advanced.html, since everything in it is now obsolete + +10/09/2004: mmatus + - Split the python std/STL C++ library files, now + all the language independent definitions are under + the directory + + Lib/std + + and hence, can be used from other languages. + + - Add more documentation to the Python STL, and + clean unnecessary code. + + - Add initial C99 complex support, and some fixes + for long double. + +10/08/2004: mmatus + - Fix the SwigValueWrapper for opaque types, now it is + applied for opaque templates and classes, for which we + don't know if there is or not a default constructor, ie + + struct A { + A(int); + }; + + Still, if you know that you class has a default + constructor, and for some very very particular reason + you want to avoid the SwigValueWrapper, and you don't + want or can't expose the class to swig, now you can + say + + %feature("novaluewrapper") A; + class A; + + or the other way around, if the class has a default + constructor, but you want to use the value wrapper, you + can say + + %feature("valuewrapper") A; + struct A { + A(); + .... + }; + + - Fix for char > 128, ie + + const char tilde_a = '\341'; + + - Add patch 1041858 for $lextype, which carries the + literal type of a symbol. See lextype.i in the + test-suite for more details. + + + + +10/07/2004: wsfulton + {Ruby, Java] Fix director + 'empty' throws + + struct A { + A() throw(); + virtual ~A() throw(); + int foo() throw(); + }; + + +10/06/2004: wuzzeb (John Lenz) + [TCL] + - Fix bug reported by William A. Hoffman propagating clientdata + between modules. Added clientdata_prop.multicpptest to check for + this bug. The fix involved the following changes: + + SwigType_clientdata_collect does not need to check + types in r_resolved because we only want to propagate clientdata + to typedefed classes, and r_mangled already takes care of typedefs. + + + SWIG_TypeRegister now copies the clientdata field correctly + + + Move SWIG_Guile_PropagateClientData function from guile module + into common.swg, because we need to call it from both guile and tcl. + + + Add base_names to swig_class to delay the lookup of bases. SWIG + now exports the base names and only when the base swig_class is + needed is SWIG_TypeQuery(name)->clientdata looked up. + + - conversion_ns_template testsuite test was failing because + the name of the wrapped constructor function was not calculated + correctly for structs. Fixed. + +10/06/2004: wsfulton + Fixes for default arguments used in directors - in virtual + methods and director constructors. + +10/06/2004: mmatus + Fix the __cplusplus macro, and bug 1041170. + Now it is working as supposed, ie, you can safely use + + #ifdef __cplusplus + ... + + all over swig, including inside %defines and %{ %} bodies. + + + *** POTENTIAL INCOMPATIBILITY *** + + The old trick of using + + #if __cplusplus + + doesn't work any more. So, if you have your own typemaps + using that syntax, you will need to migrate them to use + "#ifdef __cplusplus". + +10/05/2004: wuzzeb (John Lenz) + - Reorganize how runtime type information is stored and shared + between modules. For chicken and mzscheme, I removed + the ability to use runtime libraries, while perl, tcl, python, and + ruby default to using the new method but can go back to the old + method by declaring SWIG_ALLOW_RUNTIME. + + - line 582 in mzscheme.cxx was generating a segfault on + imports.multicpptest, so I fixed it. + +10/05/2004: wsfulton + Fixes for %extend and overloaded static methods with default + arguments. + +10/05/2004: mmatus + - [python] Fix director + method with 'empty' throw, ie + + struct A { + virtual int foo() throw(); + }; + + other languages should also easy to fix, look for + Getattr(n,"throw") in python.cxx. + + - Fix director + destructor with 'empty' throw + + struct A { + virtual ~A() throw(); + }; + + - Now SWIG_FEATURES parse all and the same options you + can pass to swig in the command line. + + - New command line flag: -features , as in + + swig -features autodoc=3,director + + ie, any global feature can be initialized from the + command line. This is mainly for testing, but users + can also take advantage of it. + +10/04/2004: mmatus + - Properly qualify type in syntax as 'long(2)' or 'Foo()', + this solve old problem with default args, and probably + other problems around. However, the default arg problem + was also already solved by William (see bellow). + + - Fix feature_set and feature_get methods. Before + they look from particular to general and keep the first + feature found. This didn't work well with templates. + Now the methods look from general to particular, and + override any found feature. + + - Previously a feature could not be applied to constructors + or destructors that weren't explicitly declared in the class. + This is now fixed, for example: + + %feature("featurename") Foo() "..." + %feature("featurename") ~Foo() "..." + class Foo { + // implicit Foo() and ~Foo() + }; + + - Fix missing features for default const/dest, by really + 'creating' the methods and applying the features. + + - Fix return_const_value.i case by adding SwigValueWrapper + specialization. + + - Fix %extend + overload, including overloading actual + class methods. + + - Adding more cases in related files in the test-suite. + +10/04/2004: wsfulton + Changes to the way default arguments are wrapped. Previously a single + method was generated for each method that had default arguments. If + a method had 5 arguments, say, of which 1 had a default argument + then the call to the wrapped method would pass 5 arguments. The default + value was copied into the wrapper method and used if the scripting + language passed just 4 arguments. However, this was flawed as the + default argument sometimes does not have global access, for example + SWIG would generate code that couldn't compile when wrapping: + + class Tricky { + public: + void foo(int val = privatevalue); + void bar(int val = Tricky::getDefault()); + private: + static int getDefault(); + enum { privatevalue = 200 }; + }; + + Also bugs in resolving symbols generated code that wouldn't compile, for example + (probably fixable though): + + namespace Space { + class Klass { + }; + Klass constructorcall(const Klass& k = Klass()); + } + + The approach also does not work for statically typed languages (C# and Java) + as these languages do not allow methods to have variable number of arguments. + Although C# has a mechanism to pass a variable number of arguments they + must be of the same type and are more like varargs. + + The new approach solves the above problems and wraps methods with default + arguments as if the method was overloaded. So SWIG will now treat + + void foo(int val=0); + + as if it had parsed: + + void foo(int); + void foo(); + + The code generated is then exactly the same as if SWIG had parsed the two + overloaded methods. The scripting languages count the arguments passed and call + the appropriate method, just like overloaded methods. C# and Java are now able + to properly wrap methods with default arguments by generating extra methods, + again as if the method was overloaded, so for: + + void bar(string s="hello", double d=10.0, int i=0); + + the following proxy methods are generated: + + void bar(string s, double d, int i); + void bar(string s, double d); + void bar(string s); + void bar(); + + The new approach comes with a couple of minor knock on effects. + + 1) SWIG support for default arguments for C (not C++) code no longer works. + Previously you could have this interface: + + %{ + void foo(int val); + %} + void foo(int val=0); + + and call the wrapped method from a scripting language and pass no arguments + whereupon the default of 0 was used. You can get the same behaviour for C + code by using the "default" typemap: + + %typemap(default) int val "$1 = 0;"; + %{ + void foo(int val); + %} + void foo(int val); + + or you could of course compile your code as C++ if you want C++ features :) : + + %{ + void foo(int val=0); + %} + void foo(int val=0); + + A couple of SWIG's libraries used this C extension and these have been modified + to use the "default" typemap. The "default" typemap is thus unchanged (and still + is not and is not fully supported by C# and Java, and is likely to remain so). + + + 2) All features (%feature, %rename, %ignore etc) no longer work as if the method + with default arguments is just one method. For example, previously + + %ignore foo(int); + + would have ignored the method completely. Now it will only ignore foo(int) but + not the extra foo() method. Instead use: + + %ignore foo; + + to ignore them all. or + + %ignore foo(int); + %ignore foo(); + + This of course allows one to fine tune the wrapping, for example one could use: + + %rename(fooint) foo(int); + %rename(foodefaults) foo(); + void foo(int val=0); + + and call them from any language like so: + + fooint(200) + foodefaults() + + or for example ignore the extra overloaded method, so the defaults cannot be used: + + %ignore foo(); + void foo(int val=0); + + *** POTENTIAL INCOMPATIBILITY *** + +10/2/2004: mmatus + [Python] + - More cleaning up and uniformation on the Python Lib + + - Added Robin's docstring patch, plus some fixes, plus + some extensions, see autodoc.i example in the test-suite, + and try using %feature("autodoc","extended"). + + This patch is not a complete solution for the + documentation problem, just enough to inform python about + the parameter list. + + The expected swig documentation support is far far away yet. + + +10/1/2004: mmatus + - Fix the %callback feature (only used in ruby and python examples, + by now, but it should be generic), now member callbacks + are working again + + - Fix wrapping of functions pointers like + + std::ostream& std::endl(std::ostream&); + + ie, the ones that return references or enums. + + [Python] Add the %pythoncallback directive, which is + an improved version of %callback, ie, + + %pythoncallback(1) foo; + %pythoncallback(1) A::bar; + %pythoncallback(1) A::barm; + + int foo(int a) { + return a; + } + + struct A + { + static int bar(int a); + int barm(int a); + + }; + + int foobar(int a, int (*pf)(int a)); + + in python you can use + + foo(2) + foobar(2,foo) + A.bar(2) + foobar(2,A.bar) + + ie, no additional pointer elements are created, and + the original 'foo' and 'A.bar' can be used as parameters. + + In the case of member fucntion however, still you need + to use the special variable Class::_cb_ptr, ie: + + foobarm(3, a, A.barm_cb_ptr) + + we will try to fix this situation also, but later. + + [Python] Add more elements from the STL library, now + you can use + + import std + std.cout << "hello " << 123 << std.endl + + [Python] Fix in/out return mechanism, now swig will behave + as 1.3.21 but using a python list when needed. The problem + is that the types std::pair,std::vector,etc, use tuples, + and they interfer with the previous inout tuple type. + + By using lists we solve the conflicts, swig acts as before, + but returns a list when more than one parameter are using + the OUT typemap. See the new inout.i example in the + test-suite. + + *** POTENTIAL INCOMPATIBILITY FOR PYTHON MODULE *** + + [Python] Much better error messages for bad arguments, now + you always get the argument number where the error occurred. + +09/27/2004: wsfulton + Patch from Bill Clarke - + 1) Warning emitted when -importall and -includeall is used together, + with -includeall taking precedence. + 2) Ensure SWIGIMPORTED is always defined when a file is being + imported with %import. Note that this is not the same as SWIGIMPORT, + which gets defined in all generated wrapper files. + +09/26/2004: mmatus + + - add %feature("exceptionclass") to identify a class used + as exception. Before swig identified and marked a class + using the "cplus:exceptionclass" attribute. However, the + class needed to appear on an throw() statement. Now + swig keeps trying to identify the exception classes, as + before, but it also allows the user to mark a class by + using the %feature explicitly. (mostly relevant for + python and chicken) + + [Python] + + - fix -modern option + exceptions, which mix old class + style with the new one. So, we always need to emit + the "nonmodern" python code. + + - add the "python:nondynamic" feature and its handler + + now if you have + + %pythonnondynamic(1) A; + + struct A { + int a; + int b; + }; + + then, in the python side + + aa = A() + + aa.a = 1 # ok + aa.b = 2 # ok + aa.c = 3 # error, the class can not be extended dynamically. + + + Since this is a feature, you can use + + %pythonnondynamic(1); + + or + + %pythondynamic(0); [ Note: %pythondynamic since deprecated ] + + to force all the wrapped classes to be "nondynamic" ones. + + The default, as in regular python, is that all the wrapped + classes are dynamics. So, careful with your spelling. + +09/14/2004: mmatus + - Support the -I- option. + + - Differentiate between %include and %include "file". + This fix several corner cases. + + + [Python] Several patches: + + - Normalize the Lib file names: + *.swg internal files, + *.i user files. + + - Fix Char[ANY] typemaps, so they also delete any extra '\0' chars, + now they behave as before (1.3.21). Still, you can use + the SWIG_PRESERVE_CARRAY_SIZE macro if you need to + preserve the original size (see pystrbase.swg). + + - Add the Char FIXSIZE[ANY] typemaps, to preserve the + original C array sizes (see above). Though, you can't + use them yet since %apply and arrays are not working + together. + + - Add pyfragments.swg, now the user can add fragments + to override the default ones. + +09/10/2004: wsfulton + Patch from Bill Clarke which fixes spurious preprocessor bug which + shows on Solaris and gcc, eg: + Warning(202): Could not evaluate '!defined(SWIGJAVA) && + !(defined(SWIGCSHARP)' + Also fixes a bug where '#if "a" == "b" == 1' wouldn't have worked + +09/10/2004: wsfulton + Restored multiple build directories for the test-suite. Patch from + Bill Clarke. + +09/06/2004: wsfulton + Added the missing runtime.dsp Visual Studio project files for the + import examples to work. + + +Version 1.3.22 (September 4, 2004) +================================== + +09/03/2004: wsfulton + The swig.m4 macro for use with the Autoconf/Automake/Libtool has + been removed and is no longer installed. Please use the new and better + maintained version derived from swig.m4 in the Autoconf macro archive. + See http://www.gnu.org/software/ac-archive/htmldoc/ac_pkg_swig.html and + http://www.gnu.org/software/ac-archive/htmldoc/ac_python_devel.html. + +09/01/2004: wsfulton + [Perl] Applied patch #1019669 from Christoph Flamm. Adds support + for %feature("shadow") in the same way as it works in Python. This + enables one to override the generated shadow/proxy methods, including + constructors and destructors. For example: + + /* Let's make the constructor of the class Square more verbose */ + + %feature("shadow") Square(double w) + %{ + sub new { + my $pkg = shift; + my $self = examplec::new_Square(@_); + print STDERR "Constructed an @{[ref($self)]}\n"; + bless $self, $pkg if defined($self); + } + %} + + class Square { + public: + Square(double w); + ... + }; + +08/31/2004: mmatus + [Python] Incompatibility reported by Bill Clarke (llib@computer.org): + + If you are using Sun Studio 8 (and possibly earlier + versions) to compile the output produced by swig + 1.3.22rc1, and you are using C++ and STL templates then + you need to use either "-runtime" or "-noruntime". If you + use neither of these options then you will probably get + compiler errors when trying to compile the wrapper file; + the error message will be like this: The name + SWIG_Python_ConvertPtr[...] is unusable in static + swigpy::traits_asptr[...] If you get this error message, + you need to regenerate your wrapper file using 'swig + -runtime' or 'swig -noruntime'. + + You shouldn't get this problem with Sun Studio 9. + + *** POTENTIAL INCOMPATIBILITY FOR PYTHON MODULE *** + +08/26/2004: wsfulton + [Perl] Applied #932333 from Ikegami Tsutomu. Fixes long long *OUTPUT + and unsigned long long *OUTPUT typemaps in typemaps.i. + +08/26/2004: wsfulton + Applied patch #857344 from Art Yerkes. Workaround for autoconf bug when + running 'make install'. + +08/26/2004: wsfulton + [Perl] Part of patch #982753 applied. This implements a %perlcode directive. + It allows one to add Perl code to the generated .pm file. Works the same + as %pythoncode. + +08/26/2004: wsfulton + [Java] Fix for directors when wrapping virtual methods with exception + specifications that were not simple types. Previously code was generated that + didn't compile, for example when the exception specification was a pointer. + +08/25/2004: wsfulton + [C#] Typemap fix for methods that return char *. The CLR would incorrectly + delete the memory pointed to by char *. Also applied the same correction to + the char array typemaps. + +08/24/2004: wsfulton + Fixes for -fmicrosoft error/warning message display: + - End of file (EOF) warning messages not displaying in correct format + - Some messages containing a file path were displaying a double backslash + instead of a single backslash + +08/23/2004: wsfulton + Applied patch #1011604 submitted by Charles Schwieters. Fix for 64 bit tcl + interpreters. + +08/23/2004: wsfulton + Fix for bug #875583 - enum forward declarations previously gave a syntax error. + +08/23/2004: mkoeppe + [Allegro CL] Use typemaps "ffitype" and "lisptype" to determine the FFI type + specifiers from the C type. This makes it possible, for instance, to control + whether a C "char" argument takes a Lisp character or a Lisp integer value. + The default (taking Lisp characters) is done by these built-in typemaps: + %typemap(ffitype) char ":char"; %typemap(lisptype) char "character"; + If char means an integer instead, use these typemaps: + %typemap(ffitype) char ":char"; %typemap(lisptype) char "integer"; + +08/22/2004: wsfulton + As discussed in bug #772453, the SWIG library directory is now installed + into a different default directory. The library used to be installed to + /usr/local/lib/swig1.3. It is now in the more usual architecture independent + directory and I have additionally used a version specific subdirectory as + the library will rarely work with older versions of SWIG. This release + will thus use /usr/local/share/swig/1.3.22 by default, which can be + tailored as before using './configure --swiglibdir'. + +08/17/2004: mkoeppe + [MzScheme] Add support to create native MzScheme structures from C structures. + To convert a C structure to an MzScheme structure, use the new runtime macro + SWIG_NewStructFromPtr in a typemap. Patch from Dmitriy Zavin. + +08/12/2004: wsfulton + Patch #837715 from Ben Reser to correctly detect Python lib directory + on 64 bit systems. + +08/12/2004: wsfulton + [C# and Java] Prevent memory leaks in the case of early return + from wrapper methods using const std::string & parameters. Modified + Mark Traudt patch #951565. + +08/12/2004: wsfulton + Bug #943783 with patch fixes php char * out typemap NULL values. + +08/03/2004: Ahmon Dancy + + [allegrocl] Additional case mode fixes. Also, make sure + foreign types are exported. + +07/24/2004: mkoeppe + [Guile] In -scm mode, SWIG modules now exchange their pointer type + information via the Guile interpreter. It is no longer necessary to build a + runtime library or to use -noruntime and -runtime etc. + + The module (Swig swigrun) which was introduced in the change of 05/17/2004 is + no longer automatically built. If you need it, run SWIG on the interface file + swigrun.i. + +07/23/2004: wsfulton + [C#] Bug #917601 Mapping C++ bool fix from Mark Traudt + +07/23/2004: wsfulton + RPM fixes for latest CVS version including removal of runtime + library. + +07/23/2004: wsfulton + Patch #908955 from Robert H De Vries. + RPM file generation fix for Fedore Core 1 and Redhat AS2.1. + +07/12/2004: wsfulton + Patch #864689 from Robin Dunn: + + This patch corrects two problems in the XML output of SWIG: + + 1. There were often extra '/>\n' in the output. + + 2. value attributes were output with '\n' in them but + since that is not technically legal most (all?) XML + parsers will strip them out. Replacing the '\n' with + the ' ' entity reference solves this as that is + legal and XML parsers will convert it to a '\n' when + reading the values back in. + + This patch also adds a new global command line option + that will allow the parse tree to be written out in XML + *after* some other language module has been run, in + order to be able to get extra info that the language + module puts in the tree. In this way the XML is a + post-processed version of the tree rather than a + pre-processed version. + + Command line option is -dump_xml or -xmlout + +07/12/2004: wsfulton + [Java] Patch from Scott Michel to fix typesafe enums and proper enums + with directors. + +07/12/2004: wsfulton + HTML documentation (makechap.py) file generator missing end of line + patch #908951 from Robert de Vries. + +07/08/2004: wsfulton + The deprecated runtime library build has been removed. This also removes + the dependency on Libtool. Libtool is no longer required to build SWIG. + The associated -ldflags SWIG commandline option has also been removed. + + The examples and test-suite testcases that used the runtime library have + been updated to use the replacement approach to using SWIG across + multiple modules, that is they use the -noruntime and -runtime commandline + options, see Modules.html. Effectively they build their own runtime + libraries using -runtime. The examples are import and import_template. + The test cases are in the imports and template_typedef_import directories. + + Anyone who wants the original runtime libraries can either run the test-suite + or build the examples and use the appropriate shared object/DLL that is + generated with the -runtime commandline option. For example libimports_runtime.so + (Python calls it lib_imports_runtime.so) is generated after running the + 'make imports.multicpptest' testcase in the Examples/test-suite/ + directory. Or use libruntime.so / runtime.dll after building the import + examples in Examples//import. + +07/07/2004: mkoeppe + [Allegro CL] Convert character and string literals in constants to + CL syntax. Fix FF:DEF-FOREIGN-CALL for mixed-case C functions. + +06/27/2004: wsfulton + [Java] New feature for Java exceptions with format %javaexception(exceptionclasses). + This feature is a slight enhancement to %exception and the only difference is the + addition of the exception classes which are generated into a throws clause. + The 'exceptionclasses' is a comma separated list of classes which will be + added to the associated proxy method's throws clause. The 'exceptionclasses' + are specified like the exception classes in the 'throws' attribute in the + typemaps. This feature should be used for correctly handling checked exceptions + thrown from JNI code. For example: + + %javaexception("java.lang.Exception") throwException %{ + ... convert a std::logic_error into a java.lang.Exception using JNI code ... + %} + + #include + void throwException() { + throw std::logic_error("Logic error!"); + } + + will generate a method with a throws clause in the module class: + + public static void throwException() throws java.lang.Exception { ... } + +06/27/2004: wsfulton + [C#] New %csconstvalue(value) feature directive for use with constants and + enums. This works the same way as %javaconstvalue. For C#, this directive + is the only way that one can fix wrapping of C/C++ enums with proper C# + enums if the enum item's initialiser cannot compile as C# code. This is + because Java enums can use a call into C code to initialise the enum item, + whereas in C#, the enum value must be a compile time constant. That is, + using %csconst(0) cannot be used in C# to initialise the C# enum item via + a PINVOKE call. + +06/27/2004: wsfulton + [Java] New %javaconstvalue(value) feature directive for use with constants and + enums. Sometimes the use of %javaconst(1) will produce code that won't compile + under Java. If a compile time constant is required, %javaconst(0) is not an + option. The %javaconstvalue directive achieves this goal and the value specified + is generated as Java code to initialise the constant. For example: + + %javaconst(1); + %javaconstvalue(1000) BIG; + %javaconstvalue("new java.math.BigInteger(\"2000\")") LARGE; + %javaconstvalue(10) bar; + %{ + const int bar = 10; + %} + %inline %{ + #define BIG 1000LL + #define LARGE 2000ULL + enum Foo { BAR = ::bar }; + %} + + Generates: + + public interface exampleConstants { + public final static long BIG = 1000; + public final static java.math.BigInteger LARGE = new java.math.BigInteger("2000"); + } + public final class Foo { + public final static Foo BAR = new Foo("BAR", 10); + ... + } + + Previously, none of BIG, LARGE or BAR would have produced compileable code + when using %javaconst(1). + +06/27/2004: wsfulton + %feature enhancements. Features can now take an unlimited number of attributes + in addition to the feature name and feature value. The attributes are optional + and are much the same as the typemap attributes. For example, the following + specifies two optional attributes, attrib1 and attrib2: + + %feature(featurename, attrib1="attribval1", attrib2="attribval2") name "val"; + %feature(featurename, val, attrib1="attribval1", attrib2="attribval2") name; + +06/27/2004: wsfulton + %feature improvements for the syntax that takes the feature value within the + %feature() brackets. The value specified is no longer restricted to being just + a string. It can be a string or a number. For example, this is now acceptable + syntax: + %feature("featurename",20.0); + whereas previously it would have to have been: + %feature("featurename","20.0"); + Useful for features that are implemented as a macro, for example: + #define %somefeature(value) %feature("somefeature",value) + These will now work accepting either a string or a number: + %somefeature("Fred"); + %somefeature(4); + +06/06/2004: wuzzeb (John Lenz) + [Chicken, Guile] + - Created the Examples/test-suite/schemerunme directory, which holds all the + runme scripts for guile and chicken (and possibly mzscheme...). The guile + and chicken _runme files then (load "../schemerunme/foo.scm"). + - In chicken module, fix a few bugs invlolving dynamic casts. + +06/03/2004: wsfulton + Patch to fix wrapping of templated methods. ISO compliant compilers, like + Comeau and GCC-3.4.0, don't like the template specifier that SWIG was generating + when calling the method. This fix may break some non standard compliant compilers, + for example, Sun workshop compilers prior to version 6.2.p2. Patch submitted + by Bill Clarke. + +06/03/2004: wsfulton + [Java, C#] Undocumented special variable $imclassname removed. + New special variable $module is replaced by the module name, as specified + by %module or -module commandline option. $imclassname can be created from $module. + +06/03/2004: wsfulton + [C#] Same as for Java below. The new typemaps are named differently, namely, + csbody and csbody_derived. The deprecated typemaps are csgetcptr and + csptrconstructormodifiers. + + *** POTENTIAL INCOMPATIBILITY FOR C# MODULE *** + +06/03/2004: wsfulton + [Java] Typemap changes for the Java proxy / typewrapper and enum classes. A new + typemap called javabody contains the essential support code for generation into the body + of these classes. There is also a new javabody_derived typemap which is used instead for + wrapped classes that have a wrapped base class. The code is basically, the getCPtr() + method and swigCPtr and swigCMemOwn member variables. These used to be hard coded + with no way to modify the code. The introduction of this typemap makes it possible for + the user to tailor nearly every aspect of the code generation. + The exception now is the code for director classes. + + The javagetcptr and javaptrconstructormodifiers typemaps are deprecated and are + no longer used as the code that these generated can be put in the more flexible + javabody and javabody_derived typemaps. + + *** POTENTIAL INCOMPATIBILITY FOR JAVA MODULE *** + + The following macros contributed by Scott Michel may help you upgrade if you have used + the javagetcptr typemap: + + /* Utility macro for manipulating the Java body code method attributes */ + %define SWIGJAVA_ATTRIBS(TYPENAME, CTOR_ATTRIB, GETCPTR_ATTRIB) + %typemap(javabody) TYPENAME %{ + private long swigCPtr; + protected boolean swigCMemOwn; + + CTOR_ATTRIB $javaclassname(long cPtr, boolean cMemoryOwn) { + swigCMemOwn = cMemoryOwn; + swigCPtr = cPtr; + } + + GETCPTR_ATTRIB static long getCPtr($javaclassname obj) { + return (obj == null) ? 0 : obj.swigCPtr; + } + %} + + %typemap(javabody_derived) TYPENAME %{ + private long swigCPtr; + + CTOR_ATTRIB $javaclassname(long cPtr, boolean cMemoryOwn) { + super($moduleJNI.SWIG$javaclassnameUpcast(cPtr), cMemoryOwn); + swigCPtr = cPtr; + } + + GETCPTR_ATTRIB static long getCPtr($javaclassname obj) { + return (obj == null) ? 0 : obj.swigCPtr; + } + %} + %enddef + + /* The default is protected getCPtr, protected constructor */ + SWIGJAVA_ATTRIBS(SWIGTYPE, protected, protected) + + /* Public getCPtr method, protected constructor */ + %define PUBLIC_GETCPTR(TYPENAME) + SWIGJAVA_ATTRIBS(TYPENAME, protected, public) + %enddef + + /* Public getCPtr method, public constructor */ + %define PUBLIC_BODYMETHODS(TYPENAME) + SWIGJAVA_ATTRIBS(TYPENAME, public, public) + %enddef + +06/03/2004: wsfulton + [Java, C#] The contents of the class modifier typemaps and pragmas have changed. + They must now include the class type. Previously 'class' was hard coded. + This change enables flexibility into what type of class is generated, + for example the proxy class could be an interface instead of a class. + + For Java this affects the javaclassmodifiers typemap and the jniclassclassmodifiers + and moduleclassmodifiers pragmas. + + For C# this affects the csclassmodifiers typemap and the imclassclassmodifiers + and moduleclassmodifiers pragmas. + + Unless you have overridden the default versions of these typemaps or pragmas, you + shouldn't be affected. However, if you have, upgrading is easy, for example + + class Foo {}; + %typemap(javaclassmodifiers) Foo "public final" + + must now be: + + class Foo {}; + %typemap(javaclassmodifiers) Foo "public final class" + + + *** POTENTIAL INCOMPATIBILITY FOR C# MODULE *** + *** POTENTIAL INCOMPATIBILITY FOR JAVA MODULE *** + +05/31/2004: wsfulton + Fix for C++ exception specifications that are references. Problem reported by + Oren Miller. Also improves the generated exception declarations in the + catch handler for pointers - a pointer is used instead of a reference to + a pointer. Added default throws typemaps for SWIGTYPE &, SWIGTYPE * and + SWIGTYPE[ANY] (Java and C#). + +05/31/2004: wsfulton + [Java, C#] Some minor typesafe enum improvements, including storing the name of + the enum item. The toSring() / ToString() methods are overridden to return this name. + +05/30/2004: wuzzeb (John Lenz) + [Chicken] + - Update how examples and the test suite are built. + - Symbol names are no longer converted to lower case + - Added union_runme.ss, which was copied and modified from the guile module + +05/26/2004: lballabio (Luigi Ballabio) + Committed on behalf of Marcelo (who still has problems with + the SourceForge CVS.) + + Added Python typemaps for FILE* with (Python-only) test. + +5/24/2004: dancy + + * Allegro CL module: Now using some macros (defined in + Lib/allegrocl/allegrocl.swg), swig-defconstant and swig-defun, for + defining constants and foreign functions. This makes the + generated file a bit neater. + + Now strips a layer of parenthesis from constants. + + Uses (* :void) instead of :foreign-address now. + +05/20/2004: wsfulton + Unnamed enum global variables are now supported in addition + to the recently added support for unnamed enum member variables. + For example: + + struct Foo { + enum { enum1, enum2 } MemberInstance; + }; + enum { enum3, enum4 } GlobalInstance; + + The int typemaps are used for wrapping the get/set accessor methods. + If the sizeof an enum is not the same size as an int then setting the + variable will silently do nothing as the casts cannot be easily and portably + generated. If you need to solve this highly obscure situation, write + the assignment using the %exception feature. + +05/20/2004: wsfulton + [C#] C# enum wrapping mods. Similar to the Java module, enums can be wrapped using + one of 3 approaches: + + 1) Proper C# enums - use %include "enums.swg" + 2) Typesafe enums - use %include "enumtypesafe.swg" + 3) Simple constant integers (original approach) - use %include "enumsimple.swg" + + See each of these files for further details. Each of these files use typemaps + and a new feature to control the generated code. The feature is: + + %csenum(wrapapproach); + + where wrapapproach should be one of: "proper", "typesafe", "typeunsafe" or "simple". + [No implementation deemed necessary for type unsafe enums]. + + The default approach is proper C# enums. Anonymous enums are always wrapped by + constant integers. + + *** POTENTIAL INCOMPATIBILITY FOR C# MODULE *** + +05/20/2004: wsfulton + [Java] Java enum support added. There are now 4 ways in which enums can be wrapped: + + 1) Proper Java enums - use %include "enums.swg" + 2) Typesafe enums - use %include "enumtypesafe.swg" + 3) Type unsafe enums (constant integers) - use %include "enumtypeunsafe.swg" + 4) Simple constant integers (original approach) - use %include "enumsimple.swg" + + See each of these files for further details. Each of these files use typemaps + and a new feature to control the generated code. The feature is: + + %javaenum(wrapapproach); + + where wrapapproach should be one of: "proper", "typesafe", "typeunsafe" or "simple". + The default typemaps will handle enums that may or may not have specified initial + values, for example ten is specified: + + enum Numbers { zero, ten(10) }; + + However, the amount of generated Java code can be cut down, by modifying these typemaps + if none of the enums have initial values (proper Java enums and typesafe enums approach). + + The default approach is typesafe enums. Anonymous enums are always wrapped by + constant integers. + + *** POTENTIAL INCOMPATIBILITY FOR JAVA MODULE *** + +05/11/2004: wsfulton + [Java, C#] Fix bug using %rename on enum items and when using + %javaconst(1) / %csconst(1) + For example, the following used to generate code that wouldn't compile: + + %rename(Obj) Object; + enum Grammar { Subject, Object }; + +04/28/2004: wsfulton + [Java, C#] Minor fixes when using combinations of the + javainterfaces, javabase, csinterfaces and csbase typemaps. + +05/18/2004: wsfulton + [Java] JVM link failure on some systems fixed when using std_vector.i. + Also adds default vector constructor for use from Java. + +05/17/2004: mkoeppe (Matthias Koeppe) + + [Guile] New runtime functions SWIG_PointerAddress, + SWIG_PointerType, SWIG_IsPointerOfType, SWIG_IsPointer. + + [Guile] In -scm mode, wrap several SWIG runtime functions + and export them into the module (Swig swigrun). The + runtime module is now built with "module" linkage. + + [Guile] GOOPS proxy objects now also print the pointer + address of the C object. + +05/14/2004: lyle + Added Kou's patch for the Ruby %import directive so that modules + with "nested" names are handled properly. Consider an interface + file foo.i that has this %module declaration at its top: + + %module "misc::text::foo" + + Now consider another interface file spam.i that imports foo.i: + + %import foo.i + + Before this patch, this would result in the following code being + generated for spam_wrap.c: + + rb_require("misc::text::foo"); + + With this patch, however, you'll get the correct path name + for the call to rb_require(), e.g. + + rb_require("misc/text/foo"); + + See SourceForge Bug #928299. + +05/12/2004: wsfulton + Patch for emitting directors when %feature("director") specified + for a class with no virtual methods, but does have a virtual destructor. + Submitted by Kevin Smith. + +05/06/2004: mkoeppe (Matthias Koeppe) + New SWIG runtime function SWIG_TypePrettyName, which + returns an unmangled type name for a swig_type_info + object. + + [Guile]: Use it for printing pointer objects. + +05/03/2004: dancy (Ahmon Dancy) + + * Lib/allegrocl/allegrocl.swg: Updated comments about identifer + conversion. + + * Sources/Modules/allegrocl.cxx: Register /dev/null for "header" + target. Also, disregard "const" qualifiers during type + conversion. + + +05/02/2004: wuzzeb (John Lenz) + [Chicken] Fix bug 782468. + To fix this bug, the runtime code has been rewritten, and + pointers are now represented as a C_SWIG_POINTER_TYPE. + + Chicken version > 1.40 is now required! + + * Typemap incompatibility: typemaps no longer use chicken_words. + If a typemap needs some space, it should just call C_alloc + + * argout typemaps no longer use the /* if ONE */ construct to + build an output list. A SWIG_APPEND_VALUE macro, exactly like + guile and mzscheme is now used. + +04/25/2004: mkoeppe (Matthias Koeppe) + [Guile] In the generated GOOPS code, don't create methods + that would not specialize any arguments; simply re-export + the primitive functions. (This is a performance + optimization which reduces load time and execution time.) + + [Guile] In -gh mode, fix the "too many initializers" error + which was caused by an incompatible swig_type_info layout. + + [Guile] The typemap for FILE * in ports.i now also accepts + a regular FILE * pointer object. Also a bug with Scheme + file ports that are open for input and output has been + fixed. + +04/25/2004: wsfulton + Change entry 03/21/2004 revoked. The change introduced another + inconsistency (reference typemaps beings used instead of + pointer typemaps for member variables as well as static + member variables and global variables for some languages, + but only for C++ and not C). This would break user's current + typemaps and introduce further inconsistencies. Alternative + solution required and being discussed. + +04/10/2004: mmatus (Marcelo Matus) + + Added the -directors flag. This enables the director + mode for the interface and all the classes that + don't set the "feature:nodirector" explicitly. + + You can use this in your module if you want to use the + director feature in all your classes, but it is most + intended for testing purposes, like: + + make check-python-test-suite SWIG="../../../swig -directors" + make check-ruby-test-suite SWIG="../../../swig -directors" + make check-java-test-suite SWIG="../../../../swig -directors" + + These commands will run the entire test-suite using + directors, and not only the specific 'directors_*' + cases. This should be done from time to time. + +04/10/2004: mmatus (Marcelo Matus) + + [python] Added support for std::wstring and wchar_t, + for compiler and python versions that support them. + + When needed, use + + %inlcude std_string.i // 'char' strings + %inlcude std_wstring.i // 'wchar_t; strings + + +04/10/2004: mmatus (Marcelo Matus) + + [python] Fix the default behaviour (seg. fault) when an + inplace operator (+=,-=,...) was wrapped, as reported by + Lucriz (lucriz@sitilandia.it), when the most common + form was used: + + A& A::operator+=(int i) { ...; return *this; } + ^^^^ ^^^^^^ + + + ie, an object is returned and its contains the same 'this' + value than the input object, which is deleted after the + operation "a += b", leaving the result with no real + object, but a seg. fault. + + To fix it, we needed to introduce a new feature and use an + old one: + + %feature("self:disown") A::operator+=; + %feature("new") A::operator+=; + + here, "self:disown" disable the ownership of the 'self' + or input object, and the "new" feature transfers the + ownership to the result object. + + The feature/solution could also be used in other languages + that use gc and implement the inplace operators, or other + operators, in a similar way. + + *** POTENTIAL INCOMPATIBILITY FOR Python MODULE *** + + If you already are using the inplace operators in python, + and you implemented some kind of workaround to the problem + fixed here, it is possible you could end with 'free' + objects that never get deleted. If that is the case, and + you want to disable the current fix, use: + + %feature("self:disown","") A::operator+=; + %feature("new","") A::operator+=; + + +04/07/2004: cheetah (William Fulton) + [C#] C++ enums are no longer wrapped by integers, they are now wrapped by + C# enums. For Example, given C++: + + enum AnEnum { foo, bar }; + typedef AnEnum AnEnumeration; + void something(AnEnum e, AnEnumeration f); + + The following is generated: + + public enum AnEnum { + foo, + bar + } + public static void something(AnEnum e, AnEnum f) {...} + + Note that a global enum like AnEnum above is generated into its own + file called AnEnum.cs. Enums defined within a C++ class are defined + within the C# proxy class. Some of the typemaps for modifying C# proxy + classes also work for enums. For example global enums can use + + %typemap(csimports) to add in extra using statements. + + Global enums and class enums can use + + %typemap(csclassmodifiers) to make the enum private, public etc. + %typemap(csbase) to change the underlying enum type (enum base) + + If we add this for the above example: + + %typemap(csclassmodifiers) AnEnum "protected" + %typemap(csbase) AnEnum "long" + + the following is generated: + + protected enum AnEnum : long { + foo, + bar + } + + *** POTENTIAL INCOMPATIBILITY FOR C# MODULE *** + +04/07/2004: cheetah (William Fulton) + Seg fault fix for empty enums, like + enum Foo {}; + +03/21/2004: mmatus + [Note: this change revoked on 04/25/2004] + [Python] Makes the following 'var' cases more uniform: + + std::string ga; + + struct A { + static std::string sa; + std::string ma; + }; + + + now the three variables (ga, sa, ma) can be assigned as: + + + cvar.ga = "hello"; + A.sa = "hello"; + a.ma = "hello"; + + ie, now 'ma' will also use a std::string typemap 'in' if + defined, before it was only accepting a 'p_std_string' + pointer. Note, however, that 'ma' will not use the + 'varin/varout' typemaps (that probably could be more + natural), but it will pick up the 'in' typemap for const + std::string& (which is easier). + + The changes in cwrap.c and lang.cxx will probably fix the + behaviour in other languages that do not overload the + membervarHandler method "too much". + + +03/21/2004: mmatus + [Python] Disabling the default instantiations like: + + %template() std::pair; + + for all the primitive types and STL containers/classes. + They are expensive, specially for pair and map, and the + previous behaviour also requires the user to perform + manual instantiations. Still, if the speed difference is + not important, it can be re-enabled by defining the macro + SWIG_STD_DEFAULT_INSTANTIATION (see std_common.i). + + Also, normalizing the INPUT/OUTPUT/INOUT typemaps. Now + they use the same conversors than the rest of the + typemaps, and you can use them for std::pair, std::string + and all the other STL types, like in: + + void p_inoutd(std::pair *INOUT); + + Added the attribute.i and implicit.i files with macros to + transform functions pairs like 'set_x'/'get_x' + (or 'T& x()'/'const T& x() const') into an attribute, + and allowing the use of implicit constructors in typemaps + (see the files for more details). + +03/21/2004: mkoeppe + [Guile] Fix the documentation strings of functions with + anonymous arguments. + +03/18/2004: mmatus + [Python] More general std_string.i interface. + Now you can wrap it using + + %template(string) std::basic_string; + + and use the std::string as a base class: + + struct A : std::string { + }; + + But more important, swig will recognize + both std::basic_string and std::string as + the same type. + +03/16/2004: mmatus + Previously added, but not mentioned before: + + - friend declaration support, swig now emits a global + function in the same class scope. + + - ref/unref features: to mix ref counting C++ classes + and native script ref counting mechanisms (like in python). + + Use it like: + + %feature("ref") RCObj "$this->ref();" + %feature("unref") RCObj "$this->unref();" + + And the class RCObj, and all the derived ones, will + perform the right ref/unref calls when a new pointer + is returned to the target language, or when the target + language attempts to delete the object. + + See the refcount.i file in the test-suite for more + details. + + +03/16/2004: mmatus + [Python] Using the new %fragment support, major rewrote + of the python swig library, including: + + - Almost automatic template/typemap instantiation for + the STL components. For example, now you can write: + + %template(vector_i) std::vector; + + and a specialized vector_i class is emitted with all + the needed typemaps. No need to use the old + 'specialize_vector' macros. + + Note you can also define + + %template(matrix_i) std::vector >; + %template(vector_pii) std::vector >; + + - The empty template instantiation + + %template() std::vector; + + defines the vector typemaps, but no proxy class. For all the + fundamental types, the empty template instantiation are + defined, so, you can say + + %include std_vector + + int func(const std::vector& a); + + where the proper typemap is applied to 'a', but no + std::vector proxy is generated. + + + - All the STL containers present a more uniform behavior and + more complete interface declaration. The following are + now supported: + + std::vector + std::list + std::deque + std::set + std::multiset + std::map + std::multimap + + not a container, but also supported: + + std::pair + + also, more typemaps are defined for all of them, + including varin, varout, typecheck, etc. + + - Initial attempt to implement the STL containers + considering allocators, ie: + + std::vector + + it is partially working, but it is just a workaround + while swig improves its template type support. + + + Please test with your particular setup. It seems to be + working with g++ 3.2.2, g++ 2.96, Intel icc and SGI CC + compilers, plus python 1.5.2, 2.0 and 2.3, but since + we are using templates, there is a chance you can find + some problems when using with an old C++ compiler. + +03/16/2004: mmatus + + - Allowing the empty %template directive, such as + + %template() std::vector; + + to process the class "typedef"s and "typemap"s. Before + only the internal "typedef"s were processed. + + This makes possible to emit the default in/out + typemaps without the need of wrapping an specialized + vector instance. + + - Adding the preprocessor extension #@ which mangles the + following macro argument, like in: + + #define macro(X) #@X + macro(int) -> int + macro(std::string) -> std_s_s_string + + - Fragments can now be "type specialized", as the typemaps. The + syntax is as follows + + %fragment("name","header") + { /* a type independent fragment (old syntax) */ } + %fragment("name" {Type}, "header") + { /* the fragment is type dependent */} + + Now fragments can also be used inside templates: + + template + struct A { + %fragment("incode"{A},"header") { + /* 'incode' specialized fragment */ + } + + %typemap(in,fragment="incode"{A}) { + /* + here we use the 'type specialized' + fragment "incode"{A} + */ + } + }; + + +03/11/2004: cheetah (William Fulton) + [Java] Director bug which meant that some virtual functions overridden in + Java were not being called on some operating systems. Bug reported and fixed + by Robert de Vries and Scott Michel. + +03/02/2004: mkoeppe (Matthias Koeppe) + [Guile] In -scm mode, don't forget to check the type of string arguments. + +02/24/2004: cheetah (William Fulton) + [C#] New commandline option -namespace . This allows one to specify + a C# namespace into which all C# classes are generated. + +02/23/2004: mkoeppe (Matthias Koeppe) + [MzScheme] Use FUNC_NAME rather than a bogus typemap variable for signalling + errors. Call scheme_wrong_type with a zero-based argument number. + Reported by Ondrej Pacovsky, SF #902621. + + [Guile] Define FUNC_NAME also in the dispatch wrapper for overloaded + functions. Patch by John Lenz, SF #896255. + +02/22/2004: mkoeppe (Matthias Koeppe) + [Guile] In -scm mode, don't try to invoke a null destructor function. + +02/20/2004: cheetah (William Fulton) + Fixes so that the SWIG source will compile using the Digital Mars Compiler + (formerly Symantic compiler) on Windows. Submitted by Scott Michel. + +02/13/2004: mkoeppe (Matthias Koeppe) + [MzScheme] New command-line argument -noinit. Use it for building + the runtime library, where we don't want to define the functions + scheme_initialize etc. Reported by Tim Brown, SF #891754. + + [MzScheme] Don't produce invalid C code when invoked with the + -declaremodule option. Reported by Tim Brown, SF #891108. + + [Guile] Build the runtime library with passive linkage, to rename + the SWIG_init function uniquely. + +02/12/2004: cheetah (William Fulton) + [Java, C#] Patch submitted by Bill Hoffman which prevents SWIG from crashing + when a file for the typewrapper class cannot be opened. + +02/11/2004: cheetah (William Fulton) + [Java, C#] Overloading changes: + - Methods which are overloaded in const only no longer generate Java + code that won't compile - the first method parsed is used and a + warning is displayed. Note that this behaviour is slightly different + to the scripting languages which always uses the non-const method. + - Warning messages 509 and 512 replaced by new warning number 516, which + is more relevant to these statically typed languages as the overloaded + methods aren't 'shadowed', they are ignored. + +01/23/2004: mkoeppe (Matthias Koeppe) + [Guile] Replace the "known_classes" hash table by a node + attribute. Methods of classes in C++ namespaces now get + the proper specializer in the GOOPS declaration. + Reported by rm@mh-freiburg.de. + +01/23/2004: mkoeppe (Matthias Koeppe) + [Guile] Uniquify the argument names in GOOPS shadow method + declarations. Reported by rm@mh-freiburg.de. + +01/21/2004: sunshine (Eric Sunshine) + Revived the NextStep port of SWIG. + + Fixed fatal problem in DohStrstr() caused by difference in strstr() + implementation which made %apply become entirely dysfunctional. On + NextStep, strstr("foo","") evaluates to NULL; whereas, on modern + platforms, it evaluates to "foo". %apply relies extensively upon + strstr("foo","") evaluating to non-NULL, therefore it failed + catastrophically when faced with NextStep's strstr(). + + Added `bool' check to configure.in since NextStep's C++ compiler + does not supply this type. swig.h now fakes up `bool' if needed. + + Worked around NextStep C++ compiler bug in which C++ code is + disallowed inside extern "C" functions. This problem affected all + language modules, since they publish hook functions of the form: + extern "C" Language *swig_foo(void) { return new FOO(); } + Fixed by creating a C++ wrapper: + static Language *new_swig_foo() { return new FOO(); } + extern "C" Language *swig_foo(void) { return new_swig_foo(); } + + Ensured that Swig_copy_string() is used in place of strdup() since + NextStep does not supply strdup(). + + Fixed detection of Ruby library name and location in configure.in. + Problem 1: Assumed that library always resided in Ruby's "archdir", + which was correct for Ruby 1.6.x, but which is incorrect for Ruby + 1.8.x, in which case the library normally resides in Ruby's + "libdir". Problem 2: Assumed that the library could always be + linked via "-l"+RUBY_INSTALL_NAME (where RUBY_INSTALL_NAME + typically is "ruby"), however this failed for platforms, such as + NextStep, which do not support shared libraries. In this case, the + static library name in 1.8.x is libruby-static.a, thus + -lruby-static is required. The new logic works correctly for + static and shared libraries for 1.6.x and 1.8.x. + + Fixed detection of Perl CFLAGS in configure.in for NextStep. + Detection code extracted CFLAGS from Perl's %Config hash but + neglected to add a newline to the value before passing it through + `sed'. NextStep's ancient `sed' discards input which is not + terminated with a newline, thus Perl CFLAGS always evaluated to the + empty string. + +01/16/2004: cheetah (William Fulton) + Tidy up in the exception handling code that is generated when + C++ exception specifications are wrapped with the throws typemap. + This redundant code is no longer generated: + + catch(...) { + throw; + } + +01/12/2004: wsfulton on behalf of mmatus (marcelo matus) + if a method uses %exception and the method requires the use + of the throws typemap, the code in a throws typemap will be + generated inside the try body. For example: + + %exception method { + try { + // method action + $action + } catch (int i) { + // method int catch handler + } catch (...) { + // method generic catch handler + } + } + %typemap(throws) Except %{ + // throws typemap Except catch handler + %} + + %inline %{ + class Except {}; + void method(int i) throw (Except); + + Will generate: + + { + try { + // method action + try { + method(arg1); + } + catch(Except &_e) { + // throws typemap Except catch handler + + } + + } catch (int i) { + // method int catch handler + } catch (...) { + // method generic catch handler + } + } + + + As can be seen, the inner try catch block is for the throws typemaps. + Previously, this was reversed so that the inner try catch block + was the %exception code. In the example above, it would have been + impossible to catch Except as the catch all (...) would catch the + exception instead. + +Version 1.3.21 (January 11, 2004) +================================= + +01/10/2004: cheetah (William Fulton) + The output format for both warnings and errors can be selected for + integration with your favourite IDE/editor. Editors and IDEs can usually + parse error messages and if in the appropriate format will easily take you + directly to the source of the error. The standard format is used by + default except on Windows where the Microsoft format is used by default. + These can be overridden using command line options, for example: + + $ swig -python -Fstandard example.i + example.i:4: Syntax error in input. + $ swig -python -Fmicrosoft example.i + example.i(4): Syntax error in input. + +01/09/2004: beazley + Fixed [ 871909 ] simple namespace problem. + This was a problem using anonymous structures in a namespace. + For example: + + namespace ns { + typedef struct { + int n; + } S; + }; + + Reported by Josh Cherry. + +01/09/2004: beazley + Fixed some broken Perl examples. + +12/28/2003: cheetah (William Fulton) + [Java and C#] Fixes for wrapping covariant (polymorphic) return types. + For example: + + struct Base { + virtual ~Base(); + virtual Base* copy() const = 0; + }; + struct Derived : Base { + virtual Derived* copy() const; + }; + + The Derived::copy proxy method returns Base not Derived. A warning is issued + about this. Previously the pointer used by the proxy class was incorrectly + treated as a Base* instead of a Derived*. + +12/18/2003: cheetah (William Fulton) + Fix so that Windows paths are displayed correctly when reporting errors. + An error previously would have been shown something like: + + .?xample.i:14: Syntax error in input. + + instead of: + + .\example.i:14: Syntax error in input. + + +Version 1.3.20 (December 17, 2003) +================================== + +12/17/2003: beazley + Last minute modifications. Perl5 module now generates shadow classes + by default like all of the other modules. PHP4 wrappers no longer + include "config.h". + +12/14/2003: beazley + Weakened warning message related to constructor names so that an + unusual nested-class wrapping technique would work again (apparently + it worked in some older SWIG releases). For example: + + class Scope { + class ClassA; + class ClassB; + }; + class Scope::ClassA { + ... + }; + class Scope::ClassB { + ... + } + + Note: There is still some odd interaction with the SWIG symbol + table/type system that will need to be looked at in a future release. + Reported by Gustavo Niemeyer. + + +12/11/2003: cheetah (William Fulton) + [Java] Protected class methods are wrapped as protected Java methods + when using the dirprot director feature. This can be changed using + %javamethodmodifiers to something else should the need arise, for + example, private or package access. + +12/11/2003: cheetah (William Fulton) + [Java, C#] + %javamethodmodifiers (Java) and %csmethodmodifiers (C#) operate slightly + differently. Previously this feature had to be present to set the method + modifiers. Now it is only used if it exists for the method being wrapped. + The default is "public" as previous however, when wrapping protected + director methods it is "protected". This change will not affect existing + use of the %javamethodmodifiers or %csmethodmodifiers. + +12/11/2003: mmatus (Marcelo Matus) + + This fix some recurring reports about keywords not been + properly identified and warned, and it solves the problem + of how to add a test file to the test-suite such that it + doesn't use any keyword of all the supported languages + (and doing it without compiling the test for all the + supported languages, thing that is not always possible, + and without requiring you to know all the supported + language keywords, thing that is always impossible). + + So these are the changes globally speaking: + + - Uniform the definition of the keyword warnings through + the supported languages: all the languages has now a + separate file that defines the keywords or bad names: + + python/pythonkw.swg + chicken/chickenkw.swg + .... + + - Added keyword list for most of the languages that didn't + have one (using the new separated file). + + - Added the "All keywords" warning support: -Wallkw option. + + This option allows you to include all the known keywords + for all the supported languages, and can be used as: + + swig -Wallkw .... + + This will help to the process of adding a test-suite + file that can be compiled in all the swig supported + languages, and it will be also helpful for users who + want to create multi-language libraries. + + And these are the detailed changes (mostly file addition): + + - For the languages that already have some sort of keyword + warning list, move it to an external languagekw.swg + file, ie: + + move keywords from python.swg -> pythonkw.swg + move keywords from chicken.swg -> chickenkw.swg + move keywords from tcl8.swg -> tclkw.swg + + and re-include languagekw.swg from language.swg. + + - For the language that didn't have a keyword list, and + for the ones that I could find a list, add the + languagekw.swg file, ie: + + csharp/csharpkw.swg + java/javakw.swg + php4/phpkw.swg + pike/pikekw.swg + ruby/rubykw.swg + + + also add a line in language.swg to include + languagekw.swg, but now it is commented!!!, like in + java.swg: + + /* java keywords */ + /* please test and activate */ + //%include "javakw.swg" + + ie, there will be no change in how swig runs normally + until the language maintainer test and uncomment that + line. + + So, please check each languagekw.swg file (I left the + link to the keyword list source for checking), and after + testing, uncomment the %include line. + + - Added the file allkw.swg, which includes all the + languagekw.swg files. + + For the languages that has no languagekw.swg file right + now, and if they need one, add the file into the + language directory, and add the corresponding include + line into the allkw.swg file. + + - Added the -Wallkw that includes the allkw.swg file. + Note that the old -lallkw.swg option couldn't be used + since it include the file after it would be needed. + + + Hopefully, the -Wallkw option will be added to the default + rules in the related test-suite Makefiles, so, when + creating a new test, or adding a new swig library file + (like _std_deque.i), swig will warn you if you are using a + bad name, considering all the language where it needs to + run. + + Right now you can test it by using: + + make check-python-test-suite SWIG="swig -Wallkw" + + or using your favorite target language, it doesn't matter. + + And yes, there are several examples that are using + reserved keywords, specially from csharp. + + *** Remember ****: the new keyword warning lists are not + included by default in any of language that before didn't + have one. To enable the keyword warnings as the default + behavior, the inclusion of the languagekw.swg file has to + be uncommented at each language.swg file. + + So, all the language maintainers, please check the + keywords list. + + Also, you can add buit-in names, and not only keywords, like + 'True/False' in python. Remember that you can be more + specific and refer only to member names, like *::configure + or *::cget (see an example in the tcl8/tcl8kw.swg file), + or only global names, like ::range (see an example in the + python/pythonkw.swg file. + + Just to be consistent, use the following codes: + + - Use code 314 for keyword and/or fatal bad names. + - Use code 321 for buit-in and/or not fatal bad names. + + so, they can't be disabled/enabled independently (see + python/pyhtonkw.swg for examples). + + **** And don't add any new test file without checking it + with the -Wallkw option!! (that includes me) *****. + + +12/11/2003: cheetah (William Fulton) + SF bug #854634 + Added support for accepting the Unix directory separator '/' on + Windows and the Mac in addition to the native one ( '\' on + Windows). This can be used in %import, %include and commandline + options taking a path, for example -I. On Cygwin, both the Windows + and Unix directory separator can now be used (was '/' only). + +12/10/2003: mmatus (Marcelo Matus) + + [python] Implementing the runtime "reprotected" director + members, if you have: + + %feature("director") B; + + class Bar { + public: + virtual ~Bar(); + virtual int hello() { return do_hello();) + + protected: + virtual int do_hi() {return 0;} + virtual int do_hello() {return 0;} + }; + + then, at the python side + + import my_module + + class Foo(my_module.Bar): + def do_hello(self): + return 1 + pass + + b = Bar() # Pure C++ Director class + f = Foo() # C++ Director + python methods + + b.hello() # Ok, and it calls C++ Bar::do_hello() + f.hello() # Ok, and it calls Python Foo::do_hello() + + b.do_hi() # RuntimeError, do_hi() is protected!! + f.do_hi() # RuntimeError, do_hi() is protected!! + + b.do_hello() # RuntimeError, do_hello() is protected!! + f.do_hello() # Ok, since it its redefined in python. + + Here Bar.do_hello is always protected, but Foo.do_hello + is "public", because it is redefined in python. Before, + all the 'do_hello' methods were public. + + This seems to be a good compromise between C++ and python + philosophies, ie, all the director protected methods keep + protected at the user side (C++ way) until they are + redefined (python way, were all defined methods are always + public). And this is not only a good compromise, it also + seems to be the only way to do it :). + + Now ruby has native director protected members, and python + pure runtime support. I guess these are the two possible + extreme cases. And hopefully, they could be used as + templates to modify the other languages that support + directors, so they can "reprotect" the protected director + members at the target language side. + + This finished the director protected support for the + python language. Ocalm will need to add the + "reprotection" later. + +12/10/2003: mmatus (Marcelo Matus) + + The following case (reported by Lyle Johnson) was fixed: + + %rename(x) Foo::y(); + + class Foo { + public: + void y(); + + protected: + int x; + }; + + swig warned that the symbol 'x' was already defined, and + the renaming fails. 'x' was not emitted, since it is + protected, but it was kept in the symbol table with too + much information. + + Now swig works for all the cases (plain, director and + dirprot) again. This was fixed by allowing the parser.y to + decide much closer what to do with 'x'. Before all the + discarding or generation was resolved at the lang.cxx + stage. Also the changes in parser.y to implement the + director protected mode are now much more encapsulated, and + they get disabled if the mode is not enabled. Before the + deactivation was done at the generation stage (lang.cxx). + + By the other hand, if the director mode is enabled, and + %rename is done, reusing a protected member name, there is + a pathological case: + + %rename(x) Foo::y(); + + class Foo : public A { + public: + void y(); + + protected: + int x; /* works */ + static int x; /* works */ + static void x(); /* works */ + typedef void x(); /* works */ + + virtual void x(); /* always fails, as it should, since + Foo::x() will be emitted in the + director */ + + void x(); /* always fails, but sometimes it shouldn't, + since the Foo::x() will not be emitted if + it is not virtual */ + + }; + + The last case is not always right because at the parser.py + stage it is not possible to decide if the protected member + Foo::x() could or not conflict with the renamed Foo::y(), + since Foo::x() could be virtual by inheritance. + + I guess this just an intrinsic limitation, and no much can + be done about it without resorting into larger changes to + postpone, under certain conditions, the multiply symbol + detection (lang.cxx stage). + + So, by now, it is just considered a well known "feature" in + the director protected mode. The good news is that it seems + to be a rare case, and it can be avoided by the user by + hiding 'x' before renaming 'y': + + %rename(_x) Foo::x(); + %rename(x) Foo::y(); + + +12/08/2003: mmatus (Marcelo Matus) + The virtual method detections now properly + treats the following cases: + + namespace foo { typedef int Int; } + struct A {}; + typedef A B; + + struct Foo { + virtual ~Foo() {} + + virtual Foo* cloner() = 0; + virtual int get_value() = 0; + virtual A* get_class() = 0; + virtual void just_do_it() = 0; + }; + + struct Bar : Foo + { + Bar* cloner(); + foo::Int get_value(); + B* get_class(); + void just_do_it(); + }; + + All the Foo and Bar methods are virtual. A new attribute + "virtual:type" record the base polymorphic type. In the + previous cases we have: + + type : Bar virtual:type : Foo + type : foo::Int virtual:type : int + type : B virtual:type : A + type : void virtual:type : void + + This attribute is useful in languages (java+directors) + that could have problems redefining Bar* Bar::cloner(). + + If you never had code like the above, you will see no + effects. But if you have some code like that, you + will see some effects since some methods that + before were not properly treated as virtual, + will start to act like that. This could enlarge + your director classes. + + +12/08/2003: mmatus (Marcelo Matus) + The director protected member support (dirprot) + is disabled by default. + + It can be enable by using '-dirprot' or by adding + the option to the module declaration, like: + + %module(directors="1",dirprot="1") my_module + + This module option was added to properly compile the + director_protected.i and director_nested.i examples. + + The feature has been tested with python[2.2,2.3] + and ruby[1.6.7], both at compilation and runtime, and + java[j2sdk1.4.1_01], but only at compilation (my java + installation doesn't run any of the director examples, + olds nor news). + + Please test for ocaml and java. + + The errors reported by William and Scott were fixed, + except for a warning about SWIG_JavaThrowExecption() + multiply defined. I can't reproduce this error with my + examples. We will wait for Scott to send us a minimal + case. + + +12/07/2003: mmatus (Marcelo Matus) + The director protected member support has been + completly moved out from python.cxx, and now + resides in the common lang.cxx, emit.cxx and + allocate.cxx files. + + This means it should work for all the other languages + that currently support directors, ie, python, java, ocalm + and ruby. + + The change has been tested with python (compilation+runtime) + and java (just compilation). + + Please add runtime tests for the missing languages + and test it. + + The '-nodirprot' option was moved to the principal main, + and can be used from all the languages. + +12/07/2003: cheetah (William Fulton) + [Java] Fixed and improved error checking of STRING_OUT typemaps in + various.i. + +12/04/2003: mmatus (Marcelo Matus) + + - Now the virtual members with no explicit declarator + are properly identified: + + struct A { + virtual int f() = 0; + }; + + struct B : A { + int f(); + }; + + Here, B::f() is virtual, and the director and the + virtual elimination mechanism now recognize that. + + - [C#] This fix also fixes the problem where 'override' was not being + used on any overridden virtual method, so for struct B above, + this C# code is generated: + + public class B : A { + ... + public override int f() { + ... + } + ... + } + + - Initial support for protected virtual methods. They are now + properly emitted when using with director (python only by + now). + + %feature("director") A; + struct A { + protected: + virtual int f1() = 0; + }; + + %feature("director") B; + struct B : A{ + protected: + int f1(); + virtual f2(); + }; + + This can be dissabled by using the '-nodirprot' option. + + - The feature 'nodirector' is working now at the top level, + so, it must work for all the languages: + + %feature("director") A; + %feature("nodirector") A::f2; + + struct A { + virtual int f1(); + virtual int f2(); + }; + + in this case, only 'f1' is exported to the director class. + + - Added director support for const TYPE& arguments (python). + +12/02/2003: cheetah (William Fulton) + [Java] Fix for INOUT and OUTPUT typemaps in typemaps.i for when the JNI type + is bigger than the C type. For example, unsigned long (32bits on most systems) + is mapped to jlong (64bits). Returned value was incorrect. Bug reported by + Brian Hawley. + +12/02/2003: cheetah (William Fulton) + [C# and Java] Better fix for entry dated 05/11/2003. Fixes the following + typemaps: + + Java: javabase, javainterfaces, javaimports, javaclassmodifiers, + javaptrconstructormodifiers, javafinalize, javagetcptr & javacode. + C#: csbase, csinterfaces, csimports, csclassmodifiers, + csptrconstructormodifiers, csfinalize, csgetcptr & cscode. + + It also fixes bug in using arrays of C structs with arrays_java.i + as reported Scott Michel. + +12/02/2003: beazley + [Perl] Fixed [ 852119 ] recursive inheritance in output .pm, perl5. + Reported by William Dowling. + +12/02/2003: beazley + [Tcl] Fixed [ 755382 ] calling func(const vector& p) evaluates p[0] in interp. + The Tcl type checker was improperly handling the interpreter result when + type violations were supposed to be ignored. + Reported by Flaviu Popp-Nowak. + +11/30/2003: cheetah (William Fulton) + Fixed [ 545058 ] configure's --with-tclincl has no effect + +11/30/2003: cheetah (William Fulton) + [Java] Fixed [ 766409 ] missing symbol SWIG_JavaThrowException during module load + SWIGs internal functions are all static as there is no need for different SWIG + generated modules to share any code at runtime. + +11/30/2003: beazley + [Tcl] Added support for C++ pointers to members. + +11/28/2003: cheetah (William Fulton) + Fixed [ 848335 ] Directors: #include wrapper .h file - was incorrectly + adding a directory to the generated #include "foo_wrap.h" statement + in some situations. + +11/28/2003: cheetah (William Fulton) + [Java] Fixed [ 849064 ] JAVA : Access modifier for derived class wrong. + The delete() method is always public now. It used to be protected whenever a + destructor was non public. An UnsupportedOperationException runtime + exception is thrown instead of making delete() protected now. + +11/28/2003: beazley + [Perl5] Added support for C++ pointers to members. + +11/28/2003: beazley + Fixed [ 850151 ] PYVERSION with python2.3 in configure of SWIG 1.3.19 (Maybe). + +11/28/2003: beazley + Fixed [ 850666 ] #include extra line added. + This should fix some problems with getting correct line numbers on + error messages. + +11/26/2003: beazley + Fixed another one of Marcelo's evil template bugs (infinite + recursion). [ 849504 ] template and typedef -> inf. recursion. + +11/26/2003: beazley + Fixed parsing problem with declarations like this: + + int *x = &somearray[0]; + +11/25/2003: beazley + Fixed [ 756552 ] missing default argument class scope with "|". + This is really only a band-aid fix for use of class-enums in + expressions. For example: + + class A { + public: + enum Flag { flag1 = 0x1, flag2 = 0x2 }; + void foo(int x = flag1 | flag2); + }; + + Note: there are still some (more subtle) cases that are broken, + but hard to fix due to an issue with template expansion. Will + address later. + Reported by Dmitry Mironov. + +11/25/2003: beazley + Incorporated [ 840878 ] support for %inline { ... } (PATCH). + This adds support for the following: + + %inline { + ... some code ... + } + + The difference between this and %inline %{ ... %} is that the + enclosed text is processed by the SWIG preprocessor. This + allows special macros and other processing to be used in + conjunction with %inline. + Contributed by Salvador Fandino Garcia. + +11/25/2003: beazley + Fixed [ 836903 ] C++ inconsistency (with void arguments). + SWIG was having difficulty with f() vs f(void) in C++ programs. + For instance: + + class A { + public: + virtual void f(void) = 0; + }; + + class B { + public: + virtual void f(); // Not matched to f(void) correctly + }; + + The parser now normalizes all declarations of the form f(void) + in C++ classes to f(). This should fix a variety of subtle + problems with inheritance, optimizations, overloading, etc. + Problem reported by Partho Bhowmick. + +11/25/2003: beazley + [Perl5] Incorporated [ 841074 ] better croaking (PATCH). This fixes some problems + with strings and provides some new error functions. + Contributed by Salvador Fandino Garcia. + +11/25/2003: beazley + Fixed [ 791835 ] Default argument with cast: txt = (char *)"txt" syntax Error. + The parser should now accept things like this: + + void foo(char *s = (char *) "Hello"); + + Problem reported by Claudius Schnorr. + +11/24/2003: beazley + [Tcl] Fixed problem with cross module linking. Previously modules referred + to base classes through a global variable. Now, the module looks up base + classes through the type system itself---avoiding the need to link to a global + like before. Caveat: modules with base classes must be loaded before + modules with derived classes. + +11/24/2003: mkoeppe (Matthias Koeppe) + [Guile] In -scm mode, use () to represent null pointers, + as it is done in -gh mode. + +11/23/2003: mkoeppe (Matthias Koeppe) + Add a generated script "preinst-swig", which can be used + to invoke SWIG before it has been installed. It arranges + that the runtime libraries from the source directory are + used. + +11/23/2003: mkoeppe (Matthias Koeppe) + [Guile] In -gh mode, don't forget to call SWIG_Guile_Init. + Add a SWIG_contract_assert macro. + +11/23/2003: mkoeppe (Matthias Koeppe) + [MzScheme] Update the configure check for the dynext object to work + with MzScheme 205. + +11/20/2003: mmatus + Fixed the include/import error reported by Kerim Borchaev, + where two files with names like + + 'dir1/hello.i' + 'dir2/hello.i' + + can not be include at the same time. Swig was including + just the first one, assuming the second one was not a + different one, since it was checking/keeping just the + basename 'hello.i'. + +11/19/2003: beazley + Changes to the SWIG runtime library support. + - The -c command line option has been renamed to -noruntime + - New command line option: -runtime. When supplied, this + inserts the symbol SWIG_GLOBAL into the wrapper code. This, + in turn, makes all of the runtime support functions globally + visible. + - New library file: swigrun.i. Used to create modules + for runtime library (if needed). + +11/18/2003: cheetah (William Fulton) + 'make srcrpm' rpmbuild fix - patch from Joe Cooper + +11/18/2003: mkoeppe (Matthias Koeppe) + [Guile] Change meaning of configure option --with-guile to + the name of the Guile executable. The new option --with-guile-prefix + can be used to specify the tree where Guile is + installed. (However, usually it suffices to use the + single option --with-guile-config.) + When running the run tests test-suite, make sure to use the + version of Guile that SWIG was configured for. + +11/17/2003: mkoeppe (Matthias Koeppe) + [Guile] Improvements to object-ownership management in + "-scm" mode. (They do not apply to the default "-gh" mode.) + * Renamed the smob type that indicates that the object can + be garbage collected from "collected swig" to "collectable + swig", which is more precise. + * Export the destructor functions again. It is now + allowed to explicitly call destructors, even for + garbage-collected pointer objects. A pointer object + that has been passed to a destructor is marked in a + special way using a new smob type, "destroyed swig". + (This helps avoid nasty memory bugs, where references to + dead C objects are still held in Scheme. Moreover, the + garbage collector will not try to free a destroyed + object once more.) + * Destructor-like functions can also mark their arguments + as destroyed by applying the typemap SWIGTYPE *DESTROYED. + (It calls the function SWIG_Guile_MarkPointerDestroyed.) + * Functions that "consume" their objects (or that "own" + them after the call) can mark their arguments as + not garbage collectable. This can be done by applying + the typemap SWIGTYPE *CONSUMED. (It calls the function + SWIG_Guile_MarkPointerNoncollectable.) + * The macro TYPEMAP_POINTER_INPUT_OUTPUT from library + pointer-in-out.i creates additional typemaps + PTRTYPE *INPUT_CONSUMED, PTRTYPE *INPUT_DESTROYED. + They mark the passed pointer object likewise. + The typemap PTRTYPE *OUTPUT creates a garbage-collectable + pointer object, like %newobject does for a returned + pointer. Use the new typemap PTRTYPE *OUTPUT_NONCOLLECTABLE + to create a pointer object that will not be garbage collected. + +11/17/2003: mkoeppe (Matthias Koeppe) + [Guile] Handle $input in "freearg" typemaps. + Never qualify GOOPS slot names with the class name. + Handle optional arguments properly in the GOOPS methods. + +11/16/2003: cheetah (William Fulton) + Fixes for installation to work with the upcoming Automake-1.8. + mkinstalldirs was being used by a non-Automake makefile. + mkinstalldirs is being phased out and so was not being + created by Automake. install-sh used instead. + +11/16/2003: cheetah (William Fulton) + [Java] Numerous director improvements, tweaks and bug fixes since + the initial implementation have been contributed by Scott Michel. + +11/12/2003: beazley + [Python] When %feature("shadow") is used to add code to shadow + classes, the special variable $action expands to the name of the + underlying wrapper function that would have been called normally. + +11/12/2003: beazley + [Python] When generating proxy class code, SWIG emits a few + default methods for __repr__() and other Python special + methods. Some of these methods are emitted after all of the + contents of a class. However, this makes it hard to override + the methods using %pythoncode and some other directives that + allow code to be inserted into a class. These special methods + are now emitted into the code *before* all of the other methods. + Suggested by Eric Jones. + +11/11/2003: beazley + Preprocessor enhancement. For include statements like this: + + %include "foo/bar.i" + + the directory "foo" is now added to the search path while + processing the contents of bar.i. Thus, if bar.i includes other + files in the same directory, they will be found. Previously, + you would have to add additional directories using -I to make this + work correctly. Note: the C preprocessor seems to behave in + an identical manner on many (most? all?) systems. + Suggested by Kerim Borchaev. + +11/11/2003: beazley + Configuration changes to make SWIG work on Mac OSX 10.3.x (Panther). + Tested with Python, Tcl, Perl, and Ruby---all of which seem to work. + +11/08/2003: cheetah (William Fulton) + [Java] Fixed the typemaps in various.i which were mostly broken. + char **STRING_IN and char **STRING_RET typemaps replaced with + STRING_ARRAY. float *FLOAT_ARRAY_RETURN typemap removed. + +11/08/2003: beazley + [Tcl] Tcl module now emits a safe module initialization function by + default. It can be removed by running 'swig -nosafe'. + +11/04/2003: mkoeppe (Matthias Koeppe) + [Guile] Only use the SCM_ API when the function + `scm_slot_exists_p' exists (needed for GOOPS support). + This function was renamed during the Guile 1.5 series + from `scm_slots_exists_p'. + Report the right runtime library when invoked with + -scm -ldflags. + +11/03/2003: mkoeppe (Matthias Koeppe) + [Chicken] Fix #782052. The --with-chickencfg configure + option (and others) were not accepted. + +11/02/2003: mkoeppe (Matthias Koeppe) + [Guile] Merge new set of GOOPS changes by John Lenz. + GOOPS objects are now manipulated directly by the C code. + Some fixes to typemap-GOOPS interaction. + +11/02/2003: mkoeppe (Matthias Koeppe) + [Guile] Remove the file argument to -scmstub and -goops. + The Scheme files are now always called MODULE.scm or + MODULE-primitive.scm, where MODULE is the module name and + "primitive" can be changed by the -primsuffix option. + The Scheme files are now placed in the directory given by + the -outdir option, or the current directory. + (Patch by John Lenz, slightly modified.) + + *** INCOMPATIBILITY [Guile] *** + +11/02/2003: mkoeppe (Matthias Koeppe) + Unify the pointer-conversion runtime API. The standard + functions are: + * SWIG_NewPointerObj (POINTER, TYPE, FLAGS) + -- Create an scripting object that represents a typed + pointer. FLAGS are language specific. + * SWIG_ConvertPtr (INPUT, RESULT, TYPE, FLAGS) + -- Get a pointer from the scripting object INPUT and + store it in the place RESULT. When a type mismatch + occurs, return nonzero. + * SWIG_MustGetPtr (INPUT, TYPE, ARGNUM, FLAGS) + -- Get a pointer from the scripting object INPUT and + return it. When a type mismatch occurs, throw an + exception. If ARGNUM > 0, report it as the + argument number that has the type mismatch. + [Guile]: No changes. + [MzScheme]: No changes. + [Perl]: Add the function SWIG_NewPointerObj. + The function SWIG_MakePtr is kept. + The function SWIG_MustGetPtr is currently not + supported. + [Python]: Add the function SWIG_MustGetPtr. + [Ruby]: Add the function SWIG_MustGetPtr. + [Tcl]: Remove the "interp" argument of + SWIG_NewInstanceObj, SWIG_ConvertPtr, + SWIG_ConvertPacked, and SWIG_ConvertPtrFromString. + The function SWIG_MustGetPtr is currently + not supported. + No changes to Pike because its pointer conversion code did + not look complete. No changes to PHP4, because I did not + understand its runtime code. No changes to Chicken + because major changes are expected soon anyway. No + changes to Java, OCaml, C# because they do not seem to + have a pointer-conversion runtime API. + + *** INCOMPATIBILITY [Tcl] *** + +11/02/2003: mkoeppe (Matthias Koeppe) + [Perl5, PHP4, Pike, Python, Ruby, Tcl]: Use the + preprocessor to rename external functions of the SWIG + runtime API to follow the naming convention + SWIG__. This should allow linking + more than one interpreter into a program. + +10/31/2003: cheetah (William Fulton) + [C#] Fix since introducing the exception and std::string delegates. + The fix overcomes linker errors when using more than one SWIG module. + Problem reported by Andreas Schörk. + +10/31/2003: beazley + Incorporated patch: [ 823302 ] Incr Tcl support. + Contributed by Alexey Dyachenko. + Note: needs documentation. + +10/31/2003: beazley + Incorporated patch: [ 829325 ] new Python Module options and features. + Robin Dunn writes: + + This patch makes a number of changes to the SWIG python module. + + 1. Add -apply option, and change the default code + output to use the foo(*args, **kw) calling syntax + instead of using apply(). If the -apply option is + given then code is generated as before. This is very + similar to Patch #737281 but the new -modern option + makes the second half of that patch unnecessary so it + is not included here. + + 2. Add -new_repr option. This is the same as my Patch + #797002 which I will mark as closed since it is no + longer needed. When this new option is used then the + __repr__ methods that are generated for proxy classes + will be more informative and give details about the + python class and the C++ class. + + 3. Add %feature("addtofunc"). It allows you to insert + one or more lines of code inside the shadow method or + function that is already generated, instead of + replacing the whole thing like %feature("shadow") does. + For __init__ it goes at the end, for __del__ it goes + at the begining and for all others the code generated + is expanded out to be like + + def Bar(*args, **kwargs): + val = _module.Foo_Bar(*args, **kwargs) + return val + + and the "addtofunc" code is inserted just before the + return statement. If the feature is not used for a + particular method or function then the shorter code is + generated just like before. + + 4. A little bit of refactoring to make implementing + addtofunc a little easier. + + 5. Added a -modern command-line flag that will cause + SWIG to omit the cruft in the proxy modules that allows + it to work with versions of Python prior to 2.2. The + result is a simpler, cleaner and faster python proxy + module, but one that requires Python 2.2 or greater. + +10/31/2003: beazley + Incorporated patch: [ 829319 ] XML module tweaks. + This adds a new command line option -xmllite that + greatly reduces the amount of emitted XML code by + eliminating some fields mostly used in SWIG's + internal processing. Contributed by Robin Dunn. + +10/31/2003: beazley + Incorporated patch: [ 829317 ] Adds DohSplitLines function. + Contributed by Robin Dunn. + +10/29/2003: beazley + Fixed [ 827907 ] argout objects not being wrapped properly (PATH). + Patch contributed by Salvador Fandiño García. + +10/29/2003: beazley + Fixed [ 826996 ] perl type checking ignores perl subclasses. + This enhancement makes it so wrapped classes and structs can + be subclassed in Perl and used normally. + Patch contributed by Salvador Fandiño García. + +10/16/2003: cheetah (William Fulton) + [C#] IntPtr marshalled with a void* instead of int in C function + declarations. The casts thus look more conventional, for example: + + // old + DllExport double SWIGSTDCALL CSharp_get_Shape_x(int jarg1) { + ... + Shape *arg1 = (Shape *) 0 ; + arg1 = *(Shape **)&jarg1; + ... + } + // new + DllExport double SWIGSTDCALL CSharp_get_Shape_x(void * jarg1) { + ... + Shape *arg1 = (Shape *) 0 ; + arg1 = (Shape *)jarg1; + ... + } + + +10/14/2003: beazley + Fixed a subtle problem with overloaded methods and smart pointers. + If a class has overloaded methods like this: + + class Foo { + public: + int bar(int x); + static int bar(int x, int y); + }; + + and the class is used as a smart pointer: + + class FooPtr { + public: + Foo *operator->(); + }; + + The SWIG would try to expose the static member Foo::bar + through FooPtr---resulting bogus wrapper code and a compiler + error. + + Due to the way in which overloading is handled, it is + extremely difficult to eliminate the static method in + this case. Therefore, it is still exposed. However, + the generated code now compiles and works. + +10/05/2003: mkoeppe (Matthias Koeppe) + [Guile, MzScheme, Chicken]: Remove symbol clashes between + the runtime libraries by renaming all extern common.swg + functions with the preprocessor. + +10/05/2003: mkoeppe (Matthias Koeppe) + [Guile] Added basic GOOPS support, contributed by John Lenz. + See the documentation for details. + + *** NEW FEATURE *** + +10/04/2003: mkoeppe (Matthias Koeppe) + [Guile] New option, -only-setters, which disables + traditional getter and setter procedures for structure slots. + +10/03/2003: mkoeppe (Matthias Koeppe) + [Guile] Added run test for reference_global_vars by John Lenz. + +09/30/2003: beazley + Partial solution to [ 792180 ] C++ smart-pointer/namespace mixup revisited. + The problem is not easy to fix (at least it doesn't seem so), but is + related to the instantiation of qualified templates inside of other + namespaces. SWIG now generates an error message in this case rather + than generating broken wrappers. + +09/30/2003: beazley + Fixed [ 800012 ] ENTER macro from CORE/scope.h clashes with libc search.h. + Reported by Britton Leo Kerin. + +09/30/2003: beazley + Fixed [ 811518 ] Casting ints to doubles (w/ solution?) + Addresses a problem with overloading in the Perl module. + Reported by Gerald Dalley. + +09/28/2003: mkoeppe + [Guile with -scm option] Fix typo in generated code for + procedures-with-setters. Reported by John Lenz. + +09/26/2003: beazley + Fixed [ 812528 ] externs not correct when throw is in signature. + Reported by Joseph Winston. + +09/23/2003: cheetah (William Fulton) + SWIG was generating a number of symbols that didn't comply with + the ISO C/C++ standard, in particular ISO/IEC 14882:1998(E) 17.4.3.1.2 + where double underscores are forbidden as well as symbols starting with + an underscore followed by an upper case letter. Most of these have + been rooted out. See new section added to internals.html development + manual 'Symbol Naming Guidelines for Generated C/C++ Code'. + +09/23/2003: cheetah (William Fulton) + Director typemap name changes: + inv => directorin + outv => directorout + argoutv => directorargout + + *** POTENTIAL INCOMPATIBILITY *** + +09/19/2003: mrose (Mark Rose) + [Python] Director constructors now default to __disown = 0, + which is the intended behavior and fixes the director_finalizer + test case under python. + +09/12/2003: cheetah (William Fulton) + [C#] - Typemaps added for std::string and const std::string &. + - New delegate for creating a C# string given a char *. It + can be used by calling SWIG_csharp_string_callback as shown + in the std::string 'out' typemap. Useful if the return type is + mapped to a C# string and the calling function is responsible + for cleaning up memory as the C# garbage collector doesn't + free the memory created in C/C++ and then returned as a C# string. + - The exception delegates have moved into an inner class in the + intermediate class, thereby freeing up the static constructor. + +09/11/2003: beazley + (Internals) + Major refactoring of iteration over lists and hashes. The + DOH library now uses iterators. They work like this: + + List *l = (some list); + + Iterator i; + for (i = First(l); i.item; i = Next(i)) { + // i.item contains the actual list item. + // i.item is NULL at end of list + ... + } + + Hash *h = (some hash); + Iterator j; + for (j = First(h); j.item; j = Next(j)) { + // j.item contains hash table item + // j.key contains hash table key + // Both j.item and j.key are NULL at end + ... + } + + The old iteration functions Firstitem(), Nextitem(), Firstkey(), + and Nextkey() are gone. + + The new iterators are simpler, result in better memory use, + and may be faster. Also, there are no longer any problems + iterating over the same list/hash in multiple places at + the same time. For example, this is fine: + + Iterator i,j; + for (i = First(l); i.item; i = Next(i)) { + for (j = First(l); j.item; j = Next(j)) { + ... + } + } + + (This never worked in previous versions). + *** POTENTIAL INCOMPATIBILITY ***. This will probably break + third party extensions to SWIG (or give them further encouragement + to join the SWIG CVS-tree :-). + +09/10/2003: mkoeppe (Matthias Koeppe) + [Guile] Fix memory leaks in the "list-vector.i" typemaps. + +09/09/2003: mkoeppe (Matthias Koeppe) + [Chicken] Use C_mk_bool rather than C_mkbool. This fixes + the wrapping of boolean values for Chicken 1.10 and newer. + Reported by Dave / Felix Winkelmann + . + +09/05/2003: cheetah (William Fulton) + [Java] Directors implemented for Java. In summary this is a big new feature + which supports upcalls from C++ to Java. Code is generated to support C++ + callbacks to call into Java and true polymorphic behaviour for Java classes + derived from C++ classes. See java.html for details. Contributed by + Scott Michel. + +09/05/2003: Tiger + Created contract example directory at /SWIG/Examples/contract + Added simple contract examples (simple_c & simple_cxx) + Modified contract module's output format + + *** NEW FEATURE *** + +09/01/2003: cheetah (William Fulton) + Test-suite build improvements: + - Multiple build directories working for the test suite, so it is now + possible to run configure in multiple subdirectories and run the test + suite in each of these sub directories. + - 'make distclean' fixed so it doesn't bomb out on the Examples directory + when using multiple subdiretory builds. Required the following directories + to be moved: + Examples/GIFPlot/Perl -> Examples/GIFPlot/Perl5 + Examples/GIFPlot/Php -> Examples/GIFPlot/Php4 + These new directories used to be symbolic links to the old directory. + Also the Examples/test-suite/Perl symbolic link has been removed. + - Running the test-suite, other than from the root directory, say + in Examples/test-suite/python will now display all the code being + executed. + - The following 3 C# compilers are detected during configure and work with + the test-suite: Mono, Portable.NET and Microsoft. + +09/01/2003: Tiger + Added inheritance support for design by contract feature. + +09/01/2003: beazley + Fixed [ 794914 ] Wrong types in template specialization. + SWIG was not handling arguments correctly in template + partial specialization. For example, + + template class Foo { + public: + T *blah(); + }; + + %template(FooInt) Foo; + + in this class, the return type of blah was set to + 'int **', but it should really be 'int *'. This has been + fixed, but it will affect all prior uses of partial + specialization. + +09/01/2003: beazley + Fixed [ 786394 ] Patch for generated perl code does not compile under RedHat9. + Reported by Scott Finneran. + +09/01/2003: beazley + Fixed [ 791579 ] (unsigned) long long handled incorrectly (Tcl). + This was an error in the Tcl typemaps.i file. + Reported by Kjell Wooding. + +09/01/2003: beazley + Fixed [ 797573 ] no way to rename classes coming from C structures. + This problem relates to renaming of anonymous structures with a + typedef. For example: + + %rename(Bar) Foo; + typedef struct { + ... + } Foo; + + Reported by Britton Leo Kerin. + +09/01/2003: beazley + Fixed [ 797576 ] -help seems to imply that only tcl-specific options exist. + Added a comment to alert user to other options. + Reported by Britton Leo Kerin. + +09/01/2003: beazley + Fixed [ 798205 ] Segfault in SWIG_ConvertPtr. + Reported by Prabhu Ramachandran. + +08/30/2003: mrose (Mark Rose) + Modified the director typemaps in python/std_complex.i to use the + new-style macro and conversion functions, which eliminated some + redundant code. Fixed a few bugs in these typemaps as well, although + more testing is needed. + +08/29/2003: mrose (Mark Rose) + Completed initial support for wrapping abstract classes with directors. + Constructor wrappers will be generated for abstract classes that have + directors, and instances of the director classes will be created regardless + of whether the proxy class has been subclassed in the target language. + No checks are made during construction to ensure that all pure virtual + methods are implemented in the target language. Instead, calls to + unimplemented methods will throw SWIG_DIRECTOR_PURE_VIRTUAL_EXCEPTION + exceptions in C++. + + Integrated Prabhu Ramachandran's typemap patches, which provide director + typemap support for enums and std::size_t, and fix a couple bugs in the + director std::vector<> typemaps. + +08/29/2003: cheetah (William Fulton) + [C#] Implemented exception handling for throwing C# exceptions from C/C++ code. + A few delegate functions are available for calling which then throw the C# + exception. Use the SWIG_CSharpThrowException function from C/C++ typemaps. + See the generated wrapper code or csharphead.swg for all available exceptions. + Example: + + SWIG_CSharpThrowException(SWIG_CSharpException, "exception description"); + + The 'throws' typemaps are also now implemented, so code is automatically + generated to convert any C++ exception into a C# System.Exception when the C++ + method declares an exception specification such as: + + int foo() throw(Bar); + + Also any parameters that are references to a C++ class or a class passed by value + and are passed as a C# null will now throw a C# NullReferenceException. + +08/29/2003: cheetah (William Fulton) + [C#] Fix to match the calling convention of all pinvoke methods so that they + match the calling convention used by default in the C# 'static extern' declarations + (__stdcall is used on Windows). + +08/19/2003: cheetah (William Fulton) + [Java] Reworked std::string typemaps. Fixes a number of string in std namespace + problems. For example %template vector. The templated class' get method + wasn't returning a Java String, but a SWIGTYPE_p_string. Reported + by Zach Baum. + +08/15/2003: beazley + Fixed [ 763522 ] 1.3.19 segfault in SwigType_add_pointer/DohInsertitem. + Related to problem with unnamed class handling in Perl module. + +08/15/2003: beazley + Fixed [ 763563 ] Missing indication of optional arguments. + Tcl module. Reported by Krzysztof Kozminski. + +08/15/2003: beazley + Fixed [ 787432 ] long param handled as int. Tcl module + now uses Tcl_GetLongFromObj to convert integer values. + +08/11/2003: beazley + Fixed [ 775989 ] numeric template parameters. There were + some errors in template expansion related to the use of + arrays where the array dimension was a template parameter. + It should work now. Reported by Bryan Green. + +08/10/2003: mrose (Mark Rose) + Added a director typemap (outv) for return by value and cleaned up up a few + of the commented director typemaps. + +08/10/2003: mrose (Mark Rose) + Fixed constructor generation for director classes to ignore private + constructors. Protected constructors are also ignored for now, pending + a solution to the problem of wrapping classes that only define protected + constructors. + +08/07/2003: cheetah (William Fulton) + New commandline option -outdir to specify where the language specific + files are to be generated. This is useful for target languages like Python, + Java etc which generate proxy files in the appropriate language. + This option does not apply to the C/C++ wrapper file. + +08/07/2003: cheetah (William Fulton) + On Windows the generated files (other than the _wrap.c or _wrap.cxx files) + were sometimes incorrectly being generated into the current directory unless + the input file used the Unix path separator. The Windows path separator + should now be used. Bug reported by Robert Davies. + +08/07/2003: beazley + Added array variable set typemap to Perl module. + +08/07/2003: beazley + Fixed [ 775677 ] Array init causes codegen bug.. + +08/07/2003: beazley + Fixed [ 779062 ] Class"\n"::foo not supported. SWIG + should now correctly handle whitespace in between + namespace qualifiers. For example "A :: Foo :: Bar". + +07/31/2003: cheetah (William Fulton) + Fixes for parameters which are classes that are passed by value and have + a default value. A copy constructor for SwigValueWrapper is required + (SF #780056). Also fixed memory leak in these circumstances. These mods + also fix SF #780054. + +07/28/2003: beazley + Improved run-time error message for pointers in Python module. + Contributed by Zooko. + +07/10/2003: ballabio (Luigi Ballabio) + [Almost all languages] Wrappers for std::pair added. + Typemaps for Python, Ruby, Guile and MzScheme. + +07/01/2003: mkoeppe (Matthias Koeppe) + [Chicken] Handle the case of more than one argout typemap + per function. + +06/29/2003: cheetah (William Fulton) + [Java, C#] SF #670949 request. The destructor wrapper function name is now + configurable. A new attribute called methodname in the + javadestruct/javadestruct_derived (Java) or csdestruct/csdestruct_derived (C#) + typemaps specifies the method name. For example in Java the destructor is + wrapped by default with the delete method: + + %typemap(javadestruct, methodname="delete") SWIGTYPE {...} + +06/27/2003: cheetah (William Fulton) + [Java, C#] The throws attribute for adding exception classes to the throws + clause also now works with the following typemaps: + newfree + javain, javaout (Java) + csin, csout (C#) + + For example, the 'AnException' will be added to the throws clause in the + proxy function: + + %typemap(javaout, throws="AnException") int { + int returnValue=$jnicall; + if (returnValue==0) throw new AnException("Value must not be zero"); + return returnValue; + } + +06/25/2003: mrose (Mark Rose) + [Python] Director typemap marshalling checks for null pointers when + walking the parameter list instead of relying soley on the parameter + count. Cures a segfault that occured for multiple argument inv typemaps. + Someone with more Swig experience should probably review this code. + +06/24/2003: mkoeppe (Matthias Koeppe) + [Chicken] Don't emit calls to "C_check_for_interrupt", + which may result in an endless loop. Patch by felix@proxima-mt.de. + +06/20/2003: cheetah (William Fulton) + [C#] Finalizers now use destructor syntax as the override which was used in + the Finalize method is not in the ECMA standards, spotted by the MS compiler. + +06/10/2003: cheetah (William Fulton) + [C#] A number of changes have been made to remove the Java naming + that was used in the C# module. + + Typemap name changes: + jni -> ctype + jtype -> imtype + jstype -> cstype + javain -> csin + javaout -> csout + javainterfaces -> csinterfaces + javabase -> csbase + javaclassmodifiers -> csclassmodifiers + javacode -> cscode + javaimports -> csimports + javaptrconstructormodifiers -> csptrconstructormodifiers + javagetcptr -> csgetcptr + javafinalize -> csfinalize + + Feature name changes: + javaconst -> csconst + javamethodmodifiers -> csmethodmodifiers + + Pragma changes: + pragma(java) -> pragma(csharp) + jniclassbase -> imclassbase + jniclassclassmodifiers -> imclassclassmodifiers + jniclasscode -> imclasscode + jniclassimports -> imclassimports + jniclassinterfaces -> imclassinterfaces + + Special variable name changes: + $javaclassname -> $csclassname + $javainput -> $csinput + $jnicall -> $imcall + + This will break SWIG interface files that use these typemaps, features + and pragmas. Please update your code or use macros for backwards + compatibility. + + *** POTENTIAL INCOMPATIBILITY FOR C# MODULE *** + +06/10/2003: mkoeppe (Matthias Koeppe) + [MzScheme] Applied MzScheme module updates contributed by + John Lenz . + + - Updated mzscheme to use SWIG's common runtime type + system from common.swg. + + - The Lib/mzscheme directory has been reorganized to + standardize names across the language modules: + mzscheme.i was moved to mzscheme.swg, mzscheme.swg and + mzschemedec.swg have been removed, mzrun.swg (which + contains the runtime code) has been added. + + - The swig_proxy structure was renamed to swig_mz_proxy. + swig_mz_proxy now contains a pointer to a swig_type_info + structure. + + - Added varin and varout typemaps for SWIGTYPE [] and + SWIGTYPE &. + + - Garbage collection by calling scheme_add_finalizer() has + been added. + + *** NEW FEATURE [MzScheme] *** + +06/10/2003: cheetah (William Fulton) + [Java] New typemaps: javadestruct and javadestruct_derived + for the C++ destructor wrapper. The javadestruct version gets used by + classes at the top of an inheritance chain and the javadestruct_derived + version gets used by other classes. + + [C#] cildispose and cildisposeoverride typemaps replaced by + csdestruct and csdestruct_derived typemaps. The delete() + method has been removed and its functionality put into these + typemaps designed for the Dispose() method. + + - New typemaps csinterfaces and csinterfaces_derived replace + the javainterfaces typemap. Also fixes the peculiarity of all classes + in an inheritance chain individually deriving from the IDisposable + interface. + + - New typemap csfinalize for finalizers. C++ destructors are now called + by garbage collector during finalization. Problem reported by + Andreas Schörk. + +06/10/2003: Tiger + Modified contract code for error message output. + Contract code can now print out simple error message. + Modified contract code to prepare for inheritance + +06/03/2003: mkoeppe + [Guile] Applied Guile module updates contributed by + John Lenz . + + - SWIG currently uses Guile's gh_ API, which is marked as + deprecated in Guile 1.6 and will be removed in Guile + 1.9. This change introduces a command-line flag "-scm" + which causes SWIG to generate wrappers that use Guile's + SCM API instead; this requires Guile >= 1.6. + + - The Lib/guile directory has been reorganized to + standardize names across language modules: guiledec.swg + and guile.swg have been moved into guile_gh_run.swg, + guile.i has been moved to guile_gh.swg, guile_scm.swg + and guile_scm_run.swg which contain the SCM API stuff + have been added + + - ghinterface.i, which contains the defines from the gh_ + functions to the scm_functions has been added + + - The API for dealing with pointer objects is now + SWIG_ConvertPtr, SWIG_MustGetPtr, SWIG_NewPointerObj. + + - Added varin and varout typemaps for SWIGTYPE [] and SWIGTYPE & + + - Garbage collection has been added. + + *** NEW FEATURE [Guile] *** + +06/01/2003: cheetah (William Fulton) + Dimensionless arrays such as + + int foo[] = {1, 2}; + extern int bar[]; + + produce a warning that the variable is read-only. Depending on the target + language, this used to cause compile errors or generate a setter that + generated a runtime error. A setter cannot be automatically generated + because the array size cannot be determined by SWIG. A varin, globalin + or memberin typemap (depending on the target language) must be written + by the user. + +05/29/2003: beazley + Refinement to default typemap matching and arrays. When an + array is declared like this: + + int foo[4]; + + The default typemap now resolves to + + SWIGTYPE [ANY] + + If no match is found for that, it then resolves to + + SWIGTYPE [] + + If no array dimension is specified in the original declaration, + the SWIGTYPE [] is used right away. + + Note: This change has been made to resolve problems related to + arrays with and without dimensions. For example, sometimes SWIG + was generating setter functions for array variables with no dimensions + (an error). Likewise, SWIG sometimes made arrays with dimensions + read-only (also an error). This fixes the arrays_global test + problem. + +05/28/2003: beazley + Fixed subtle type handling bug with references and pointers. + If you had functions like this: + + typedef Foo Bar; + + Foo *func1(); + void func2(Bar &x); + + Then func2() wouldn't accept objects returned by func1() + because of a type error. It should work now. + Reported by Brian Yang. + +05/21/2003: cheetah (William Fulton) + Fixes to some of the Visual C++ example project files which would not + work with spaces in the paths held in the environment variables used to + point to the target language's library / include directory. + SF bug #740769 + +05/21/2003: songyanf (Tiger) + Added -contracts option. + First try of the idea of "Wrap by Contract": + build up realiable cross-language module by wrapping with SWIG. + Implemented basic assertion + (preassertion & postassertion & invariant) + for simple C/C++ functions. + + Current format of contracts are: + %contract class_name :: func_name (paras...) { + require: + boolean exprs; + exprs; + ensure: + boolean expr; + exprs; + invariant: + boolean expr; + exprs; + } + + *** NEW FEATURE *** + +05/19/2003: cheetah (William Fulton) + Build tweaks. There were a few preprocessor definitions which were + specified in the Makefile for passing on the commandline when compiling. + These are now all defined in swigconfig.h. Autoconf doesn't normally + allow installation directories to be defined in this config header file, + but an autoconf archive macro enables this. This macro along with future + autoconf macros are going to be put in the Tools/config directory. + + 'swig -version' now reports the target build platform. + +05/11/2003: cheetah (William Fulton) + [C# and Java] Fix to the following typemaps: + + javabase, javainterfaces, javaimports, javaclassmodifiers, + javaptrconstructormodifiers, javafinalize, javagetcptr & javacode. + + These are the typemaps for modifying/generating proxy classes. + Previously the typemaps would use the proxy class name and not the + C++ type, which was inconsistent with all other typemaps. + + In most circumstances the proxy class name and the C++ class name/type + is the same except for classes in namespace, templated classes etc. so + this shouldn't affect most cases. + + *** POTENTIAL INCOMPATIBILITY FOR JAVA and C# MODULES *** + +05/09/2003: cheetah (William Fulton) + Visual C++ Project files have been added so that the runtime libraries + can be built on Windows (for Tcl, Perl, Python and Ruby). + +05/01/2003: beazley + Fixed problem with return by value, const, and private constructors. + For example: + + class B { + private: + B(); + public: + B(const B&); + }; + + class A { + ... + const B returnB() const; + ... + }; + + Problem and patch suggestion reported by Bill Hoffman. + +04/29/2003: cheetah (William Fulton) + Build changes: + - Single autoconf invocation - autoconf in the Tools directory has gone. + + - Libtool bootstrapped when running autogen.sh. This requires anyone + using the cvs version of SWIG to have libtool installed on their + machine. Suggest version 1.4.2 or higher, preferably the latest - 1.5. + + - Automake is now used to build the runtime libraries in conjunction + with libtool. + + - Runtime libraries are now successfully built as DLLs on Cygwin. + + - Skipping languages is no longer just determined in the top level + makefile but in configure.in. This info is used for building + the runtime libraries and for running the examples and test-suite. + + - These changes have fixed multiple build directory builds, that is + building from directories other than the top level directory. + Installation from multiple build directories also working. An initial + configure in the top level directory is no longer needed as described + in 04/02/2003 entry. A 'make distclean' will be needed before building + in a directory other than the top level directory if the autotools + have been run from this top level directory at some point, but + autoconf will tell you this. Note that 'make check' only works from + the top level directory at the moment. + +04/28/2003: beazley + Fixed [ 723471 ] Wrapper_print() fails with preprocessor directives. + +04/28/2003: beazley + Minor refinement of const static member variable handling + described in CHANGES 08/11/2002. Previously, SWIG merely + checked to see if there was an initializer in the declaration. + Now, SWIG additionally checks to make sure the static member + is const. + +04/25/2003: ljohnson (Lyle Johnson) + [Ruby] Added a kind of limited support for multiple inheritance, + activated using the -minherit command-line option. I've also updated + the "C++ Inheritance" section of the Ruby documentation to discuss + how this works, and its limitations. Also also modified the minherit.i + test case to run against this. + +04/25/2003: ljohnson (Lyle Johnson) + [Ruby] Added the -globalmodule command-line option for the Ruby + module, for wrapping stuff into the global module (Kernel) instead + of a nested module. Updated documentation accordingly. + +04/23/2003: mrose (Mark Rose) + Fixed symname error in director calls to Python methods + that extend C++ operators. + + Stopped director destructor wrappers from calling __set_up, + which was leaving the director flag in an inconsistent state. + +04/23/2003: beazley + Fixed problem with namespace resolution and nested namespaces. + Reported by Alfred Lorber (and Marcelo Matus). + +04/16/2003: cheetah (William Fulton) + Patch for Java examples and test-suite to run on Mac OS X. + +04/15/2003: ljohnson (Lyle Johnson) + [Ruby] Incorporated Nobu Nakada's patches for supporting the Ruby + 1.8 allocation framework. + +04/15/2003: ljohnson (Lyle Johnson) + [Ruby] Replaced all uses of the deprecated STR2CSTR() macro with the + safer StringValuePtr() macro. For more information, see ruby-talk:67059 + and follow-ups to that post. + +04/11/2003: beazley + Fixed problem with preprocessor macro expansion. For example: + + #define min(x,y) ((x) < (y)) ? (x) : (y) + int f(int min); + + Reported by Sebastien Recio. + +04/10/2003: cheetah (William Fulton) + [Java] Added a runtime check to typemaps in arrays_java.i library to check + that the Java array passed in is the same size as the C array and throw an + exception if not. + + Also fix to use delete instead of free for arrays created using new. + +04/07/2003: cheetah (William Fulton) + Remove GCC3 warning when compiling the examples and test-suite: + + cc1plus: warning: changing search order for system directory "/usr/include" + cc1plus: warning: as it has already been specified as a non-system directory + + See SF patch #715531 submitted by Gerald Williams + +04/03/2003: cheetah (William Fulton) + [C#] Improved wrapping of enums and constants. These were previously + wrapped as C# variables rather than constants. Either these are wrapped + as readonly (runtime) constants or compile time constants, depending on + the %javaconst directive (The directive is likely to change name soon). + For example wrapping: + %javaconst(0); + #define ABC 22 + %javaconst(1) XYZ; + #define XYZ 33 + is now: + public static readonly int ABC = examplePINVOKE.get_ABC(); + public const int XYZ = 33; + +04/03/2003: cheetah (William Fulton) + [Java] Global constants and enums are put in their own interface called + xxxConstants, where xxx is the module name. This is an improvement as + it is possible to derive (implement) a Java class from the xxxConstants + interface to improve the syntax; namely when wrapping: + enum {ONE=1, TWO, THREE}; + accessing these from a Java class implementing xxxConstants is neater: + int number = ONE; + than the previous: + int number = xxx.ONE; + + Patch submitted by Dave Dribin. + +04/02/2003: cheetah (William Fulton) + Build improvements for multiple builds. This allows one to build + the SWIG executable and runtime libraries for different platforms/compilers + etc by running configure in different directories. This isn't 100% just + yet and won't be until libtool is better configured... a 'configure' and + 'make distclean' needs to be run in the root directory before it all works. + For example: + $ ./configure + $ make distclean + $ mkdir config1; cd config1; ../configure CC=gcc CXX=g++; make; cd .. + $ mkdir config2; cd config2; ../configure CC=cc CXX=c++; make; cd .. + + To be improved. A 'make check' does not work yet either. + +04/01/2003: beazley + Fixed template partial specialization argument expansion bug. + This showed up when trying to use std_vector.i with vectors + of pointers. + +03/31/2003: cheetah (William Fulton) + Fix for parallel make builds of SWIG, for example + make -j 4 + Build failure reported by Bill Clarke. + +03/28/2003: beazley + Released 1.3.19. + + + +Version 1.3.19 (March 28, 2003) +=============================== + +03/28/2003: beazley + Variety of minor bug fixes to the 1.3.18 release including: + + - Segmentation fault with %extend directive. + - Typemap variable substitution bug. + - Expression evaluation bug. + - Large memory leak with template expansion. + +Version 1.3.18 (March 23, 2003) +=============================== + +03/21/2003: beazley + Fixed two problems with the %extend directive, overloading, and + template expansion. See the 'template_extend_overload' and + 'template_extend_overload_2' tests in Examples/test-suite for + details. + +03/20/2003: cheetah (William Fulton) + [C#] Added some typemaps as suggested by Andreas Schoerk for handling + parameters that are passed as pointers or by reference. These have + been put in typemaps.i. + +03/20/2003: beazley + Fixed a C++ scoping bug related to code like this: + + class Foo { + public: + int Foo::bar(); + }; + + Previously, SWIG just tossed out the Foo::bar() declaration. Now, + the declaration is wrapped provided that the prefix is exactly the + same as the current scope (including any enclosing namespaces). + Reported by Bruce Lowery. + +03/20/2003: beazley + Incorporated [ 696516 ] Enabling exception processing for data member access. + In some compilers, attribute access can generate exceptions. However, + SWIG ordinarily assumes that no exceptions will be raised. To disable this, + use the %feature("allowexcept"). For example: + + %feature("allowexcept") Foo::x; + ... + class Foo { + public: + int x; /* Exception handling enabled */ + ... + }; + + Patch contributed by Yakov Markovitch. + +03/20/2003: beazley + Incorporated Patch. [ 701860 ] Improve Performance (python proxies). + Gives a performance boost to proxy class code and the management of the + .this and .thisown attributes. Contributed by Mike Romberg. + +03/19/2003: cheetah (William Fulton) + [C# and Java] Added missing vararg support. + +03/18/2003: mrose (Mark Rose) + Removed code related to tagging individual methods for directors. + The concept of having directors for some but not all virtual methods + of a class is deeply flawed. The %feature("nodirector") tag is also + gone. + + Directors are off by default. To enable them for a class, issue + %feature("director") classname; which will create director methods + for every virtual method in the hierarchy of the class. + +03/17/2003: beazley + Fixed a subtle problem with passing arguments of type function. For + example: + + int foo(int x(int, int)); + + or + + typedef int binop_t(int, int); + int foo(binop_t x); + + In old versions, this would produce code that wouldn't compile. Now, + SWIG merely adds an extra pointer, making these declarations the same + as: + + int foo(int (*x)(int, int)); + + typedef int binop_t(int, int); + int foo(binop_t *x); + + Reported by Garth Bushell. + +03/17/2003: mrose (Mark Rose) + Fixed the return statement for director base class calls that have no + return value. + +03/15/2003: beazley + Fixed a problem with const smart-pointer wrapping. For example: + + class Foo { + public: + int x; + void bar() const; + void spam(); + }; + + class Blah { + ... + const Foo *operator->(); + ... + }; + + In this case, only "x" and "bar" are visible from Blah (since application + of spam violates constness). Moreover, access to "x" is read-only. + +03/15/2003: mrose (Mark Rose) + Cleaned up two signed versus unsigned comparisons in python/std_vector.i. + +03/15/2003: cheetah (William Fulton) + [C#] Global variables are wrapped using properties instead of get and set methods. + Member variable wrapping bug fixes, for example wrapping pointers work now. + Typemaps are used for all variable wrapping to generate the property code. + +03/13/2003: mrose (Mark Rose) + Fixed a bug in the virtual method unrolling for directors. + The order of unrolling is now from base to derived, to ensure + that the most derived implementation of a director method is + found. + + Director methods for pure virtual methods now throw + DIRECTOR_PURE_VIRTUAL_EXCEPTION if _up is set. + +03/12/2003: cheetah (William Fulton) + [C#] Polymorphism fix: virtual functions now use the appropriate + keyword in the C# proxy class, virtual or override. + Some 'using System;' statement fixes needed by the Mono compiler. + +03/11/2003: beazley + Fixed subtle bug in the application of SwigValueWrapper<> to + template classes with default constructors. Reported by + Bruce Lowery. + +03/11/2003: beazley + The $descriptor(type) variable is now expanded in code supplied to + %extend. This is useful for certain kinds of advanced wrapping + (especially container classes). + +03/11/2003: luigi + Support for std::map. + (a) Integration with scripting language (a la std::vector) for + Python, Ruby, MzScheme, and Guile; + (b) Simple wrapper for other languages + +03/10/2003: beazley + Fixed problem with escape sequences in string and character constants. SWIG + wasn't parsing certain octal codes correctly. + +03/07/2003: beazley + Fixed a variety of subtle preprocessor problems reported by + Sebastien Recio. + + (a) Empty preprocessor values no longer generate "bad constant + value" errors. For example: + + #define FOO + #define FOO BAR + + (b) Macro names can now span multiple lines (technically valid, + although questionable practice). For example: + + #define A_LONG_MACRO_\ + NAME 42 + + (c) Whitespace is no longer required before certain macro values. + For example: + + #define FOO"Hello" + #define BAR\ + "Hello" + +03/07/2003: ljohnson (Lyle Johnson) + [Ruby] Added missing long long and unsigned long long typemaps + in the Lib/ruby/typemaps.i library file. + +03/07/2003: mrose (Mark Rose) + Added Examples/python/callback to demostrate how directors can + be used to implement callbacks in Python + Added Examples/python/extend to demonstrate virtual method + calls from C++ to Python (really the same as the callback + example, just a different context). + Added four tests for very basic director functionality. These + have runtime tests under python. + The Python module now emits #define SWIG_DIRECTORS near the + top of the output file if directors are enabled. This is useful + for disabling parts of tests in target languages that don't + support directors. + +03/06/2003: mrose (Mark Rose) + Added a section to Doc/Manual/Python.html on cross language + polymorphism (directors). + +03/06/2003: mrose (Mark Rose) + The short-lived "-fdirectors" command line option has been + removed. To enable directors, instead use the extended %module + directive as follows: + + %module(directors="1") modulename + +03/06/2003: cheetah (William Fulton) + The long long typemaps have been rewritten so that they can be more + easily used with non ISO compilers, like Visual C++. For example + if you are wrapping the Windows 64 bit type __int64 the long long + typemaps can be used with %apply: + + %apply long long { __int64 }; + __int64 value1(__int64 x); + + __int64 will now appear in the generated code instead of long long. + +03/06/2003: beazley + *** DEVELOPER CHANGE *** + Swig module mutation has been changed slightly. When a language + class method wants to save node attributes, it now uses one of the + following functions: + + Swig_require() + Swig_save() + + The first argument to these functions is a namespace in which + saved attributes are placed. For example,this code + + Node *n; + Swig_save("cDeclaration",n,"type","parms","name",NIL); + + saves the attributes as "cDeclaration:type", "cDeclaration:parms", + and so forth. If necessary, a language module can refer to + old values by using this special namespace qualifier. + + In addition to this, a special attribute "view" contains the name + of the last namespace used to save attributes. In the above + example, "view" would have the value "cDeclaration". The value + of "cDeclaration:view" would have the previous view and so forth. + + Swig_restore(n) restores a node to the state before the last + Swig_require() or Swig_save() call. + + Note: This change makes it easier for language modules to refer + to old values of attributes. + + +03/06/2003: mrose (Mark Rose) + Merged the cross-language polymorphism patch. When enabled, C++ + "proxy" classes (called directors) are generated for each specified + C++ class. Directors pass method calls from C++ to Python, similar + to the way the usual proxy (shadow) classes pass method calls from + Python to C++. Together, these two types of proxies allow C++ + classes that are extended in Python to behave just like ordinary + C++ classes and be used in C++ like native objects. + + This feature is still very experimental and is disabled by default. + To enable director support, specify '-fdirectors' on the SWIG command + line or in the SWIG_FEATURES environment variable. In the interface + file, add %feature("director") to generate directors for all classes + that have virtual methods. + + See http://stm.lbl.gov/~tm2/swig/ProxyDoc.html for more details. + + +03/03/2003: beazley + Fixed a small glitch in typemap local variable replacement. If you had + a typemap like this: + + %typemap(in) type ($1_type temp) { + ... + temp = ...; + ... + } + + and no occurrence of "$1_type" appeared in the body, then the local + variable type wouldn't be substituted. + +03/03/2003: cheetah (William Fulton) + [C#] New version of the CSharp module which is typemap based. + It also uses ECMA C# and no longer uses Microsoft Visual C++.NET + glue. This means that it will work on non-Windows platforms. + Contributed by Neil Cawse. + +02/27/2003: beazley + Fixed [ 653548 ] error parsing casting operator definition. + SWIG now ignores casting operators declared outside of a class. + For example: + + inline A::operator char *() { ... } + + Bug reported by Martin Casado. + +02/27/2003: beazley + Added support for anonymous bit-fields. For example: + + struct Foo { + int x : 4; + int : 4; + int y : 8; + }; + + Anonymous bit-fields are ignored by SWIG. Problem + reported by Franz Höpfinger. + +02/26/2003: cheetah (William Fulton) + [Java] Better typemaps in the Examples/java/typemap example and also + fixes subtle bug when using the StringBuffer typemaps more than once. + +02/26/2003: beazley + Fixed [ 642112 ] Constants char bug. + +02/26/2003: beazley + Fixed [ 675337 ] Partial template specialization not entirely working. + There was a subtle problem related to the naming and ordering of + template partial specialization arguments. Matching worked okay, + the resulting templates weren't expanded correctly. + +02/25/2003: beazley + Fixed problem with parsing (and generating code) for + references to arrays. For example: + + int foo(int (&x)[10]); + +02/25/2003: beazley + Fixed [ 635347 ] Compilation warning from libpy.c. + Reported by Daniel L. Rall. + +02/25/2003: beazley + Fixed a subtle problem with virtual method implementation + checking and typedef. + + typedef int *intptr; + + struct A { + virtual int *foo() = 0; + }; + struct B : public A { + virtual intptr foo() { }; + }; + + SWIG was treating these declarations as different even though + they are the same (via typedef). + +02/25/2003: ljohnson (Lyle Johnson) + [Ruby] Added range checking for the NUM2USHRT macro, per [ 675353 ]. + +02/24/2003: beazley + Fixed a subtle problem with the code that determined if a class is abstract + and can be instantiated. If you had classes like this: + + struct A { + virtual int foo(int) = 0; + }; + struct B : virtual A { + virtual int foo(int); + }; + + struct C : virtual A { + }; + + /* Note order of base classes */ + struct D : B, C { }; /* Ok */ + struct E : C, B { }; /* Broken */ + + then SWIG determined that it could instantiate D(), but not E(). + This inconsistency arose from the depth-first search of the + inheritance hierarchy to locate the implementations of virtual + methods. This problem should now be fixed---SWIG will attempt + to locate any valid implementation of a virtual method by + traversing over the entire hierarchy. + +02/22/2003: cheetah (William Fulton) + [Java] Fix for using enum typemaps. The Java final static variable type + can be set using the jstype typemap, enabling enums to be mapped to + something other than int. Bug reported by Heiner Petith. + +02/21/2003: songyanf (Tiger) + Added CSharp (C#) module prototype + i.e. csharp.cxx & csharp.h at Source/Modules/. + They are for test usage only now and need improvement. + The interface also need to be modified. + + *** NEW FEATURE *** + +02/20/2003: songyanf (Tiger) + Fixed problem with typedef with -fvirtual. + Similar as beazley's modification today. + +02/20/2003: beazley + Added support for gcc-style variadic preprocessor macros. + Patch [ 623258 ] GCC-style vararg macro support. + Contributed by Joe Mason. + +02/20/2003: beazley + Fixed [ 605162 ] Typemap local variables. + Reported by Lyle Johnson. + +02/20/2003: beazley + Fixed problem with abstract classes and typedef. For example: + + class Foo { + public: + virtual void foo(int x) = 0; + }; + + typedef int Integer; + class Bar : public Foo { + public: + virtual void foo(Integer x); + }; + + SWIG was getting confused about the latter method---making Bar + abstract. Reported by Marcelo Matus. + +02/19/2003: cheetah (William Fulton) + [Java] %javaconst(flag) can also be used on enums as well as constants. + This feature enables true Java compiler constants so that they can be + used in Java switch statements. Thanks to Heiner Petith for patches. + +02/19/2003: songyanf (Tiger) + Modified -fcompact feature to deal with PP lines + +02/18/2003: beazley + Fixed [ 689040 ] Missing return value in std_vector.i. + Reported by Robert H. de Vries. + +02/18/2003: beazley + Fixed a few evil scoping problems with templates, namespaces, and the + %extend directive. Problem reported by Luigi Ballabio. + + +02/18/2003: cheetah (William Fulton) + [Ruby] Improved support for Visual C++ and other native Windows compilers. + It is no longer necessary to specify "/EXPORT:Init_", where is the + swig module name when linking using these native Windows compilers. + +02/15/2003: songyanf (Tiger) + Added -fvirtual option. + Reduce the lines and size of the wrapper file + by omitting redifined virtual function in children classes. + + Modified -compact option to -fcompact option + + Added -small option. + -small = -fvirtual -fcompact + And it can be extended by future feature options, + which are used to reduce wrapper file szie. + + Added SWIG_FEATURES environment variable check. + To dynamically set the feature options such as -fcompact & -fvirtual + *** NEW FEATURE *** + +02/13/2003: lenz + Updated Doc/Manual/Perl5.html to talk about C++ compile problems + configure.in now checks for PERL5_CCFLAGS + Runtime/Makefile.in and Example/Makefile.in now use PERL5_CCFLAGS + Added Lib/perl5/noembed.h which contains all the known macro conflicts + +02/12/2003: beazley + Fixed [ 685410 ] C++ Explicit template instantiation causes SWIG to exit. + Fixes a syntax error with declarations similar to this: + + template class std::vector; + + SWIG now ignores the instantiation and generates a warning message. + We might do more later. Reported by Thomas Williamson. + +02/11/2003: cheetah (William Fulton) + Rewrote bool typemaps to remove performance warning for compiling generated code + under Visual C++. + +02/11/2003: cheetah (William Fulton) + Fix for wrapping reference variables (const non-primitive and all non-const types) + for example: + int& i; + Class& c; + const Class& c; + +02/11/2003: beazley + Fixed more very subtle preprocessor corner cases related to recursive + macro expansion. For example: + + #define cat(x,y) x ## y + + cat(cat(1,2),3) // Produces: cat(1,2)3 + + #define xcat(x,y) cat(x,y) + + xcat(xcat(1,2),3) // Produces 123 + + See K&R, 2nd Ed. p. 231. + +02/10/2003: cheetah (William Fulton) + Fixed [ 683882 ] - patch submitted by F. Postma for SWIG to compile on HP-UX. + +02/10/2003: beazley + Fixed subtle preprocessor argument expansion bug. Reported by Marcelo Matus. + +02/10/2003: songyanf + Added -compact option. + Reduce the lines and size of the wrapper file + by omitting comments and combining short lines. + *** NEW FEATURE *** + +02/07/2003: beazley + Fixed [ 651355 ] Syntax error with cstring.i + Reported by Omri Barel. + +02/07/2003: beazley + Fixed [ 663632 ] incompatibility with standard cpp. + This is a refinement that fixes this problem: + + // Some macro with an argument + #define FOO(x) x + + int FOO; /* Not a macro---no arguments */ + +02/05/2003: beazley + Fixed [ 675491 ] parse error with global namespace qualification. + Submitted by Jeremy Yallop. + +02/04/2003: beazley + Fixed bug in varargs processing introduced by the numinputs typemap parameter. + +01/08/2003: ttn + [xml] Fix string-replacement ordering buglet. + Thanks to Gary Herron. + +12/23/2002: cheetah (William Fulton) + Further build changes: + - The SWIG executable is now built using a single Makefile. + - This makefile is generated by Automake (Source/Makefile.am). + - Dependency tracking and tags support are in this makefile. + - Automake 1.7.2 and Autoconf 2.54 minimum versions are needed to build SWIG from CVS. + - Running ./autogen.sh now installs Autoconf/Automake support files into + Tools/config and these files are no longer stored in CVS. + - Bug fixes in 'make install' for systems using .exe executable extension and + ./configure --with-release-suffix=whatever + +12/16/2002: cheetah (William Fulton) + More build changes: + - Autoconf's AC_CANONICAL_HOST replaces proprietary approach for detecting build host. + - Autoconf support files moved to Tools/config. + +12/16/2002: cheetah (William Fulton) + Modifications to run on MacOS, submitted by Bernard Desgraupes. + Mainly ensuring generated files are output in the appropriate directory for + some modules. + +12/11/2002: cheetah (William Fulton) + Various build modifications and bug fixes: + - Simplification of version string. Use autoconf's PACKAGE_VERSION instead. + - Build time removed from SWIG version. + - Using standard autoconf config header generation. + - Updated old autoconf macros as reported by autoupdate. + - Removed $prefix in autoconf from search paths as autoconf won't expand them. + - Subtle bug fix where 'make prefix=/somewhere; make clean; make prefix=/somwhere/else' + produced an executable using the incorrect library directories. + - Added -ldflags commandline option for MzScheme, Ocaml, Pike and PHP. + - Fixed reporting of compiler used when using -version commandline option. + - SWIG web address added to -version commandline option. + +12/11/2002: beazley + Minor fix to Tcl dynamic cast typemaps. Reported by + Kristopher Blom. + +12/10/2002: beazley + Fixed subtle template argument replace bug. Reported by + Chris Flatley. + +12/10/2002: beazley + Reverted CHANGES 09/03/2002, preprocessor argument evaluation. Arguments + are not evaluated during collection, K&R, p. 230. + +12/06/2002: beazley + Fixed [ 649022 ] Compilation problems with KAI/KCC + +12/02/2002: beazley + SWIG 'rel-1-3' CVS branch merged back into the main branch. + + +Version 1.3.17 (November 22, 2002) +================================== + +11/19/2002: beazley + Fixed [ 613922 ] preprocessor errors with HAVE_LONG_LONG. + +11/19/2002: beazley + Fixed [ 615480 ] mzscheme SWIG_MustGetPtr_. + +11/19/2002: beazley + Fixed [ 635119 ] SWIG_croak causes compiler warning. + +11/16/2002: cheetah (William Fulton) + [Java] Added typemaps for pointers to class members. + +11/15/2002: cheetah (William Fulton) + [Java] Bug fix: Overloaded C++ functions which cannot be overloaded in Java + once again issue a warning. + +11/14/2002: cheetah (William Fulton) + [Java] Handling of NULL pointers is improved. A java null object will now + be translated to and from a NULL C/C++ pointer by default. Previously when + wrapping: + + class SomeClass {...}; + void foo(SomeClass *s); + + and it was called from Java with null: + + modulename.foo(null) + + a Java NullPointerException was thrown. Extra typemaps had to be written in + order to obtain a NULL pointer to pass to functions like this one. Now the + default wrapping will detect 'null' and translate it into a NULL pointer. + Also if a function returns a NULL pointer, eg: + + SomeClass *bar() { return NULL; } + + Then this used to be wrapped with a SomeClass proxy class holding a NULL + pointer. Now null is returned instead. These changes are subtle but useful. + The original behaviour can be obtained by using the original typemaps: + + %typemap(javaout) SWIGTYPE { + return new $&javaclassname($jnicall, true); + } + %typemap(javaout) SWIGTYPE *, SWIGTYPE &, SWIGTYPE [] { + return new $javaclassname($jnicall, $owner); + } + %typemap(javagetcptr) SWIGTYPE, SWIGTYPE *, SWIGTYPE &, SWIGTYPE [] %{ + protected static long getCPtr($javaclassname obj) { + return obj.swigCPtr; + } + %} + + *** POTENTIAL INCOMPATIBILITY FOR JAVA MODULE *** + + +11/12/2002: beazley + Fixed problem with abstract methods and signatures. For example: + + class abstract_foo { + public: + virtual int meth(int meth_param) = 0; + }; + + + class abstract_bar : public abstract_foo { + public: + int meth(int meth_param_1, int meth_param_2) { return 0; } + }; + + In this case, abstract_bar is still abstract. + + Fixes [ 628438 ] Derived abstract class not abstract. + Reported and patched by Scott Michel. + +11/11/2002: beazley + Fixed a matching problem with typemaps and array dimensions. For example, if you + had this: + + typedef char blah[20]; + + and a typemap: + + %typemap() char [ANY] { + ... $1_dim0 ... + } + + then $1_dim* variables weren't be expanded properly. It should work now. + Problem reported by Pankaj Kumar Goel. + +11/07/2002: mkoeppe + Added an experimental new module that dumps SWIG's parse + tree as (Common) Lisp s-expressions. The module is + invoked with SWIG's -sexp command-line switch. The output + can be read into Common Lisp. There is (prototype) + example Lisp code that generates Foreign Function Interface + definitions for use with Kevin Rosenberg's UFFI. + + *** EXPERIMENTAL NEW FEATURE *** + +11/07/2002: mkoeppe + Removed duplicate declaration of "cpp_template_decl" in + parser.y; bison 1.75 complained. + +11/06/2002: cheetah (William Fulton) + [Java] Default primitive array handling has changed like arrays of classes. + C primitive arrays are no longer wrapped by a Java array but with a pointer + (type wrapper class). Again the changes have been made for efficiency reasons. + The original typemaps have been moved into arrays_java.i, so the original + behaviour can be obtained merely including this file: + + %include "arrays_java.i" + + The array support functions are no longer generated by default. They are only + generated when including this file, thus this often unused code is only + generated when specifically requiring this type of array support. + + *** POTENTIAL INCOMPATIBILITY FOR JAVA MODULE *** + +11/05/2002: ljohnson (Lyle Johnson) + [Ruby] Added support for nested module declarations (as was + previously added for the Perl module). So a %module directive + of the form: + + %module "Outer::Inner::Foo" + + will nest everything as (in Ruby code): + + module Outer + module Inner + module Foo + # stuff goes here + end + end + end + +11/05/2002: mkoeppe + [MzScheme] Add an argument (-declaremodule) that generates + code to correctly declare a primitive module extension. + Patch submitted by Bruce Butterfield. + +11/02/2002: cheetah (William Fulton) + [Java] Added patch submitted by Michael Cahill to remove unused parameter + warnings for the jenv and cls parameters. This patch also also allows one + to use "void" in the jni typemap for any type without code being generated + attempting to return a value. + +10/29/2002: cheetah (William Fulton) + [Java] Array handling is different. Arrays of classes are no longer wrapped + with proxy arrays, eg wrapping + + class X {...}; + X foo[10]; + + used to be wrapped with these Java getters and setters: + + public static void setFoo(X[] value) {...} + public static X[] getFoo() {...} + + This approach is very inefficient as the entire array is copied numerous + times on each invocation of the getter or setter. These arrays are now + wrapped with a pointer so it is only possible to access the first array element + using a proxy class: + + public static void setFoo(X value) {...} + public static X getFoo() {...} + + Arrays of enums have also been similarly changed. This behaviour is now like the + other SWIG language's implementation and the array library should be used to + access the other elements. The original behaviour can be achieved using the + macros and typemaps in arrays_java.i, for example: + + %include "arrays_java.i" + JAVA_ARRAYSOFCLASSES(X) + class X {...}; + X foo[10]; + + *** POTENTIAL INCOMPATIBILITY FOR JAVA MODULE *** + +10/29/2002: cheetah (William Fulton) + [Java] Two new typemaps javain and javaout for generating the proxy class + and type wrapper class method calls to the JNI class. The new typemaps are + really used for transforming the jstype (used in proxy class and type wrapper + classes) to the jtype (used in the JNI class) and visa versa. A javain typemap + is required whenever an in typemap is written and similarly javaout for an out + typemap. An example is probably best to show them working: + + %typemap(javain) Class "Class.getCPtr($javainput)" + %typemap(javain) unsigned short "$javainput" + %typemap(javaout) Class * { + return new Class($jnicall, $owner); + } + + %inline %{ + class Class {}; + Class * bar(Class cls, unsigned short ush) { return new Class(); }; + %} + + The generated proxy code is then: + + public static Class bar(Class cls, int ush) { + return new Class(exampleJNI.bar(Class.getCPtr(cls), ush), false); + } + + + Some new special variables have been introduced in order to use these typemaps. + Here $javainput has been replaced by 'cls' and 'ush'. $jnicall has been replaced by + the native method call, 'exampleJNI.bar(...)' and $owner has been replaced by 'false'. + $javainput is analogous to the $input special variable. It is replaced by the parameter name. + $jnicall is analogous to $action in %exception. It is replaced by the call to the native + method in the JNI class. + $owner is replaced by either true if %newobject has been used otherwise false. + + The java.swg file contains default javain and javout typemaps which will produce the same code + as previously. This change is only of concern to those who have written their own typemaps as + you will then most likely have to write your own javain and javaout typemaps. + + The javaout typemap also makes it possible to use a Java downcast to be used on abstract + proxy base classes. See the Java documentation on dynamic_cast. + + *** POTENTIAL INCOMPATIBILITY FOR JAVA MODULE *** + +10/24/2002: ttn + [Methodology] Upgaded to libtool 1.4.3, presumably w/ better + support for newish platforms (like MacOS X). + +10/21/2002: ttn + Fixed Runtime/Makefile.in bug -- thanks to Richard Calmbach. + +10/18/2002: ttn + Fixed typo in doh.h -- thanks to Max Horn. + +Version 1.3.16 (October 14, 2002) +================================= + +10/13/2002: beazley + Fixed bug with %extend directive and %feature reported + by William Fulton. + +10/13/2002: beazley + Added OpenVMS build directory (vms). Contributed by + Jean-François Pieronne. + +10/09/2002: cheetah (William Fulton) + [Java] Added throws clause to the native functions in the JNI class. + The throws clause is the same as the one generated for proxy functions + and module class functions. + +09/27/2002: beazley + Fixed some problems with the %import directive and classes that + were defined but not wrapped. Problem reported by Leslie Brooks, + Gerry Woods, and others. + +09/23/2002: cheetah (William Fulton) + [Java] Some error checking added: + 1) OutOfMemoryException check in the char * typemaps. + 2) As SWIG treats pointers, references and passing by value all the + same, it is possible to pass a NULL pointer to a function that expects + an object passed by value or by reference. A NullPointerException is + now thrown under this scenario. + +09/20/2002: ttn + [Methodology] Reworked "make clean" and "make install" + to be more table driven. + [Docs] Explain how to extend "make install" w/ extra-install.list. + +09/15/2002: beazley + Deprecation of the "ignore" typemap. The "ignore" typemap has + been deprecated in favor of a generalization of the "in" typemap. + To ignore an argument, use something like this instead: + + %typemap(in,numinputs=0) int *output (int temp) { + $1 = &temp; + } + + This change fixes a number of subtle bugs related to the interaction + of the "in" and "ignore" typemaps (which were supposed to be + mutually exclusive). + + The use of the numinputs argument is reserved for future expansion. + Currently, values >1 will generate an error. However, future + releases of SWIG may utilize that to support multi-input typemaps. + + %typemap(ignore) still works, but generates a warning message and is + translated to %typemap(in,numinputs=0). + + *** POTENTIAL INCOMPATIBILITY *** + *** NEW FEATURE *** + +09/15/2002: beazley + Fixed segmentation fault for unnamed structures. For example: + + typedef struct { + } *blah; + + + Reported by Roger Gibson. + Note: we might be able to generate wrappers in special cases. + +09/13/2002: beazley + Minor modification to generated wrapper functions. Pointer arguments are now + always set to an initial value of 0. Simplifies typemap writing and cleanup + code (since you can rely on zero-value initialization). This also greatly + reduces the need to ever write an "arginit" typemap. + +09/12/2002: beazley + Minor enhancement to smart-pointer support. If operator->() + is part of an ignored base class like this, + + %ignore Bar; + + class Foo { + public: + int blah(); + }; + + class Bar { /* Ignored */ + public: + ... + Foo *operator->(); + ... + }; + + class Spam : public Bar { }; + + then methods from Foo are still available. For example, + + >>> s = Spam() + >>> s.blah() + 0 + >>> + + The only catch is that the operator->() itself is not available + (since it wasn't wrapped). Therefore, there won't be any + __deref__() operation unless it is explicitly added to Spam + (either using %extend or just placing operator->() in the + definition of Spam). + +09/11/2002: ttn + [Methodology] Reworked "make check" to be more table driven. + [Docs] Docuemented methodology in Manual/Extending.html. + +09/11/2002: ttn + [Docs] Prefixed Manual/*.html with "" to + pander dotingly to (over-)sensitive editors. + +09/10/2002: ttn + [Guile] Converted Examples/guile/simple "make check" + behavior to actually check execution results. Reduced + iteration counts so that the test doesn't take too long. + +09/10/2002: beazley + SWIG-1.3.15 released. + + +Version 1.3.15 (September 9, 2002) +================================== + +09/09/2002: beazley + Fixed nasty runtime type checking bug with subtypes and inheritance + and templates. + +09/09/2002: cheetah (William Fulton) + [Java] Java exception classes for a method's throws clause can be generated by + specifying them in a comma separated list in the throws attribute in any one + of the following typemaps: in, out, check, freearg, argout and throws. A classic + example would be to convert C++ exceptions into a standard Java exception: + + %typemap(throws, throws="java.io.IOException") file_exception { + jclass excep = jenv->FindClass("java/io/IOException"); + if (excep) + jenv->ThrowNew(excep, $1.what()); + return $null; // or use SWIG_fail + } + + class file_exception {...}; + void open(const char *filename) throw(file_exception); + + The Java method will then be declared with a throws clause: + + public static void open(String filename) throws java.io.IOException {...} + +09/08/2002: mkoeppe + * [Guile] Improved the documentation system. The arglist no + longer gets cluttered with type specification, making it + more readable. (Also the ILISP function C-u M-x + `arglist-lisp' RET works better this way.) The types of + arguments are explained in an extra sentence after the + arglist. + + There are now two documentation-related typemap arguments: + + %typemap(in, doc="$NAME is a vector of integers", + arglist="$name") int *VECTOR { ... } + + The "arglist" texts of all arguments of a function make up + its arglist in the documentation. The "doc" texts of all + arguments are collected to make a sentence that describes + the types of the arguments. Reasonable defaults are + provided. + + As usual, $name is substituted by the name of the + argument. The new typemap variable $NAME is like $name, + but marked-up as a variable. This means that it is + upper-cased; in TeXinfo mode ("-procdocformat texinfo") it + comes out as @var{name}. + + The directives %values_as_list, %values_as_vector, + %multiple_values now also have an effect on the + documentation. (This is achieved via the new pragmas + return_nothing_doc, return_one_doc, return_multi_doc.) + + Documentation has also improved for variables that are + wrapped as procedures-with-setters (command-line switch + "-emit-setters"). + + * [Guile] Emit constants as _immutable_ variables. (This + was broken recently.) + +09/07/2002: mkoeppe + [Guile] Updated the typemaps in list-vector.i. + +09/07/2002: mkoeppe + Short-circuit the typechecks for overloaded functions. + (The changes in code generation are visible in the new + testcase "overload_complicated".) + +09/06/2002: cheetah (William Fulton) + [Java] Solution for [ 596413 ] + New typemap so that the Java proxy classes and type wrapper classes + wrapper constructor modifier can be tailored by users. The default value is + protected. Normally SWIG generates a constructor like this which can only + be accessed within one package: + + protected Bar(long cPtr, boolean cMemoryOwn) { + ... + } + + If you are using SWIG across multiple packages or want to use this constructor + anyway, it can now be accessed outside the package. To modify use for example: + + %typemap(javaptrconstructormodifiers) SWIGTYPE "public" + + to change to public for all proxy classes and similarly for all type wrapper classes: + + %typemap(javaptrconstructormodifiers) SWIGTYPE, SWIGTYPE *, SWIGTYPE &, SWIGTYPE [] "public" + +09/06/2002: cheetah (William Fulton) + [Java] Added throws typemaps for the Java module. C++ exceptions get converted into + java.lang.RuntimeException Java exceptions. + + Warning: This may change from java.lang.Runtime exception in the future. + +09/05/2002: cheetah (William Fulton) + [Java] Fix for variables declared as references. + +09/05/2002: beazley + Fixed [ 605162 ] Typemap local variables. Reported by Lyle Johnson. + +09/05/2002: ljohnson (Lyle Johnson) + [Ruby] More updates to the Ruby module documentation, including + a new typemap example that demonstrates how to collect key-value + pairs from an argument list into a Hash. + +09/05/2002: beazley + Fixed bug with template expansion and constructors. + + template class Foo { + public: + Foo() { } + }; + + The extra in the constructor was carried through in the + name--causing runtime problems in generated modules. + Reported by Jordi Arnabat Benedicto. + +09/05/2002: mkoeppe + [Guile] Support overloading. + +09/04/2002: ljohnson (Lyle Johnson) + [Ruby] Updated typemaps for long long and unsigned long long types + to use Ruby 1.7 support for these types when available. + +09/04/2002: ljohnson (Lyle Johnson) + [Ruby] Added output typemaps for const reference to primitive + types. + +09/04/2002: mkoeppe + [Guile] Fix pass-by-value typemaps. Reported by Arno + Peters via Debian bugtracking (#156902), patch by Torsten + Landschoff . + +09/03/2002: samjam (Sam Liddicott) + Better reference support. + Functions that want a void** can take a NULL by reference and + the void* will be made for you and then passed-by-reference + + Also all integer-class native types can be passed by reference + where an int* or int& etc is needed + +09/03/2002: beazley + Changed the evaluation order of preprocessor macro arguments. + Arguments are now expanded by the preprocessor *before* they + are passed to macro expansion. This fixes a subtle expansion + bug reported by Anthony Heading. + +09/03/2002: beazley + Fixed the file include order (again, apparently). See 2/27/99. + +09/02/2002: beazley + [Perl] Better exception handling support. Since Perl error handling + relies on setjmp/longjmp, wrapper functions have been modified slightly + to provide an extra block scope: + + XS(foo) { + char _swigmsg[SWIG_MAX_ERRMSG] = ""; + const char *_swigerr = _swigmsg; + { + /* Normal wrapper function here */ + ... + SWIG_croak("An error occurred\n"); + ... + XSRETURN(argvi); /* Successful return */ + fail: + /* cleanup code */ + } + croak(_swig_err); + } + + The macro SWIG_croak(x) sets the value of _swigerr to x and + executes a "goto fail". The whole wrapper function is enclosed + block scope to provide proper cleanup of C++ objects. Since + croak executes a longjmp(), there is no way to properly reclaim + resources if this executes in the same scope as the wrapper + function. + + The _swigmsg[] variable is normally unused, but can be used + to store small error messages using sprintf or snprintf. It + has a capacity of at least 256 bytes (SWIG_MAX_ERRMSG). + +09/02/2002: beazley + [Tcl] Added better support for exceptions. Instead of returning TCL_ERROR, + use the macro SWIG_fail to return with an error. This ensures that + arguments are properly cleaned up. Exception specifiers are now + handled by default. + +09/02/2002: ljohnson (Lyle Johnson) + [Ruby] The type-checking system for the Ruby module has had a flaw + in that some types which should be considered equivalent + weren't. This bug was best demonstrated by the inherit_missing.i + test suite case, which defines a base class "Foo" that is + subclassed by "Bar". The "Foo" class isn't actually wrapped (i.e. + it's not directly accessible from Ruby) but we'd still like to be + able to pass "Bar" instances to functions expecting Foos and have + that work; it wasn't. The revised implementation (similar to that + used for some other language modules) adds a new instance variable + (__swigtype__) to each object that indicates its SWIG type; + that is, each "Bar" instance will now have a string instance + variable called "__swigtype__" whose value is "_p_Bar". + + Unless developers were taking advantage of this low-level + implementation detail, they shouldn't notice any compatibility + problems; nevertheless, I'm marking it as a "potential + incompatibility". + + *** POTENTIAL INCOMPATIBILITY *** + +09/01/2002: ljohnson (Lyle Johnson) + [Ruby] Fixed SF Bug #603199. + +08/08/2002: cheetah (William Fulton) + [Java] Added OUTPUT, INPUT and INOUT typemaps in typemaps.i for C++ + references. + +08/27/2002: mkoeppe + [Guile] Fixed error in "lib_std_vector" testcase and + compiler warning in "lib_cdata" testcase. + +08/27/2002: ljohnson (Lyle Johnson) + [Ruby] Added the "%mixin" directive, which allows the user to + specify a comma-separated list of module names to mix-in to a + class. So, for example, if you'd like to specify that Ruby's + Enumerable module should be mixed-in to your class Foo, you'd + write: + + %mixin Foo "Enumerable"; + + or to specify that the modules Fee, Fie and Fo should be mixed + in to Foo: + + %mixin Foo "Fee,Fie,Fo"; + + *** NEW FEATURE *** + +08/27/2002: ljohnson (Lyle Johnson) + [Ruby] Modified the %alias directive so that multiple aliases + can be specified for an instance method by using a comma-separated + list of aliases. + +08/27/2002: ljohnson (Lyle Johnson) + [Ruby] Added "throw" typemaps for the Ruby module. + +08/26/2002: beazley + Two new command line options for printing dependencies. + 'swig -M' lists all file dependencies. 'swig -MM' lists + dependencies, but excludes files in the SWIG library. + Example: + + % swig -M -python example.i + example_wrap.cxx: \ + /u0/beazley/Projects/lib/swig1.3/swig.swg \ + /u0/beazley/Projects/lib/swig1.3/python/python.swg \ + example.i \ + example.h + + % swig -MM -python example.i + example_wrap.cxx: \ + example.i \ + example.h + + *** NEW FEATURE *** + +08/26/2002: beazley + Fixed [ 597599 ] union in class: incorrect scope. + Reported by Art Yerkes. + +08/26/2002: beazley + Fixed [ 600132 ] Default argument with namespace. + Reported by Shibukawa Yoshiki. + +08/24/2002: beazley + Automatic C++ exception handling enabled for all language modules. This is + pretty simple. If you have a class like this: + + class Foo { + }; + class Bar { + public: + void blah() throw(Foo); + } + + then the generated wrapper code looks like this: + + wrap_Bar_blah() { + ... + try { + arg1->blah(); + } + catch (Foo &_e) { + /* "throw" typemap code inserted. $1 = _e */ + } + catch (...) { + throw; + } + } + The "throw" typemap can be used to raise an error in the target + language. It can do anything. Here is a very simple example: + + %typemap("throw") Foo { + PyErr_SetString(PyExc_RuntimeError, "Foo exception"); + return NULL; + } + + To make this work in each language module, simply define a few default + "throw" typemaps for SWIGTYPE, SWIGTYPE *, int, const char *, and a + few common exception types. That's all there is to it. + + Automatic exception handling can be disabled using -noexcept or + setting the NoExcept global variable to 1. + *** NEW FEATURE *** + +08/23/2002: beazley + [ Python ] + Automatic translation of C++ exception specifications into error handling code. + For example: + + class Foo { + }; + class Bar { + public: + void blah() throw(Foo); + } + + In this case, Foo is wrapped as a classic-style class (compatible + with exception handling). Furthermore, you can write Python code + like this: + + b = Bar() + try: + b.blah(); + except Foo,e: # Note use of exception class here! + # Handle Foo error + ... + + The object "e" in the exception handler is just a wrapped Foo + object. Access it like a normal object. + + If an exception is not wrapped as a class, a RuntimeError + exception is raised. The argument to this exception is + the exception object. For example: + + class Bar { + public: + void blah() throw(int); + } + + b = Bar() + try: + b.blah(); + except RuntimeError,e: + print e.args[0] # Integer exception value + + Comments: + + - If a class is used as an exception, it *must* be wrapped + as a Python classic-style class (new classes don't work). + + - Automatic exception handling is compatible with %exception. + + - Use -noexcept to turn off this feature. + + - The newly introduced "throw" typemap is used to raise + Python errors (naturally). + + *** EXPERIMENTAL NEW FEATURE *** + +08/23/2002: beazley + Information from throw() specifiers is now stored in the parse + tree. For example: + + class Foo { + public: + int blah() throw(spam,bar); + } + + The stored information is fully corrected for namespaces and works + with templates. Uses will follow. + +08/22/2002: beazley + Exception handling code is no longer applied to member access + function. For example, in this code + + %exception { + try { + $action + } catch(whatever) { + ... + } + } + + class Foo { + public: + int x; + ... + } + + The exception handling code is not applied to accessor functions + for Foo::x. This should reduce the amount of extra code + generated. + + Caveat: Exception handling code *is* used when attributes are + accessed through a smart-pointer or a synthesized attributed + added with %extend is used. + +08/22/2002: beazley + Made more patches to hopefully eliminate problems when compiling SWIG + as a 64-bit executable. + +08/22/2002: beazley + Fixed a bug with const reference members, variables, and static members. + For example: + + class Foo { + public: + static const int &ref; + }; + + SWIG was trying to generate "set" functions which wouldn't compile. + +08/21/2002: beazley + Made the warning message for "Class X might abstract" off by default. + Enable with -Wall. + +08/21/2002: beazley + Refined handling of const and non-const overloaded methods. If + a class defines a method like this: + + class Foo { + public: + int bar(int); + int bar(int) const; + } + + Then the non-const method is *always* selected in overloading and + the const method silently discarded. If running with -Wall, a warning + message will be generated. + +08/19/2002: beazley + Better support for using declarations and inheritance. Consider this: + + class Foo { + public: + int blah(int x); + }; + + class Bar { + public: + double blah(double x); + }; + + class FooBar : public Foo, public Bar { + public: + char *blah(char *x); + using Foo::blah; + using Bar::blah; + }; + + Now SWIG wraps FooBar::blah as an overloaded method that uses all + accessible versions of blah(). See section 15.2.2 in Stroustrup, 3rd Ed. + + SWIG also supports access change through using declarations. For example: + + class Foo { + protected: + int x; + int blah(int x); + }; + + class Bar : public Foo { + public: + using Foo::x; + using Foo::blah; + }; + + + Caveat: SWIG does not actually check to see if declarations imported + via 'using' are in the inheritance hierarchy. If this occurs, the + wrapper code won't compile anyways---not sure it's worth worrying about. + +08/18/2002: beazley + Modified overloading dispatch to not include nodes with an "error" attribute. + A language module can set this if a node couldn't be wrapped and you don't want + it included in the dispatch function. + +08/18/2002: beazley + Enhancement to overloaded function dispatch. The dispatcher is now aware of + inheritance relationships. For example: + + class Foo { }; + class Bar : public Foo { }; + + void spam(Foo *f); + void spam(Bar *b); + + In this case, the dispatcher re-orders the functions so that spam(Bar *b) is + checked first---it is more specific than spam(Foo *f). + +08/17/2002: beazley + Added -Werror command line option. If supplied, warning messages are treated + as errors and SWIG will return a non-zero exit code. + +08/17/2002: beazley + Fixed [ 596135 ] Typedef of reference can't compile. For example: + + typedef int &IntRef; + void foo(IntRef i); + + SWIG-1.3.14 generated code that wouldn't compile. + +Version 1.3.14 (August 12, 2002) +================================ + +08/11/2002: mmatus + Static const members initialized during declaration, and + only them, ie: + + struct A + { + static const int a = 1 ; // this one + static const int b; // not this one + }; + + are emitted like constants (equivalent to enums or + explicit %constant). + + This is because they cannot be added directly to 'cvar' + since they lack the needed reference (well, you can force + them to have a real reference, but in an ugly way which + goes completely again the original purpose of initialize + them during declaration, you also have to deal with extra + linking matters, and it take a while to figure out what is + the problem and how to solve it). + + Please test it with your preferred target language, and + not only the code generation, but really run the example + in the test-suite (static-const-member-2.i) because the + problem and the solution cannot be "fully" appreciated + until you try to load the module and run it. + + In some target languages (python specially), this can + produces a difference in the way that the static constant + members 'a' and 'b' are internally wrapped. Hopefully, + they still can be accessed in the same way. + + +08/11/2002: mmatus + [python] Now static const members can be accessed in a more + natural way, ie, if you have + + struct A + { + typedef unsigned int viewflags; + static const viewflags forward_field = 0; + static const viewflags backward_field; + }; + + now you can do: + + print A.backward_field + + and also + + a = A() + print a.forward_field + + Note that if the static const members don't have an + initializer (like backward_field), still you can access + them in the same way in the python side, but the + implementation is a quite different: backward_field will + still appear in the cvar entity, and also, you are + responsible to initialize it in some code unit, and link it + properly. forward_field, by the other hand, will not + appear in the cvar entity but only as a A member, similar + to what happen with enum or %constant members. + +08/11/2002: mmatus + [python] Common code in the __setattr__/__getattr__ now + goes to two "free" methods at the beginning of the proxy + file, from where each class use it. This change reduces + the size of the proxy file, specially if you wrap a lot of + small classes in one module (up to 33% in some cases), + making it faster to load too. + +08/09/2002: beazley + [Perl5] If a function that returns char * returns NULL, + undef is returned to the Perl interpreter. + +08/09/2002: beazley + Fix to conversion operators and namespaces. For example: + + namespace ns { + struct Foo { }; + struct Bar { + operator Foo*(); + }; + } + + In the wrapper code, SWIG was using ->operator Foo*() + when it should have been using ->operator ns::Foo*(). + + Note: if using %rename with a conversion operator, you + might have to do this: + + %rename(toFooPtr) ns::operator ns::Foo*(); + // ^^^^ note extra qualifier + namespace ns { + ... + + +08/09/2002: beazley + [Python] Minor enhancement to 'const' variable declarations. + Normally const declarations are wrapped as read-only variables + accessible only through the cvar attribute (see SWIG.html for + a discussion of why). However, in many programs, "const" + declarations may just be constants---making the cvar. access + awkward. To fix this, "const" declarations are now available + both through cvar. and as a simple name. For example: + + const int FOO = 42; + + In Python: + + >>> print example.cvar.FOO + 42 + >>> print example.FOO + 42 + + Note: There are cases where the value of a "const" variable + might change. For example: + + char *const BAR = "Hello World"; + + In this case, the pointer itself can not change, but the + data being pointed to could be modified. In these situations, + cvar.BAR should be accessed to obtained the current value. + +08/08/2002: beazley + [Python] Fixed generation of the proxy code (.py files) to more + closely follow the order of declarations as they appear in + the .i file. In the past, all of the class wrappers appeared + first, followed by function stubs, inserted Python code, and + other details. + +08/08/2002: cheetah (William Fulton) + [Java] Proxy method _delete() changed to delete(). There shouldn't ever + be a wrapped function called delete() as it is a C++ keyword and there + is no such thing as a member function in C. + + *** POTENTIAL INCOMPATIBILITY FOR JAVA MODULE *** + + Backwards compatibility can be achieved by adding the function back in + for all proxy classes: + %typemap(javacode) SWIGTYPE %{ + public void _delete() { + delete(); + } + %} + + Java backwards compatibility summary + ------------------------------------ + + There are a number of changes that have been made in improving the Java module + for ver 1.3.14. If at all possible change your code to take advantages of the + improvements. If you were using proxy classes you may not notice any backwards + compatibility issues. Here is an example which will help with most backwards + compatibility problems where it is not possible to modify the code that uses + the generated output: + + Replace: + %module modulename + + With: + %module (jniclassname="modulename") modulename; + %typemap(javacode) SWIGTYPE %{ + public long getCPtr$javaclassname() { + return swigCPtr; + } + public void _delete() { + delete(); + } + %} + %pragma(java) jniclassclassmodifiers="public"; + + The proxy constructors that took parameters (long cPtr, boolean cMemoryOwn) + were public and are now protected. If you were making use of these then you'll + have to modify your code and the best solution would be to use the new type + wrapper classes. + + The other main areas are the pragmas and global variable wrapping. Replace + the pragmas with one of the new directives or typemaps mentioned below and use + %rename on the variables. + + If you were not using proxy classes, you will have to define a jstype typemap + as well as a jtype typemap. + +08/08/2002: cheetah (William Fulton) + [Java] Fix for wrapping two dimension array variables. + +08/07/2002: beazley + [Python,Tcl] + Object management now has a much better sense of ownership. + Ownership bits is changed whenever an object is stored in a + global variable or structure member. For example: + + struct Foo { + int val; + Foo *next; + }; + + Now in Python + + >>> f = Foo() + >>> f.thisown + 1 + >>> g = Foo() + >>> g.next = f # Assign a pointer + >>> f.thisown # Notice ownership change + 0 + >>> + + This scheme is mostly a conservative heuristic designed to + provide segmentation faults. It could cause a memory leak + if ownership is changed unnecessarily. In this case, you can + either write a typemap (that doesn't change ownership), or + manually set the thisown attribute back to 1. + +08/07/2002: beazley + [Tcl] Major usability improvements to the object interface. + Suppose you had code like this: + + struct Foo { + int x; + int spam(); + }; + + void blah(Foo *f); + + In past versions of SWIG, you could create objects and use + them like this: + + % Foo f + % f configure -x 3 + % f spam + 37 + + The only problem is that if you tried to call blah(), it didn't + work: + + % blah f + Type Error. Expected _p_Foo + % + + Instead, you had to do this: + + % blah [f cget -this] + + SWIG now automatically extracts the -this pointer, avoiding this + problem. This means that saying "blah f" is perfectly legal and + everything will still work normally. + + Caveat: Since pointer strings start with a leading underscore (_), + don't use this in object names. For example: + + % Foo _f + % blah _f # Potential crash + + Objects now have a -thisown attribute that shows the ownership. + This builds upon the CHANGES 11/24/2001 entry. + +08/07/2002: samjam, Sam Liddicott + Properly implemented pointer system using php resources. + Still need to work out whether or not to let script-users call + destructors directly + +08/06/2002: beazley + Upgraded mzscheme module to support version 201 and added + overloading support. + +08/05/2002: beazley + Added parsing support for extra grouping (in very limited cases). + For example: + + typedef int (FuncPtr)(int, double); + + *** EXPERIMENTAL *** + +08/03/2002: ljohnson (Lyle Johnson) + [Ruby] Updates to typemaps.i as those done previously for Perl, + Python and Tcl modules. Now supports reference types with INPUT, + OUTPUT and INOUT typemaps. + +08/02/2002: beazley + New library file cstring.i added. Provides macros for + manipulating char * data. + +08/02/2002: beazley + Deprecated the %new directive. Use %newobject instead. For + example: + + %newobject foo; + ... + char *foo(); + + %newobject follows the same rules as %rename, %ignore, %feature, + etc. + + *** POTENTIAL INCOMPATIBILITY *** + +08/01/2002: cheetah (William Fulton) + [Java] New attribute 'jniclassname' for the module directive allows a way of + changing the JNI class name from the default which uses the modulename with JNI + appended after it. + + %module (jniclassname="name") modulename + + If 'name' is the same as 'modulename' then the module class name gets changed + from 'modulename' to modulenameModule. + +08/01/2002: beazley + Fixed problem with file include order. Language specific + directories should take precedence over generic directories. + For example: "swig_lib/python/foo.i" should be loaded before + "swig_lib/foo.i". I thought this was the case already, but + apparently it has been broken for quite some time. + +08/01/2002: beazley + Added std_deque.i library file. Work in progress. + +08/01/2002: beazley + [Python,Tcl,Perl] + Improvements to typemaps.i. INPUT/INOUT typemaps perform better + error checking. Typemaps are now supplied for references like + int &OUTPUT, double &INOUT, etc. + +08/01/2002: beazley + [Python] Deprecated the T_* and L_* typemaps in typemaps.i. + Multiple return values are always placed in a tuple. Deprecated + the BOTH typemaps. This is now INOUT (e.g., int *INOUT). + + *** POTENTIAL INCOMPATIBILITY FOR PYTHON MODULE *** + +08/01/2002: beazley + Deprecated the array.i, carray.i, and timer.i library files. + +08/01/2002: beazley + Deprecated the pointer.i library file. Use cpointer.i instead. + *** POTENTIAL INCOMPATIBILITY *** + +08/01/2002: cheetah (William Fulton) + [Java] For consistency the global variable getters and setters use the JavaBean + property design pattern like member variables always have. This means if you are + wrapping a variable called foo, the getter is called getFoo() and the setter is + called setFoo(). Before the recent changes to the Java module the getters and + setters were called get_foo() and set_foo(). If you really want the original + function names use the %rename directive like this: %rename(_foo) Foo; + +07/31/2002: beazley + Fixed casting problem with multiple inheritance. If you had this, + + class foo {}; + class bar : public foo {}; + class baz : public foo {}; + class spam : public bar, public baz {}; + + then the wrappers wouldn't compile due to an ambiguous cast. + Reported by Art Yerkes. + +07/30/2002: cheetah (William Fulton) + [Java] Due to new static typechecking all pointers held in a Java long are part of + the internal workings and this pointer value in the Java long has become abstracted + data. The type wrapper constructor and getCPtr() methods are as such protected. + If you need to mess around with pointers from Java or for example create a proxy + class or type wrapper class around a null pointer, add a function/constructor + to do so with the %javacode typemap. You can also make getCPtr() public again with + the %javagetcptr typemap. + +07/30/2002: cheetah (William Fulton) + [Java] Fixes for %typemap(ignore). In particular when ignoring the last parameter + in a function. Also for all parameters in constructors. These mods have also fixed + multi-argument typemaps for proxy classes - SF 581791. + +07/30/2002: cheetah (William Fulton) + [Java] %newobject (replacement for %new) now implemented for Java. + +07/29/2002: beazley + Fixed problem with typemap copies, %apply, and %clear inside + C++ namespaces. + +07/28/2002: cheetah (William Fulton) + [Java] The JNI class now has package access as the class modifier + has been changed from "public" to nothing. This has been done + as this class is now more for the internal workings of SWIG since the module + class has static type checking for all types. + + *** POTENTIAL INCOMPATIBILITY FOR JAVA MODULE *** + + Backwards compatibility can be achieved by using the %jniclassclassmodifier + pragma to change it back to "public". + +07/28/2002: cheetah (William Fulton) + [Java] Proxy/Shadow classes are generated by default. The -proxy and + -shadow command line options are deprecated. If you want to use the + low-level functional interface then use the new -noproxy commandline option. + + *** POTENTIAL INCOMPATIBILITY FOR JAVA MODULE *** + +07/28/2002: cheetah (William Fulton) + [Java] Remaining pragmas shakeup. These were the remaining pragmas and their + new names where changed: + + modulebase + modulecode + moduleclassmodifiers + moduleimport => moduleimports + moduleinterface => moduleinterfaces + + The moduleimports works slightly differently to how the moduleimport pragma worked. + Now it actually takes code which gets placed before the class definition so the + whole import statement has to be given, for example: + + %pragma(java) moduleimports=%{ + import java.io.*; + import java.math.*; + %} + + The moduleinterfaces is slightly different to the old moduleinterface in that if + more than one interface is required they must be comma separated in one use of + the pragma, for example: + + %pragma(java) moduleinterfaces="Serializable, MyInterface" + + These last two pragmas are consistent with the javainterfaces and javaimports + typemap. + + A similar set of pragmas has been introduced, namely: + + jniclassbase + jniclasscode + jniclassclassmodifiers + jniclassimport + jniclassinterface + + These work in the same way as their module counterparts. Note that previously + the moduleXXX pragmas worked on the old module class which is now called the + JNI class (the class with the native functions). The jniclassXXX pragmas now + work on the new module class (the class that has all the global functions and + global variable getters and setters when using proxy classes, plus all other + remaining functions when using the low-level procedural interface). + + In summary the contents of the pragmas make up a class like this: + + + class modulename extends implements { + + ... SWIG generated functions ... + } +} + *** POTENTIAL INCOMPATIBILITY FOR JAVA MODULE *** + +07/28/2002: cheetah (William Fulton) + [Java] Deprecated modulemethodmodifiers pragma and replaced with + a better %feature based directive called %javamethodmodifiers. + A useful example would be for synchronisation in multi-threaded apps: + + %javamethodmodifiers foo(int a) "public synchronized"; + + Changes this function from the default ("public") to "public synchronized". + + *** POTENTIAL INCOMPATIBILITY FOR JAVA MODULE *** + +07/26/2002: beazley + Several directives now allow optional configuration parameters. + These include: + + %module(name="value", name="value", ...) modulename + %import(name="value", ...) "filename.i" + %extend(name="value", ...) classname { + ... + } + + These currently have no effect and are reserved for + future expansion. + +07/26/2002: beazley + Enhancements to smart-pointer handling. SWIG only provides + extra support for a smart-pointer if operator->() returns + a proper pointer. For example: + + Foo *operator->(); + + If operator->() returns an object by value or reference, + then SWIG examines the returned object to see if it also + implements operator->(). If so, SWIG chases operator->() + until it can find one that returns a pointer. This allows + cases like this to work: + + class Foo { + public: + void blah(); + }; + + class Bar { + ... + Foo *operator->(); + ... + }; + + class Spam { + ... + Bar operator->(); + ... + }; + + For example: + + >>> s = Spam() + >>> s.blah() # Invokes Foo::blah() + + The s.blah() call actually invokes: + + ((s.operator->()).operator->())->blah(); + +07/26/2002: beazley + Fixed a bug with typedef and references. For example: + + typedef Foo & FooRef; + FooRef blah(); + + Previous versions of SWIG generated code that wouldn't + compile. + +07/25/2002: beazley + Wrapping of static methods has been improved in proxy classes. In older + versions of SWIG, if you had this: + + class Foo { + public: + static void bar(); + }; + + The static method was only available as a function Foo_bar(). For example: + + >>> Foo_bar() + + Now, the static method can also be invoked through an instance like this: + + >>> f = Foo() + >>> f.bar() # Invokes static method + + This works with all versions of Python. Additionally, for Python-2.2, + the static method can be invoked as: + + >>> Foo.bar() + + The old-style function is still support for backwards compatibility. If + you care about making your code across different versions of Python, + either use Foo_bar() or access the method through an instance. + +07/25/2002: beazley + Changes to the Python module. Proxy classes now utilize new Python-2.2 + features including properties and static methods. However, these features + are supported in a way that provides backwards compatibility with older + Python versions. In other words, proxy classes work with all versions + of Python and only use new features when running on Python-2.2. + + +07/25/2002: beazley + Modified %extend so that overloaded methods can be added. For example: + + %extend Foo { + void bar(int x) { }; + void bar(char *s) { }; + ... + } + + This works with both C++ *and* C. + +07/24/2002: cheetah (William Fulton) + [Java] More new typemaps so that the Java proxy classes and type wrapper classes + can be further tailored by users. These are the default code for generating the + finalize() methods (proxy classes only) and the getCPtr() methods for proxy + classes and type wrapper classes: + + %typemap(javafinalize) SWIGTYPE %{ + protected void finalize() { + _delete(); + } + %} + + %typemap(javagetcptr) SWIGTYPE, SWIGTYPE *, SWIGTYPE &, SWIGTYPE [] %{ + public static long getCPtr($javaclassname obj) { + return obj.swigCPtr; + } + %} + + The javagetcptr typemap will enable users to handle Java null by overriding + this typemap - a requested feature. + + The -nofinalize commandline option has been deprecated. The javafinalize + typemap is more powerful as it will allow the removal of the finalize methods + for all or any one or more particular proxy class. + +07/23/2002: cheetah (William Fulton) + [Java] The getCPtrXXX() function has been changed to a static function and + is now of the form: + + protected static long getCPtr(XXX obj) {...} + + This is a requested change which will allow Java null pointers to be used as null + can be passed in for obj. However, to achieve this the appropriate code must be + written using the new javagetcptr typemap directive. + + *** POTENTIAL INCOMPATIBILITY FOR JAVA MODULE *** + + Backwards compatibility can be achieved by adding this function back in using the + new javacode typemap: + + %typemap(javacode) SWIGTYPE %{ + + // SWIG-1.3.12 and SWIG-1.3.13 + public long getCPtr$javaclassname() { + return swigCPtr; + } + // SWIG-1.3.11 and earlier + public long getCPtr() { + return swigCPtr; + } + + %} + + +07/23/2002: cheetah (William Fulton) + [Java] New directive to control constant code generation - %javaconst. + The default handling for handling constants is to get the value through + a JNI call, eg + + #define YELLOW 5 + #define BIG 1234LL + + results in: + + public final static int YELLOW = modulename.get_YELLOW(); + public final static long BIG = modulename.get_BIG(); + + Earlier versions of the Java module initialised the value using the C value: + + public final static int YELLOW = 5; + public final static long BIG = 1234LL; + + This works in most cases, but the value for BIG won't compile as 1234LL is not + valid Java code and this is one of the reasons why the default is now to get the + values through a JNI call. The side effect is that these 'constants' cannot be used + in switch statements. The %javaconst directive allows one to specify the + way the constant value is initialised and works like other %feature + directives, eg + + %javaconst(0); // all constants from this point on are initialised using the C value + %javaconst(1) BIG; // just BIG initialised using JNI call (must be parsed before BIG is defined) + +07/23/2002: beazley + *** IMPORTANT CHANGES TO THE PYTHON MODULE *** + + (1) The Python module now enables shadow/proxy classes by default. + This means that two files are always created by SWIG. For + instance, if you have this: + + // file: foo.i + %module foo + ... + + Then swig generates two files "foo_wrap.c" and "foo.py". + + (2) The name of the low-level C extension module has been changed + to start with a leading underscore. This means that you have + to compile the module as follows: + + $ cc -c -I/usr/local/include/python2.2 foo_wrap.c + $ cc -shared foo_wrap.o $(OBJS) -o _foo.so + ^^^^ + note extra underscore + + This naming scheme is consistent with other Python modules that + utilize extension code. For instance, the socket module consists + of "_socket.so" and "socket.py". In previous versions of SWIG, + the shared object file was named "foocmodule.so". + + (3) A new directive can be used to insert Python code into + the corresponding .py file. For example: + + %pythoncode %{ + def foo(): + print "Hello World" + %} + + This directive allows you to create modules as a mix of C and Python. + Python code is seamlessly added to the module. + + (4) The -shadow command line option is deprecated. This is turned on + by default. + + (5) To disable the generation of the extra python file, use the "-noproxy" + command line option. + + *** POTENTIAL INCOMPATIBILITY *** + This change will likely break the build environment of projects that + utilize shadow classes. To fix this, you probably only need to + change the name of the target .so file. For example, if you have + Makefile information like this: + + TARGET = examplecmodule.so + + Just change it to: + + TARGET = _example.so + + *** DOCUMENTATION UPDATE *** + The file Doc/Manual/Python.html has been updated to describe these changes. + + +07/23/2002: beazley + Added -noextern option. If supplied, SWIG will not generate + extra extern declarations. This is sometimes an issue on + non-unix platforms. + +07/23/2002: beazley + Added a warning for ignored friend functions. + +07/23/2002: beazley + Fixed [ 574498 ] -proxy and %include "pointer.i" clash. + Reported by David Creasy. + +07/23/2002: beazley + Fixed [ 576103 ] global destruction warning with shadow. + Perl extensions should no longer report the warning + + "Use of uninitialized value during global destruction." + + when running with "perl -w". Reported by + Brett Williams. + +07/23/2002: beazley + In C++ mode, SWIG now always defines namespace std. By default, + it's empty. However, this will silence errors from programs + that include statements such as "using namespace std;". + This fixes Bug [ 584017 ] using namespace std generates error. + Reported by Joseph Winston. + +07/22/2002: beazley + Added a new warning message for %apply. If you use %apply but no typemaps + are defined, you will get a warning message. This should help with + problems like this: + + %apply char *OUTPUT { ... }; + + In old versions of SWIG, this silently did nothing. Now you get an error like this: + + file:line. Warning. Can't apply (char *OUTPUT). No typemaps are defined. + +07/22/2002: cheetah (William Fulton) + [Java] Started Java pragma deprecation. Replacements use %typemap based + directives and enable proxy classes and the new type wrapper classes to be + tailored in various ways. These are the new typemaps: + + %typemap(javabase) - base (extends) for Java class + %typemap(javaclassmodifiers) - class modifiers for the Java class: default is "public" + %typemap(javacode) - java code is copied verbatim to the Java class + %typemap(javaimports) - import statements for Java class + %typemap(javainterfaces) - interfaces (extends) for Java class + + And these are the %pragma directives being deprecated: + allshadowbase + allshadowclassmodifiers + allshadowcode + allshadowimport + allshadowinterface + shadowbase + shadowclassmodifiers + shadowcode + shadowimport + shadowinterface + + Note that it is possible to target a particular proxy class: + %typemap(javaimports) Foo "import java.util.*"; + or a particular type wrapper class: + %typemap(javaimports) double* "import java.math.*"; + Note that $javaclassname in these typemaps are substituted with either the proxy + classname when using proxy classes or the SWIGTYPE class name. + +07/18/2002: cheetah (William Fulton) + [Java] Java module overhaul to implement static type checking of all + types. + + 1) Changes when using Java Proxy classes + ---------------------------------------- + + Previously when wrapping global functions: + + class SomeClass{}; + void foo(SomeClass* s); + SomeClass* bar(); + + The native method prototypes used a long for pointers and looked like this: + + public class modulename { + ... + public final static native void foo(long jarg1); + public final static native long bar(); + } + + and unlike member functions of a C++ class there was no wrapper around the native calls + to make the use of them more user friendly. They would be used from Java like this: + + SomeClass s = new SomeClass(modulename.bar(), false); + modulename.foo(s.getCPtrSomeClass()); + + Note that the following will have the same effect, but then it would not have + been possible to call any proxy member functions in SomeClass: + + long s = modulename.bar(); + modulename.foo(s); + + Now wrapper functions are generated: + + public class modulename { + public static void foo(SomeClass s) { + // calls the native function + } + + public static SomeClass bar() { + // calls the native function + } + } + + Which means these functions can now be used more naturally with proxy classes: + + SomeClass s = modulename.bar(); + modulename.foo(s); + + 2) Changes when not using Java Proxy classes + -------------------------------------------- + + The so called low-level interface was rather low-level indeed. The + new static type checking implementation makes it less so but it remains a + functional interface to the C/C++ world. Proxy classes are the obvious way to use + SWIG generated code, but for those who want a functional interface all non-primitive + types now have a simple Java class wrapper around the C/C++ type. Pointers and + references to primitive types are also wrapped by type wrapper classes. The type + wrapper classnames are based on the SWIG descriptors used by the other language + modules. For example: + + C/C++ type Java type wrapper class name + ---------- ---------------------------- + int* SWIGTYPE_p_int + double** SWIGTYPE_p_p_double + SomeClass* SWIGTYPE_p_SomeClass + SomeClass& SWIGTYPE_p_SomeClass + SomeClass SWIGTYPE_p_SomeClass + + Note that everything wrapped by SWIG is accessed via a pointer even when wrapping + functions that pass by value or reference. So the previous example would now be + used like this: + + SWIGTYPE_p_SomeClass s = example.bar(); + example.foo(s); + + Note that typedefs that SWIG knows about are resolved, so that if one has + + class Foo{}; + typedef Foo Bar; + + then any use of Bar will require one to use SWIGTYPE_p_Foo; + + Some considerations: + Make sure you make a firm decision to use either proxy classes or the functional + interface early on as the classnames are different. + + 3) Pointers and non-parsed types + -------------------------------- + Sometimes SWIG cannot generate a proxy class. This occurs when the definition of + a type is not parsed by SWIG, but is then used as a variable or a parameter. + For example, + + void foo(Snazzy sds); + + If SWIG has not parsed Snazzy it handles it simply as a pointer to a Snazzy. + The Java module gives it a type wrapper class around the pointer and calls it + SWIGTYPE_p_Snazzy. In other words it handles it in the same manner as types are + handled in the low-level functional interface. This approach is used for all + non-proxy classes, eg all pointer to pointers and pointers to primitive types. + + 4) Backwards compatibility + ----------------------- + Backwards compatibility is not an issue if you have been using proxy classes and + no global variables/functions. Otherwise some changes will have to be made. + The native methods still exist but they are now in a JNI class, which is called + modulenameJNI. As this class is really part of the internal workings, + it should not be required so the class has become protected. Some pragmas/directives + will hopefully be added to help with backwards compatibility. + + *** POTENTIAL INCOMPATIBILITY FOR JAVA MODULE *** + +07/18/2002: beazley + Modified wrapping of uninstantiated templates returned by + value. Just to be safe, they are now wrapped by SwigValueWrapper<> + just in case they don't define a default constructor. This + would be used if you had code like this + + Foo blah(); + void moreblah(Foo x); + + but you didn't instantiate Foo using %template. + We should probably add a warning for this. + +07/17/2002: beazley + Added an error check to detect shadowed template paramaters. + For example: + + template class Foo { + public: + int T; + }; + + This results in an error, not a warning. This warning is + also needed to fix some rather insidious problems like + this: + + struct T { + int blah; + }; + + template class Foo { + public: + typedef T Traits; // Which T is this???? + }; + + In this case, the template parameter T shadows the outer + structure (which is what you want). + +07/16/2002: beazley + Improved support for templates with integer arguments. SWIG is + much more aware of situations such as this: + + const int Size = 100; + + %template(Foo100) Foo<100>; + void bar(Foo *x); // Knows that Foo is the same as Foo<100>; + +07/15/2002: beazley + Fixed bug with %feature/%ignore/%rename and namespaces. + For example: + + %ignore Foo::Bar + namespace Foo { + class Bar { + ... + }; + } + + Reported by Marcelo Matus. + +07/09/2002: beazley + Added parsing support for constructors that try to catch + exceptions in initializers. For example: + + class Foo { + Bar b; + public: + Foo(int x) try + : b(x) { ... } + catch(int) { + ... + } + } + + This has no effect on the generated wrappers. However, the try and catch + parts of the declaration are ignored. See Stroustrup, 3rd Ed, section + 14.4.6.1 for details. + +07/06/2002: beazley + Fixed bug in template symbol table management. This fixes + two bugs. First, mixing abstract methods, templates, and + inheritance no longer generates a failed assertion. + + template + class A { + public: + virtual void foo() = 0; + }; + + template + class B : public A + { + }; + %template(A_int) A; + %template(B_int) B; + + This fix also fixes a subtle problem with default values and + templates. For example: + + template + struct B { + typedef unsigned int size_type; + static const size_type nindex = static_cast(-1); + void foo(size_type index = nindex); + }; + + Bugs reported by Marcelo Matus. + + +07/05/2002: ljohnson (Lyle Johnson) + [Ruby] Changed the definition of the SWIG_ConvertPtr() function + for the SWIG/Ruby runtime support so that it looks like the + Python version. If the last argument (flags) is non-zero, + SWIG_ConvertPtr() will raise an exception for type mismatches + as before. If flags is zero, this function will return -1 for + type mismatches without raising an exception. + + *** POTENTIAL INCOMPATIBILITY FOR RUBY MODULE *** + +07/04/2002: beazley + Overloaded functions/methods/constructors now work in many language + modules. The support is completely transparent--just call the + function normally and SWIG will dispatch to the correct implementation. + There are a variety of issues associated with this. Please refer + to the overloading section of Doc/Manual/SWIGPlus.html for details. + *** NEW FEATURE *** + +07/04/2002: beazley + Fixed a bug with namespaces, enums, and templates. For example: + + namespace hello { + enum Hello { Hi, Hola }; + + template + struct traits + { + typedef double value_type; + }; + + traits::value_type say_hi() + { + return traits::value_type(1); + } + } + SWIG wasn't generating wrappers that properly qualified + traits. Reported by Marcelo Matus. + +06/30/2002: beazley + Supplied array variable typemaps for Tcl module. If you have a + variable like this: + + int foo[10]; + + then a set function like this is generated: + + void foo_set(int *x) { + memmove(foo,x,10*sizeof(int)); + } + +06/30/2002: beazley + New %fragment directive. When writing typemaps, it can be easy to + get carried away and write a lot of code. However, doing so causes + tremendous code bloat. A common way to solve this is to write + helper functions. For example: + + %{ + void some_helper_function() { + ... + } + %} + + %typemap(in) type { + some_helper_function(...); + } + + The only problem with this is that the wrapper file gets polluted + with helper functions even if they aren't used. To fix this, + a new fragment directive is available. For example: + + (corrected typo in line below - 06/26/2008) + %fragment("type_header","header") %{ + void some_helper_function() { + ... + } + %} + + %typemap(in, fragment="type_header") type { + some_helper_function(...); + } + + In this case, the code fragment is only emitted if the typemap is + actually used. A similar capability is provided for declaration + annotation and the %feature directive. For example: + + %feature("fragment","type_header") SomeDeclaration; + + The first argument to %fragment is the fragment name. The second argument + is the file section where the fragment should be emitted. + + The primary use of this directive is for writers of language modules + and advanced users wanting to streamline typemap code. + + *** EXPERIMENTAL NEW FEATURE *** + +06/30/2002: beazley + Supplied memberin typemaps for all arrays in an attempt to eliminate + confusion about their use. + +06/29/2002: beazley + Experimental support for smart-pointers. When a class defines + operator->() like this + + class Foo { + ... + Bar *operator->(); + ... + }; + + SWIG locates class Bar and tries to wrap its member variables and + methods as part of Foo. For example, if Bar was defined like this: + + class Bar { + public: + int x; + int spam(); + }; + + You could do this (in the target language): + + f = Foo() + f.x = 4 # Accesses Bar::x + f.spam() # Accesses Bar::spam + + The primary use of this feature is to emulate the behavior of C++ + smart-pointers---which allow attributes to accessed transparently + through operator->. + + This feature is supported automatically in SWIG---no special directives + are needed. To disable this behavior. Use %ignore to ignore + operator->. + *** NEW FEATURE *** + +06/26/2002: beazley + Deprecated the %except directive. %exception should be used instead. + +06/25/2002: beazley + Major cleanup of the modules directory. Eliminated most + header files, consolidated module code into single files. + +06/24/2002: beazley + Reworked the instantiation of language modules. All language + modules must now define a factory function similar to this: + + extern "C" Language * + swig_python(void) { + return new PYTHON(); + } + + This function is then placed in a table and associated with + a command line option in swigmain.cxx. + + This approach has a number of benefits. It decouples the + SWIG main program from having to know about the class + definitions for each module. Also, by using a factory + function, it will be easier to implement dynamic loading + of modules (simply load the file and invoke the factory + function). + +06/24/2002: beazley + Fixed syntax error for reference conversions. For example: + + operator Foo &(); + +06/24/2002: beazley + Fixed syntax error for operator new[] and operator delete[]. + +06/24/2002: beazley + Fixed code generation problem for constants and default arguments + involving templates. + +06/19/2002: ljohnson (Lyle Johnson) + [Ruby] Fixed a bug for the '-feature' command line argument; + that setting was effectively being ignored and so the feature + name was always set equal to the module name. + +06/17/2002: beazley + Fixed problems with static members and enums in templates. + +Version 1.3.13 (June 17, 2002) +============================== + +06/16/2002: beazley + Fixed a bug with __FILE__ expansion in the preprocessor. On Windows, + the backslash (\) is now converted to (\\) in the string literal + used for __FILE__. Reported by Steve Glaser. + +06/14/2002: beazley + Fixed warning message about 'name private in this context'. The + warning is only generated for public methods. Reported by + Scott Michel. + +06/14/2002: beazley + Fixed some problems related to template instantiation + and namespaces. When SWIG expands a template, it does + so with fully resolved types. For example, if you have this: + + template class foo { }; + typedef double Double; + %template(foo_d) foo; + + then, it is handled as foo in the typesystem. + This fixes a number of subtle problems with inheritance + and templates. + +06/14/2002: ljohnson (Lyle Johnson) + [Ruby] Added missing bool typemaps for INPUT, OUTPUT and + INOUT in Lib/ruby/typemaps.i. + +05/29/2002: cheetah (William Fulton) + [Java] Fix for a couple of broken pragmas. + +05/29/2002: cheetah (William Fulton) + Fix for unnecessary cast when wrapping global variable where + the type is not parsed by SWIG - Java variables example + failure as reported by Larry Virden. + +06/10/2002: beazley + Modified %template to allow for empty instantiations. + + %template() foo; + + This registers foo with the type system, but + doesn't wrap it (same as %ignore). This may only be a + temporary measure. SWIG might be able to automatically + instantiate templates in certain cases. + +06/10/2002: beazley + Fixed function prototype problems with Tcl 8.4 + +06/09/2002: beazley + Fixed problem with templates and location of base classes. + This one is a little mind-bending, but here is an example + that illustrates: + + template + struct traits + { + typedef ArgType arg_type; + typedef ResType res_type; + }; + + template + struct Function + { + }; + + template + struct Class : Function::arg_type, + typename traits::res_type> + { + }; + + %template(traits_dd) traits ; + %template(Function_dd) Function ; + %template(Class_dd) Class ; + + + In this example, the base class of 'Class' is determined from + the Function template, but the types are obtained through typedefs. + Because of this, SWIG could not locate the wrapped base class + (Function). Should be fixed in 1.3.13 even + though I can think of a million other things that might + also be broken. + +06/07/2002: beazley + Fixed a problem with conversion operators. If you had an + operator like this, + + operator double() const; + + SWIG was ommitting the "const" qualifier. This affected + %rename and other directives. Reported by Zhong Ren. + +06/07/2002: beazley + Lessened the strictness of abstract class checking. If + you have code like this: + + class Foo { + public: + virtual int method() = 0; + }; + + class Bar : public Foo { + public: + Bar(); + ~Bar(); + }; + + SWIG will go ahead and generate constructor/destructors + for Bar. However, it will also generate a warning message + that "Bar" might be abstract (since method() isn't defined). + In SWIG-1.3.12, SWIG refused to generate a constructor at all. + +06/07/2002: beazley + Change to %template directive. If you specify something like this: + + %template(vi) std::vector; + + It is *exactly* the same as this: + + namespace std { + %template(vi) vector; + } + + SWIG-1.3.12 tried to instantiate the template outside of the namespace + using some trick. However, this was extremely problematic and full + holes. This version is safer. + +06/07/2002: beazley + Fixed bug with scope qualification and templates. For example: + + A::DD + + Before, this was separated as scopes A, and DD. Fixed now. + +06/06/2002: beazley + Allow the following syntax: + + class A { }; + struct B : A { ... }; + + A base class without a specifier is assumed to be public for a struct. + +06/06/2002: beazley + Fixed syntax error with template constructor initializers. + Reported by Marcelo Matus. + +06/06/2002: beazley + Fixed bug with default template arguments. + Reported by Marcelo Matus. + +06/05/2002: beazley + Fixed subtle problems with %rename directive and template + expansion. + + Code like this should now work: + + %rename(blah) foo::method; + ... + template class foo { + public: + void method(); + }; + + %template(whatever) foo; + +06/05/2002: beazley + Resolved some tricky issues of multi-pass compilation and + and inheritance. The following situation now generates + an error: + + class Foo : public Bar { + ... + }; + + class Bar { + ... + }; + + The following code generates a warning about incomplete classes. + + class Bar; + class Foo : public Bar { }; + + The following code generates a warning about an undefined class. + + class Foo : public Bar { }; // Bar undefined + + This fixes a failed assertion bug reported by Jason Stewart. + +06/05/2002: ljohnson + [Ruby] Added a warning message for the Ruby module about the lack + of support for multiple inheritance. Only the first base class + listed is used and the others are ignored. (Reported by Craig + Files). + +06/03/2002: beazley + Fixed a bug with struct declarations and typedef. For example: + + typedef struct Foo Foo; + struct Foo { + ... + }; + + A few other subtle struct related typing problems were + also resolved. + +Version 1.3.12 (June 2, 2002) +============================= + +05/30/2002: beazley + Fixed problem related to forward template class declarations and + namespaces. Bug reported by Marcelo Matus. + +05/30/2002: beazley + Added 'make uninstall' target. Contributed by Joel Reed. + +05/29/2002: beazley + Fixed rather insidious bug with %rename, %feature and template specialization. + For example: + + %exception vector::__getitem__ { + ... some exception ... + } + + template class vector { + ... + T __getitem__(int index); // Fine + ... + }; + + template<> class vector { + ... + T __getitem__(int index); // Oops. + ... + }; + + Now, the %exception directive (and other features) should correctly apply to + both vector and specializations. + +05/29/2002: beazley + Subtle changes to %template() directive. Template arguments are now + reduced to primitive types in template matching. For example: + + template class vector { + ... partial specialization ... + } + + typedef int *IntPtr; // Gross typedef + + // Gets the above partial specialization + %template(vectorIntPtr) vector; + + This change is extremely subtle, but it fixes a number of potential + holes in Luigi's STL library modules. For example: + + typedef int Integer; + %template(vectori) vector; + +05/29/2002: beazley + Fixed rather insidious typemap bug related to const. const + was being discarded through typedefs. + +05/29/2002: ljohnson (Lyle Johnson) + [Ruby] Added input typemaps for const references to primitive + types (in Lib/ruby/ruby.swg). + +05/29/2002: cheetah (William Fulton) + [Java] The java arrray support functions are enclosed by + a SWIG_NOARRAYS #define. Useful if not using arrays and + it is desirable to minimise the amount of compiled code. + +05/29/2002: cheetah (William Fulton) + [Java] Enums were not renamed when using %name or %rename + fix. + +05/28/2002: ljohnson + [Ruby] Modified the name of the wrapper functions for the + "new" singleton method and "initialize" instance method for + consistency with the other language modules. The wrapper name + for the function that implements "new" is alloc_classname and + the wrapper name for the function that implements "initialize" + is new_classname. + + +05/27/2002: beazley + Changes to runtime. Pointer conversion/creation functions + now almost always have an extra "flags" argument. For + example: + + SWIG_ConvertPtr(obj, void **, swig_type_info *ty, int flags); + ^^^^^^^^^^ + This extra parameter is reserved for future expansion and will + be used for more control over pointers in future versions. + +05/27/2002: beazley + Fix for C++ classes with private assignment operators. It + is now possible to safely return objects like this by value. + Caveat: the class must provide a copy constructor. + +05/26/2002: beazley + -proxy option added to many language modules. This is the + same as -shadow. We are merely changing terminology. + +05/26/2002: beazley + [perl] Fixed some inconsistencies in the -package option. + -package merely sets the package name to be used on the + wrappers. It does not change the name of the shared library + file or the name of the generated .pm file. This was + broken at some point, but works again now. + +05/25/2002: beazley + [perl] Fixed [ 475452 ] memory leak in return-by-value. + Problem related to static member variables returning newly + allocated objects. Reported by Roy Lecates. + +05/25/2002: beazley + [perl] Fixed [ 513134 ] %BLESSEDMEMBERS isn't always right. + Reported by Fleur Diana Dragan. + +05/25/2002: beazley + Fixed [ 540735 ] -importall and the -I option. + +05/25/2002: beazley + [guile] Fixed [ 532723 ] Default arg for char* can SegV. + Error in guile module. Reported by Brett Williams. + +05/25/2002: beazley + Subtle change to typemap application code. The "freearg" + typemap must exactly match up with the "in" or "ignore" + typemap. For example: + + %typemap(in) (char *data, int len) { ... }; + %typemap(freearg) char *data { ... }; + + void foo(char *data, int len); + + In this case, the "in" typemap is applied, but the + freearg typemap is not. This is because the freearg + typemap doesn't match up with the input argument sequence. + +05/25/2002: beazley + Fixed [ 548272 ] Default argument code missing braces. + Reported by Brett Williams. + +05/25/2002: beazley + Fixed [ 547730 ] SwigValueWrapper needed for constructors. + Reported by William Fulton. + +05/25/2002: beazley + Undefined identifiers now evaluate to 0 when evaluating + preprocessor expressions. For example: + + #if !FOO + ... + #endif + + where FOO is undefined or set to some non-numeric value. + + Fixes [ 540868 ] #if defined whatever - not parsed. + Reported by Adam Hupp. + + +05/24/2002: beazley + SWIG now ignores the C++ 'export' keyword. + +05/23/2002: beazley + Some refinement of type-name mangling to account for pointers, arrays, + references, and other embedded type constructs. + +05/23/2002: beazley + Initial attempt at supporting template partial specialization. At + the very least, it is parsed and the classes are stored. Matching + of instantiations to specialized version is more limited and based on + the SWIG default typemap rules: + + SWIGTYPE * + SWIGTYPE [] + SWIGTYPE & + + Now, why in the world would you want to use this feature? Other + than allowing for slightly modified class APIs, this capability is + primarily used to provide advanced wrapping support for STL-like + objects. It can also be mixed with typemaps. Here is an example: + + + /* Generic version */ + template class vector { + %typemap(in) vector * { + // A container of objects + } + }; + /* Partial specialization (pointers) */ + template class vector { + %typemap(in) vector * { + // A container of pointers to objects. + } + }; + /* Specialization (integers). */ + template<> class vector { + %typemap(in) vector * { + // A container of integers. + } + }; + + *** EXPERIMENTAL FEATURE *** + +05/23/2002: beazley + Enhancement to typemaps. Normally, typemap variables are + renamed to avoid conflicts. For example: + + %typemap(in) int * (int temp) { + $1 = &temp; + } + + This results in code that creates and uses variables "temp1","temp2", + "temp3" and so forth depending on how many times the typemap is used. + Sometimes you want a single variable instead. To do that, using + the following naming scheme: + + %typemap(in) int *(int _global_temp) { + } + + Is this case, a single variable _global_temp is emitted in the + wrapper functions. It is shared across all typemaps. Repeated + typemaps do not replicate the variable---they use the first one + emitted. + *** NEW FEATURE *** + +05/23/2002: beazley + Minor enhancement to typemaps. If you have this code, + + %typemap(in) Foo (int somevar = 3) { + ... + } + + the default value for somevar is now emitted into the wrapper code. + +05/22/2002: beazley + Fixed %extend to be better behaved in namespaces. If you have code + like this: + + namespace foo { + struct bar { + %extend { + void blah(); + }; + }; + } + + SWIG matches the blah() method to a C function named + void foo_bar_blah(foo::bar *self). + + This is consistent with the non-namespace version. + Bug reported by Marcelo Matus. + +05/22/2002: beazley + New library files: cpointer.i, carrays.i, cmalloc.i. These + provide access to C pointers and memory allocation functions. + See Doc/Manual/Library.html for details. + +05/22/2002: cheetah (William Fulton) + [Java] C type char no longer maps to Java type byte, but to Java type char. + It is now treated as a character rather than a signed number. This fits in + with the other language modules and is a more natural mapping as char* is + mapped as a string of characters. Note that the C signed char type is still + mapped to a Java byte. + + *** POTENTIAL INCOMPATIBILITY FOR JAVA MODULE *** + +05/22/2002: cheetah (William Fulton) + [Java] Improved constants wrapping. Constants (#define and %constant) values + are now obtained through a JNI call. Previously the value was compiled as + Java code, but this didn't work for all cases, eg #define 123ULL. + +05/22/2002: beazley + Fixed bogus error message with %extend directive and C++ + access specifiers. Reported by Marcelo Matus. + +05/22/2002: beazley + Namespaces and enums now work correctly. For example: + + namespace Foo { + enum Bar { A, B }; + } + + Bug reported by Marcelo Matus. + +05/21/2002: beazley + The %types directive can now be used to specify inheritance relationships + in the runtime type system. For example, + + %types(Foo = Bar); + + specifies that Foo isa Bar. Using this is potentially quite dangerous. + However, this is useful in certain cases (and in the SWIG library). + +05/20/2002: beazley + %nodefault and %makedefault directives now require a trailing semicolon. + For example: + + %nodefault; + ... + %makedefault; + + In addition both directives can take a class name. For example: + + %nodefault Foo; + + class Foo { /* No default constructor/destructor */ + }; + + class Bar { /* Default constructor/destructor generated */ + }; + + *** POTENTIAL INCOMPATIBILITY *** + If you don't use the trailing semicolon, things will mysteriously break. + +05/20/2002: beazley + More improvements to type system handling. SWIG now correctly handles + template names and parameters in a namespace. For example: + + namespace foo { + template class bar { }; + typedef int Integer; + + void blah(bar *x); + }; + + In the generated code, all of the typenames are properly qualified. + +05/17/2002: cheetah (William Fulton) + [Java] deprecated broken -jnic and -jnicpp commandline options. The C or C++ + JNI calling convention is now determined from the -c++ commandline option. + +05/16/2002: cheetah (William Fulton) + [Java] The JCALL macros which exist so that the same typemaps can be used + for generating both the C and C++ JNI calling conventions no longer appear + in the generated code. This is because the output is now passed through the + SWIG preprocessor which does the macro expansion for either C or C++ (depending + on whether -c++ is passed on the SWIG commandline). + + The generation of the functions used in the array typemaps have been adjusted + to take account of this. The side effect is that any typemaps which contained + JCALL macros within %{ %} brackets will have to be moved within {} brackets + so that the SWIG preprocessor can expand the macros. + + *** POTENTIAL INCOMPATIBILITY FOR JAVA MODULE *** + +05/13/2002: beazley + Class templates may now be used as template parameters. For example: + + template class C> class Foo { + ... + }; + template class Bar { + ... + }; + + %template(Fooi) Foo; + + SWIG doesn't really do anything special with this---it's just + another way of specifying a template parameter. + +05/13/2002: beazley + Minor refinement of template support. Template parameter names are no longer + required for types. For example: + + template class Foo { + }; + + Obviously, names are required for template; + +05/12/2002: beazley + New macro expansion in typemaps. The sequence: + + $descriptor(type) + + Will expand into the SWIG type descriptor structor for + the given type. Type may be any abstract datatype. + For example: + + $descriptor(int *) + $descriptor(int (*)(int,double)) + $descriptor(vector *) + + Caveat: It is *NOT* currently legal to use other typemap + substitution variables in the macro. For example + $descriptor($1_type). + + The primary purpose of this modification is to better + support typemaps for container objects or to allow typemaps + that might be performing type conversions. + *** NEW FEATURE *** + +05/11/2002: beazley + The wrapping of references to primitive types has been + changed as follows: + + Arguments of type 'const primitive &' are now passed + by value as opposed to pointers. Return values of + type 'const primitive &' are returned as values instead of + pointers. + + 'primitive' is any one of int, short, long, long long, + char, float, double, bool (as well as unsigned variants). + + This change is being made to better support C++ wrapping--especially + code that makes use of templates and the STL. + +05/11/2002: beazley + The %template directive can now be used to access templates + in a namespace. For example: + + namespace std { + template class complex { + T re, im; + public: + complex(T _r = T(), T _i = T()) : re(_r), im(_i) { } + T real() { return re; } + T imag() { return im; } + }; + } + + %template(complex) std::complex; + + Note: There are some very subtle namespace/symbol table + management issues involved in the implementation of this. + It may not work in certain cases. + +05/10/2002: beazley + Member template constructor support added. For example: + + template + struct pair { + _T1 first; + _T2 second; + pair() : first(_T1()), second(_T2()) { } + template pair(const pair<_U1,_U2> &x); + }; + + To instantiate the template, use %template and %extend. + For example, this expands the constructor into a default + copy constructor: + + %extend pair { + %template(pair) pair<_T1,_T2>; + } + + Highly experimental. Other uses may be broken. + +05/10/2002: beazley + The %extend (%addmethods) directive no longer works unless + it appears in the public section of a class. An error + message is now generated (as opposed to a segmentation fault). + +05/09/2002: beazley + New %warnfilter() directive. This directive attaches a warning + filter to specific declarations and has the same semantics as + %rename, %ignore, %feature, and so forth. For example: + + %warnfilter(501) foo; // Suppress overloaded warning + int foo(int); + int foo(double); + + or + + %warnfilter(501) Object::foo(double); + class Object { + public: + int foo(int); + int foo(double); + }; + + This feature only suppresses warnings in later stages of code + generation. It does not suppress warnings related to preprocessing + or parsing. + *** NEW FEATURE *** + +05/09/2002: beazley + SWIG now supports C99 variadic preprocessor macros. For example: + + #define debugf(fmt,...) fprintf(stderr,fmt,__VA_ARGS__) + + The argument "..." is used to indicate variable arguments which + are all placed into the special argument name __VA_ARGS__ in + the macro expansion. + + SWIG also implements the GNU (##) extension for swallowing the + preceding comma when __VA_ARGS__ is empty. For example: + + #define debugf(fmt,...) fprintf(stderr,fmt, ##__VA_ARGS__) + + Here is how this is expanded: + + debugf("%d", 3) --> fprintf(stderr,"%d",3) + debugf("Hello") --> fprintf(stderr,"Hello" ) + + (notice the deleted comma). + *** NEW FEATURE *** + +05/08/2002: samjam (Sam Liddicott) + Many changes to php module. Shadow classes are now implemented + entirely in native C and no need for php-code shadow wrappers + Populated template config.m4 and Makefile.in as needed by + phpize are generated. + +05/08/2002: ljohnson (Lyle Johnson) + [Ruby] A copy constructor is now turned into a "clone" + instance method (see Dave's change for copy constructors + dated 4/7/2002). This seems like the appropriate thing + to do for Ruby code. + +05/08/2002: ljohnson (Lyle Johnson) + [Ruby] Fixed [ 553864 ] Inline destructor code not written. + +05/08/2002: beazley + %ignore behaves better with constructors, destructors, and the + type system in general. For constructors and destructors, + %ignore now suppresses the creation of a default constructor + or destructor. For example: + + %ignore ~Foo; + class Foo { + public: + Foo(); + ~Foo(); + ... + }; + + In SWIG-1.3.11, ~Foo() simply "disappeared" and the code generator + created a wrapper for a default destructor (as if it was never + declared in the interface). In SWIG-1.3.12, %ignore suppresses + the creation of a destructor if one is actually defined. + + Similarly, even though a declaration is ignored, information + may still be needed to properly handle types. For example, here + is a very subtle error that is fixed by this change: + + %ignore std::string; // Prevent class wrapping + namespace std { + class string { + ... + }; + %typemap(in) string * { + ... + } + } + + void foo(std::string *s); // Broken. + + Before this fix, %ignore would cause the class definition to disappear. + This, in turn, would cause the typemap to be misapplied. + +05/08/2002: beazley + Minor changes to %rename, %ignore, %feature, and related directives + for better support of destructors. Destructors can now be precisely + tagged. For example: + + %ignore Foo::~Foo; + %feature("action") ~Bar { + ... + } + + *Developer warning* + Operations such as renaming and feature attachment for classes used to + be applied to destructors as well. For instance, if you did this: + + %rename(Bar) Foo; + + The operation applied to the class itself, the constructor, and + the destructor. This is no longer the case. Now such operations + will only apply to the class and the constructor. Note: if you + were relying on this for class renaming, be aware that renamed + classes should really only be handled at the level of the class itself + and not the level of individual declarations in the class (although + they can be renamed individually if needed). As far as I know, + the Language class is already taking care of this case correctly. + +05/07/2002: beazley + New set of tests. The Examples/test-suite/errors directory contains + tests that try to exercise all of SWIG's error and warning messages. + +05/07/2002: beazley + Start of a warning framework. Warning messages are now assigned numeric values + that are shown in warning messages. These can be suppressed using the + -w option. For example: + + swig -w302 example.i + swig -w302,305 example.i + + Alternatively, the #pragma preprocessor directive can be used to disable this: + + #pragma SWIG nowarn=302 + #pragma SWIG nowarn=302,305 + + Note: Since SWIG is a multi-pass compiler, this pragma should + only be used to change global settings of the warning filter. It should + not be used to selectively enable/disable warnings in an interface file. + The handling of #pragma occurs in the C++ preprocoessor and affects all + subsequent stages of compilation. + + The -Wall option turns on all warnings and overrides any filters that + might have been set. + + Warnings can be issued from an interface using %warn. For example: + + %warn "110:%section is deprecated" + + The first part of a warning message is an optional warning number. + A complete set of warning numbers is found in Source/Include/swigwarn.h. + *** NEW FEATURE *** + +05/07/2002: beazley + Internal parsing change. Directives to include files now use brackets [ ... ] + instead of { ... }. + + %includefile "foo.i" [ + ... + ] + + The use of { ... } was a bad choice because they were included implicitly by + the preprocessor and made it impossible to properly detect legitimate missing '}' + errors. + +04/16/2002- +05/02/2002: beazley + SWIG European Tour: Paris-Amsterdam-Bath. + +04/23/2002: beazley + The %addmethods directive has been renamed to %extend. + For example: + + class Foo { + ... + }; + + %extend Foo { + int blah() { ... }; + int bar() { ... }; + ... + }; + + Motivation: the %addmethods directive can be used for many + other tasks including adding synthesized attributes, constructors, + and typemaps. Because of this, "addmethods" is somewhat misleading. + %extend more precisely describes this operation---extension of a + class or structure. + + *** POTENTIAL INCOMPATIBILITY *** + %addmethods still works via a macro definition. However, + a warning message may be generated. Errors involving %addmethods + will actually refer to the %extend directive. + +04/23/2002: beazley + Further refinement of the type system. Typedef now + propagates through functions, pointers to functions, + and pointers to member functions. + For example: + + typedef int Integer; + void foo(int (*x)(int), Integer (*y)(Integer)); + + In this case, arguments 'x' and 'y' have exactly + the same type (and would obviously accept objects + of either type). + + Similarly, consider this: + + class Foo { + }; + + typedef Foo Bar; + void bar(int (Foo::*x)(int), int (Bar::*y)(int)); + + In this case, arguments x and y are the same + type (via typedef). + +04/22/2002: beazley + SWIG now generates a warning message if any part of + an expression involves values from a private part of a class. + For example: + + class Foo { + private: + static int X; + public: + void blah(int a, int b = X); // Warning + }; + + In this case, the default argument is ignored. There + are workarounds, but they are rather clumsy. For instance, + you might do this: + + %feature("action") blah(int,int) { + if ($nargs == 1) { + result = blah(arg1); + } else { + result = blah(arg1,arg2); + } + } + void blah(int a, int b = 0); + + +04/21/2002: beazley + Use of the %inline directive inside a namespace is + forbidden and now generates an error message. This is + not allowed since the inlined code that is emitted is + not placed inside a namespace. This confuses other + stages of parsing. + +04/21/2002: beazley + Some bug fixes to casting operations and expression + parsing. Due to some parsing issues, it is not + currently possible to use casts for all possible + datatypes. However, the common cases work. + +04/20/2002: beazley (Amsterdam) + Member templates now work. Simply use the %template + directive inside a class or %addmethods to create + instantiations (see Doc/Manual/SWIGPlus.html). Supporting + this was easy---earlier changes to templates made it + possible using only a two-line modification to the parser + and a few minor modifications elsewhere. Hmmm, come to + think of it, the smoke was rather thick in that Internet "cafe". + *** NEW FEATURE *** + +04/19/2002: beazley (TGV) + Improved handling of non-type template parameters. For example: + + vector; + + Simple numbers and strings can be used with the %template + directive as well. For example: + + %template(vecint100) vector; + + Note: Arithmetic expressions are not currently allowed. + + Default template arguments now work and do not have to + be given to %template. + +04/18/2002: beazley (Paris) + Change in internal template handling. Template + parameters are now fully integrated into the type + system and are aware of typedefs, etc. This builds + upon the change below. + + *** DEVELOPER WARNING *** + Word of caution to language module writers. The "name" + parameter of certain parse tree nodes (classes, functions, etc.) + may be parameterized with types. This parameterization is + done using SWIG type-strings and not the underlying C version. + For example, + + int max(int *,int *) + + has a name of "max<(p.int)>". If you use the name directly, + you may get syntax errors in the generated code. To fix this, + use SwigType_namestr(name) to convert a parameterized name + to a C name with valid syntax. The internal version is + used to reduce template types to a common representation + and to handle issues of typedef. + +04/16/2002: beazley (somewhere over the Atlantic) + Enhancement of typedef resolution. The type system is now + aware of template arguments and typedef. For example: + + typedef int Integer; + + foo(vector *x, vector *y); + + In this case, vector and vector are + the same type. There is some interaction between this + mechanism and the implementation of typemaps. For example, + a typemap defined for vector * would apply to either type. + However, a typemap for vector * would only apply to + that type. + + Typedefs and typemaps and matched by left-most expansion. + For example: + + vector --> + vector --> + vector + + +04/24/2002: cheetah (William Fulton) + [Java] Changes to Java shadow classes. + Overcomes a bug where the module assumed that a pointer to a derived + class could be used in place of a pointer to a base class. Thanks + to Stephen McCaul for analysing the bug and submitting patches. + + A consequence is that the getCPtr() method in each shadow class has + disappeared and has been replaced with a getCPtrXXX(), where XXX is the + shadow class name. If you have code that previously used getCPtr(), + and the associated class is wrapping a C struct or a C++ class that + is not involved in an inheritance chain, just use the new method. If + however, the class is involved in an inheritance chain, you'll have + to choose which pointer you really want. Backwards compatibility + has been broken as not using the correct pointer can lead to weird bugs + through ill-defined behaviour. If you are sure you want the old methods, + you could add them back into all shadow classes by adding this at the + beginning of your interface file: + + %pragma(java) allshadowcode=%{ + public long getCPtr(){ + return swigCPtr; + } + %} + + Please see entry dated 07/23/2002 to see how to do this after the deprecation + of the allshadowcode pragma. + + *** POTENTIAL INCOMPATIBILITY FOR JAVA MODULE *** + +04/13/2002: beazley + Fixed problem with default arguments and references. Declarations such + as this should now work: + + void foo(const string &x = "Hello"); + +04/12/2002: beazley + Added typemap $* substitutions for typemaps involving arrays. + Requested by William Fulton. + +04/11/2002: beazley + Template specialization is now supported. For example: + + template<> class vector { + ... + }; + + When the %template directive is used, it will use a specialization + if one is defined. There are still some limitations. Partial + specialization is not supported. A template of type does + not match all pointers. + *** NEW FEATURE *** + +04/11/2002: beazley + Major change to template wrapping internals. Template declarations are + no longer processed as macros but now result in real parse-tree + nodes. The %template directive expands these nodes into a + specific instantiation. This change enables a number of + new and interesting capabilities: + + Directives such as %rename, %feature, and %addmethods can + now be applied to uninstantiated templates. For example: + + %rename(barsize) vector::bar(char *buf, int len); + ... + template class vector { + public: + ... + void bar(char *buf); + void bar(char *buf, int len); // Renamed + ... + }; + + %template(intvector) vector; // Renaming carries through + + + By parsing templates into an internal data structure, it will + be possible to support specialization (and maybe partial + specialization). + + This is highly experimental and a work in progress. + + *** POTENTIAL INCOMPATIBILITY *** + In SWIG-1.3.11, template declarations were simply processed + as weird macros. No other information was retained. This + made it impossible to support more advanced features and + complicated many other parts of the implementation. + +04/09/2002: beazley + Change to template class wrapping. There were a variety of + "issues" with the old approach related to parsing, the type + system, and namespaces. These changes are meant to rectify + some of these problems: + + A specific instantiation of a template can now be specified + by including the class inline like this: + + class vector { + public: + vector(); + ~vector(); + ... whatever ... + }; + + This is template specialization, but partial specialization is + not yet implemented. + + The %template directive has been modified to expand roughly as + follows: + + %template(vecint) vector; + + becomes + + %rename(vecint> vector; + class vector { + public: + vector(); + ... + }; + + Note that this simply builds upon the code above (templates + included inline). + + This modified approach to wrapping fixes some subtle type + issues. For instance, you can now define typemaps and typedefs + like this: + + %typemap(in) vector * { + ... + } + typedef vector intvector; + ... + void blah(intvector *v); // Gets the above typemap + + This did not work in SWIG-1.3.11 due to a peculiarity of + the template implementation. + + %template(name) no longer installs the template as a class + with name "name". This might break %addmethods as described + in the manual. For example: + + %template(vecint) vector; + %addmethods vecint { // Fails. vecint not a class + ... + }; + + To fix this, just use the template name instead: + + %addmethods vector { + ... + } + + Note: This technique might be a way to implement some bizarre + template specialization techniques. For example: + + %addmethods vector { + // Only applied if vector instantiated later + %typemap(in) vector * { + ... + } + ... + }; + + *** POTENTIAL INCOMPATIBILITY *** + +04/08/2002: beazley + Fixed [ 540868 ] #if defined whatever - not parsed. SWIG should + now correctly handle preprocessor directives like this: + + #if defined __cplusplus + ... + #endif + + Note: was implemented previously, but there was a minor bug. + Reported by Adam Hupp. + +04/07/2002: beazley + %readonly and %readwrite are deprecated due to a change in the + implementation. Instead of being pragmas, mutability is now + controlled as a "feature" using the following two directives: + + %immutable; + int x; // read-only variable + int y; // read-only variable + %mutable; + int z; // Modifiable + + %immutable and %mutable are much more powerful than their older + counterparts. They can now pinpoint a specific declaration like + this: + + %immutable x; /* Any x */ + %immutable Foo::x; /* x in class Foo */ + + In fact, the matching algorithm is the same as for %rename, + %ignore, and other directives. This means that the declaration + + %immutable Foo::x; + + would not only apply to class Foo but to all derived classes + as well. + + *** POTENTIAL INCOMPATIBILITY *** + %immutable and %mutable must be terminated by a semi-colon. This + differs slightly from the older %readonly and %readwrite directives. + Since %immutable and %mutable can be applied to declarations the + semicolon is needed to distinguish between a global feature and + one targeted to a single declaration. Note: this incompatibility is the + primary reason for changing the name of the directive. + +04/07/2002: beazley + New handling of copy constructors. If a class defines + constructors like this: + + class Foo { + public: + Foo(); + Foo(const Foo &); // Copy constructor + ... + }; + + SWIG now generates a function copy_Foo() for the copy + constructor. + + In previous verions, this generated a name-clash and an + error message. To preserve backwards compatibility, SWIG + does not change the behavior if %rename is used to resolve + the name conflict. However, if no name resolution is made, + this new approach is used. + + Copy constructors may be handled as a special case in the + target language. However, this is up to the language module + itself. + +04/07/2002: beazley + The %template directive is now namespace aware. This allows + code like this: + + namespace foo { + template max(T a, T b) { return a > b ? a : b; } + } + + using namespace foo; + %template(maxint) max; // Ok + + namespace bar { + using foo::max; + %template(maxdouble) max; // Ok + } + + Caveat: the template name supplied to %template must be defined in the + same scope in which the %template directive appears. This code is + illegal: + + %template(maxint) foo::max; + +04/07/2002: beazley + Minor enhancement to preprocessor. The preprocessor can now perform + string comparison. For example: + + #define A "hello" + ... + #if A == "hello" + ... + #endif + + The primary use of this is in SWIG macros. For example: + + %define FOO(x) + #if #x == "int" + /* Special handling for int */ + ... + #endif + %enddef + + Normal users can probably safely ignore this feature. However, it may + be used in parts of the SWIG library. + +04/07/2002: beazley + Further refinement of default constructor/destructor wrapper generation. + SWIG is now much more aware of pure virtual methods. For instance: + + class A { /* Abstract */ + public: + virtual void method1() = 0; + virtual void method2() = 0; + }; + class B : public A { /* Abstract */ + public: + virtual void method1() { }; + }; + + class C : public B { /* Ok */ + public: + virtual void method2() { }; + }; + + In this case, SWIG will only generate default constructors for C. + Even though B looks fine, it's missing a required method and is abstract. + +04/04/2002: beazley + Subtle change to structure data member access. If you + have a structure like this: + + struct Foo { + Bar b; + }; + + The accessor functions for b are generated as follows: + + (1) If b is *not* defined as a structure or class: + + Bar Foo_b_get(Foo *self) { + return self->b; + } + void Foo_b_set(Foo *self, Bar value) { + self->b = value; + } + + (2) If b *is* defined as a structure or class: + + Bar *Foo_b_get(Foo *self) { + return &self->b; + } + void Foo_b_set(Foo *self, Bar *value) { + self->b = *value; + } + See the "Structure data members" section of Doc/Manual/SWIG.html + for further details. + + *** POTENTIAL INCOMPATIBILITY *** + This may break interfaces that relied on a lot of a undeclared + structure and class names. To get the old behavior, simply + use a forward declaration such as "struct Bar;" + +04/04/2002: beazley + C++ namespace support added. SWIG supports all aspects of + namespaces including namespace, using, and namespace alias + declarations. The default behavior of SWIG is to flatten + namespaces in the target language. However, namespaces are + fully supported at the C++ level and in the type system. + See Doc/Manual/SWIGPlus.html for details on the implementation. + +04/02/2002: cheetah (William Fulton) + [Java] Sun has modified javac in jdk1.4 to no longer compile + an import of an unnamed namespace. To fix this SWIG no longer + generates the import for packageless classes. + http://developer.java.sun.com/developer/bugParade/bugs/4361575.html + As reported SF #538415. + +03/27/2002: ljohnson (Lyle Johnson) + [Ruby] Added support for pointer-to-member, similar to that + for the Python module. Remarkably similar. Also added a new + example for this (Examples/ruby/mpointer), which is remarkably + similar to the Python example of the same name. + +03/26/2002: ljohnson (Lyle Johnson) + [Ruby] Made a few minor edits to the "Advanced Topics" + chapter of the SWIG manual and added a new major section + about how to create multi-module Ruby packages with SWIG. + +03/26/2002: ljohnson (Lyle Johnson) + [Ruby] Removed all of the old Ruby pragmas. If any of this + functionality is truly missed we can resurrect it, preferably + with some kind of feature-based directive. + +03/25/2002: ljohnson (Lyle Johnson) + [Ruby] Fixed SWIG exception library support for Ruby, which + has apparently been broken for some time. Luckily, no one seems + to have noticed. + +03/23/2002: beazley + C++-namespace support in SWIG directives. + + %addmethods: + + The %addmethods directive now accepts a fully qualified classname + and can be used inside C++ namespace declarations. For example: + + // Attaches to the class Foo::Bar below + %addmethods Foo::Bar { + int somemethod() { ... } + }; + + namespace Foo { + class Bar { + public: + ... + }; + + // Attaches to the class Bar above + %addmethods Bar { + int othermethod() { ... }; + } + } + + %feature, %rename, %ignore, %exception, and related directives: + + Namespaces are fully integrated into the the renaming and declaration + matcher. For example: + + %rename(display) Foo::print; // Rename in namespace Foo + %ignore Foo::Bar::blah; // Ignore a declaration + + %rename directives can be placed inside namespace blocks as well. For + example: + + namespace Foo { + %rename(display) print; // Applies to print below + + void print(); + }; + + Most other SWIG directives should work properly inside namespaces. + No other changes are needed. + +03/22/2002: beazley + Some changes to internal symbol table handling. SWIG no longer + manages structures and unions in a separate namespace than normal + declarations like ANSI C. This means you can't have a structure + with the same name as a function. For example: + + struct Foo { + ... + } + + int Foo() { ... } + + This approach is more like C++. It's not clear that SWIG ever + really supported the ANSI C anyways---using the same name would + almost certainly generate a name-clash in the target language. + +03/22/2002: ljohnson (Lyle Johnson) + [Ruby] Fixed [ 517302 ] for handling of renamed overloaded + constructors. Now, renamed overloaded constructors are converted + into class singleton methods (basically acting as "factory" + methods). + +03/21/2002: beazley + Fixed [ 532957 ] %ignore parse error and casting operator. + Reported by William Fulton. + +03/18/2002: beazley (** ADVANCED USERS ONLY **) + Added support for dynamic casting in return values. A somewhat + common problem in certain C++ programs is functions that hide + the identity of underlying objects when they are returned + from methods and functions. For example, a program might include + some generic method like this: + + Node *getNode(); + + However, Node * may just be base class to a whole hierarchy + of different objects. Instead of returning this generic Node *, + it might be nice to automatically downcast the object into the + appropriate type using some kind dynamic cast. + + Assuming you understand the peril involved, a downcast can now + be performed using the following function in the run-time type + checker: + + swig_type_info *SWIG_TypeDynamicCast(swig_type_info *, void **ptr); + + This function checks to see if the type can be converted to another + type. If so, a different type descriptor (for the converted type) + is returned. This type descriptor would then be used to create + a pointer in the target language. + + To use this, you would write a typemap similar to this: + + %typemap(out) Node * { + swig_type_info *ty = SWIG_TypeDynamicCast($1_descriptor, (void **) &$1); + $result = SWIG_NewPointerObj($1, ty); + } + + Alternatively, + + %typemap(out) Node * = SWIGTYPE *DYNAMIC; + + To make the typemap have any effect, you have to write a supporting + function that knows how to perform downcasting. For example: + + %{ + static swig_type_info * + Node_dynamic_cast(void **ptr) { + Node **nptr = (Node **) ptr; + Element *e = dynamic_cast(*nptr); + if (e) { + *ptr = (void *) e; + return SWIGTYPE_p_Element; + } + Data *d = dynamic_cast(*nptr); + if (d) { + *ptr = (void *) d; + return SWIGTYPE_p_Data; + } + return 0; + } + %} + + There is no restriction on how types are determined. dynamic_cast<> + uses C++ RTTI. However, if you had some other mechanism for determining + the type, you could use that here. Note: it is important to save + the new pointer value back into the argument as shown. When downcasting, + the value of the pointer could change. + + Finally, to make the casting function available, you have to register + it with the run-time type checker. Put this macro in your interface file. + + DYNAMIC_CAST(SWIGTYPE_p_Node, Node_dynamic_cast); + + Note: this feature does not introduce a performance penalty on + normal SWIG operation. The feature is only enabled by writing + a new typemap that explicitly calls SWIG_TypeDynamicCast() to + make a conversion. + + Examples/test-suite/dynamic_cast.i contains a simple example. + This feature is not supported in the Java module due to differences + in the type-checking implementation. + + *** EXPERIMENTAL FEATURE *** + +03/17/2002: beazley + Small change to type-name handling of unnamed structures and + typedef. If a structure of this form appears: + + typedef struct { + ... + } Foo; + + Then 'Foo' is used as the proper typename for the structure. + Furthermore, Foo can now be used as a name in C++ inheritance. + SWIG was already kind of doing this, but this modification refines + the implementation to more closely follow the C++ ARM, section + 7.1.3, p. 106. This fixes a couple of obscure corner cases. + +03/16/2002: beazley + Modified C++ inheritance with a few enhancements. First, type information + needed for casting and type-equivalence is generated even when base-classes + aren't defined in the interface. For example: + + class Foo : public Bar { /* Bar unspecified */ + public: + ... + }; + + void blah(Bar *b); + + In this case, the blah() function still accepts Foo * even though nothing + is really known about Bar. Previous SWIG versions would just generate + a type error. + + Inheritance has also been modified to work through typedef. For example: + + class Bar { + }; + + typedef Bar OtherBar; + class Foo: public OtherBar { + } + + In this case, the base class of OtherBar is correctly resolved back to + Bar. The use of the name OtherBar is lost in this resolution (the wrappers + will simply use Bar instead of the typedef name OtherBar). + +03/13/2002: beazley + %typemap, %apply, and related directives can now appear inside + class definitions. + +03/13/2002: beazley + Fixed a variety of problems related to compiling SWIG on 64-bit + platforms. + +03/12/2002: beazley + Fixed problem with "ignore" and "in" typemaps. Local variables + associated with "in" were being added to the wrapper function even + though they were never used. Mostly harmless, but it would lead + to a variety of compilation warnings. + +03/12/2002: beazley + Some changes to the internal type system and handling of nested C++ + types. In previous versions of SWIG, if you had the following: + + class Foo { + public: + typedef int Blah; + }; + class Bar : public Foo { + public: + void somemethod(Blah x); + }; + + The argument type in somemethod() would implicitly be set to Bar::Blah. + Although this is technically allowed, it breaks typemaps. For example: + + %typemap(in) Foo::Blah { ... } + + doesn't match like you expect. This has been changed in SWIG-1.3.12. + Now, types are expanded using the class in which they were defined. + So, the argument type in somemethod() will be Foo::Blah---since the + type Blah was defined in Foo. + +03/10/2002: beazley + Fixed some subtle type scoping problems with typedef and C++ classes. + For example: + + typedef int Blah; + class Bar { + public: + typedef double Blah; + void foo(Blah x, ::Blah y); + ... + } + +03/10/2002: beazley + Highly experimental change to handle variable length arguments. + First, there is no portable or reliable way to wrap + a varargs function in full generality. However, you *can* change + the function signature using %varargs. + + %varargs(char *) fprintf; + ... + void fprintf(FILE *f, char *fmt, ...); + + In this case, the variable length parameter "..." is + simply replaced by the parameters given in %varargs. This + results in a function like this: + + void fprintf(FILE *f, char *fmt, char *s); + + More than one argument can be used and default values + can be defined. For example, this code specifies a + maximum of four arguments. + + %varargs(char *x1 = 0, char *x2 = 0, char *x3 = 0, char *x4 = 0) fprintf; + + *** EXPERIMENTAL NEW FEATURE *** + +03/10/2002: beazley + Change to handling of variable length arguments. varargs + is now handled as a proper parameter and is passed to the + code generator. However, it still can't be handled correctly + (and will generate a typemap warning). This change has been + made to better incorporate variable length arguments with other + directives such as %ignore, %rename, %feature, and so forth. + +03/10/2002: beazley + Fixed [ 522555 ] Syntax error parsing "define" construct. SWIG + is a little more restrictive in determining #define statements + that will be wrapped as constants. Also added a better parser + error rule for handling bad constants. + +03/08/2002: cheetah (William Fulton) + [Java] Bug fix: Classes renamed with %rename that are derived from + another class generate more appropriate shadow class code. + +03/08/2002: cheetah (William Fulton) + [Java] Fixed SF [ #523632 ] and [ #513335 ] both reported by Israel + Tanner. Support for types that are used which are in a typedef. The + appropriate shadow class name is generated. Also generated correct + shadow classname when a templated class is used within another + templated class. See the cpp_typedef.i testcase. + +03/08/2002: cheetah (William Fulton) + [Java] Bug fix: No type was generated in shadow classes for types + that weren't wrapped by SWIG. The type is treated as a raw + pointer, ie no shadow class. + +02/22/2002: beazley + Refined the matching algorithm used by %rename, %ignore, and + %feature. If a type signature is supplied, it must exactly + match that used in the declaration---including any use of + const. For example: + + %rename(foo1) foo(int); + %rename(bar1) bar(int) const; + + class Blah { + public: + void foo(int); // Matched --> foo1 + void foo(int) const; // Not matched + void bar(int); // Not matched + void bar(int) const; // Matched --> bar1 + } + + In previous versions, a non-const specification would match + both the non-const and const declarations. However, the whole + point of %rename and related directives is that they be able + to precisely pinpoint exact declarations in an interface. This + fixes the problem. + +02/21/2002: beazley + Reworked the handling of default constructor and destructors. + SWIG now makes a preliminary pass over the parse tree to discover + which classes support default allocation. This fixes a number + of very subtle issues in code generation and call/return by value. + +02/18/2002: cheetah (William Fulton) + Improved support on Cygwin: Perl, Python, Tcl, Ruby and Java should + work out of the box, barring the runtime library. Removed dllwrap + and replaced with newly working gcc -shared instead for Cygwin. + All this will require the new improved binutils 20010802 and later, + but the latest Cygwin is usually the best recommendation. + +02/15/2002: beazley + Fixed some problems related to wrapping of global variables + and Perl shadow classes. Reported by Chia-liang Kao. + +02/15/2002: ljohnson (Lyle Johnson) + [Ruby] Made a fix to the code generation for C++ class + constructors so that we get both a "new" singleton method + and an "initialize" instance method for each class. This + change enables developers to derive new Ruby classes from + SWIG-wrapped C++ classes and then override their initialize + methods to provide subclass-specific instance initialization. + +02/15/2002: ljohnson (Lyle Johnson) + [Ruby] Massive documentation update for the Ruby module, + contributed by Craig Files. + +02/14/2002: ljohnson (Lyle Johnson) + [Ruby] Bug fix: An error in the SWIG runtime support for Ruby + was causing several of the examples to fail. Reported by + William Fulton. + +02/14/2002: ljohnson (Lyle Johnson) + [Ruby] Bug fix: Enumerations defined within a class (such + as those seen in the Examples/ruby/enum example) were not + being exported with the correct names. Reported by William + Fulton. + +02/13/2002: ljohnson (Lyle Johnson) + [Ruby] Added a warning message when we run across overloaded + class constructors for C++ code, that this is currently not + supported (even if the overloads have been %renamed). For an + example of where this doesn't work, see Examples/ruby/operator. + +02/13/2002: ljohnson (Lyle Johnson) + [Ruby] Added an "ignored" warning message when the parser runs + across an operator!=() declaration for C++ code. + +02/11/2002: ljohnson (Lyle Johnson) + [Ruby] Added the "import", "import_template", "operator" and + "template" examples. + +02/11/2002: ljohnson (Lyle Johnson) + [Ruby] Added multi-module support. + +02/09/2002: ljohnson (Lyle Johnson) + [Ruby] Added the missing "#define SWIG_NOINCLUDE" at the top of + the wrapper code when the '-c' option is used. + +02/09/2002: ljohnson (Lyle Johnson) + Corrected a minor off-by-one error for the size of the + swig_types[] array that's generated in the wrapper code. + +02/08/2002: beazley + Fixed SF [ #515058 ] Wrong code for C++ templates. + Reported by Israel Taller. + +Version 1.3.11 (January 31, 2002) +================================= + +01/30/2002: beazley + Fix to pass/return by value for C++ objects that define + no default constructor. Changes to the typemap system + made it impossible to wrap C++ objects with no default + constructor. This has been fixed, but the solution + involves some clever template magic contributed by + William Fulton. Please see the comments in the file + Lib/swig.swg for further details. This solution is + experimental and may be refined in a future release. + +01/30/2002: beazley + Global variables and member data of type "const char *" + can be set, but the old value is silently discarded without + any garbage collection. This may generate a memory leak. + This change is needed to more safely handle variables + like this: + + const char *foo = "Hello World\n"; + + In this case, it's not safe to free the old value. However, + SWIG can dynamically allocate a new value and make foo point + to it. To fix this memory leak, you can probably do this: + + %clear const char *foo; + %apply char * {const char *foo}; + + *** POTENTIAL INCOMPATIBILITY *** + +01/30/2002: beazley + Two minor typemap enhancements have been added. First, + typemaps can issue a warning message by including a special + warning attribute. For example: + + %typemap(in,warning="I'm going to do something dangerous") ... + + The warning message will show up whenever the typemap is + applied. + + Second, a typemap can force a no-match by defining + + %typemap(in) sometype "pass"; + + If this is used, the typemap system will *not* record a + typemap match for "sometype". This can be used to block + selected typemaps. For example, if you wanted to disable + a typemap feature for some type, you could do this. + + // Do not allow global variables of type 'const char *' to be set. + %typemap(varin) const char * "pass"; + + It might also be possible to use this to do subtle and + strange things with typemaps. For example, if you wanted to + make 'blah *' an output value and 'const blah *' an input + parameter, you might do this: + + %typemap(ignore) blah *(blah temp) { + $1 = &temp; + } + %typemap(argout) blah * { + ... return a value ... + } + /* Block unqualified typemaps defined above */ + %typemap(ignore) const blah * "pass"; + %typemap(argout) const blah * "pass"; + %typemap(in) const blah * { + ... get input value ... + } + + (This potential applications of typemaps suggested by Greg Stein). + *** NEW FEATURE *** + +01/29/2002: cheetah (william fulton) + [Java] Bug fix: No enumerations were wrapped when the -shadow + commandline option was not specified. Reported by Israel Taller. + +01/28/2002: cheetah (william fulton) + [Java] Global arrays are successfully wrapped. In fact they started + mostly working in SWIG-1.3.10. + +01/28/2002:richardp + Added first attempt at C++ and -shadow support for PHP4 module, + please test and mail me if any problems/ideas on improving it. + + There is a known problem with uninitialized member variables, + please see Examples/php4/sync/README for details. + + Also more PHP documentation added to Doc/Manual/Php.html + +01/27/2002:beazley + The ANSI C size_t type is now recognized as an integer by default. + +01/26/2002:beazley + long long and unsigned long long support added to many language modules. + This is not a portable feature and will require compiler support + for the long long type. In target languages that do not support + long long (e.g., Tcl and Perl), numbers are converted to a string + of digits. This prevents their use in arithmetic calculations, but + still allows values to be set from a string. + + long long support requires the use of the strtoll() and strtoull() + functions as well as the 'lld' and 'llu' format specifiers + of sprintf(). + +01/26/2002:beazley + Fixed [ #501827 ] Delete method is not called. The Tcl + module wasn't correctly calling destructors when they + were defined using %addmethods. This has been fixed. + Reported by Reinhard Fobbe. + +01/26/2002: beazley + Better support for long long and unsigned long long. Typemaps + have been included in a number of modules for handling these types. + In addition, the parser has been modified to accept long long + literals such as 1234LL and 1234ULL. + +01/27/2002: cheetah (william fulton) + [Java] A C char[] is mapped to a Java String which is the default + SWIG handling of char[] and char*. It used to be mapped to byte[]. + Note that a C signed char[] array is mapped to byte[]. + + *** POTENTIAL INCOMPATIBILITY *** + +01/25/2002: beazley + Fixed a problem with return-by-value, C++, and + objects that define no default constructor. + Reported by Joel Reed. + +01/25/2002: cheetah (william fulton) + [Java] Overhaul of the Java module. The C code generation is now + done from typemaps. + +01/24/2002: cheetah (william fulton) + [Java] Support for arrays of enum pointers + +01/20/2002: cheetah (william fulton) + [Java] Error checking for null Java objects being passed to native + functions. Exception thrown now whereas before the JVM crashed. + +01/18/2002: cheetah (william fulton) + [Java] Corrected behaviour for functions that take arrays. For + example, when this c function: + + void arrayfn(int array[]); + + is wrapped the corresponding native function + + public final static native void arrayfn(int[] array); + + is produced. Previously if the C function made any changes to the + array elements, these were not reflected back into the Java array. + This has now been corrected so that the changes are propogated back + to Java and the calling function will see these changes. This is + how pure Java functions work, ie arrays are passed by reference. + +01/15/2002:mkoeppe + [Guile] New file cplusplus.i with C++ typemaps contributed + by Marcio Luis Teixeira . + +01/11/2002: cheetah (william fulton) + [Java] Changed mapping of C long to Java type. Was mapped to Java + long, now mapped to Java int. If you want the previous mapping to + Java long use this approach in your interface file: + + %clear long; + %typemap(jni) long "jlong" + %typemap(jtype) long "long" + %typemap(jstype) long "long" + + %clear long[ANY]; + %typemap(jni) long[ANY] "jlongArray" + %typemap(jtype) long[ANY] "long[]" + %typemap(jstype) long[ANY] "long[]" + %typemap(in) long[ANY] {write me for array support} + %typemap(out) long[ANY] {write me for array support} + %typemap(argout) long[ANY] {write me for array support} + %typemap(freearg) long[ANY] {write me for array support} + + *** POTENTIAL INCOMPATIBILITY *** + + This new mapping is more appropriate when interfacing to 32 bit + applications which are used in the current 32-bit JVMs. For future + 64-bit JVMs you may have to change these mappings - eg on Unix LP64 + systems, but not on Microsoft 64bit Windows which will be using a + P64 IL32 model. This may be automated in a future version of SWIG. + +01/10/2002:beazley + Fixed [ 501677 ] %init block in wrong place. Reported + by Luigi Ballabio. + +01/09/2002: cheetah (william fulton) + [Java] Default support for the long long type. signed long long is + mapped to a Java long. unsigned long long is mapped to BigInteger. + +01/09/2002:beazley + Experimental change to parser to better support mixing of + int, long, short, unsigned, float, and double. The parser + should now support types like this: + + short unsigned int + int unsigned short + unsigned short int + unsigned int short + + This change also enables a type of 'long double' (previously + unsupported) to be used. + *** NEW FEATURE *** + +01/05/2002: cheetah (william fulton) + [Java] Casting fix for when function return type is a pointer as + reported by Gary Pennington 2002-01-05. The upper 32bits of the + 64 bit jlong will have contained junk for 32bit pointers. + +01/05/2002: cheetah (william fulton) + [Java] Better pointer handling in Java is possible as the + INPUT, OUTPUT and INOUT typemaps have been added into typemaps.i. + +01/05/2002: cheetah (william fulton) + [Java] $null can be used in input typemaps to return early from JNI + functions that have either void or a non-void return type. Example: + + %typemap(check) int * %{ + if (error) { + SWIG_exception(SWIG_IndexError, "Array element error"); + return $null; + } + %} + + If the typemap gets put into a function with void as return, $null + will expand to nothing: + + void jni_fn(...) { + if (error) { + SWIG_exception(SWIG_IndexError, "Array element error"); + return ; + } + ... + } + + otherwise $null expands to zero, where javareturntype is either a + pointer or a primitive type: + + javareturntype jni_fn(...) { + if (error) { + SWIG_exception(SWIG_IndexError, "Array element error"); + return 0; + } + ... + } + +01/02/2002: cheetah (william fulton) + [Java] The Java module incorrectly used argout typemaps for + strings. This is now corrected and the code now resides + in the freearg typemap. The argout array typemaps have been split into + argout and freearg typemaps. This correction may require some user + written typemaps to be modified. + *** POTENTIAL INCOMPATIBILITY *** + +12/28/2001: cheetah (william fulton) + [Java] Multi typemaps now working for Java see multimap example. + [Java] Fix for recently introduced bug - freearg typemap code was appearing + before the function call. + +12/28/2001: cheetah (william fulton) + [Java] JCALL macro for JNI calls that work in both C and C++ typemaps + have been replaced with JCALL0, JCALL1, JCALL2, JCALL3 and JCALL4 + macros. + *** POTENTIAL INCOMPATIBILITY *** + +12/22/2001:beazley + Resolved some inconsistent behavior with %rename and class renaming. + If you specify the following: + + %rename(Foo) Bar; + + class Bar { + public: + Bar(); + ~Bar(); + } + + Then the %rename directive applies to the class itself, the constructor, + and the destructor (all will be renamed to Foo). + + If a class defines more than one constructor, the overloaded variants + can still be renamed by specifying parameters to %rename. For example: + + %rename(Bar_copy) Bar(Bar &); + class Bar { + public: + Bar(); + Bar(Bar &); + ~Bar(); + }; + + There are still some odd corner cases. If you specify + + %rename(Foo) ::Bar; + + then only the name of the class is changed and the constructor/destructor + names are left unmodified. If you specify + + %rename(Foo) *::Bar; + + then the names of the constructor/destructor functions are modified but + the name of the class is not. + +12/21/2001: cheetah (william fulton) + [Java] jni, jtype and jstype typemaps no longer hardcoded but real + typemaps. New variable substitution, $javaclassname, can be used in + the jstype typemaps. It is replaced with the Java shadow class name + where applicable. + [Java] Fix for recently introduced bug to do with inheritance when + using %import. + [Java] A few more bug fixes, todo with %rename and using the kind + with the type, eg + void fn(union uni myuni, struct str mystr, class cl mycl); + +12/20/2001:beazley + Fixed [ #494524 ] Preprocessor bug - apostrophe and #subst. + +12/20/2001:beazley + Added SWIG_VERSION preprocessor symbol. This is a hexadecimal + integer such as 0x010311 (corresponding to SWIG-1.3.11). This can + be used in the interface as follows: + + #if SWIG_VERSION >= 0x010311 + /* Use some fancy new feature */ + #endif + + Note: The version symbol is not defined in the generated SWIG + wrapper file. + + *** NEW FEATURE *** + +12/20/2001:mkoeppe + [MzScheme]: Renamed mzswig_make_boolean to + swig_make_boolean, as the latter is used in the typemaps. + Reported by Luigi Ballabio. + +12/17/2001:mkoeppe + [Guile]: Rewrote list-vector.i using multi-dispatch + typemaps. Updated pointer-in-out.i. Make the + deprecated typemap-substitution of "$source" in "argout" + work as before. + +12/16/2001:mkoeppe + [Guile]: Fixed macros %values_as_list, %values_as_vector, + %multiple_values to use the proper %pragma syntax. New + Guile example/test "multivalue"; new Guile run-test for + test-suite item "list-vector" (currently broken). + +12/14/2001:mkoeppe + [Guile]: Fixed typemap-substition bug for "varin". Relaxed + valid-identifier check to allow all R5RS identifiers. + + +Version 1.3.10 (December 10, 2001) +================================== + +12/08/2001:beazley + Modified %typemap so that %{ ... %} can also be used as a + code block (mostly for completeness). For example: + + %typemap(in) blah %{ + ... + %} + + This form does not introduce a new block scope. Also, the + code enclosed in %{ ... %} is not processed by the preprocessor. + +12/08/2001:beazley + Fixed [ #459614 ] SWIG with multiple TCL interpreters. + +12/08/2001:beazley + Fixed [ #417141 ] rubydec.swg is wrong + Reported by Paul Brannan. + +12/08/2001:beazley + Fixed [ #410557 ] Problem with %addmethods on NT. + Reported by Magnus Ljung. + +12/08/2001:beazley + Fixed [ #445233 ] Enhancement: handle access change. + SWIG now parses (but ignores) C++ access changes for the + the following: + + class A { + protected: + void something() { } + public: + A() {} + }; + + class B : private A { + public: + B() : A() { } + protected: + A::something; <---- Parsed, but ignored + }; + + Suggested by Krzysztof Kozminski. + +12/08/2001: cheetah (william fulton) + Fix for Ruby to work using Visual C++. + +12/06/2001:beazley + Fixed [ #465687 ] unsigned short parameters fail. + Reported by Gerald Williams. + +12/06/2001:beazley + Fixed SF [ #489594 ] PyString_FromString can't take NULL arg. + Reported by John Merritt. SWIG now converts string values + to Python using code like this: + + resultobj = result ? PyString_FromString(result) : Py_BuildValue(""); + +12/06/2001:beazley + Fixed SF [ #463561 ] Type conversions not generated. + Reported by Gerald Williams. + +12/04/2001:beazley + Fixed SF [ #470217 ] Tcl default argument handling. + Reported by Shaun Lowry. + +12/04/2001:beazley + Fixed SF [ #472088 ] defined(MACRO) expanded everywhere. + Embedded preprocessor directives such as + + %#if defined(FOO) + + are not expanded by the SWIG preprocessor. + Reported by Gerald Williams. + +12/04/2001:beazley + Fixed SF [ #476467 ] Problems with #define & commas. + +12/04/2001:beazley + Fixed SF [ #477547 ] wrong declaration of pointer functions. + Bad prototypes in Lib/tcl/ptrlang.i. + +12/04/2001:beazley + Fixed SF [ #483182 ] Constants can take args by mistake. + When swig -perl5 -const is used, constants are declared + with a void prototype. For example: + + sub ICONST () { $examplec::ICONST } + + Patch submitted by Rich Wales. + +12/03/2001:beazley + New %exception directive. This is intended to replace %except. + It works in exactly the same manner except it does not accept a + language specifier. For example: + + %exception { + try { + $action + } + catch(SomeError) { + error + } + } + + %exception is also name aware---allowing it to be applied to + specific declarations in an interface. For example: + + %exception foo { + ... + exception for any function/method foo + ... + } + + %exception Foo::bar { + ... + exception for method bar in class Foo + ... + } + + %exception Foo::bar(double) { + ... + exception for method bar(double) in class Foo + ... + } + + The semantics of this name matching is exactly the same as for %rename. + *** NEW FEATURE *** + +12/03/2001:beazley + Substantial cleanup of the Python shadow class code. Shadow classes + used to be created in this rather complicated manner involving about + a half-dozen strings created in bits and pieces. Shadow classes + are now generated in a more straightforward manner--in the same + order that appears in the interface file. + + *** POTENTIAL INCOMPATIBILITY *** + The order in which declarations appear in the shadow file may differ. + +12/03/2001:beazley + The %insert directive (%{ ... %}, %runtime, %header, %wrapper, etc.) + can now be used inside of a class definition. This has potential + uses when generating shadow class code. For example: + + class Foo { + ... + %insert("shadow") %{ + # Some python code + def blah(self): + print "I'm blah!" + %} + ... + }; + + The support for class code insertion depends on the language module. + However, the intent of this feature is to simplify the task of extending + shadow class code. In the Python module, this inserts code with the + proper level of indendation (regardless of what was used in the SWIG + interface). + *** NEW FEATURE *** + +11/29/2001: cheetah (william fulton) + Modifications for Java and Python modules to work on cygwin. + Unfortunately a lot of the python module has started to produces code + which cannot be auto-imported using cygwin libtools so most of it is + still broken. + +11/28/2001:beazley + The %rename and %feature directive can now be used inside + of a class definition. For example: + + class Foo { + %rename(foo_i) foo(int); + %rename(foo_d) foo(double); + public: + ... + void foo(int); + void foo(double); + ... + }; + + When used in this manner, the %rename directive only applies + to members of the class in which it appears as well as all + derived classes. In fact, this is really just the same + as saying: + + %rename(foo_i) Foo::foo(int); + %rename(foo_d) Foo::foo(double); + class Foo { + ... + }; + + *** NEW FEATURE *** + +11/26/2001:beazley + Added the experimental %feature directive. %feature can be + used to attach arbitrary string attributes to parse tree nodes. + For example: + + %feature("except") blah { + try { + $function + } catch (Error) { + whatever; + } + } + + or + + %feature("set") *::x_set "x"; + + or + + %feature("blah") Foo::bar(int,double) const "spam"; + + The syntax is borrowed from the %rename directive. In fact, the + exact same semantics apply (inheritance, matching, etc.). + + %feature is a very powerful low-level primitive that can be used to + customize individual language modules and to provide hints to + any stage of code generation. Features are attached to + parse tree nodes as attributes with names like "feature:*" where * + is replaced by the feature name (e.g., "feature:except", "feature:set", + etc.). Language modules can then look for the features using + a simple attribute lookup. + + %feature is intended to be a replacement for a number of + older SWIG directives including %except and specialized + pragmas. It is more powerful (due to its parameterized + name matching) and it provides very precise control over + how customization features are attached to individual + declarations. There are future expansion plans that will + build upon this capability as well. + + It's not certain that %feature will ever be used directly + by SWIG users. Instead, it may be a low-level primitive + that is used in high-level macro definitions. For instance, + to support properties, you might define a macro like this: + + %define %property(name, setf, getf) + %feature("set") setf #name; + %feature("get") getf #name; + %enddef + + Which allows a user to specify things like this: + + %property(p, get_p, set_p); + + class Blah { + public: + int get_p(); + void set_p(int); + }; + + *** EXPERIMENTAL NEW FEATURE *** + +11/24/2001:beazley + The Tcl module has been expanded with some new features for + managing object ownership. For example: + + set c [Circle -args 20] + $c area # Invoke a method + $c -disown # Releases ownership of the object + $c -acquire # Acquires ownership of the object + + If Tcl owns the object, its destructor is invoked when the + corresponding object command is deleted in Tcl. + + To simplify the destruction of objects, the following syntax + can be used: + + $c -delete # Delete an object + + This is an alternative for the more obscure variant of + + rename $c {} + + These features also add functionality at the C API level. + The following functions manage ownership from C and + can be used in typemaps. + + SWIG_Acquire(void *ptr); + SWIG_Disown(void *ptr); + + A new function for constructing instances is also available: + + Tcl_Obj * + SWIG_NewInstanceObj(Tcl_Interp *interp, void *ptr, + swig_type_info *type, int own); + + When used in a typemap, this creates a pointer object and + an interpreter command that can be used to issue methods and + access attributes as shown above. + *** NEW FEATURE *** + +11/23/2001:beazley + All Python-related %pragma operations have been eliminated. + Most of these were written for older SWIG versions in order to + compensate for limitations in earlier releases. In an effort + to reduce the amount of code-clutter and potential for errors, + it is easier to simply eliminate the pragmas and to start over + (if needed). To be honest, I'm not even sure the pragmas + worked in 1.3.9 and recent releases. + + Note: If you need to insert code into the shadow class file + created by SWIG, simply use the %shadow directive like this: + + %shadow %{ + def some_python_code(): + print "blah!" + %} + + *** POTENTIAL INCOMPATIBILITY *** + +11/22/2001:beazley + Sweeping changes to the way in which the Python module handles + shadow classes. In early implementations, shadow classes were + merely Python wrappers around typed pointer objects. However, + some users actually wanted to receive the shadow class object in C. + To accomodate this, the dereferencing of the "this" pointer in + a shadow class was moved to C as described in CHANGES [8/8/99]. + However, the process of returning pointers to Python was still + somewhat problematic. Specifically, shadow classes never worked + in situations such as these: + + - Use of any kind of output typemap ('out' or 'argout') + - Global variables (broken as far as I can tell). + + In the past, some users have dealt with this by manually trying + to create shadow class objects themselves from C/C++. However, + this was difficult because the C wrappers don't really know how + to get access to the corresponding Python class. + + The Python module has now been modified to automatically attach + shadow class objects to pointers when they are returned to + Python. This process occurs in the function SWIG_NewPointerObj() + so the process is completely transparent to users. As a result, + shadow classes are now more seamlessly integrated with typemaps + and other features of SWIG. + + This change may introduce a number of incompatibilities. The + SWIG_NewPointerObj() now takes an extra parameter "own" to + indicate object ownership. This can be used to return a pointer + to Python that Python should destroy. In addition, older code + that tries to manually construct shadow class objects or which + expects bare pointers may break---such pointers may already be + encapsulated by a shadow class. + *** POTENTIAL INCOMPATIBILITY *** + +11/20/2001:beazley + Modified the %insert directive to accept single braces { ... }. + For example: + + %insert("header") { + ... some code ... + } + + This works exactly like %{ ... %} except that the code in the + braces is processed using the preprocessor. This can be useful + in certain contexts such as low-level code generation in + language modules. + *** NEW FEATURE *** + +11/20/2001:beazley + Command line options are now translated into preprocessor + symbols. For example: + + ./swig -python -shadow -module blah interface.i + + Creates the symbols: + + SWIGOPT_PYTHON 1 + SWIGOPT_SHADOW 1 + SWIGOPT_MODULE blah + + Modules can look for these symbols to alter their code generation + if needed. + *** NEW FEATURE *** + +11/20/2001:beazley + Massive overhaul of the Perl5 module. A lot of code generation is + now driven by tables and typemaps. The generated wrapper code + also makes use of tables to install constants, variables, and + functions instead of inlining a bunch of procedure calls. The + separate variable initialization function is gone. Most + code generation is controlled via the perl5.swg file in the + library. + *** POTENTIAL INCOMPATIBILITY *** + +11/13/2001:beazley + Added parsing support for the C++ typename keyword. Primarily this + is added to better support templates. For example: + + template void blah(C& v) { + typename C::iterator i = v.begin(); + } + + Note: typename is supported in the parser in the same way as 'struct' + or 'class'. You probably shouldn't use it anywhere except in templates. + *** NEW FEATURE *** + +11/11/2001:beazley + Massive overhaul of the language module API. Most functions now + use a common, very simple, API. There are also a number of + interesting semantic side-effects of how code is actually generated. + Details will be forthcoming in Doc/Manual/Extending.html. + + *** POTENTIAL INCOMPATIBILITY *** Language modules written for + previous versions of SWIG will no longer work, + +11/10/2001:beazley + Fixed a very subtle bug due to unnamed class wrapping. For example, if + you did this + + typedef struct { + int x,y; + } gdPoint, *gdPointPtr; + + void foo(gdPointPtr x); + + Then the foo function would get a type-error. The problem has + to do with internal typedef handling and the fact that the typedef + declarations after the struct appear later in the parse tree. + It should work now. Problem reported by Vin Jovanovic. + +11/09/2001:beazley + Subtle change to "out" typemaps (and related variations). The name + that is attached to the typemap is now the raw C identifier that + appears on a declaration. This changes the behavior of + member functions. For example: + + %typemap(out) int foo { + ... + } + + class Blah { + public: + int foo(); // typemap gets applied + } + + Previous versions never really specified how this was supposed to + work. In SWIG1.1, you could probably write a typemap for the + wrapper name like this: + + %typemap(out) int Blah_foo { ... } + + However, this old behavior is now withdrawn and not supported. + Just use the member name without any sort of special prefix. + *** POTENTIAL INCOMPATIBILITY *** + +11/06/2001:beazley + Changes to Tcl module initialization: + + (1) SWIG now automatically includes the code needed to work with + Tcl stubs. Simply compile with -DUSE_TCL_STUBS. + + (2) SWIG now automatically calls Tcl_PkgProvide to register + a package name. The package name is the same as the name + specified with the %module directive. The version number is + set to "0.0" by default. To change the version number, use + swig -pkgversion 1.2 interface.i. + + *** POTENTIAL INCOMPATIBILITY *** + Modules that provided stubs and Tcl_PkgProvide on their own might + break. Simply remove that code. + +11/05/2001:beazley + Changed code generation of constants in the Tcl module. Constants + are now stored in a large table that get installed at module startup. + There are also no longer any static variables so it should generate + somewhat less code. + +11/04/2001:beazley + The "const" typemap has been renamed to "constant" in many language + modules. "const" is a C keyword which made the handling of the typemap + directive somewhat awkward in the parser. + *** POTENTIAL INCOMPATIBILITY *** + +11/04/2001:beazley + %typemap directive can now accept nearly arbitrary keyword parameters. + For example: + + %typemap(in,parse="i",doc="integer") int "..."; + + The purpose of the keyword parameters is to supply code generation + hints to the target language module. The intepretation of the + parameters is language specific. + *** NEW FEATURE *** + +11/04/2001:beazley + Slight semantic change to internal call/return by value handling. + In previous versions of SWIG, call-by-value was translated + into pointers. For example: + + double dot_product(Vector a, Vector b); + + turned into this: + + double wrap_dot_product(Vector *a, Vector *b) { + return dot_product(*a,*b); + } + + This translation was normally performed by the SWIG core, outside + of the control of language modules. However, a side effect + of this was a lot of bizarre typemap behavior. For example, + if you did something like this: + + %typemap(in) int32 { + ... + } + + You would find that int32 was transformed into a pointer everywhere! + (needless to say, such behavior is unexpected and quite awkward to + deal with). To make matters worse, if a typedef was also used, + the pointer behavior suddenly disappeared. + + To fix this, the pointer transformation is now pushed to the + language modules. This produces wrappers that look roughly + like this: + + double wrap_dot_product(Vector *a, Vector *b) { + Vector arg1 = *a; + Vector arg2 = *b; + return dot_product(arg1,arg2); + } + + This change also makes it easy to define typemaps for + arbitrary undefined types. For example, you can do this (and it + will work regardless what int32 is): + + %typemap(in) int32 { + $1 = (int32) PyInt_AsLong($input); + } + + *** POTENTIAL IMCOMPATIBILITY *** + This change may break call/return by value code generation in + some language modules. + +11/03/2001:beazley + Changed the name of the default typemaps to the following: + + %typemap() SWIGTYPE { + ... an object ... + } + %typemap() SWIGTYPE * { + ... a pointer ... + } + %typemap() SWIGTYPE & { + ... a reference ... + } + %typemap() SWIGTYPE [] { + ... an array ... + } + %typemap() enum SWIGTYPE { + ... an enum value ... + } + %typemap() SWIGTYPE (CLASS::*) { + ... pointer to member ... + } + + + These types are used as the default for all types that don't match + anything else. See CHANGES log entry for 8/27/2000 for the + old behavior. The role of these types is also described in + Doc/Manual/Typemaps.html + + *** POTENTIAL INCOMPATIBILITY *** + +10/25/2001:beazley + Modified Guile and Mzscheme modules to support + multi-argument typemaps. + +10/25/2001: cheetah (william fulton) + [Java] Fix to handle pointers to arrays. + +10/24/2001:beazley + Defining a typemap rule for enum SWIGENUM can now be used + to define default behavior for enum variables. + +10/22/2001:beazley + Ruby module modified to support multi-argument typemaps. + +10/22/2001:beazley + The Ruby module can now handle functions with an arbitrary + number of arguments. Previous versions were limited to + to functions with only 9 or 16 arguments depending on + the use of default arguments. Note: from some inspection + of the Ruby interpreter source, the new approach might be + a little faster as well. + +10/18/2001:beazley + Fixed a bug with forward class declarations and + templates. + + class Foo ; + + Bug reported by Irina Kotlova. + +10/16/2001:beazley + Support for multivalued typemaps added. The typemaps + are specified using the syntax below. Within each + typemap, variable substitution is handled as follows: + + %typemap(in) (int argc, char *argv[]) { + $arg; // The input object in the target language + $1; // C local variable for first argument + $2; // C local variable for second argument + + // These variables refer to either argument + $1_type, $1_ltype, $1_basetype, etc... (argc) + $2_type, $2_ltype, $2_basetype, etc... (argv[]) + + // Array dimension of argv + $2_dim0 + } + + Basically any variable that was available in normal typemaps + is available for either argument by prefacing the variable + name by '$n_' where n is the argument position. + + Notes: + (1) Multi-valued typemaps can only be applied to a single + object in the target scripting language. For example, + you can split a string into a (char *, int) pair or + split a list into a (int, char []) pair. It is not + possible to map multiple objects to multiple arguments. + + (2) To maintain compatibility with older SWIG versions, the + variables such as $target and $type are preserved and + are mapped onto the first argument only. + + (3) This should not affect compatibility with older code. + Multi-valued typemaps are an extension to typemap handling. + Single valued typemaps can be specified in the usual + way. + + The old $source and $target variables are officially + deprecated. Input variables are referenced through + $arg$ and output values are reference through $result$. + + *** NEW FEATURE *** + +10/16/2001:beazley + Added parsing support for multivalued typemaps. The syntax + is a little funky, but here goes: + + // Define a multivalued typemap + %typemap(in) (int argc, char *argv[]) { + ... typemap code ... + } + + // Multivalued typemap with locals + %typemap(in) (int argc, char *argv[])(int temp) { + ... typemap code ... + } + + // Copy a multivalued typemap + %typemap(in) (int argcount, char **argv) = (int argc, char *argv[]); + + // Apply a multivalued typemap + %apply (int argc, char *argv[]) { (int argcount, char **argv) }; + + Note: this extra parsing support is added for future extension. + No language modules currently support multi-valued typemaps. + +10/11/2001:beazley + Modified the typemap matching code to discard qualifiers when + checking for a match. For example, if you have a declaration + like this: + + void blah(const char *x); + + The typemap checker checks for a match in the following order: + + const char *x + const char * + char *x + char * + + If typedef's are involved, qualifier stripping occurs before + typedef resolution. So if you had this, + + typedef char *string; + void blah(const string x); + + typemap checking would be as follows: + + const string x + const string + string x + string + const char *x + const char * + char *x + char * + + The primary reason for this change is to simplify the implementation + of language modules. Without qualifier stripping, one has to write + seperate typemaps for all variations of const and volatile (which + is a pain). + + *** POTENTIAL INCOMPATIBILITY *** Typemaps might be applied in + places where they weren't before. + + +10/9/2001: beazley + SWIG now generates wrappers that properly disambiguate + overloaded methods that only vary in constness. For + example: + + class Foo { + ... + void blah(); + void blah() const; + ... + }; + + To handle this, the %rename directive can be used normally. + + %rename(blah_const) blah() const; + + In the resulting wrapper code, method calls like this + are now generated: + + (obj)->blah() // Non-const version + ((Foo const *)obj)->blah() // const version + + This should force the right method to be invoked. + Admittedly, this is probably obscure, but we might + as well get it right. + +10/8/2001: beazley + The preprocessor now ignores '\r' in the input. + This should fix the following bug: + [ #468416 ] SWIG thinks macro defs are declarations? + +10/8/2001: beazley + Added support for ||, &&, and ! in constants. This + fixes SF [ #468988 ] Logical ops break preprocessor. + However, at this time, constants using these operators + are not supported (the parser will issue a warning). + +10/4/2001: beazley + Added -show_templates command line option. This makes + SWIG display the code it actually parses to generate + template wrappers. Mostly useful for debugging. + *** NEW FEATURE *** + +10/4/2001: beazley + Change to semantics of %template directive. When + using %template, the template arguments are handled + as types by default. For example: + + %template(vecint) vector; + %template(vecdouble) vector; + + To specify a template argument that is *not* a type, you + need to use default-value syntax. For example: + + %template(vecint) vector; + %template(vecdouble) vector; + + In this case, the type name doesn't really matter--only + the default value (e.g., 50, 100) is used during + expansion. This differs from normal C++, but I couldn't + figure out a better way to do it in the parser. Might + implement an alternative later. + *** POTENTIAL INCOMPATIBILITY *** + +10/4/2001: beazley + Major changes to template handling in order to provide + better integration with the C++ type-system. The main + problem is as follows: + + Suppose you have a template like this: + + template void blah(const T x) { stuff }; + + Now suppose, that you instantiate the template on a + type like this in SWIG: + + %template(blahint) blah; + + In C++, this is *supposed* to generate code like this: + + void blah(int *const x) { stuff }; + + However, in SWIG-1.3.9, the template substitution gets it wrong + and produces + + void blah(const int *x) { stuff }; + + (notice the bad placement of the 'const' qualifier). + + To fix this, the SWIG parser now generates implicit typedefs + for template type arguments that produces code roughly + equivalent to doing this: + + typedef int *__swigtmpl1; + %template(blahint) blah<__swigtmpl1>; + + which generates code like this: + + void blah(const __swigtmpl1 x) { stuff }; + + Since this is correct in both C++ and SWIG, it provides the right + semantics and allows everything to compile properly. However, + to clean up the generated code a little bit, the parser keeps + track of the template types and performs back-substitution to + the original type when building the parse tree. Thus, even + though the implicit typedef is used in the input and may appear + in the generated wrapper file (for proper compilation), the parse + tree will hide a lot of these details. For example: + + void blah(const __swigtmpl1 x) { stuff }; + + will look like it was declared as follows (which is what + you want): + + void blah(int *const x) { stuff } + + The only place you are likely to notice the typedef hack + is in bodies of template functions. For example, if you + did this, + + template class blah { + ... + %addmethods { + void spam() { + T tempvalue; + ... + } + } + } + + you will find that 'T tempvalue' got expanded into some + strange typedef type. This *still* compiles correctly + so it's not a big deal (other than looking kind of ugly + in the wrapper file). + +10/4/2001: beazley + Fixed some inheritance problems in Tcl Object interface. + +10/1/2001: beazley + Tcl module has changed to use byte-backed pointer strings. This + implementation should be safe on 64-bit platforms. However, + the order in which digits appear in pointer values no longer + directly corresponds to the actual numerical value of a + pointer (on little-endian machines, pairs of digits appear + in reverse order). + +10/1/2001: beazley + Perl5 module is now driven by a configuration file 'perl5.swg' + in the SWIG library. + +10/1/2001: beazley + The perl5 module no longer tries to apply the "out" typemap + in code generated for magic variables. I'm surprised that + this ever worked at all (since all of the code that was there + was wrong anyways). Use the "varout" typemap to handle + global variables. + +10/1/2001: beazley + Fixed a bug related to character array members of structures. + For example: + + struct Foo { + char name[32]; + }; + + SWIG is normally supposed to return a string, but this was + broken in 1.3.9. The reason it was broken was actually + due to a subtle new feature of typemaps. When a data member + is set to an array like this, the return type of the related + accessor function is actually set to an array. This means + that you can now write typemaps like this: + + %typemap(python,out) char [ANY] { + $target = PyString_FromStringAndSize($source,$dim0); + } + + This functionality can be used to replace the defunct + memberout typemap in a more elegant manner. + +9/29/2001: beazley + Some further refinement of qualified C++ member functions. + For example: + + class Foo { + ... + void foo() const; + ... + }; + + (i) The SWIG parser was extended slightly to allow 'volatile' + and combinations of 'const' and 'volatile' to be used. This + is probably rare, but technically legal. Only added for + completeness. + + (ii) For the purposes of overloading, qualified and non-qualified + functions are different. Thus, when a class has methods like this: + + void foo(); + void foo() const; + + Two distinct methods are declared. To deal with this, %rename + and similar directives have been extended to recognize const. + Thus, one can disambiguate the two functions like this: + + %rename(fooconst) Foo::foo() const; + + or simply ignore the const variant like this: + + %ignore Foo::foo() const; + + Note: SWIG currently has no way to actually invoke the const + member since the 'const' is discarded when generating wrappers + for objects. + +9/27/2001: beazley + New directive. %namewarn can be used to issue warning + messages for certain declaration names. The name + matching is the same as for the %rename directive. + The intent of this directive is to issue warnings for + possible namespace conflicts. For example: + + %namewarn("print is a python keyword") print; + + The name matching algorithm is performed after a name + has been resolved using %rename. Therefore, a + declaration like this will not generate a warning: + + %rename("Print") print; + ... + void print(); /* No warning generated */ + + Since the warning mechanism follows %rename semantics, it is + also to issue warnings for specific classes or just for + certain member function names. + + (Dave - I've been thinking about adding something like this + for quite some time. Just never got around to it) + *** NEW FEATURE *** + + +9/27/2001: beazley + Enhanced the %ignore directive so that warning messages + can be issued to users. This is done using %ignorewarn + like this: + + %ignorewarn("operator new ignored") operator new; + + The names and semantics of %ignorewarn is exactly the + same as %ignore. The primary purpose of this directive + is for module writers who want to ignore certain types + of declarations, but who also want to alert users about it. + A user might also use this for debugging (since messages + will appear whenever an ignored declaration appears). + *** NEW FEATURE *** + +9/26/2001: beazley + Super-experimental support for overloaded operators. + This implementation consists of a few different parts. + + (i) Operator names such as 'operator+' are now allowed + as valid declarator names. Thus the 'operator' syntax + can appear *anyplace* a normal declarator name was used + before. On the surface, this means that operators can + be parsed just like normal functions and methods. + However, it also means that operator names can be used + in many other SWIG directives like %rename. For example: + + %rename(__add__) Complex::operator+(const Complex &); + + (ii) Operators are wrapped *exactly* like normal functions + and methods. Internally, the operator name is used + directly meaning that the wrapper code might contain + statements like this: + + arg0->operator*((Complex const &)*arg1); + + This all seems to parse and compile correctly (at least + on my machine). + + (iii) SWIG will no longer wrap a declaration if its symbol + table name contains illegal identifier characters. If + illegal characters are detected, you will see an error + like this: + + Warning. Can't wrap operator* unless renamed to a valid identifier. + + The only way to fix this is to use %rename or %name to bind + the operator to a nice name like "add" or something. Note: + the legal identifier characters are determined by the target + language. + + There are certain issues with friend functions and operators. + Sometimes, friends are used to define mixed operators such + as adding a Complex and a double together. Currently, SWIG + ignores all friend declarations in a class. A global operator + declaration can probably be made to work, but you'll have to + rename it and it probably won't work very cleanly in the + target language since it's not a class member. + + SWIG doesn't know how to handle operator specifications + sometimes used for automatic type conversion. For example: + + class String { + ... + operator const char*(); + ... + }; + + (this doesn't parse correctly and generates a syntax error). + + Also: operators no longer show up as separate parse-tree + nodes (instead they are normal 'cdecl' nodes). I may + separate them as a special case later. + + See Examples/python/operator for an example. + + *** SUPER-EXPERIMENTAL NEW FEATURE *** + +Version 1.3.9 (September 25, 2001) +================================== + +9/25/2001: beazley + Fixed parsing problem with type declarations like + 'char ** const'. SWIG parsed this correctly, but the + internal type was represented incorrectly (the pointers + and qualifiers were in the wrong order). + +9/25/2001: beazley + Withdrew experimental feature (noted below) that was + causing serious parsing problems. + +Version 1.3.8 (September 23, 2001) +================================== + +9/23/2001: beazley + Included improved distutils setup.py file in the Tools + directory (look for the setup.py.tmpl file). Contributed by + Tony Seward. + +9/23/2001: beazley + Included two new RPM spec files in the Tools directory. Contributed + by Tony Seward and Uwe Steinmann. + +9/21/2001: beazley + Fixed SF Bug [ #463635 ] Perl5.swg does not compile in Visual C++ + +9/21/2001: beazley + Two new directives control the creation of default + constructors and destructors: + + %nodefault + %makedefault + + These replace %pragma nodefault and %pragma makedefault. + (old code will still work, but documentation will only + describe the new directives). + +9/21/2001: beazley + Fixed SF Bug [ #462354 ] %import broken in 1.3.7. + +9/20/2001: beazley + + Parser modified to ignore out-of-class constructor + and destructor declarations. For example: + + inline Foo::Foo() : + Bar("foo") + { + } + + inline Foo::~Foo() { + } + + Suggested by Jason Stewart. + *** EXPERIMENTAL FEATURE *** + +9/20/2001: beazley + Modified the parser to ignore forward template class + declarations. For example: + + template class MapIter; + + Suggested by an email example from Irina Kotlova. + +9/20/2001: beazley + Fixed problem with undeclared tcl_result variable in + the "out" typemap for Tcl. Reported by Shaun Lowry. + +9/20/2001: beazley + Incorporated changes to make SWIG work with ActivePerl. + Contributed by Joel Reed. + +9/20/2001: beazley + Slight change to the parsing of C++ constructor initializers. + For example: + + class Foo : public Bar { + public: + Foo() : Bar(...) {...} + }; + + SWIG now discards the contents of the (...) regardless of + what might enclosed (even if syntactically wrong). SWIG + doesn't need this information and there is no reason to + needless add syntax rules to handle all of the possibilities + here. + +9/20/2001: beazley + Change to typemaps for structure members. If you have a + structure like this: + + struct Vector { + int *bar; + }; + + The member name 'bar' is now used in any accessor functions. + This allows the "in" typemap to be used when setting the value. + For example, this typemap + + %typemap(python,in) int *bar { + ... + } + + now matches Vector::bar. It should be noted that this will also + match any function with an argument of "int *bar" (so you should + be careful). + *** NEW FEATURE. POTENTIAL INCOMPATIBILITY *** + +9/20/2001: beazley + Fixed SF bug #462642 setting string values in structures + +9/20/2001: beazley + Fixed SF bug #462398 problem with nested templates. + +9/20/2001: beazley + Fixed SF bug #461626 problem with formatting and C++ comments. + +9/20/2001: beazley + Fixed SF bug #462845 Wrong ownership of returned objects. + +9/19/2001: beazley + Fixed SF bug #459367. Default constructors for classes + with pure virtual methods. + +9/19/2001: beazley + Fixed problem with default arguments and class scope. For + example: + + class Foo { + public: + enum bar { FOO, BAR }; + void blah(bar b = FOO); + ... + } + + SWIG now correctly generates a default value of "Foo::FOO" for + the blah() method above. This used to work in 1.1, but was + broken in 1.3.7. Bug reported by Mike Romberg. + +Version 1.3.7 (September 3, 2001) +================================== + +9/02/2001: beazley + Added special %ignore directive to ignore declarations. This + feature works exactly like %rename. For example: + + %ignore foo; // Ignore all declarations foo + %ignore ::foo; // Only ignore foo in global scope + %ignore Spam::foo; // Only ignore in class Spam + %ignore *::foo; // Ignore in all classes + + %ignore can also be parameterized. For example: + + %ignore foo(int); + %ignore ::foo(int); + %ignore Spam::foo(int); + %ignore *::foo(int); + + *** NEW FEATURE *** + + +9/02/2001: cheetah (william fulton) + [Java] shadowcode pragma modified so that the code that is output + in the shadow file is placed relative to where it is placed in the + c/c++ code. This allows support for JavaDoc function comments. + +9/01/2001: beazley + Fixed SF Patch [ #447791 ] Fix for python -interface option. + Submitted by Tarn Weisner Burton. + +9/01/2001: beazley + SWIG no longer generates default constructors/destructors + for a class if it only defines a private/protected constructor + or destructor or if any one of its base classes only has + private constructors/destructors. This was reported in + SF Patch [ #444281 ] nonpublic/default/inhereted ctor/dtor + by Marcelo Matus. + +9/01/2001: beazley + Added patch to Perl5 module that allows constants to be + wrapped as constants that don't require the leading $. + This feature is enabled using the -const option. + Patch contributed by Rich Wales. + *** NEW FEATURE *** + +8/31/2001: beazley + Added parsing support for the 'volatile' type qualifier. + volatile doesn't mean anything to SWIG, but it is + needed to properly generate prototypes for declarations + that use it. It's also been added to make the SWIG type + system more complete. + *** NEW FEATURE *** + +8/30/2001: beazley + Added support for parameterized %rename directive. *** This + new feature can be used to greatly simplify the task of + resolving overloaded methods and functions. *** + + In prior versions of SWIG, the %rename directive was + used to consistently apply an identifier renaming. For + example, if you said this: + + %rename foo bar; + + Every occurrence of 'foo' would be renamed to 'bar'. + Although this works fine for resolving a conflict with a + target language reserved word, it is useless for + for dealing with overloaded methods. This is because + all methods are simply renamed to the same thing + (generating the same conflict as before). + + Therefore, the only way to deal with overloaded methods + was to go through and individually rename them all using + %name. For example: + + class Foo { + public: + virtual void bar(void); + %name(bar_i) virtual void bar(int); + ... + }; + + To make matters worse, you had to do this for all + derived classes too. + + class Spam : public Foo { + public: + virtual void bar(void); + %name(bar_i) virtual void bar(int); + ... + }; + + Needless to say, this makes it extremely hard to resolve + overloading without a lot of work and makes it almost + impossible to use SWIG on raw C++ .h files. + + To fix this, %rename now accepts parameter declarators. + The syntax has also been changed slightly. For example, + the following declaration renames all occurrences of 'bar(int)' + to 'bar_i', leaving any other occurrence of 'bar' alone. + + %rename(bar_i) bar(int); + + Using this feature, you can now selectively rename + certain declarations in advance. For example: + + %rename(bar_i) bar(int); + %rename(bar_d) bar(double); + + // Include raw C++ header + %include "header.h" + + When %rename is used in this manner, all occurrence of bar(int) + are renamed wherever they might occur. More control is obtained + through explicit qualification. For example, + + %rename(bar_i) ::bar(int); + + only applies the renaming if bar(int) is defined in the global scope. + The declaration, + + %rename(bar_i) Foo::bar(int); + + applies the renaming if bar(int) is defined in a class Foo. + This latter form also supports inheritance. Therefore, if you + had a class like this: + + class Spam : public Foo { + public: + void bar(int); + } + + The Spam::bar(int) method would also be renamed (since Spam + is a subclass of Foo). This latter feature makes it easy + for SWIG to apply a consistent renaming across an entire + class hierarchy simply by specifying renaming rules for + the base class. + + A class wildcard of * can be used if you want to renaming + all matching members of all classes. For example: + + %rename(bar_i) *::bar(int); + + will rename all members bar(int) that are defined in classes. + It will not renamed definitions of bar(int) in the global + scope. + + The old use of %rename is still supported, but is somewhat + enhanced. + + %rename(foo) bar; // Renames all occurrences of 'bar'. + %rename(foo) ::bar; // Rename all 'bar' in global scope only. + %rename(foo) *::bar; // Rename all 'bar' in classes only. + %rename(foo) Foo::bar; // Rename all 'bar' defined in class Foo. + + *** NEW FEATURE *** + +8/30/2001: beazley + Added support for data-member to member-function + transformation. For example, suppose you had a + structure like this: + + struct Vector { + double x,y; + }; + + Now suppose that you wanted to access x and y + through a member function interface instead + of the usual SWIG behavior. For example: + + f.set_x(3.4) # instead of f.x = 3.4 + x = f.get_x() # instead of x = f.x + + To do this, simply use the new %attributefunc + directive. For example: + + %attributefunc(get_%s,set_%s) + struct Vector { + double x,y; + }; + %noattributefunc + + The arguments to %attributefunc are C-style printf + format strings that determine the naming convention + to use. %s is replaced with the actual name of the + data member. SWIG provides a number of printf + extensions that might help. For example, if you + wanted to title case all of the attributes, you + could do this: + + %attributefunc(get%(title)s,set%(title)s); + + This will turn an attribute 'bar' to 'getBar()' and 'setBar()'. + + (someone requested this long ago, but I finally figured + how to implement it in a straightforward manner). + *** EXPERIMENTAL NEW FEATURE *** + +8/30/2001: beazley + SWIG now automatically generates default constructors + and destructors if none are defined. This used to be + enabled with a command line switch -make_default, but + most people want these functions anyways. To turn + off this behavior use the -no_default option or include + the following pragma in the interface file: + + %pragma no_default; + + This may break certain interfaces that defined their + own constructors/destructors using the same naming + convention as SWIG. If so, you will get duplicate + symbols when compiling the SWIG wrapper file. + *** POTENTIAL INCOMPATIBILITY *** + +8/29/2001: beazley + Changes to Perl5 shadow class code generation. Iterators + are no longer supported (FIRSTKEY, NEXTKEY). Also, attribute + access has been changed to rely on inheritance in order + to provide better behavior across modules. + +8/28/2001: beazley + Various obscure improvements to the type system and classes. + Strange declarations like this are now wrapped correctly + (i.e., the generated wrapper code doesn't cause the C++ + compiler to die with a type error). + + class Foo { + public: + typedef double Real; + Real foo(Real (*op)(Real,Real), Real x, Real y); + }; + + Inheritance of types is also handled correctly. + +8/28/2001: beazley + Changes to class wrappers. When SWIG sees two classes like this, + + class X { + public: + void foo(); + ... + } + + class Y : public X { + public: + void bar(); + ... + } + + it now only generates two wrapper functions: + + X_foo(X *x) { x->foo(); } + Y_bar(Y *y) { y->bar(); } + + Unlike SWIG1.15, the foo() method does *not* propagate to a wrapper + function Y_foo(). Instead, the base class method X_foo() must be + used. + + This change should not affect modules that use shadow classes, but + it might break modules that directly use the low-level C wrappers. + This change is being made for a number of reasons: + + - It greatly simplifies the implementation of SWIG--especially + with anticipated future changes such as overloaded methods. + + - It results in substantially less wrapper code--especially + for big C++ class hierarchies (inherited declarations + are no longer copied into every single derived class). + + - It allows for better code generation across multiple + SWIG generated modules (code isn't replicated in + every single module). + + *** POTENTIAL INCOMPATIBILITY *** + +8/22/2001: cheetah (william fulton) + Provided some Windows documentation in the Win directory and some + Visual C++ project files for running examples on Windows. + +8/28/2001: mkoeppe + [Guile] Handle renamed overloaded functions properly; + thanks to Marc Zonzon for the + patch. See the new test case name_cxx. + +8/27/2001: mkoeppe + [Tcl] Removed lots of warnings issued by the Sun Forte + compilers, which were caused by mixing function pointers + of different linkages (C++/C). + +8/23/2001: mkoeppe + Improved the MzScheme module by porting Guile's pointer + type checking system and making type dispatch + typemap-driven. + +8/22/2001: beazley + Entirely new symbol table processing. SWIG should be able to + report much better error messages for multiple declarations. + Also, the new symbol table allows for overloaded functions + (although overloading isn't quite supported in the language + modules yet). + +8/22/2001: cheetah (william fulton) + * [Java] %new support added. + * [Java] Package JNI name refixed! + +8/19/2001: beazley + Python module modified to support pointers to C++ members. This + is an experimental feature. + *** NEW FEATURE *** + +8/19/2001: beazley + Added limited parsing and full type-system support for pointers to + members. None of SWIG's language modules really know how to deal with + this so this is really only provided for completeness and future + expansion. Note: SWIG does not support pointers to members which + are themselves pointers to members, references to pointers to members, + or other complicated declarations like this. + *** NEW FEATURE *** + +8/19/2001: beazley + SWIG is much better at parsing certain C++ declarations. Operators and + friends generally don't cause anymore syntax errors. However, neither + are really supported. + +8/18/2001: beazley + Added *highly* experimental support for wrapping of C++ + template declarations. Since C++ templates are essentially + glorified macros and SWIG has a fully operational C + preprocessor with macro support, the parser now converts + template declarations to macros. For example, a function + template like this + + template T max(T a, T b); + + is internally converted into a macro like this: + + %define %_template_max(__name,T) + %name(__name) T max(T a, T b); + %enddef + + To instantiate a version of the template, a special %template declaration + is used like this: + + %template(maxint) max; + %template(maxdouble) max; + + The parameter to the %template directive must be proper C identifier that's + used to uniquely name the resulting instantiation. When used, the + the expanded macro looks like this: + + %name(maxint) int max(int a, int b); + %name(maxdouble) double max(double a, double b); + + A similar technique is used for template classes. For instance: + + template class vector { + T *data; + int sz; + public: + vector(int nitems); + T *get(int n); + ... + }; + + Gets converted into a macro like this: + + %define %_template_vector(__name, T) + %{ + typedef vector __name; + %} + class __name { + T *data; + int sz; + public: + __name(int nitems); + T *get(int n); + ... + }; + typedef __name vector; + %enddef + + An a specific instantiation is created in exactly the same way: + + %template(intvec) vector; + + The resulting code parsed by SWIG is then: + + %{ + typedef vector intvec; + %} + class intvec { + int *data; + int sz; + public: + intvec(int nitems); + int *get(int n); + ... + }; + typedef intvec vector; + + Note: the last typedef is non-standard C and is used by SWIG to provide + an association between the name "intvec" and the template type + "vector". + + CAUTION: This is an experimental feature and the first time SWIG has + supported C++ templates. Error reporting is essential non-existent. + It will probably break in certain cases. + *** EXPERIMENTAL NEW FEATURE **** + +8/15/2001: beazley + Change to wrapping of multi-dimensional arrays. Arrays + are now properly mapped to a pointer to an array of + one less dimension. For example: + + int [10]; --> int * + int [10][20]; --> int (*)[20]; + int [10][20][30]; --> int (*)[20][30]; + + This change may break certain SWIG extensions because + older versions simply mapped all arrays into a single + pointer such as "int *". Although possibly unusual, + the new version is correct in terms of the C type system. + *** POTENTIAL INCOMPATIBILITY *** + +8/06/2001: cheetah (william fulton) + * [Java] Array setters generated for struct/class array members. + +8/13/2001: beazley + Many improvements to Tcl/Perl/Python modules to better + work with multiple interface files and the %import directive. + +8/13/2001: beazley + Fixed up the behavior of %import in the Python module. + SWIG no longer pollutes the module namespace by using + 'from module import *' to refer to the other module. + Instead, it does a proper 'import module'. Also, SWIG + may work a lot better when importing modules that include + references to other imported modules. + +8/13/2001: mkoeppe + Added new typemap substitutions, generalizing those of the + Guile-specific 5/27/2001 changes: + * $descriptor is the same as SWIGTYPE$mangle, but also + ensures that the type descriptor of this name gets + defined. + * $*type, $*ltype, $*mangle, $*descriptor are the same as + the variants without star, but they REMOVE one level of + pointers from the type. (This is only valid for pointer + types.) + * $&type, $<ype, $&mangle, $&descriptor are the same as + the variants without ampersand, but they ADD one level of + pointers to the type. + The Guile-specific substitution $basedescriptor was removed + because it was useless. + +8/12/2001: beazley + The %extern directive is now deprecated and withdrawn. The + purpose of this directive was to import selected definitions + from other interface files and headers. However, the same + functionality is better handled through %import. This + leaves SWIG with two file inclusion directives: + + %include filename - Inserts into current interface + %import filename - Import types and classes from + another module + + *** POTENTIAL INCOMPATIBILITY *** + +8/09/2001: beazley + Added new support for wrapping C/C++ callback functions. + A common problem with some C libraries is that many + functions take a function pointer as an argument. For example: + + int do_op(..., int (*op)(int,int), ...); + + Unfortunately, the only way to call such a function is to + pass it a function pointer of some compatible type. In + previous versions of SWIG, you had to solve this problem + with some really gross hacks. For example, if you wanted to + use the following function as a callback, + + int foo(int, int); + + you had to install a pointer to it as a constant. For example: + + %constant int (*FOO)(int,int) = foo; + + or + + const int (*FOO)(int,int) = foo; + + or if you had a really old SWIG version: + + typedef int (*OP_FUNC)(int,int); + int do_op(..., OP_FUNC, ...); + const OP_FUNC FOO = foo; + + + Now, you can do one of two things: + + %constant int foo(int,int); + + This creates a constant 'foo' of type int (*)(int,int). + Alternatively, you can do this: + + %callback("%s"); + int foo(int,int); + int bar(int,int); + %nocallback; + + In this case, the functions are installed as constants where + the name is defined by the format string given to %callback(). + If the names generated by the format string differ from the + actual function name, both a function wrapper and a callback + constant are created. For example: + + %callback("%(upper)s"); + int foo(int,int); + int bar(int,int); + %nocallback; + + Creates two wrapper functions 'foo', 'bar' and additionally + creates two callback constants 'FOO', 'BAR'. + + Note: SWIG still does not provide automatic support for + writing callback functions in the target language. + *** NEW FEATURE *** + +8/06/2001: cheetah (william fulton) + * struct nesting fixes as per SF bug #447488. + +8/03/2001: beazley + The %name directive now applies to constants created with + #define and %constant. However, most language modules + were never written to support this and will have to be + modified to make it work. Tcl, Python, and Perl modules + are working now. + *** NEW FEATURE *** + +8/03/2001: beazley + Massive changes and simplification of C declaration parsing. + Although SWIG is still not a full C parser, its ability + to handle complex datatypes including pointers to functions + and pointers to arrays has been vastly improved. + +8/03/2001: cheetah (william fulton) + * Distribution fixes: autoconf no longer needed to install SWIG. + +8/02/2001: beazley + Removed two undocumented parsing features. SWIG no longer + supports out-of-class static function or variable + declarations. For example: + + static int Foo::bar; + + This feature may return if there is sufficient demand. + However, since SWIG is most often used with header files, + it is more likely for these definitions to be included + in the class definition. + *** POTENTIAL INCOMPATIBILITY *** + +8/02/2001: cheetah (william fulton) + * Cleanup of the GIFPlot examples. Upgraded Java GIFPlot example. + +8/01/2001: cheetah (william fulton) + * [Java] Efficiency changes: _cPtr used where possible rather than + getCPtr(). Bug fixes for inheritance - derived class sometimes + didn't delete the c memory when _delete() was called. + * [Java] Abstract c++ classes are wrapped with a java abstract shadow + class. Also a pure virtual function is mapped with an abstract method. + * The default output file has always been _wrap.c. It is now + _wrap.cxx if the -c++ commandline option is passed to swig. + This has been done as otherwise c++ code would appear in a c file. + *** POTENTIAL INCOMPATIBILITY *** + +7/31/2001: beazley + Modified the %constant directive to be more C-like in syntax. + The syntax is now: + + %constant NAME = VALUE; + %constant TYPE NAME = VALUE; + + For example: + + %constant Foo *Bar = &Spam; + + A more subtle case is as follows: + + %constant int (*FOO)(int,int) = blah; + + *** POTENTIAL INCOMPATIBILITY *** Modules that were using + the %constant directive directly will need to be modified. + +7/30/2001: beazley + Removed obscure and undocumented form of the %inline directive: + + %inline int blah(int a, int b) { + ... + } + + *** POTENTIAL INCOMPATIBILITY *** + (note: this feature was never documented and is withdrawn) + +7/30/2001: beazley + Removed support for functions with no explicitly declared + return type. For example: + + foo(int); + + In C, such functions were implicitly assumed to return an 'int'. + In C++, this is illegal. Either way, it's considered bad + style. Removing support for this in SWIG will simplify + certain issues in parsing. + *** POTENTIAL INCOMPATIBILITY *** + +7/30/2001: mkoeppe + * Partial merge from the CVS trunk. The Source/DOH directory + and most of the Source/Swig directory is up-to-date now. + * [Guile] %scheme is now a macro for %insert("scheme"). + New syntax: %scheme "FILENAME"; + New syntax: %scheme %{ SCHEME-CODE %} + New macros %multiple_values, %values_as_list, + %values_as_vector. + +7/29/2001: beazley + %readonly and %readwrite have been turned into SWIG pragmas. + %pragma(swig) readonly and %pragma(swig) readwrite. Macros + are used to provide backwards compatibility. + +7/29/2001: beazley + Minor changes to %pragma directive. %pragma must always + be directed to a specific language. For example: + + %pragma(swig) make_default; + %pragma(perl5) include = "blah.i"; + + Also extended the pragma directive to allow code blocks + + %pragma(foo) code = %{ + ... some code ... + %} + + *** POTENTIAL INCOMPATIBILITY *** + +7/29/2001: beazley + Change to the way 'const' variables are wrapped. In + previous versions of SWIG, a 'const' variable was + wrapped as a constant. Now, 'const' variables are + wrapped as read-only variables. There are several + reasons for making this change, mostly pertaining to + subtle details of how 'const' actually works. + + This will probably break old interfaces that used 'const' + to create constants. As a replacement, consider using this: + + const int a = 4; ===> %constant int a = 4; + *** POTENTIAL INCOMPATIBILITY *** + +7/29/2001: beazley + Reorganization and simplification of type parsing. + Types with 'const' should work correctly now. + +7/29/2001: beazley + Most swig directives related to the documentation system + are now deprecated. + +7/29/2001: beazley + Removed support for Objective-C in order to simplify + parser reconstruction. Will return if there is sufficient + demand. + *** POTENTIAL INCOMPATIBILITY *** + +7/29/2001: beazley + Code inclusion has been modified in the parser. A common + directive %insert is now used for everything. This + inserts a file into the output: + + %insert(header) "foo.swg" + + This inserts some inline code into the output + + %insert(header) %{ + ... some code ... + %} + + There are five predefined targets for the insert directive: + + "header" - Header section of wrapper file + "runtime" - Runtime section of wrapper file + "wrapper" - Wrapper section + "init" - Initialization function + "null" - Nothing. Discard. + + The following directives are still supported, but are + now defined in terms of macros: + + %{ ... %} -> %insert(header) %{ ... %} + %init %{ ... %} -> %insert(init) %{ ... %} + %wrapper %{ ... %} -> %insert(wrapper) %{ ... %} + %runtime %{ ... %} -> %insert(runtime) %{ ... %} + + Language modules can define new named targets by using the + C API function Swig_register_filebyname() (see main.cxx). + For example, if you wanted to expose a shadow class file, + you could do this: + + Swig_register_filebyname("shadow", f_shadow); + + Then in the interface file: + + %insert(shadow) %{ ... %} + + Note: this change should not affect any old interfaces, but + does open up new possibilities for enhancements. + +7/29/2001: beazley + SWIG now always includes a standard library file 'swig.swg'. + This file defines a large number of macro definitions + that define the behavior of various SWIG directives. + Previously, all SWIG directives were handled as special + cases in the parser. This made the parser a large + bloated mess. Now, the parser is stripped down to a few + simple directives and macros are used to handle everything else. + +7/26/2001: cheetah (william fulton) + * Fixes for Sourceforge bug #444748 - new testcase cpp_static: + [TCL] Class with just static member variable/function fix + [Java] Fixed static variables support + [Ruby] Static variables workaround removed + +7/27/2001: mkoeppe + * stype.c (SwigType_default): Strip qualifiers first. The + default type of "int * const" is now "SWIGPOINTER *". + * main.cxx: Define "__cplusplus" in SWIG's preprocessor if + in C++ mode. + * [Guile]: Added some support for arrays and C++ + references, fixing the "constant_pointers" test case. + * Moved most tests from the old Guile-specific test-suite + to the new test-suite. Also moved perl5/pointer-cxx + example there. + +7/26/2001: cheetah (william fulton) + * Test-suite added. + * Initial testcases: constant_pointers cpp_enum defines + sizeof_pointers unions virtual_destructor + * Make clean improvements. + +7/24/2001: cheetah (william fulton) + * [Java] Underscores in the package name and/or module name + no longer give linking problems. + +7/17/2001: cheetah (william fulton) + * More parser bug fixes for constant pointers + +7/19/2001: mkoeppe + * [Guile] Aesthetic improvement in variable wrappers. + +7/18/2001: beazley + * Fixed core-dump problem in pointer library when + freeing character arrays. + SF Bug [ #415837 ] pointer lib core dump + +7/18/2001: beazley + * Fixed problem with default destructors and shadow + classes. SF bug #221128. + +7/18/2001: beazley + * To provide better line-number tracking in interfaces + with lots of macros, special locator comments are + now generated by the SWIG preprocessor. For example: + + /*@foo.i,42,BLAH@*/expanded macro/*@@*/ + + The first /*@...@*/ sequence sets the context + to point to the macro code. The /*@@*/ comment + terminates the context. The SWIG parser should + ignore all of the locator comments as should + the C compiler (should such comments end up + in generated wrapper code). + +7/18/2001: mkoeppe + * The parser now handles severely constified types in + typemaps. This introduced a new shift/reduce conflict, but + only with a heuristic function-pointer catch-all rule. + * [Guile]: Added typemaps for severely constified types. + * Fixed the "template-whitespace" problem by canonicalizing + whitespace, especially around angle brackets and commas. + +7/17/2001: mkoeppe + * [Guile]: A Scheme file is emitted if the -scmstub FILE.SCM + command-line option is used. The %scheme directive + (implemented as a macro for a pragma) allows to insert + arbitrary code here. In "simple" and "passive" linkage, + the file gets filled with define-module and export + declarations. + +7/17/2001: cheetah (william fulton) + * Parser bug fix to support constant pointers, eg int* const ptr. + Fixed everywhere - variables, parameters, return types etc. Note that + when wrapping a constant pointer variable only the getter is generated. + +7/17/2001: mkoeppe + * Fixed SF bug #441470 (#define X "//" would not be parsed, + see test-suite entry "preproc-1"), reported by T. W. Burton + . + * Changed the type of character constants to "char", rather + than "char *". Changed the individual language modules + to keep the old behaviour, except for the Guile module, + where it is desired to make them Scheme characters. This + fixes SF bug #231409, test-suite entry "char-constant". + * Applied patch for DOH/Doh/memory.c by Les Schaffer + (avoid required side effects in + assert). + +7/17/2001: cheetah (william fulton) + * Bug fix in parser for virtual destructor with void as parameter + * Bug fix in parser #defines embedded within classes/structs/unions + Consequently %constant can now also be placed within a struct/class/union. + * Bug fix in parser to allow sizeof(*I_am_a_pointer) within a #define + +7/16/2001: mkoeppe + * Added changes for the Macintosh contributed by Luigi + Ballabio . + * Some "const" fixes in the code. + * [Guile]: Made the constant-wrapper functions much shorter. + +7/13/2001: mkoeppe + * [Guile]: Some "const" fixes for Guile version 1.3.4. + * Handle anonymous arguments with default values and static + array members of classes. Both bugs reported by Annalisa Terracina + ; see the files + Examples/guile/test-suite/static-array-member.i and + anonymous-arg.i. + +Version 1.3.6 (July 9, 2001) +============================= + +7/09/2001: cheetah (william fulton) + * GIFPlot examples: FOREGROUND and BACKGROUND definition missing + after TRANSPARENT #define fix in GIFPlot + +7/03/2001: beazley + Fixed up the version numbers so that the release is known + as 1.3.6. All future releases should have a similar + version format. + +7/02/2001: mkoeppe + * [Python]: Prevent the problem of self.thisown not being + defined if the C++ class constructor raised an exception. + Thanks to Luigi Ballabio . + +6/29/2001: mkoeppe + * More portability fixes; fixed "gcc -Wall" warnings. + +6/29/2001: cheetah (william fulton) + * GIFPlot examples: TRANSPARENT #define multiple times on Solaris + (clashes with stream.h). + * Multiple definition bug fix for shadow classes. The perl and python + modules had workarounds which have been replaced with fixes in + the core. Many of the Language::cpp_xxxx functions now set a + flag which the derived classes can access through + is_multiple_definition() to see whether or not code should be + generated. The code below would have produced varying degrees + of incorrect shadow class code for the various modules: + class TestClass + { + public: + TestClass() {}; + TestClass(int a) {}; + ~TestClass() {}; + unsigned long xyz(short k) {}; + unsigned long xyz(int n) {}; + static void static_func() {}; + static void static_func(int a) {}; + }; + void delete_TestClass(int a); + +6/27/2001: mkoeppe + * [Perl] Another const-related portability fix. + +6/26/2001: cheetah (william fulton) + * [Java] Added in cpp_pragma() support with a host of new pragmas - see + jswig.html. These are designed for better mixing of Java and c++. It + enables the user to specify pure Java classes as bases and/or interfaces + for the wrapped c/c++. + * [Java] Old pragmas renamed. Warning given for the moment if used. + *** POTENTIAL INCOMPATIBILITY FOR JAVA MODULE *** + +6/25/2001: mkoeppe + * Incorporated more build changes contributed by Wyss Clemens + for swig/ruby on cygwin. + +6/20/2001: cheetah (william fulton) + * Makefile mods so that 'make check' uses the swig options in the makefiles + * [Java] Removed Generating wrappers message + * [Java] NULL pointer bug fix + * [Java] Bug fix for Kaffe JVM + +6/20/2001: mkoeppe + * SWIG_TypeQuery from common.swg now returns a + swig_type_info* rather than a void*. This fixes a problem + when using pointer.i and C++, as illustrated by the new + test-suite example perl5/pointer-cxx. + * Portability fixes (const char *). + * Incorporated build changes contributed by Wyss Clemens + , which make swig runnable on cygwin. + +6/19/2001: cheetah (william fulton) + * [Java] Bug fix for SF bug #211144. This fix is a workaround + until fixed in the core. + +6/19/2001: mkoeppe + * [Guile]: Portability fixes for use with the Sun Forte + compilers. + * [Tcl]: Portability fix (const char *). + * [Tcl]: Configure now first tries to find a tclConfig.sh + file in order to find the Tcl include directory, library + location and library name. + * [Python]: Added a few possible library locations. + +6/18/2001: mkoeppe + * [Guile]: Don't call scm_c_export if nothing is to be + exported. Don't warn on %module if module has been set + already (this frequently occurs when %import is used). + +6/16/2001: mkoeppe + * [Guile]: New "passive" linkage, which is appropriate for + multi-module extensions without Guile module magic. + +6/15/2001: mkoeppe + * [Guile]: Fixed printing of smobs (space and angle were + missing). + * Properly generate type information for base classes + imported with the %import directive. Thanks to Marcelo + Matus for the report and the + patch; this closes SF bug #231619; see also + Examples/guile/test-suite/import*. + * [Guile]: Fix casting between class and base class; the + runtime type system had it the wrong way around; see + Examples/guile/test-suite/casts.i + * Make typemaps for SWIGPOINTER * with arg name take + precedence over those without arg name, to match normal + typemap precedence rules. + * Fixed the random-line-numbers problem reported as SF bug + #217310; thanks to Michael Scharf . + * [Guile]: Handle the %name and %rename directives. + * New syntax: %name and %rename now optionally take double + quotes around the scripting name. This is to allow scripting + names that aren't valid C identifiers. + +6/14/2001: beazley + Made a minor change to the way files are loaded in + order to get file/line number reporting correct in + the preprocessor. + +6/14/2001: mkoeppe + * The parser now understands the (non-standard) "long long" + types. It is up to the individual language modules to + provide typemaps if needed. Reported by Sam Steingold, SF + bug #429176. + * The parser now understands arguments like "const int * + const i". This fixes SF bug #215649. + * Fixed the Guile test-suite. + +6/13/2001: mkoeppe + Partial merge from the CVS trunk at tag + "mkoeppe-merge-1". This covers the following changes: + +| 01/16/01: ttn +| Wrote table of contents for Doc/engineering.html. Added section +| on CVS tagging conventions. Added copyright to other docs. +| 9/25/00 : beazley +| Modified the preprocessor so that macro names can start with a '%'. +| This may allow new SWIG "directives" to be defined as macros instead +| of having to be hard-coded into the parser. +| +| *** Also a yet-to-be-documented quoting mechanism with backquotes +| *** has been implemented? + +6/13/2001: mkoeppe + * When configure does not find a language, don't use default + paths like /usr/local/include; this only causes build + problems. + * New directory: Examples/Guile/test-suite, where a few + bugs in 1.3a5 are demonstrated. + * Handle C++ methods that have both a "const" and a "throw" + directive (see Examples/Guile/test-suite/cplusplus-throw.i); + thanks to Scott B. Drummonds for the report and the fix. + * Handle C++ pointer-reference arguments (like "int *& arg") + (see Examples/Guile/test-suite/pointer-reference.i, + reported as SF bug #432224). + * [Ruby] Fixed typo in rubydec.swg; thanks to Lyle Johnson! + * Don't stop testing when one test fails. + * [Guile, MzScheme] Don't print "Generating wrappers...". + +6/12/2001: mkoeppe + [Guile] VECTORLENINPUT and LISTLENINPUT now have separate + list length variables. TYPEMAP_POINTER_INPUT_OUTPUT + attaches argument documentation involving SCM_TYPE to the + standard pointer typemaps. INOUT is now an alias for BOTH. + +6/12/2001: cheetah (william fulton) + Some Java documentation added. + [Java] Fixed bugs in import pragma and shadow pragma. + +6/12/2001: mkoeppe + Fix declarations of SWIG_define_class + (Lib/ruby/rubydec.swg) and SWIG_TypeQuery + (Lib/common.swg). Thanks to Lyle Johnson + for the patches. + +6/11/2001: mkoeppe + [Guile] Use long instead of scm_bits_t; this makes the + generated wrapper code compatible with Guile 1.3.4 + again. Thanks to Masaki Fukushima for pointing this out. + +6/11/2001: cheetah (william fulton) + The generic INSTALL file from autoconf added. Few changes to README file. + +6/11/2001: mkoeppe + Fixed typo in Makefile.in; thanks to Greg Troxel + . + +6/08/2001: cheetah (william fulton) + make check works again. Examples/GIFPlot configure generated by + top level autoconf now. + +6/08/2001: mkoeppe + Another build change: The new script autogen.sh runs + autoconf in the appropriate directories. The top-level + configure also configures in Examples/GIFPlot. + +6/07/2001: mkoeppe + Made the Makefile work with non-GNU make again. + +6/07/2001: cheetah (william fulton) + [Java] Class/struct members that are arrays of pointers to classes/structs - + Shadow class's get/set accessors now use Java classes instead of longs (pointers). + [Java] Shadow classes will now clean up memory if function return type + is a class/struct. + [Java] New example called reference based on the same example from other modules. + +6/06/2001: mkoeppe + New configure option --with-release-suffix allows for + attaching a suffix to the swig binary and the swig runtime + libraries. Minor changes to the build system. "swig + -swiglib" works again. If invoked with the new option + "-ldflags", SWIG prints a line of linker flags needed to + link with the runtime library of the selected language + module. + +6/06/2001: mkoeppe + [Guile] gswig_list_p is an int, not a SCM. This typo + caused warnings when compiling with a Guile configured with + strict C type checking. In INPUT and BOTH typemaps + generated by the SIMPLE_MAP macro, use the SCM_TO_C + function to convert from Guile to C (rather than C_TO_SCM). + Use scm_intprint to print pointers (rather than + sprintf). Allow using "-linkage" instead of "-Linkage". + +6/05/2001: cheetah (william fulton) + [Java] Mods for using inherited c++ classes from Java + [Java] New example called class based on the same example from other modules + +6/05/2001: cheetah (william fulton) + [Java] destructor (_delete()) was not aware of %name renaming + [Java] extends baseclass did not know about %name renaming + [Java] extends baseclass did extend even when the baseclass was not known to swig + [Java] sometimes enum-declarations occured before the Java class declaration + [Java] unrelated enum initialisations no longer appear in Java class + [Java] if module ends in '_' correct JNI names are now produced + +6/04/2001: cheetah (william fulton) + [Java] Shadow class mods - Modified constructor replaces + newInstance(). _delete() now thread safe. getCPtr() replaces + _self. _selfClass() removed as now redundant. + *** POTENTIAL INCOMPATIBILITY FOR JAVA MODULE *** + + [Java] Not all output java files had SWIG banner. New banner. + + [Java] Shadow class finalizers are output by default: Command + line option -finalize deprecated and replaced with -nofinalize. + *** POTENTIAL INCOMPATIBILITY FOR JAVA MODULE *** + +6/ 1/2001: mkoeppe + [Guile] Cast SCM_CAR() to scm_bits_t before shifting it. + This is required for compiling with a Guile configured with + strict C type checking. + +6/ 1/2001: mkoeppe + Added configure option "--with-swiglibdir". + +5/31/2001: mkoeppe + [Guile] Support multiple parallel lists or vectors in + the typemaps provided by list-vector.i. New typemaps file, + pointer-in-out.i. + +5/25/2001: cheetah (william fulton) + [Java] HTML update for examples. + +5/28/2001: mkoeppe + Minor changes to the build system. Added subdirectory for + Debian package control files. + +5/28/2001: mkoeppe + [Guile] Build a runtime library, libswigguile. + +5/28/2001: mkoeppe + [Guile] New typemap substitution $*descriptor. Use the {} + syntax, rather than the "" syntax for the standard + typemaps, in order to work around strange macro-expansion + behavior of the SWIG preprocessor. This introduces some + extra braces. + +5/27/2001: mkoeppe + [Guile] Handle pointer types with typemaps, rather than + hard-coded. New typemap substitutions $descriptor, + $basedescriptor; see documentation. Some clean-up in the + variable/constants wrapper generator code. New convenience + macro SWIG_Guile_MustGetPtr, which allows getting pointers + from smobs in a functional style. New typemap file + "list-vector.i", providing macros that define typemaps for + converting between C arrays and Scheme lists and vectors. + +5/25/2001: cheetah (william fulton) + [Java] STL string moved into its own typemap as it is c++ code and + it break any c code using the typemaps.i file. + - Fixes for wrappers around global variables - applies to primitive + types and user types (class/struct) and pointers to these. + - Structure member variables and class public member variables getters + and setters pass a pointer to the member as was in 1.3a3 and 1.1 + (1.3a5 was passing by value) + - Parameters that were arrays and return types were incorrectly + being passed to create_function() as pointers. + - Fix for arrays of enums. + [Java] Updated java examples and added two more. + [Java] Java module updated from SWIG1.3a3 including code cleanup etc. + [Java] enum support added. + [Java] Array support implemented + [Java] Shadow classes improved - Java objects used rather than + longs holding the c pointer to the wrapped structure/c++class + +5/22/2001: mkoeppe + [Guile] Fixed extern "C" declarations in C++ mode. Thanks + to Greg Troxel . + +5/21/2001: mkoeppe + [Guile] New linkage "module" for creating Guile modules for + Guile versions >= 1.5.0. + +4/18/2001: mkoeppe + [MzScheme] Added typemaps for passing through Scheme_Object + pointers. + +4/9/2001 : mkoeppe + [MzScheme] Added typemaps for `bool'. Inclusion of headers + and support routines is now data-driven via mzscheme.i. + Headers come from the new file mzschemdec.swg. Don't abort + immediately when a type-handling error is reported. When + searching for typemaps for enums, fall back to using int, + like the Guile backend does. Support char constants. Emit + correct wrapper code for variables. + +3/12/2001: mkoeppe + [Guile] Fixed typemaps for char **OUTPUT, char **BOTH. + +3/2/2001 : mkoeppe + [Guile] Every wrapper function now gets a boolean variable + gswig_list_p which indicates whether multiple values are + present. The macros GUILE_APPEND_RESULT, GUILE_MAYBE_VALUES + and GUILE_MAYBE_VECTOR use this variable, rather than + checking whether the current return value is a list. This + allows for typemaps returning a list as a single value (a + list was erroneously converted into a vector or a + multiple-value object in this case). + +3/1/2001 : mkoeppe + [Guile] Added support for returning multiple values as + vectors, or passing them to a muliple-value + continuation. By default, multiple values still get + returned as a list. + +3/1/2001 : mkoeppe + [Guile] Added a "beforereturn" pragma. The value of this + pragma is inserted just before every return statement. + +3/1/2001 : mkoeppe + [Guile] Added support for Guile 1.4.1 procedure + documentation formats, see internals.html. + +2/26/2001: mkoeppe + [Guile] Made the wrapper code compile with C++ if the + "-c++" command-line switch is given. Thanks to + . + +2/26/2001: mkoeppe + [Guile] Now two type tables, swig_types and + swig_types_initial, are used, as all other SWIG language + modules do. This removes the need for the tricky + construction used before that the broken Redhat 7.0 gcc + doesn't parse. Reported by . + +2/26/2001: mkoeppe + [Guile] Fixed typemaps for char *OUTPUT, char *BOTH; a bad + free() would be emitted. Added typemap for SCM. + + +Version 1.3 Alpha 5 +=================== + +9/19/00 : beazley + [Python] Python module generates more efficient code for + creating the return value of a wrapper function. Modification + suggested by Jon Travis. + +9/19/00 : beazley + Library files specified with the -l option are now included at the + end of the interface file (reverting to the old behavior). + +9/19/00 : beazley + Fixed some problems with enum handling. enums are now manipulated as + 'int', but cast into the enum type when values are passed to the + corresponding C function. + +9/19/00 : mkoeppe + [Guile] Removed "-with-smobs" command-line option, as this is the + default now. Added "-emit-setters" command-line option, + which turns on generating procedures-with-setters; see + internals.html. + +9/18/00 : mkoeppe + Incorporated patch #101430, fixing bugs in the Guile module: + 1. Some arguments were erroneously taken as *optional* arguments when + ignored arguments were present. + 2. Guile 1.3.4 was not supported since functions introduced in Guile + 1.4 were used. + 3. Added handling of `const char *'. + +9/17/00 : beazley + Fixed problem with failed assertion and large files. + +9/17/00 : beazley + Fixed problem with the '%' character appearing in added methods + and function bodies. Preprocessor bug. + +Version 1.3 Alpha 4 (September 4, 2000) +======================================= + +9/3/00 : ttn + Added instructions for maintainers in Examples/README on how + to make examples also be useful in the testing framework. + Also, "make check" now uses ./Lib by via env var `SWIG_LIB'. + This is overridable like so: + make chk-swiglib=/my/experimental/swig/Lib check + +9/3/00 : beazley + Added $typemap variable to typemaps. This gets replaced with + a string indicating the typemap that is applied. Feature + request from rsalz. + +9/3/00 : beazley + Experimental optimization to code generation for virtual + member functions. If you have two classes like this: + + class A() { + virtual void foo(); + } + + class B() : public A { + virtual void foo(); + } + + Swig now will generate a single wrapper function for this + + A_foo(A *a) { + a->foo(); + } + + and use it as the implementation of both A_foo() and B_foo(). + This optimization only takes place if both methods are declared + as virtual and both take identical parameters. + *** EXPERIMENTAL FEATURE *** + +9/3/00 : beazley + Restored the "memberin" typemap for setting structure members. + Unlike the old version, the new version is expanded inline in the + wrapper function allowing access to scripting language + internals (a sometimes requested feature). The "memberout" typemap + is gone. Use the "out" typemaps instead. + *** POTENTIAL INCOMPATIBILITY *** + +9/3/00 : beazley + Attribute set methods no longer return the value of a member. + For example: + + struct Foo { + int x; + ... + } + + now gets set as follows: + + void Foo_x_set(Foo *f, int x) { + f->x = x; + } + + In SWIG1.1 it used to be this: + + int Foo_x_set(Foo *f, int x) { + return (f->x = x); + } + + This has been changed due to the complexity created by trying + to do this with more exotic datatypes such as arrays. It also + complicates inlining and handling of the "memberin" typemap. + *** POTENTIAL INCOMPATIBILITY *** + +9/2/00 : beazley + Removed the ptrcast() and ptrmap() functions from the + pointer.i library file. Old implementation is incompatible + with new type system. + *** POTENTIAL INCOMPATIBILITY *** + +9/2/00 : beazley + New runtime function SWIG_TypeQuery(const char *name) added. + This function can be used to extract the type info structure + that is used for type-checking. It works with either the + nice C name or mangled version of a datatype. For example: + + swig_type_info *ty = Swig_TypeQuery("int *"); + swig_type_info *ty = Swig_TypeQuery("_p_int"); + + This is an advanced feature that has been added to support some + exotic extension modules that need to directly manipulate + scripting language objects. + *** NEW FEATURE *** + +9/2/00 : beazley + New directive %types() added. This is used to + explicitly list datatypes that should be included in + the runtime type-checking code. Normally it is never + necessary to use this but sometimes advanced extensions + (such as the pointer.i library) may need to manually + add types to the type-checker. + *** NEW FEATURE *** + +8/31/00 : beazley + Improved handling of string array variables. For example, + a global variable of the form "char name[64]" is automatically + managed as a 64 character string. Previously this didn't + work at all or required the use of a special typemap. + *** NEW FEATURE (Tcl, Perl, Python) *** + +8/31/00 : ttn + Added Makefile target `check-c++-examples', which uses new + files under Examples/C++ contributed by Tal Shalif. Now "make + check" also does "make check-c++-examples". Also, expanded + actions in `check-gifplot-example' and `check-aliveness'. + +8/30/00 : mkoeppe + Major clean-up in the Guile module. Added typemap-driven + documentation system. Changed to handle more than 10 + args. Updated and extended examples. + *** NEW FEATURE *** + +8/29/00 : beazley + Added new %insert directive that inserts the contents of a file + into a portion of the output wrapper file. This is only intended + for use by writers of language modules. Works as follows: + + %insert(headers) "file.swg"; + %insert(runtime) "file.swg"; + %insert(wrappers) "file.swg"; + %insert(init) "file.swg"; + + *** NEW FEATURE *** + +8/29/00 : beazley + Added new %runtime directive which includes code into the runtime + portion of the wrapper code. For example: + + %runtime %{ + ... some internal runtime code ... + %} + + There is no practical reason for ordinary users to use this + feature (almost everything can be done using %{ ... %} + instead). However, writers of language modules may want to + use this in language configuration files. + *** NEW FEATURE *** + +8/28/00 : beazley + Typemaps can now be specified using string literals like + this: + + %typemap(in) int "$target = SvIV($source);"; + + When code is specified like this, it is *NOT* enclosed + inside a local scope (as with older typemap declarations). + Note: character escape sequences are interpreted in the + code string so if you want to include a quote or some + other special character, make sure you use a (\). + *** NEW FEATURE *** + +8/27/00 : beazley + Typemaps have been modified to follow typedef declarations. + For example, if you have this: + + typedef int Number; + + %typemap(in) int { + ... get an integer ... + } + + void foo(Number a); + + The typemap for 'int' will be applied to the argument 'Number a'. + Of course, if you specify a typemap for 'Number' it will take + precedence (nor will it ever be applied to an 'int'). + *** POTENTIAL INCOMPATIBILITY *** + +8/27/00 : beazley + Default typemap specification has changed. In older + versions of swig, you could do this: + + %typemap(in) int SWIG_DEFAULT_TYPE { + ... + } + + To specify the default handling of a datatype. Now that + SWIG follows typedef declarations, this is unnecessary. + Simply specifying a typemap for 'int' will work for all + variations of integers that are typedef'd to 'int'. + + Caveat, specifying the default behavior for pointers, + references, arrays, and user defined types is a little + different. This must be done as follows: + + %typemap() SWIGPOINTER * { + ... a pointer ... + } + %typemap() SWIGREFERENCE & { + ... a reference ... + } + %typemap() SWIGARRAY [] { + ... an array ... + } + %typemap() SWIGTYPE { + ... a user-defined type (by value) ... + } + *** POTENTIAL INCOMPATIBILITY *** + +8/15/00 : dustin + The file swig-1.3a1-1.spec has been added to the Tools directory. + It can be used to build a redhat package for SWIG, although it + will need to be updated for the next public release. + +8/15/00 : beazley + Typemaps have been completely rewritten. Eventually they may be + replaced with something better, but for now they stay. However, + there are a number of a significant changes that may trip some + people up: + + 1. Typemap scoping is currently broken. Because of this, the + following code won't work. + + %typemap(in) blah * { + ... + } + class Foo { + ... + int bar(blah *x); + } + %typemap(in) blah *; /* Clear typemap */ + + (this breaks because the code for the class Foo is actually + generated after the entire interface file has been processed). + This is only a temporary bug. + + 2. In SWIG1.1, the %apply directive worked by performing a + very complex type-aliasing procedure. From this point on, + %apply is simply a generalized typemap copy operation. + For example, + + %apply double *OUTPUT { double *x, double *y }; + + Copies *ALL* currently defined typemaps for 'double *OUTPUT' and + copies them to 'double *x' and 'double *y'. + + Most people probably won't even notice this change in + %apply. However, where it will break things is in code like + this: + + %apply double *OUTPUT { double *x }; + %typemap(in) double *OUTPUT { + ... whatever ... + } + + void foo(double *x); + + In SWIG1.1, you will find that 'foo' uses the 'double *OUTPUT' rule + even though it was defined after the %apply directive (this is + the weird aliasing scheme at work). In SWIG1.3 and later, + the 'double *OUTPUT' rule is ignored because it is defined + after the %apply directive. + + 3. The %clear directive has been modified to erase all currently + defined typemaps for a particular type. This differs from + SWIG1.1 where %clear only removed rules that were added using + the %apply directive. + + 4. Typemap matching is now performed using *exact* types. + This means that things like this + + %typemap(in) char * { } + %typemap(in) const char * { } + + are different typemaps. A similar rule applies for pointers, + arrays, and references. For example: + + %typemap(in) double * { } + + used to apply to 'double &', 'double []', Now, it only applies + to 'double *'. If you want a 'double &', you'll need to handle + that separately. + + 5. Array matching has been simplfied. In SWIG1.1, array matching + was performed by trying various combinations of dimensions. + For example, 'double a[10][20]' was matched as follows: + + double [10][20] + double [ANY][20] + double [10][ANY] + double [ANY][ANY] + + In SWIG1.3, only the following matches are attempted: + + double [10][20] + double [ANY][ANY] + + On the positive side, typemap matching is now *significantly* faster + than before. + *** POTENTIAL INCOMPATIBILITY *** + +8/15/00 : beazley + Secret developer feature. Since datatypes are now represented as + strings internally, you can bypass limitations of the parser and + create a wild datatype by simply enclosing the raw string encoding + in backticks (``) and sticking it in the interface file anywhere a + type is expected. For example, `a(20).a(10).p.f(int,int)`. This + feature is only intended for testing (i.e., you want to see what + happens to your language module if it gets a reference to a pointer + to an array of pointers to functions or something). + *** SICK HACK *** + +8/14/00 : beazley + Completely new type-system added to the implementation. + More details later. + +8/11/00 : beazley + Cleaned up some of the I/O handling. SWIG no longer generates + any temporary files such as _wrap.wrap, _wrap.ii, _wrap.init. + Instead, these "files" are kept around in memory as strings + (although this is transparent to language modules). + +8/4/00 : ttn + Added Makefile target "check" and variants. + This can be used like "make check" or, to explicitly skip a + language LANG: "make skip-LANG=true check". LANG is skipped + automatically if ./configure determines that LANG support is + insufficient. + + Currently, the check is limited to doing the equivalent of + "make all" in some of the Examples directories. This should + be expanded both horizontally (different types of tests) and + vertically (after "make all" in an Examples subdir succeeds, + do some additional tests with the resulting interpreter, etc). + +8/4/00 : ttn + Added Makefile target "distclean", which deletes all the + files ./configure creates, including config.status and friends. + +8/3/00 : harcoh + java changes??? [todo: document changes] + +7/23/00 : beazley + Typemaps have been modified to key off of the real datatypes + used in the interface file. This means that typemaps for + "const char *" and "char *" will be difference as will typemaps + for "Vector" and "Vector *." + *** POTENTIAL INCOMPATIBILITY *** + This is likely to break interfaces that rely on the odd type + handling behavior of typemaps in SWIG1.1--especially with + respect to interfaces involving pass-by-value. + +7/23/00 : beazley + New %constant directive. This directive can be used to + create true constants in the target scripting language. + It's most simple form is something like this: + + %constant FOO 42; + + In this case, the type is inferred from the syntax of the + value (in reality, all #define macros are translated into + directives of this form). + + An expanded version is as follows: + + %constant(Foo *) FOO = &FooObj; + + In this case, an explicit type can be specified. This + latter form may be useful for creating constants that + used to be specified as + + const Foo *FOO = &FooObj; + + (which are now treated as variables). + *** EXPERIMENTAL FEATURE *** The syntax may change in + the final release. + +7/23/00 : beazley + Modified the parser so that variable declarations of the form + "const type *a" are handled as variables, not constants. + Note: SWIG1.1 handled this case erroneously because + const char *a is a pointer variable that can be reassigned. + *** POTENTIAL INCOMPATIBILITY *** + Note: just because this is the "right" way to do things, + doesn't mean it's the most appropriate interpretation. + I suspect that many C programmers might use 'const char *' + with the intent of creating a constant, without realizing + that they've created a reassignable global variable. + +7/23/00 : beazley + The C/C++ wrapping layer has been completely redesigned and + reimplemented. This change should iron out a few rough + spots with the handling of datatypes. In addition, the + wrapper code is somewhat cleaner. + *** POTENTIAL INCOMPATIBILITY *** + This change may break interfaces that involve + subtle corner-cases with typemaps and the %addmethods + directive since some of these features had somewhat + type handling behavior in SWIG1.1. + +7/23/00 : beazley + The "memberin" and "memberout" typemaps are gone for the + moment, but they might return as soon as I figure out + how to integrate them with some of the streamlined C wrapper + functions. + *** POTENTIAL INCOMPATIBILITY *** + +7/22/00 : beazley + A variety of old type handling functions such as print_type(), + print_full(), print_mangle(), etc... are gone and have been + replaced with a smaller set of functions. See the file + Doc/internals.html for details. This will break all third + party language modules. + *** POTENTIAL INCOMPATIBILITY *** + +7/20/00 : beazley + Deprecated the %val and %out directives. These directives + shouldn't really be necessary since typemaps can be used + to achieve similar results. This also cleans up the + handling of types and parameters quite a bit. + *** POTENTIAL INCOMPATIBILITY *** + +7/20/00 : ttn + Fixed unspecified-module bug in Guile support and removed + more non-"with-smobs" functionality using patches submitted + by Matthias Koeppe. + + Re-enable recognition of "-with-smobs" (with no effect since + we use smobs by default now) for the time being. After the + 1.3a4 release, this option will signal an error. + +7/17/00 : ttn + Fixed NULL-input bug in parameter list handling. + Reported by Matthias Koeppe. + +7/12/00 : beazley + Fixed memory leak in Python type-checking code. Reported by + Keith Davidson. Bug #109379. + +7/10/00 : beazley + Changed internal data structures related to function parameters. + +7/10/00 : beazley + Fixed some bugs related to the handling of the %name() directive + and classes in the Tcl module. Problem reported by James Bailey. + +7/10/00 : beazley + Fixed parsing and enum handling problems with character constants. + Reported by Greg Kochanski. + +7/10/00 : beazley + Removed WrapperFunction class from the core and updated the language + module. This will break third party modules. + *** POTENTIAL INCOMPATIBILITY *** + +7/9/00 : beazley + Implementation of SWIG no longer makes use of C++ operator overloading. + This will almost certainly break *all* third party language modules + that are not part of the main SWIG CVS tree. Sorry. + *** POTENTIAL INCOMPATIBILITY *** + +7/8/00 : beazley + Removed the experimental and undocumented "build" typemap that + was intended to work with multiple arguments. Simply too weird + to keep around. Besides, a better replacement is in the works. + +7/6/00 : ttn + Removed non-"with-smobs" functionality (Guile support), i.e., + "-with-smobs" is now the default and no longer needs to be + specified on the command-line. + +7/5/00 : ttn + Incorporated Ruby support contributed by Masaki Fukushima. + +6/28/00 : ttn + Applied more-than-10-args bugfix patch contributed + by Matthias Koeppe. + +6/27/00 : beazley + Rewrote some of the string handling and eliminated the C++ + implementation (which is now just a wrapper). + +6/27/00 : ttn + Added Doc/index.html and Doc/internals.html. The target + audience for the latter is new SWIG developers. + + +Version 1.3 Alpha 3 (June 18, 2000) +=================================== + +6/18/00 : beazley + Removed the naming.cxx, hash.cxx, and symbol.cxx files from + the SWIG1.1 directory. Continued to migrate things away + from the C++ base (although there's still a lot of work to do). + +6/17/00 : beazley + Added a few more examples to the Examples directory. Still + need to do a lot of work on this. + +6/16/00 : beazley + Added -includeall to follow all #include statements in the + preprocessor. + +6/15/00 : beazley + Tried to fix as many C++ warnings as possible when compiling + with the Sun Workshop C++ compiler. Unfortunately, this means + that there are a lot of statements that contain string literals + of the form (char*)"Blah". + +6/15/00: beazley + A variety of cleanup and performance optimization in the + low-level DOH library. This seems to result in a speedup + of 50-100% for preprocessing and other related tasks. + +5/10/00 : ttn + Applied variable-wrapping bugfix patch contributed + by Matthias Koeppe. + +4/17/00 : ttn + Updated MzScheme support contributed by Oleg Tolmatcev. + We now use a `Scheme_Type'-based structure to wrap pointers. + +4/11/00 : ttn + Incorporated further Guile-support patch by Matthias Koeppe. + Typemaps previously deleted have been re-added. There is now + exception handling (see Doc/engineering.html). `SWIG_init' is now + declared extern only for simple linkage. Some bugs were fixed. + +4/06/00 : ttn + Incorporated MzScheme support contributed by Oleg Tolmatcev. + This includes new directories Lib/mzscheme and Examples/mzscheme. + +4/03/00 : ttn + Added Examples/guile and children. This is an adaptation of + the same-named directory from the SWIG-1.1p5 distribution. + Added Guile-specific section to Doc/engineering.html. + +4/02/00 : ttn + Incorporated new guilemain.i by Martin Froehlich. + Incorporated Guile-support rewrite patch by Matthias Koeppe. + The command line option "-with-smobs" enables implementation of + pointer type handling using smobs, the canonical mechanism for + defining new types in Guile. Previous implementation (using + strings) is at the moment still supported but deprecated. At + some point, "-with-smobs" will be the default and no longer + required. + +3/13/00 : beazley + Added purify patches submitted by Ram Bhamidipaty. + +3/02/00 : ttn + Added support for different Guile "linkage" schemes. + Currently, "-Linkage hobbit" works. + + +Version 1.3 Alpha 2 (March 1, 2000) +=================================== + +2/29/00 : beazley + Made SWIG ignore the 'mutable' keyword. + +2/29/00 : beazley + Incorporated some patches to the Perl5 module related to + the -hide option and the destruction of objects. + Patch submitted by Karl Forner. + +2/27/00 : ttn + Incorporated Guile support contributed by Matthias Koeppe. + This includes a cpp macro in Lib/guile/guile.swg and the + entire file Lib/guile/typemaps.i. + +2/25/00 : ttn + Modified configure.in and Makefile.in files to support + non-local build (useful in multi-arch environments). + +2/24/00 : ttn + Incorporated Guile support contributed by Clark McGrew. + This works with Guile 1.3, but since it depends heavily + on the gh_ interface, it should work for all later versions. + It has not been tested with versions before 1.3. + WARNING: Code is unstable due to experimentation by ttn. + +2/16/00 : beazley + A variety of performance improvements to the Python shadow + class code generation. Many of these result in substantial + runtime performance gains. However, these have come at + a cost of requiring the use of Python 1.5.2. For older + versions, use 'swig -noopt -python' to turn off these + optimization features. + +Version 1.3 Alpha 1 (February 11, 2000) +======================================= + +2/11/00 : Added 'void' to prototype of Python module initializer. + Reported by Mark Howson (1/20/00). + +2/11/00 : beazley + Modified the Python shadow class code to discard ownership of an + object whenever it is assigned to a member of another object. + This problem has been around for awhile, but was most recently + reported by Burkhard Kloss (12/30/99). + +2/11/00 : beazley + Added braces around macros in the exception.i library. Reported + by Buck Hodges (12/19/99) + +2/11/00 : beazley + Fixed bug in the constraints.i library. Reported by Buck + Hodges (12/14/99) + +2/11/00 : beazley + The %native directive now generates Tcl8 object-style command calls. + A full solution for Tcl7 and Tcl8 is still needed. Patch suggested + by Mike Weiblen (11/29/99) + +2/11/00 : beazley + Modified the typemap code to include the $ndim variable for arrays. + Patch provided by Michel Sanner (11/12/99). + +2/11/00 : beazley + Modified the Python module to raise a Runtime error if an attempt + is made to set a read-only member of a shadow class. Reported by + Michel Sanner (11/5/99). + +2/10/00 : The documentation system has been removed. However, it is likely + to return at some point in the future. + +2/1/00 : Added a number of performance enhancements to the Python shadow + classing and type-checking code. Contributed by Vadim Chugunov. + + 1. Remove _kwargs argument from the shadow wrappers when -keyword + option is not specified. This saves us a construction of keyword + dictionary on each method call. + + def method1(self, *_args, **_kwargs): + val = apply(test2c.PyClass1_method1, (self,) + _args, _kwargs) + return val + + becomes + + def method1(self, *_args): + val = apply(test2c.PyClass1_method1, (self,) + _args) + return val + + 2. Incorporate self into the _args tuple. This saves at least one tuple + allocation per method call. + + def method1(self, *_args): + val = apply(test2c.PyClass1_method1, (self,) + _args) + return val + + becomes + + def method1(*_args): + val = apply(test2c.PyClass1_method1, _args) + return val + + 3. Remove *Ptr classes. + Assume that we are SWIGging a c++ class CppClass. + Currently SWIG will generate both CppClassPtr class + that hosts all methods and also CppClass that is derived + from the former and contains just the constructor. + When CppClass method is called, the interpreter will try + to find it in the CppClass's dictionary first, and only then + check the base class. + + CppClassPtr functionality may be emulated with: + + import new + _new_instance = new.instance + def CppClassPtr(this): + return _new_instance(CppClass, {"this":this,"thisown":0}) + + This saves us one dictionary lookup per call. + + The new module was first added in Python-1.5.2 so it + won't work with older versions. I've implemented an + alternative that achieves the same thing + + 4. Use CObjects instead of strings for pointers. + + Dave: This enhancements result in speedups of up to 50% in some + of the preliminary tests I ran. + +2/1/00 : Upgraded the Python module to use a new type-checking scheme that + is more memory efficient, provides better performance, and + is less error prone. Unfortunately, it will break all code that + depends on the SWIG_GetPtr() function call in typemaps. + These functions should be changed as follows: + + if (SWIG_GetPtr(string,&ptr,"_Foo_p")) { + return NULL; + } + + becomes + + if (SWIG_ConvertPtr(pyobj, &ptr, SWIG_TYPE_Foo_p) == -1) { + return NULL; + } + + Note: In the new implementation SWIG_TYPE_Foo_p is no longer + a type-signature string, but rather an index into a type + encoding table that contains type information. + *** POTENTIAL INCOMPATIBILITY *** + +1/30/00 : loic + Conditionaly compile experimental code with --enable-experiment + configure flag. + Fix .cvsignore to ignore configrue & yacc generated files + +1/28/00 : loic + Apply automake everywhere + Keep configure scripts so that people are not *forced* to autoconf + Keep sources generated by yacc so that compilation without yacc + is possible. + Source/LParse/cscanner.c: change lyacc.h into parser.h to please + default yacc generation rules. + Use AC_CONFIG_SUBDIRS in configure.in instead of hand made script. + Update all relevant .cvsignore to include .deps + Fixed missing ; line 136 Source/Swig/swig.h + +1/13/00 : beazley + Fixed a number of minor end-of-file parsing problems in the + preprocessor. + +1/13/00 : beazley + Added -freeze option that forces SWIG to freeze upon exit. + This is only used as a debugging tool so that I can more + easily examine SWIG's memory footprint. + +1/13/00 : beazley + Added patch to guile module for supporting optional arguments + Patch contributed by Dieter Baron. + +1/13/00 : loic + Added .cvsignore, Examples/.cvsignore, Source/DOH/Doh/.cvsignore + Source/SWIG1.1/main.cxx: Fixed -I handling bug + Source/Modules1.1/java.cxx: fixed char* -> const char* warnings that are + errors when compiling with gcc-2.95.2 + Source/SWIG1.1/main.cxx: cast const char* to char* for String_replace + token and rep should really be const. + +1/12/00 : beazley + Added Harco's Java modules. + +1/12/00 : beazley + Revoked the %ifdef, %ifndef, %endif, %if, %elif, and %else + directives. These are no longer needed as SWIG now has a real + preprocessor. + *** POTENTIAL INCOMPATIBILITY *** + +1/12/00 : beazley + Moved the documentation modules from the SWIG directory + to the Modules directory (where they really should have been + to begin with). + +1/12/00 : beazley + Removed the -stat option for printing statistics. The + statistics reporting was inadequate and mostly broken + anyway. + *** POTENTIAL INCOMPATIBILITY *** + +1/12/00 : beazley + Removed the -t option for reading a typemap file. More + trouble than it's worth. Just include typemaps at the top + of the interface file. + *** POTENTIAL INCOMPATIBILITY *** + +1/12/00 : beazley + Removed the %checkout directive. + *** POTENTIAL INCOMPATIBILITY *** + +1/12/00 : beazley + Removed the -ci option for file checkin. Too problematic + to implement. Probably better to just put your SWIG library + under CVS instead. + *** POTENTIAL INCOMPATIBILITY ***. + +1/11/00 : beazley + Deleted the LATEX module. Sorry... Didn't know anyone + who was using it. Besides, I'm looking to simplify + the documentation system. + *** POTENTIAL INCOMPATIBILITY *** + +1/11/00 : beazley + Modified the ASCII documentation module to use a .txt + suffix for its output file instead of .doc. + +1/11/00 : beazley + Added the long-lost SWIG preprocessor back to the system. + It should be enabled by default. Raw preprocessed output + can be viewed using swig -E file.i. + *** NEW FEATURE *** + +1/11/00 : beazley and djmitche + Completely reorganized the SWIG directory structure. The + basic organization is now: + + Source/ SWIG source code + Lib/ SWIG library files (swig_lib) + Doc/ Documentation + Examples/ Examples + + More directories will be added as needed. + +12/08/99: Loic Dachary (loic@senga.org) + Enhanced package handling for perl5 and c++. + + With new option -hide Foo::Bar, every perl5 object (Frob) is + qualified by Foo::Bar::Frob. The package name is solely used + to encapsulate C/C++ wrappers output in _wrap.c and the + corresponding perl package in .pm. Note that a package + name may contain :: (Frob::Nitz) and will be relative to the + package name provided by -hide (Foo::Bar::Frob::Nitz). + + In *_wrap.c, SWIG_init macro is used. Was previously defined + but not used and simplifies code. + + Added typemap(perl5,perl5in) and typemap(perl5,perl5out) that + do the equivalent of typemap(perl5,in) and typemap(perl5,out) + but contain perl code and applies to wrappers generated by + -shadow. + + Lacking proper regression tests I used + Examples/perl5/{c++,constraint,defarg,except, + graph/graph[1234],multinherit,nested,shadow,simple,tree, + typemaps/{argv,argv2,arraymember,database,file,ignore,integer, + output,passref,reference,return}}/. I ran swig with and without + the patches, diff the generatedsources, run the .pl files + and checked that the results are identical. In all those examples + I had no error. + +11/21/99: Modified the Tcl module to provide full variable linking capabilities + to all datatypes. In previous versions, a pair of accessor functions + were created for datatypes incompatible with the Tcl_LinkVar() function. + Now, we simply use variable traces to support everything. This may + break scripts that rely upon the older behavior. + *** POTENTIAL INCOMPATIBILITY *** + +11/21/99: Added slight tweak to wrapper generator to collect local variables + of similar type. Produces somewhat more compact wrapper code. + +11/20/99: Modified the Tcl module to use SWIG_GetArgs() to parse + arguments. This is a technique borrowed from Python in which + arguments are converted using a format string convention similiar + to fprintf(). This results in a *substantial* reduction in the + size of the resulting wrapper code with only a modest runtime overhead + in going through the extra conversion function. + +11/13/99: Completely rewrote the class/structure generation code for the + Tcl module. Now, a small set of runtime functions are used + to implement the functionality for all classes (instead of a + massive amount of runtime code being generated for each class). + Class specific information is simply encoded in a series of + static tables. This results in a *HUGE* reduction in wrapper + code size--especially for C++. + +11/13/99: Removed the -tcl (Tcl 7.x) module. Tcl 8.0 is now several + years old and the defacto standard--no real reason to keep + supporting the old version at this point. + +11/13/99: Cleaned up -c option for Python module. The pyexp.swg file + is now gone. + +11/13/99: Fixed external declarations to work better with static linking + on Windows. Static linking should now be possible by defining + the -DSTATIC_LINK option on the command line. Patch contributed + by Alberto Fonseca. + +11/5/99 : Fixed an obscure code generation bug related to the generation + of default constructors. Bug reported by Brad Clements. + +11/5/99 : Fixed a few memory problems found by purify. + +11/5/99 : Officially deprecated the -htcl, -htk, and -plugin options + from the Tcl and Tcl8 modules. + +10/26/99: Removed unused variable from python/typemaps.i. Patch + contributed by Keith Davidson. + +8/16/99 : Added _WIN32 symbol to libraries to better support Windows. + +8/16/99 : Deprecated the Perl4 module. It is no longer included in the + distribution and no longer supported. In the entire 3 years SWIG + has been around I never received a single comment about it so I'm + assuming no one will miss it... + +8/16/99 : Modified the type-checking code to register type mappings using a + table instead of repeated calls to SWIG_RegisterMapping(). This + reduces the size of the module initialization function somewhat. + +8/15/99 : Cleaned up the pointer type-checking code in the Tcl module. + +8/15/99 : Many changes to the libraries to support runtime libraries. + +8/13/99 : Eliminated C++ compiler warning messages about extern "C" linkage. + +8/13/99 : Some cleanup of Python .swg files to better support runtime libraries + on Windows. + +8/13/99 : Modified the %pragma directive to attach pragmas declared inside + a class definition to the class itself. For example: + + class foo { + ... + %pragma(python) addtomethod = "insert:print `hello world'" + ... + } + + Most people don't need to worry about how this works. For people + writing backend modules, class-based pragmas work like this: + + lang->cpp_open_class() // Open a class + lang->cpp_pragma() // Supply pragmas + ... // Emit members + + lang->cpp_close_class() // Close the class + + All of the pragmas are passed first since they might be used to + affect the code generation of other members. Please see + the Python module for an example. Patches contributed + by Robin Dunn. + +8/13/99 : Patch to Python shadow classes to eliminate ignored + exception errors in destructors. Patch contributed + by Robin Dunn. + +8/11/99 : Minor patch to swig_lib/python/swigptr.swg (added SWIGSTATIC + declaration). Patch contributed by Lyle Johnson. + +8/11/99 : Added FIRSTKEY/NEXTKEY methods to Perl5 shadow classes + Patch contributed by Dennis Marsa. + +8/11/99 : Modified Python module so that NULL pointers are returned + and passed as 'None.' Patch contributed by Tal Shalif. + +8/10/99 : Fixed missing 'int' specifiers in various places. + +8/10/99 : Added Windows makefile for Runtime libraries. Contributed + by Bob Techentin. + +8/10/99 : Fixed minor problem in Python runtime makefile introduced + by keyword arguments. + +8/8/99 : Changed $target of perl5(out) typemap from ST(0) to + ST(argvi). Patch contributed by Geoffrey Hort. + +8/8/99 : Fixed bug in typemap checking related to the ANY keyword + in arrays and ignored arguments. Error reported by + Geoffrey Hort. + +8/8/99 : %enabledoc and %disabledoc directives can now be used + inside class/structure definitions. However, no check + is made to see if they are balanced (i.e., a %disabledoc + directive inside a class does not have to have a matching + %enabledoc in the same class). + +8/8/99 : Keyword argument handling is now supported in the Python + module. For example: + + int foo(char *bar, int spam, double x); + + Can be called from Python as + + foo(x = 3.4, bar="hello", spam=42) + + To enable this feature, run SWIG with the '-keyword' command + line option. Mixing keyword and default arguments + should work as well. Unnamed arguments are assigned names + such as "arg1", "arg2", etc... + + *** POTENTIAL INCOMPATIBILITY *** + Functions with duplicate argument names such as + bar(int *OUTPUT, int *OUTPUT) will likely cause problematic + wrapper code to be generated. To fix this, use different + names or use %apply to map typemaps to alternate names. + +8/8/99 : Handling of the 'this' pointer has been changed in Python shadow + classes. Previously, dereferencing of '.this' occured in the + Python shadow class itself. Now, this step occurs in the C + wrappers using the following function: + + SWIG_GetPtrObj(PyObject *, void **ptr, char *type) + + This function can accept either a string containing a pointer + or a shadow class instance with a '.this' attribute of + appropriate type. This change allows the following: + + 1. The real shadow class instance for an object is + passed to the C wrappers where it can be examined/modified + by typemaps. + + 2. Handling of default/keyword arguments is now greatly + simplified. + + 3. The Python wrapper code is much more simple. + + Plus, it eliminated more than 300 lines of C++ code in the + Python module. + + *** CAVEAT : This requires the abstract object interface. + It should work with Python 1.4, but probably nothing older + than that. + + +8/8/99 : Fixed handling of "const" and pointers in classes. In particular, + declarations such as + + class foo { + ... + const char *msg; + const int *iptr; + } + + are handled as assignable variables as opposed to constant + values (this is the correct behavior in C/C++). Note: + declarations such as "char *const msg" are still unsupported. + Constants declared at the global level using const are also + broken (because I have a number of interfaces that rely upon + this behavior). + + *** POTENTIAL INCOMPATIBILITY *** This may break interfaces that + mistakenly treat 'const char *' types as constant values. + +8/8/99 : Modified the parser to support bit-fields. For example: + + typedef struct { + unsigned int is_keyword : 1; + unsigned int is_extern : 1; + unsigned int is_static : 1; + } flags; + + Bit-fields can only be applied to integer types and their + are other restrictions. SWIG performs no such type-checking + (although the C compiler will catch problems when it tries to + compile the wrapper code). + +8/8/99 : Removed trailing space of $basetype substitution in typemaps. + This is to allow things like this: + + %typemap(python, argout) spam** OUTPUT{ + ... + char* a = "$basetype_p"; + ... + } + + (Patch suggested by Nathan Dunfield). + +6/22/99 : Made a very slight tweak to the Perl5 shadow class + code that allows typemaps to alter the return type + of objects (to support polymorphic types). Patch + contributed by Drake Diedrich. + +4/8/99 : Fixed null pointer handling bug in Perl module. + Patch contributed by Junio Hamano. + +3/17/99 : Fixed bug in perl5ptr.swg for ActiveState Perl. + Patch contributed by Greg Anderson. + +2/27/99 : Eliminated segmentation fault when Swig runs on + empty files. + +2/27/99 : Added patch to Guile module to eliminate unused + variables. Contributed by Mike Simons. + +2/27/99 : Fixed problem with %addmethods returning references. + +2/27/99 : Fixed Runtime/Makefile. Patch contributed by + Mike Romberg. + +2/27/99 : Incorporated patches to the type-checker. + +2/27/99 : Fixed problem with -exportall switch and shadow classes + in Perl5 module. Patch contributed by Dennis Marsa. + +2/27/99 : Modified Perl5 module to recognize 'undef' as a NULL char *. + Patch contributed by Junio Hamano. + +2/27/99 : Fixed the Perl5 module to support the newer versions of + ActiveState Perl for Win32. + +2/27/99 : Fixed the include order of files specified with the + -I option. + +2/5/98- : Dave finishes his dissertation, goes job hunting, moves to +2/5/99 Chicago and generally thrashes about. + +Version 1.1 Patch 5 (February 5, 1998) +====================================== + +2/4/98 : Fixed a bug in the configure script when different package + locations are specified (--with-tclincl, etc...). + +2/2/98 : Fixed name-clash bug related to the switch to C macros for accessor + functions. The new scheme did not work correctly for objects + with members such as 'obj', 'val', etc... Fixed the bug by + appending the word 'swig' to macro argument names. Patch + contributed by Rudy Albachten. + +2/2/98 : Slight fix to the Perl5 module to eliminate warning messages + about 'varname used only once : possible typo'. Fix + contributed by Rudy Albachten. + +1/9/98 : Fixed a bug in the Perl 5 module related to the creation of + constants and shadow classes. + +1/9/98 : Fixed linking bug with Python 1.5 embed.i library file. + +Version 1.1 Patch 4 (January 4, 1998) +===================================== + +1/4/98 : Changed structured of the Examples directory to be more friendly + to Borland C++. + +1/4/98 : Added the function Makefile.win.bc for compiling the examples + under Borland 5.2. + +1/4/98 : Slight change to the perl5 module and C++ compilation. The + library is now included before any Perl headers + because Perl the extern "C" linkage of math.h screws alot + of things up (especially on Windows). + +1/2/98 : Change to the Python module that reduces the number of constants + created by C++ classes, inheritance, and shadow classes. This + modification may introduce a few slight incompatibilities if + you attempt to use the non-shadow class interface with shadow + classes enabled. Patch contributed by Mike Romberg. + +1/2/98 : Support for Tcl 8.0 namespaces has been added. This *replaces* + the original SWIG mechanism that assumed [incr Tcl] namespaces. + To use namespaces, simply run SWIG with the following options + + swig -tcl -namespace foo.i + + This places everything in a namespace that matches + the module name + + swig -tcl -namespace -prefix bar foo.i + + This places everything in the namespace 'bar' + + The use of namespaces is new in Tcl 8.0. However, the wrapper code + generated by SWIG will still work with all versions of Tcl newer + than and including Tcl 7.3/Tk3.6 even if the -namespace option is + used. + + *** POTENTIAL INCOMPATIBILITY *** + This change may break existing applications that relied on the + -prefix and -namespace options. + +1/2/98 : Added the following constants to the Tcl wrapper code + + SWIG_name - Name of the SWIG module + SWIG_prefix - Prefix/namespace appended to command names + SWIG_namespace - Name of the namespace + + SWIG library writers can use these to their advantages. + +1/2/98 : Fixed a bug in the Tcl8 module related to the creation of + pointer constants (the function SWIG_MakePtr was missing from + the wrapper code). + +1/2/98 : Added the consthash.i library file to the Tcl and Tcl8 modules. + +1/1/98 : Changed and cleaned up the Python typemaps.i file. The following + significant changes were made : + + 1. The OUTPUT typemap now returns Python tuples instead of + lists. Lists can be returned as before by using the + L_OUTPUT type. If compatibility with older versions + is needed, run SWIG with the -DOUTPUT_LIST option. + + 2. The BOTH typemap has been renamed to INOUT. For backwards + compatibility, the "BOTH" method still exists however. + + 3. Output typemaps now generate less code than before. + + Changes to typemaps.i may break existing Python scripts that assume + output in the form of a list. + *** POTENTIAL INCOMPATIBILITY *** + +12/31/97: Fixed long overdue problems with the testing scripts and certain + makefiles that required the use of the bash shell. Everything should + work properly with the standard Bourne shell (sh) now. + +12/31/97: Modified typemaps to allow $basetype as a valid local variable. + This allows for all sorts of bizarre hackish typemaps that + do cool things. Patch contributed by Dominique Dumont. + +12/31/97: Switched accessor functions generated for member data to + C preprocessor macros (except in cases involving typemaps + or char *). + +12/31/97: Fixed a bug related to C++ member data involving references. + +12/31/97: Changed accessor functions for C++ member functions to + preprocessor macros. This cleans up the wrapper code + and results in fewer function definitions. + +12/31/97: Changed the default C constructor to use calloc() instead + of malloc() + +12/30/97: Changed the creation of constants in the Perl5 module. + For all practical purposes, they should work in exactly the + same way as before except that they now require much less + wrapper code. Modules containing large numbers of + constants may see greater than a 50% reduction in wrapper + code size. + +12/30/97: Modified the Python module to be more intelligent about the + creation of constants. SWIG no longer generates redundant + global variables and the size of the module initialization + function should be reduced. (Many thanks to Jim Fulton). + +12/29/97: Fixed a bug in C++ code generation related to member functions, + default arguments, and references. + +12/29/97: Fixed configure script and a few makefiles to support Python 1.5 + +12/29/97: Added 'embed15.i' library file. This file should be used to + staticly link versions of Python 1.5. To make it the default, + simply copy 'swig_lib/python/embed15.i' to 'swig_lib/python/embed.i' + +Version 1.1 Patch 3 (November 24, 1997) +======================================== + +11/23/97: Fixed a bug in the Perl5 module with shadow classes and + static class functions that return class instances. + Note : The fix for this bug requires a slight restructuring of + of the .pm files created by SWIG. + +11/23/97: Fixed a bug in the Tcl/Tcl8 modules related to variable linking + of character arrays. If you declared a global variable 'char foo[10]', + the generated wrapper code would either cause a segmentation fault + immediately upon loading or weird memory corruption elsewhere. + This should now be fixed although character arrays can only be + read-only. + +11/23/97: Fixed a bug with the %import directive that caused it to + fail if files were imported from directories other than + the current working directory. + +11/23/97: Fixed incorrect diagnostic message in the ASCII documentation + module. + +11/23/97: Changed the behavior of the -o option when used with shadow + classes. If -o was used to specify both the pathname and filename + of SWIG's output such as + + swig -o /home/swig/wrapper.c -shadow -perl5 foo.i + + The wrapper code would be placed the file specified with -o, + but the .pm file and documentation would be placed in the + directory where SWIG was run. Now, these files are placed + in the same directory as the file specified with the -o option. + This change is also needed for proper operation on the + Macintosh. + +11/23/97: Added a 'this()' method to Perl5 shadow classes. This can + be used to return the normal pointer value from a shadow + class that is represented as a tied hash. To use just + invoke as a method like this : + + $l = new List; # Create an object + $ptr = $l->this(); # Get the normal pointer value + + *** NEW FEATURE *** + +11/23/97: Fixed the Tcl 8 pointer.i library file (which was completely + broken in 1.1p2). + +11/23/97: Modified the Perl5 type-checker to fix a few problems + with global variables of pointer types and to allow + tied hashes to be used interchangably with normal + pointer values. + +11/23/97: Modified the typemap mechanism to allow output + typemaps of type 'void'. These were ignored previously, + but now if you specify, + + %typemap(lang,out) void { + ... return a void ... + } + + You can change or assign a return value to the function. + +11/23/97: Fixed processing of 'bool' datatypes in the Python module. + +11/23/97: Fixed minor parsing error with C++ initializers. For example, + + class B : public A { + public: + B() : A() { ... }; + ... + } + +11/23/97: Fixed the Tcl8 module so that C functions that call back into + Tcl don't corrupt the return result object (SWIG was gathering + the result object too early which leads to problems if subsequent + Tcl calls are made). + +11/23/97: Fixed a code generation bug in the Python module when two or + more output parameters were used as the first arguments of a + function. For example : + + %include typemaps.i + void foo(double *OUTPUT, double *OUTPUT, double a); + + Previously, doing this resulted in the creation of an + extraneous comma in the output, resulting in a C syntax error. + +11/22/97: Fixed a bug when template handling that was stripping whitespace + around nested templates. For example : + + Foo > + + was getting munged into Foo> which is a syntax error in + in the C++ compiler. + +11/22/97: Fixed bugs in the Borland C++ makefiles. + +11/22/97: Fixed memory corruption bug when processing integer + arguments in Tcl8 module. + +11/21/97: Fixed a bug in the Runtime/Makefile related to Tcl 8. + +11/21/97: Fixed a bug with the %new directive and Perl5 shadow classes. + No longer generates a perl syntax error. + +11/9/97 : Changed a strncpy() to strcpy() in the pointer type-checker. + This results in a substantial performance improvement in + type-checking. + +10/29/97: Fixed a bug in the code generation of default arguments and + user-defined types. For example : + + void foo(Vector a, Vector b = d); + + should now work properly. + +Version 1.1 Patch 2 (September 4, 1997) +======================================= + +9/4/97 : Fixed problem with handling of virtual functions that + was introduced by some changes in the C++ module. + +Version 1.1 Patch 1 (August 27, 1997) +===================================== + +8/26/97 : Fixed compilation and run-time bugs with Tcl 8.0 final. + +8/21/97 : Fixed code generation bug with arrays appearing as arguments + to C++ member functions. For example : + + class Foo { + public: + void Bar(int a[20][20]); + }; + + There is still a bug using arrays with added methods + however. + +8/20/97 : Fixed a bug with generating the code for added methods + involving pass-by-value. + +8/19/97 : Modified the typemapper to substitute the '$arg' value + when declaring local variables. For example : + + %typemap(in) double * (double temp_$arg) { + ... do something ... + } + + When applied to a real function such as the following : + + void foo(double *a, double *b, double *result); + + three local variables will be created as follows : + + double temp_a; + double temp_b; + double temp_result; + + This can be used when writing multiple typemaps that need + to access the same local variables. + + +7/27/97 : Fixed a variety of problems with the %apply directive and arrays. + The following types of declarations should now work : + + %apply double [ANY] { Real [ANY] }; + %apply double [4] { double [10] }; + + A generic version of apply like this : + + %apply double { Real }; + + should now work--even if arrays involving doubles and Reals are + used later. + +7/27/97 : Changed warning message about "Array X has been converted to Y" to + only appear if running SWIG in verbose mode. + +7/27/97 : Added the variables $parmname and $basemangle to the typemap + generator. $parmname is the name of the parameter used + when the typemap was matched. It may be "" if no parameter + was used. $basemangle is a mangled version of the base + datatype. Sometimes used for array handling. + +7/27/97 : Changed the behavior of output arguments with Python shadow classes. + Originally, if a function returned an object 'Foo', the shadow class + mechanism would create code like this : + + def return_foo(): + val = FooPtr(shadowc.return_foo()) + val.this = 1 + return val + + The problem with this is that typemaps allow a user to redefine + the output behavior of a function--as a result, we can no longer + make any assumptions about the return type being a pointer or + even being a single value for that matter (it could be a list, + tuple, etc...). If SWIG detects the use of output typemaps + (either "out" or "argout") it returns the result unmodified like + this : + + def return_foo(): + val = shadowc.return_foo() + return val + + In this case, it is up to the user to figure out what to do + with the return value (including the possibility of converting it + into a Python class). + +7/26/97 : Fixed a parsing problem with types like 'unsigned long int', + 'unsigned short int', etc... + +7/24/97 : Minor bug fix to Tcl 8 module to parse enums properly. Also + fixed a memory corruption problem in the type-checker. + (patch contributed by Henry Rowley. + +7/24/97 : Added Python-tuple typemaps contributed by Robin Dunn. + +7/24/97 : Incorporated some changes to the Python module in support of + Mark Hammond's COM support. I'm not entirely sure they + work yet however. Needs documentation and testing. + +7/24/97 : Fixed code generation bugs when structures had array members + and typemaps were used. For example : + + %typemap(memberin) double [20][20] { + ... get a double [20][20] ... + } + struct Foo { + double a[20][20]; + } + + Originally, this would generate a compiler-type error when + the wrapper code was compiled. Now, a helper function like + this is generated : + + double *Foo_a_set(Foo *a, double val[20][20]) { + ... memberin typemap here ... + return (double *) val; + } + + When writing typemaps, one can assume that the source variable + is an array of the *same* type as the structure member. This + may break some codes that managed to work around the array bug. + *** POTENTIAL INCOMPATIBILITY *** + +7/13/97 : Fixed bug in Perl5 module when using C global variables that + are pointers. When used in function calls and other operations, + the value of the pointer would be invalid---causing core + dumps and other problems. SWIG implements global variables + using Perl magic variables. As it turns out, the error + was caused by the fact that the pointer-extraction code + was somehow bypassing the procedure used to resolve magical + variables (hence, leaving the value undefined). To fix + the problem, SWIG now explicitly resolves magic before + extracting pointer values. + +7/12/97 : Eliminated the last remnants of free() and malloc() from + the SWIG compiler. + +7/12/97 : Fixed parsing problems with typemaps involving arrays and + temporary variables of arrays. Also made it possible for + SWIG to handle typemaps like this : + + %typemap(in) double [ANY] (double temp[$dim0]) { + ... store data in temp[$dim0] ... + } + + Not only does this typemap match any double [] array, it + creates a local variable with precisely the right dimensions. + (ie. $dim0 gets filled in with the real number of dimensions). + Of course, off the record, this will be a way to add more + functionality to the typemaps.i libraries. + +7/9/97 : Fixed some problems with Perl5, static linking, and shadow + classes. When statically linking multiple modules together, write + a top-level interface file like this when shadow classes are not + used : + + %module swig, foo, bar, glob; + %include perlmain.i + + When shadow classes are used, the module names have an extra 'c' + appended so it should read as : + + %module swig, fooc, barc, globc; + %include perlmain.i + + When linking multiple modules, consider using the SWIG runtime + library. + +7/8/97 : Incorporated fixed versions of the Borland C++ Makefiles. + +7/8/97 : First cut at trying to eliminate excessive compiler warnings. + As it turns out, alot of warnings go away if you just make + declarations like this + + clientData = clientData; + + in the resulting wrapper code. Most compilers should just + ignore this code (at least would can hope). + +7/8/97 : Fixed bizarre code generation bug with typemaps and C++ classes. + In some cases, typemaps containing printf formatting strings such as + + %typemap(memberout) int * { + printf("%d",42); + } + + Would generate completely bogus code with garbage replacing + the '%d'. Caused by one faulty use of printf (wasn't able to find + any other occurences). + +7/7/97 : Fixed bug in Python shadow class generation with non-member + functions that are returning more than one value. + +7/7/97 : Incorporated modifications to make SWIG work with Guile 1.2. + Still need to test it out, but it is rumored to work. + +7/2/97 : Fixed some bugs related to output arguments and Python shadow + classes. If an output argument is detected, SWIG assumes + that the result is a list and handles it appropriately. + If the normal return type of an function is an object, + it will be converted into a shadow class as before, but + with the assumption that it is the first element of a + list. *** NOTE : This behavior has been subsequently changed *** + +6/29/97 : Changed EXPORT to SWIGEXPORT in all of the language modules. + Should provide better compatibility with Windows. + +6/29/97 : Modified Python shadow classes so that output arguments + work correctly (when typemaps are used). + +Version 1.1 (June 24, 1997) +=========================== + +6/24/97 : Fixed Objective-C constructor bug when working with Perl5 + shadow classes. + +6/23/97 : Fixed some parsing problems with Objective-C. Declarations + such as the following should work now : + + - foo : (int) a with: (int) b; + +6/22/97 : Added SWIG Runtime library. This library contains + the SWIG pointer type-checker and support functions + that are normally included in every module. By using + the library, it is easier to work with multiple SWIG + generated modules. + +6/22/97 : Fixed minor bug in Perl5 module related to static linking + of multiple modules. + +6/22/97 : Fixed some bugs with the %import directive. When used with + Perl5 shadow classes, this generates a 'require' statement + to load in external modules. + +6/22/97 : Added -swiglib option. This prints out the location of the + SWIG library and exits. This option is only really useful to + configuration tools that are looking for SWIG and its library + location (e.g. autoconf, configure, etc...). + +6/21/97 : Fixed export bug with Perl5.004 on Windows-NT. + +6/20/97 : Minor change to code generation of class/structure members in + order to work better with typemaps. Should have no noticable + impact on existing SWIG modules. + +6/19/97 : Added -t option. This allows SWIG to load a typemap file before + processing any declarations. For example : + + swig -t typemaps.i -python example.i + + At most, only one typemap file can be specified in this manner. + *** NEW FEATURE *** + +6/18/97 : Need a Makefile fast? Type + + swig [-tcl, -perl5, -python] -co Makefile + + and you will get a Makefile specific to that target language. + You just need to modify it for your application and you're + ready to run. + +6/18/97 : Completed the -ci option. This option checks a file into the + SWIG library. It should be used in conjunction with a + language option. For example : + + swig -tcl -ci foobar.i + + Checks the file foobar.i into the Tcl part of the library. + In order to check a file into the general library (accessible + to all languages modules), do the following + + swig -ci -o ../foobar.i foobar.i + + (Admittedly this looks a little strange but is unavoidable). + The check-in option is primarily designed for SWIG maintenance + and library development. The command will fail if the user does + not have write permission to the SWIG library. Third party library + extensions can easily install themselves by simply providing + a shell script that uses 'swig -ci' to install the appropriate + library files. It is not necessary to know where the SWIG library + is located if you use this mechanism. + *** NEW FEATURE *** + +6/16/97 : Fixed a bug in shadow class generation when %name() was applied + to a class definition. Unfortunately, fixing the bug required + a change in the Language C API by adding an extra argument to + the Language::cpp_class_decl() function. This may break + SWIG C++ extensions. + *** POTENTIAL INCOMPATIBILITY *** + +6/15/97 : Added a warning message if no module name is specified with the + %module directive or -module option. + +6/15/97 : Fixed line number bug when reporting errors for undefined + base classes. + +6/15/97 : Added new %rename directive. This allows the forward declaration + of a renaming. For example : + + %rename OldName NewName; + + .... later ... + int OldName(int); + + Unlike %name, %rename will rename any occurence of the old name. + This applies to functions, variables, class members and so forth. + There is no way to disable %rename once set, but you can change the + name by redeclaring it to something else. + *** NEW FEATURE *** + +6/15/97 : Improved the implementation of the %name directive so that it + could be used with conditional compilation : + + #ifdef SWIG + %name(NewName) + #endif + int OldName(int); + +6/15/97 : Added support for functions with no return datatype. In this case, + SWIG assumes a return type of 'int'. + +6/11/97 : Improved error reporting in the parser. It should be a little + less sensitive to errors that occur inside class definitions + now. Also reports errors for function pointers. + +6/11/97 : Made '$' a legal symbol in identifiers. This is to support + some Objective-C libraries. Some compilers (such as gcc) may also + allow identifiers to contain a $ in C/C++ code as well (this is + an obscure feature of C). When '$' appears in identifier, SWIG + remaps it to the string '_S_' when creating the scripting language + function. Thus a function 'foo$bar' would be called 'foo_S_bar'. + +6/11/97 : Fixed bug in Python shadow classes with __repr__ method. If + supplied by the user, it was ignored, but now it should work. + +6/9/97 : Fixed the Tcl 8.0 module to work with Tcl 8.0b1. SWIG is no + longer compatible with *any* alpha release of Tcl 8.0. + *** POTENTIAL INCOMPATIBILITY *** + +6/7/97 : Put a maximal error count in (currently set to 20). SWIG will bail out + if it generates more errors than this (useful for preventing SWIG + from printing 4000 syntax errors when it gets confused). + +6/7/97 : Fixed segmentation fault when parsing variable length arguments. + +6/7/97 : Minor change to Perl5 module. C++ static functions are now + put in the same package as their class when using shadow classes. + +6/7/97 : Centralized the naming of functions, members, wrappers etc... By + centralizing the naming scheme, it should be possible to make + some multi-file optimizations. Also, it should be possible to + change SWIG's naming scheme (perhaps a new feature to be added + later). + +6/2/97 : Added 'arginit' typemap. This can be used to assign initial values + to function arguments. Doing so makes it somewhat easier to detect + improper argument passing when working with other typemaps. + +6/2/97 : Fixed code generation bug when read-only variables were inherited + into other classes. Under inheritance, the variables would + become writable, but this has now been corrected. + +5/30/97 : An empty %name() directive is no longer allowed or supported. + This directive was originally used to strip the prefix + off of a class or structure. Unfortunately, this never really + seemed to work right and it complicated the C++ code generator + significantly. As far as I can tell no one uses it, so it + is now history. *** POTENTIAL INCOMPATIBILITY *** + +5/28/97 : Fixed a parsing bug with #define and C++ comments. Declarations + such as the following now work properly : + + #define CONST 4 // A Comment + +5/28/97 : Made some performance improvements to the SWIG String class. + (only affects the SWIG compiler itself). + +5/28/97 : Modified the parser to skip template definitions and issue a + warning message. + +5/28/97 : Preliminary support for parameterized types added (ie. templates). + Types such as the following should pass through the SWIG compiler + + void foo(vector *a, vector *b); + + When used, the entire name 'vector' becomes the name + of the datatype. Due to space limitations in datatype + representations, the name should not exceed 96 characters. + + Note : This is only part of what is needed for template support. + Template class definitions are not yet supported by SWIG. + + The template notation above may also be used when specifying + Objective-C protocol lists. + *** NEW FEATURE *** + +5/24/97 : First cut at Objective-C support added. As it turns out, almost + everything can be handled with only a few minor modifications to + the C++ module. + *** NEW FEATURE *** + +5/23/97 : Fixed repeated definition bug in multiple inheritance handling + when multiple base classes share a common base class (ie. + the evil diamond). + +5/21/97 : Fixed rather embarrassing typo that worked its way into the + Tests/Build directory. + +5/19/97 : Fixed code generation bug when using native methods and + shadow classes with Python and Perl5 modules. + +5/19/97 : Modified the %apply directive slightly so that it would work + with pointers a little better. For example : + + %apply unsigned long { DWORD }; + + Applies *all* typemaps associated with "unsigned long" to + "DWORD". This now includes pointers to the two datatypes. + For example, a typemap applied to "unsigned long **" would + also be applied to any occurrence of "DWORD **" as well. + +5/19/97 : Fixed an ownership assignment bug in the Perl5 module when + class members were returning new objects belonging to + different classes. + +5/17/97 : Added a few more typemap variables. + + $name - Name of function/variable/member + $basetype - Base datatype (type without pointers) + $argnum - Argument number + +5/16/97 : Fixed embarrassing underscore error in local variable + allocator. + +5/16/97 : Fixed namespace clash bug in parameterized typemaps + when creating arrays as new local variables. + +5/15/97 : Fixed some bugs with inheritance of added methods across + multiple files. SWIG now uses names of base classes + when generating such functions. + +5/14/97 : Finished support for default typemaps. Primarily used + internally, they can be used to match the basic + built-in datatypes used inside of SWIG. You can + specify them in interface files as well like this : + + %typemap(tcl,in) int SWIG_DEFAULT_TYPE { + $target = atoi($target); + } + + Unlike normal typemaps, this default map will get applied + to *all* integer datatypes encountered, including those + renamed with typedef, etc... + +5/13/97 : Fixed substring bug in type checker. + +5/12/97 : Fixed bug in parameterized typemaps when declaring local + variables of structures. + +Version 1.1 Beta6 (May 9, 1997) +=============================== + +5/9/97 : Fixed bizarre NULL pointer handling bug in Perl5 module. + +5/8/97 : Fixed mysterious segmentation fault when running SWIG on an + empty file. + +5/7/97 : The code generator will now replace the special symbol "$cleanup" + with the cleanup code specified with the "freearg" typemap. + This change needed to properly manage memory and exceptions. + +5/5/97 : Added the 'typemaps.i' library file. This contains a + variety of common typemaps for input values, pointers, + and so on. + +5/5/97 : Changed behavior of "argout" typemap in Python module. + Old versions automatically turned the result into a + Python list. The new version does nothing, leaving the + implementation up to the user. This provides more flexibility + but may break older codes that rely on typemaps. + *** POTENTIAL INCOMPATIBILITY *** + +5/5/97 : Fixed bug in Python module related to the interaction of + "argout" and "ignore" typemaps. + +5/5/97 : Fixed bug in Python module that would generate incorrect code + if all function arguments are "ignored". + +5/4/97 : Added %apply and %clear directives. These form a higher level + interface to the typemap mechanism. In a nutshell, they + can be used to change the processing of various datatypes without + ever having to write a typemap. See the SWIG documentation + for more details. ** NEW FEATURE ** + +5/4/97 : Added a local variable extension to the typemap handler. + For example : + + %typemap(tcl,in) double *(double temp) { + temp = atof($source); + $target = &temp; + } + + In this case, 'temp' is a local variable that exists + in the entire wrapper function (not just the typemap + code). This mechanism provides better support for + certain types of argument handling and also makes it + possible to write thread-safe typemaps. Any number + local variables can be declared by supplying a comma + separated list. Local variables are guaranteed to be + unique, even if the same typemap is applied many times + in a given function. + ** Not currently supported in Perl4 or Guile modules. + +5/2/97 : Fixed processing of %ifdef, %endif, %if, etc... (These are + SWIG equivalents of the C preprocessor directives that + can pass through the C preprocessor without modification). + +5/2/97 : Fixed major (but subtle) bug in the run-time type checker + related to searching and type-checking for C++ inheritance. + To make a long story short, if you had two classes named + "Foo" and "FooObject" the type checker would sometimes + get confused and be unable to locate "Foo" in an internal + table. + +5/2/97 : Fixed some bugs in the -co option. + +4/24/97 : Pointer library added to the SWIG library. + +4/19/97 : Added the %new directive. This is a "hint" that can be used + to tell SWIG that a function is returning a new object. For + example : + + %new Foo *create_foo(); + + This tells SWIG that create_foo() is creating a new object + and returning a pointer to it. Many language modules may + choose to ignore the hint, but when working with shadow classes, + the %new is used to handle proper ownership of objects. + + %new can also be used with dynamically allocated strings. + For example : + + %new char *create_string(); + + When used, all of the language modules will automatically cleanup + the returned string--eliminating memory leaks. + ** NEW FEATURE ** + +4/19/97 : Added a new typemap "newfree". This is used in conjunction with + the %new directive and can be used to change the method by which + a new object returned by a function is deleted. + +4/19/97 : The symbol "__cplusplus" is now defined in the SWIG interpreter + when running with the -c++ option. + +4/17/97 : Added support for static member functions when used inside the + %addmethods directive. + +4/15/97 : Added a special typemap symbol PREVIOUS that can be used to + restore a previous typemap. For example : + + %typemap(tcl,in) int * = PREVIOUS; + + This is primarily used in library files. + +4/13/97 : Added %pragma directive for Perl5 module. Two new pragmas are + available : + + %pragma(perl5) code = "string" + %pragma(perl5) include = "file.pl" + + Both insert code into the .pm file created by SWIG. This can + be used to automatically customize the .pm file created by SWIG. + +4/13/97 : Scanner modified to only recognize C++ keywords when the -c++ + option has been specified. This provides support for C programs + that make use of these keywords for identifiers. + SWIG may need to be explicitly run with the -c++ option when + compiling C++ code (this was allowed, but not recommended in + previous versions). **POTENTIAL INCOMPATIBILITY** + +4/11/97 : Fixed a rather nasty bug in the Perl5 module related to using + variable linking with complex datatypes and pointers. On Unix, + code would work (somehow), but would cause an access violation + under Windows-NT. The fix should correct the problem, + but there may still be a problem using global variables of + complex datatypes in conjunction with shadow classes. Fortunately, + this sort of thing seems to be relatively rare (considering + that the bug has been around for more than a year - yikes!). + +4/11/97 : Fixed bizarre constant evaluation bug in Perl5 code generation + when running under Windows-NT. + +4/8/97 : Bug when using default arguments and C++ references fixed. + +4/8/97 : Fixed code generation bugs in Python and Perl5 modules related to + using class renaming (applying the %name directive to a class + definition) and shadow classes. + +4/7/97 : Fixed minor bugs in swigptr.swg, tcl8ptr.swg, and perl5ptr.swg to + prevent infinite loops when weird datatypes are passed. + +3/29/97 : 'Makefile.win' added. This is used to build most of the examples + in the Examples directory under Windows NT/95. + +3/27/97 : Fixes to SWIG's error return codes. SWIG now returns non-zero + exit codes for certain kinds of errors (which makes it more + friendly to makefiles). An overhaul of the error handling + is on the to-do list and will probably show up in a later release. + +3/25/97 : Bug fix. "freearg" and "argout" typemaps have been fixed in + the Perl5 module. In previous versions, function input parameters + and function output parameters shared the same memory space--causing + all sorts of nasty problems when trying to pass perl values by + reference. SWIG now internally makes a "copy" (which is really + just a pointer) of affected parameters and uses that. This + is done transparently so there is no noticable impact on any + SWIG generated modules. This change is probably only noticable + to expert users. + +3/25/97 : Added type-check to verbose and stat mode. SWIG will now generate a list + of all datatypes that were used but undefined (useful for tracking + down weird bugs). This is enabled with the -v option (which + is now officially known as "overly verbose" mode) or the -stat option. + +3/25/97 : Slight change to the parser to make include guards work correctly. + For example : + + #ifndef INTERFACE_I + #define INTERFACE_I + %module foobar.i + ... declarations ... + #endif + +3/24/97 : %checkout directive added. This allows an interface file to + extract files from the SWIG library and place them in the + current directory. This can be used to extract scripts and + other helper code that might be associated with library files. + For example : + + %checkout array.tcl + + Will look for a file "array.tcl" in the library and copy it + to the current directory. If the file already exists in the + directory, this directive does nothing (it will not overwrite an + existing file). This only an experimental feature for now. + +3/24/97 : SWIG will now look in the SWIG Library for a file if it can't + find it in the current directory. As a result, it is easy to + make modules from SWIG library files. For example, if you + want to make a Python module from the SWIG timers library, just + type this in any directory : + + swig -python timers.i + + You will get the files timers_wrap.c and timers_wrap.doc in + the current directory that you can now compile. The file + remains in the SWIG library (although you can check it out + using the -co option). *** New Feature *** + +3/24/97 : -co option added to SWIG to allow easy access to the SWIG library. + When used, this instructs SWIG to check out a library file and + place it in the current directory. For example : + + unix > swig -co array.i + array.i checked out from the SWIG library + unix > + + Once in your directory you can customize the file to suit your + particular purposes. The checkout option makes it easy to + grab library files without knowing anything about the SWIG + installation, but it also makes it possible to start + including scripts, C code, and other miscellaneous files + in the library. For example, you could put a cool script + in the library and check it out whenever you wanted to use it. + *** New Feature *** + +3/24/97 : #pragma export directives added to Tcl output for compiling + shared libraries on the Mac. + +3/24/97 : Minor changes to wish.i and tclsh.i library files to provide + support for the Macintosh. + +3/19/97 : SWIG's policy towards NULL pointers has been relaxed. The + policy of requiring a special compiler directive -DALLOW_NULL + to use NULL pointers is no longer supported. While this may + seem "unsafe", it turns out that you can use a "check" + typemap to achieve some safety. For example : + + %typemap(perl5,check) Node * { + if (!$target) + croak("NULL Pointers not allowed."); + } + + This prevents any NULL value of a "Node *" pointer to be + passed to a function. (I think this is much cleaner + than the old -DALLOW_NULL hack anyways). + +3/19/97 : Fixed pointer handling errors in Perl5 module. Modules no + longer core dump when a Perl reference is inadvertently + passed in as a C pointer. + +3/18/97 : Added a "check" typemap. This can be used to check the + validity of function input values. For example : + + %typemap(perl5,check) int posint { + if ($target < 0) + croak("Argument is not a positive integer"); + } + +3/18/97 : Added an $arg variable to Tcl typemaps. This makes it easier + to return argument values by "reference". + +3/18/97 : Fixed a code generation bug when using C++ references and + the %addmethods directive. + +3/18/97 : Fixed a few glitches in the typemap module with respect to + chaining. For example : + + %typemap(tcl,in) int { + $in // Inserts prexisting typemap + printf("Received a %d\n", $target); + } + + This has been allowed for quite some time, but didn't work + if no existing typemap was defined. Now, it still doesn't + work if no existing typemap is defined, but it issues a + warning message. There is some support using default typemaps, + but none of the language modules take advantage of it. This + should be considered experimental at this time. + +Version 1.1b5 Patch 1 (March 16, 1997) +====================================== + +3/16/97 : Fixed references bug with C++ code generation. + +3/16/97 : Fixed initialization bug in the documentation system that + was causing weird problems. + +3/16/97 : Fixed fatal bug with -c option in the Python module. + +3/13/97 : Fixed bug in the documentation system involving the %text directive + and sorting. In the old system, %text entries would float to the + top of a section because they were "nameless". Now they are + attached to the previous declaration and will stay in the proper + location relative to the previous entry. + +Version 1.1b5 (March 12, 1997) +============================== + +3/11/97 : Fixed compilation problems introduced by Tcl/Tk 8.0a2. + *** INCOMPATIBILITY *** SWIG no longer works with Tcl/Tk 8.0a1. + +3/10/97 : Fixed bug with ignored arguments and C++ member functions in + the Python module. + +3/9/97 : Parsing bugs with nested class definitions and privately + declared nested class definitions fixed. + +3/9/97 : Fixed a few minor code generation bugs with C++ classes and + constructors. In some cases, the resulting wrapper code + would not compile properly. SWIG now attempts to use + the default copy constructor instead. + +3/8/97 : Added a -l option to SWIG that allows additional SWIG library files + to be grabbed without having them specified in the interface file. + This makes it easier to keep the interface file clean and move certain + options into a Makefile. For example : + + swig -tcl example.i # Build a normal Tcl extension + swig -tcl -lwish.i example.i # Build it as a wish extension + # by including the 'wish.i' file. + + swig -python example.i # Build a dynamically loaded extension + swig -python -lembed.i example.i # Build a static extension + + These kinds of options could previously be accomplished with + conditional compilation such as : + + %module example + ... + #ifdef STATIC + %include embed.i + #endif + +3/8/97 : Incorporated changes to Guile module to use the new gh interface + in FSF Guile 1.0. The older gscm interface used in Cygnus + Guile releases is no longer supported by SWIG. + +3/8/97 : Cleaned up the Tcl Netscape plugin example. It should work with + version 1.1 of the plugin now. + +3/8/97 : Added better array support to the typemap module. The keyword + ANY can now be used to match any array dimension. For example : + + %typemap(tcl,in) double [ANY] { + ... get an array ... + } + + This will match any single-dimensional double array. The array + dimension is passed in the variables $dim0, $dim1, ... $dim9. For + example : + + %typemap(tcl,in) double [ANY][ANY][ANY] { + printf("Received a double[%d][%d][%d]\n",$dim0,$dim1,$dim2); + } + + Any typemap involving a specific array dimension will override any + specified with the ANY tag. Thus, a %typemap(tcl,in) double [5][4][ANY] {} + would override a double [ANY][ANY][ANY]. However, overuse of the ANY + tag in arrays of high-dimensions may not work as you expect due to + the pattern matching rule used. For example, which of the following + typemaps has precedence? + + %typemap(in) double [ANY][5] {} // Avoid this! + %typemap(in) double [5][ANY] {} + +3/7/97 : Fixed a number of bugs related to multi-dimensional array handling. + Typedefs involving multi-dimensional arrays now works correctly. + For example : + + typedef double MATRIX[4][4]; + + ... + extern double foo(MATRIX a); + + Typecasting of pointers into multi-dimensional arrays is now + implemented properly when making C/C++ function calls. + +3/6/97 : Fixed potentially dangerous bug in the Tcl Object-oriented + interface. Well, actually, didn't fix it but issued a + Tcl error instead. The bug would manifest itself as follows: + + % set l [List] # Create an object + ... + % set m [List -this $l] # Make $m into an object assuming $l + # contains a pointer. + # Since $m == $l, $l gets destroyed + # (since its the same command name) + % $m insert Foo + Segmentation fault # Note : the list no longer exists! + + Now, an error will be generated instead of redefining the command. + As in : + + % set l [List] + ... + % set m [List -this $l] + Object name already exists! + + Use catch{} to ignore the error. + +3/3/97 : Better support for enums added. Datatypes of 'enum MyEnum' + and typedefs such as 'typedef enum MyEnum Foo;' now work. + +3/3/97 : Parser modified to ignore constructor initializers such as : + + class Foo : public Bar { + int a,b; + public: + Foo(int i) : a(0), b(i), Bar(i,0) { }; + }; + +3/3/97 : Modified parser to ignore C++ exception specifications such as : + + int foo(double) throw(X,Y); + +3/3/97 : Added %import directive. This works exactly like %extern + except it tells the language module that the declarations are + coming from a separate module. This is usually only + needed when working with shadow classes. + +3/2/97 : Changed pointer type-checker to be significantly more + efficient when working with derived datatypes. This + has been accomplished by storing type-mappings in sorted + order, using binary search schemes, and caching recently + used datatypes. For SWIG generated C++ modules that + make a large number of C function calls with derived types, + this could result in speedups of between 100 and 50000 percent. + However, due to the required sorting operation, module + loading time may increased slightly when there are lots of + datatypes. + +3/2/97 : Fixed some C++ compilation problems with Python + embed.i library files. + +2/27/97 : Slight change to C++ code generation to use copy constructors + when returning complex data type by value. + +2/26/97 : Fixed bug in Python module with -c option. + +2/26/97 : Slight tweak of parser to allow trailing comma in enumerations + such as + + enum Value (ALE, STOUT, LAGER, }; + +2/25/97 : Fixed code generation bug in Tcl module when using the + %name() directive on a classname. + +2/25/97 : Finished code-size optimization of C++ code generation with + inheritance of attributes. Inherited attributes now + only generate one set of wrapper functions that are re-used + in any derived classes. This could provide big code + size improvements in some scripting language interfaces. + +2/25/97 : Perl5 module modified to support both the Unix and Windows + versions. The windows version has been tested with the + Activeware port of Perl 5.003 running under Windows 95. + The C source generated by SWIG should compile without + modification under both versions of Perl, but is now + even more hideous than before. + +2/25/97 : Modified parser to allow scope resolution operation to + appear in expressions and default arguments as in : + + void foo(int a = Bar::defvalue); + +2/25/97 : Fixed bug when resolving symbols inside C++ classes. + For example : + + class Foo { + public: + enum Value {ALE, STOUT, LAGER}; + ... + void defarg(Value v = STOUT); + + }; + +2/24/97 : Fixed bug with member functions returning void *. + +2/23/97 : Modified Python module to be better behaved under Windows + + - Module initialization function is now properly exported. + It should not be neccessary to explicitly export this function + yourself. + + - Bizarre compilation problems when compiling the SWIG wrapper + code as ANSI C under Visual C++ 4.x fixed. + + - Tested with both the stock Python-1.4 distribution and Pythonwin + running under Win95. + +2/19/97 : Fixed typedef handling bug in Perl5 shadow classes. + +2/19/97 : Added exception support. To use it, do the following : + + %except(lang) { + ... try part of the exception ... + $function + ... catch part of exception ... + } + + $function is a SWIG variable that will be replaced by the + actual C/C++ function call in a wrapper function. Thus, + a real exception specification might look like this : + + %except(perl5) { + try { + $function + } catch (char *& sz) { + ... process an exception ... + } catch(...) { + croak("Unknown exception. Bailing out..."); + } + } + +2/19/97 : Added support for managing generic code fragments (needed + for exceptions). + +2/19/97 : Fixed some really obscure typemap scoping bugs in the C++ + handler. + +2/18/97 : Cleaned up perlmain.i file by removing some problematic, + but seemingly unnecessary declarations. + +2/18/97 : Optimized handling of member functions under inheritance. + SWIG can now use wrapper functions generated for a + base class instead of regenerating wrappers for + the same functions in a derived class. This could + make a drastic reduction in wrapper code size for C++ + applications with deep inheritance hierarchies and + lots of functions. + +2/18/97 : Additional methods specified with %addmethods can now + be inherited along with normal C++ member functions. + +2/18/97 : Minor internal fixes to make SWIG's string handling a little + safer. + +2/16/97 : Moved some code generation of Tcl shadow classes to + library files. + +2/16/97 : Fixed documentation error of '-configure' method in + Tcl modules. + +2/16/97 : Modified Perl5 module slightly to allow typemaps + to use Perl references. + +2/12/97 : Fixed argument checking bug that was introduced by + default arguments (function calls with too many + arguments would still be executed). Functions now + must have the same number of arguments as C version + (with possibility of default/optional arguments + still supported). + +2/12/97 : Fixed default argument bug in Perl5 module when + generating wrapper functions involving default + arguments of complex datatypes. + +2/12/97 : Fixed typemap scoping problems. For example : + + %typemap(tcl,in) double { + .. get a double .. + } + + class Foo { + public: + double bar(double); + } + + %typemap(tcl,in) double { + .. new get double .. + } + + Would apply the second typemap to all functions in Foo + due to delayed generation of C++ wrapper code (clearly this + is not the desired effect). Problem has been fixed by + assigning unique numerical identifiers to every datatype in + an interface file and recording the "range of effect" of each + typemap. + +2/11/97 : Added support for "ignore" and "default" typemaps. Only use + if you absolutely know what you're doing. + +2/9/97 : Added automatic creation of constructors and destructors for + C structs and C++ classes that do not specify any sort of + constructor or destructor. This feature can be enabled by + running SWIG with the '-make_default' option or by inserting + the following pragma into an interface file : + + %pragma make_default + + The following pragma disables automatic constructor generation + + %pragma no_default + +2/9/97 : Added -make_default option for producing default constructors + and destructors for classes without them. + +2/9/97 : Changed the syntax of the SWIG %pragma directive to + %pragma option=value or %pragma(lang) option=value. + This change makes the syntax a little more consistent + between general pragmas and language-specific pragmas. + The old syntax still works, but will probably be phased + out (a warning message is currently printed). + +2/9/97 : Improved Tcl support of global variables that are of + structures, classes, and unions. + +2/9/97 : Fixed C++ compilation problem in Python 'embed.i' library file. + +2/9/97 : Fixed missing return value in perlmain.i library file. + +2/9/97 : Fixed Python shadow classes to return an AttributeError when + undefined attributes are accessed (older versions returned + a NameError). + +2/9/97 : Fixed bug when %addmethods is used after a class definition whose + last section is protected or private. + +2/8/97 : Made slight changes in include file processing to support + the Macintosh. + +2/8/97 : Extended swigmain.cxx to provide a rudimentary Macintosh interface. + It's a really bad interface, but works until something better + is written. + +1/29/97 : Fixed type-casting bug introduced by 1.1b4 when setting/getting the + value of global variables involving complex data types. + +1/29/97 : Removed erroneous white space before an #endif in the code generated + by the Python module (was causing errors on DEC Alpha compilers). + +1/26/97 : Fixed errors when using default/optional arguments in Python shadow + shadow classes. + +1/23/97 : Fixed bug with nested %extern declarations. + +1/21/97 : Fixed problem with typedef involving const datatypes. + +1/21/97 : Somewhat obscure, but serious bug with having multiple levels + of typedefs fixed. For example : + + typedef char *String; + typedef String Name; + +Version 1.1 Beta4 (January 16, 1997) +==================================== + +Note : SWIG 1.1b3 crashed and burned shortly after take off due +to a few major run-time problems that surfaced after release. +This release should fix most, if not all, of those problems. + +1/16/97 : Fixed major memory management bug on Linux + +1/14/97 : Fixed bug in functions returning constant C++ references. + +1/14/97 : Modified C++ module to handle datatypes better. + +1/14/97 : Modified parser to allow a *single* scope resolution + operator in datatypes. Ie : Foo::bar. SWIG doesn't + yet handle nested classes, so this should be + sufficient for now. + +1/14/97 : Modified parser to allow typedef inside a C++ class. + +1/14/97 : Fixed some problems related to datatypes defined inside + a C++ class. SWIG was not generating correct code, + but a new scoping mechanism and method for handling + datatypes inside a C++ class have been added. + +1/14/97 : Changed enumerations to use the value name instead + of any values that might have appeared in the interface + file. This makes the code a little more friendly to + C++ compilers. + +1/14/97 : Removed typedef bug that made all enumerations + equivalent to each other in the type checker (since + it generated alot of unnecessary code). + +Version 1.1 Beta3 (January 9, 1997) +=================================== + +Note : A *huge* number of changes related to ongoing modifications. + +1. Support for C++ multiple inheritance added. + +2. Typemaps added. + +3. Some support for nested structure definitions added. + +4. Default argument handling added. + +5. -c option added for building bare wrapper code modules. + +6. Rewrote Pointer type-checking to support multiple inheritance + correctly. + +7. Tcl 8.0 module added. + +8. Perl4 and Guile modules resurrected from the dead (well, they + at least work again). + +9. New Object Oriented Tcl interface added. + +10. Bug fixes to Perl5 shadow classes. + +11. Cleaned up many of the internal modules of the parser. + +12. Tons of examples and testing modules added. + +13. Fixed bugs related to use of "const" return values. + +14. Fixed bug with C++ member functions returning void *. + +15. Changed SWIG configuration script. + +Version 1.1 Beta2 (December 3, 1996) +==================================== + +1. Completely rewrote the SWIG documentation system. The changes + involved are too numerous to mention. Basically, take everything + you knew about the old system, throw them out, and read the + file Doc/doc.ps. + +2. Limited support for #if defined() added. + +3. Type casts are now allowed in constant expressions. ie + + #define A (int) 3 + +4. Added support for typedef lists. For example : + + typedef struct { + double x,y,z; + } Vector, *VectorPtr; + +5. New SWIG directives (related to documentation system) + + %style + %localstyle + %subsection + %subsubsection + +6. Reorganized the C++ handling and made it a little easier to + work with internally. + +7. Fixed problem with inheriting data members in Python + shadow classes. + +8. Fixed symbol table problems with shadow classes in both + Python and Perl. + +9. Fixed annoying segmentation fault bug in wrapper code + generated for Perl5. + +10. Fixed bug with %addmethods directive. Now it can be placed + anywhere in a class. + +11. More test cases added to the SWIG self-test. Documentation + tests are now performed along with other things. + +12. Reorganized the SWIG library a little bit and set it up to + self-document itself using SWIG. + +13. Lots and lots of minor bug fixes (mostly obscure, but bugs + nonetheless). + + +Version 1.1 Beta1 (October 30, 1996) +==================================== + +1. Added new %extern directive for handling multiple files + +2. Perl5 shadow classes added + +3. Rewrote conditional compilation to work better + +4. Added 'bool' datatype + +5. %{,%} block is now optional. + +6. Fixed some bugs in the Python shadow class module + +7. Rewrote all of the SWIG tests to be more informative + (and less scary). + +8. Rewrote parameter list handling to be more memory + efficient and flexible. + +9. Changed parser to ignore 'static' declarations. + +10. Initializers are now ignored. For example : + + struct FooBar a = {3,4,5}; + +11. Somewhat better parsing of arrays (although it's + usually just a better error message now). + +12. Lot's of minor bug fixes. + + +Version 1.0 Final (August 31, 1996) +=================================== + +1. Fixed minor bug in C++ module + +2. Fixed minor bug in pointer type-checker when using + -DALLOW_NULL. + +3. Fixed configure script to work with Python 1.4beta3 + +4. Changed configure script to allow compilation without + yacc or bison. + +Version 1.0 Final (August 28, 1996) +=================================== + +1. Changed parser to support more C/C++ datatypes (well, + more variants). Types like "unsigned", "short int", + "long int", etc... now work. + +2. "unions" added to parser. + +3. Use of "typedef" as in : + + typedef struct { + double x,y,z; + } Vector; + + Now works correctly. The name of the typedef is used as + the structure name. + +4. Conditional compilation with #ifdef, #else, #endif, etc... + added. + +5. New %disabledoc, %enabledoc directives allow documentation + to selectively be disabled for certain parts of a wrapper + file. + +6. New Python module supports better variable linking, constants, + and shadow classes. + +7. Perl5 module improved with better compatibility with XS + and xsubpp. SWIG pointers and now created so that they + are compatible with xsubpp pointers. + +8. Support for [incr Tcl] namespaces added to Tcl module. + +9. %pragma directive added. + +10. %addmethods directive added. + +11. %native directive added to allow pre-existing wrapper functions + to be used. + +12. Wrote configure script for SWIG installation. + +13. Function pointers now allowed with typedef statements. + +14. %typedef modified to insert a corresponding C typedef into + the output file. + +15. Fixed some problems related to C++ references. + +16. New String and WrapperFunction classes add to make generating + wrapper code easier. + +17. Fixed command line option processing to eliminate core dumps + and to allow help messages. + +18. Lot's of minor bug fixes to almost all code modules + + +Version 1.0 Beta 3 (Patch 1) July 17, 1996 +========================================== + +1.0 Final is not quite ready yet, but this release fixes a +number of immediate problems : + +1. Compiler errors when using -strict 1 type checking have been fixed. + +2. Pointer type checker now recognizes pointers of the form + _0_Type correctly. + +3. A few minor fixes were made in the Makefile + +Version 1.0 Beta 3 (June 14, 1996) +================================== + + +There are lots of changes in this release : + +1. SWIG is now invoked using the "swig" command instead of "wrap". + Hey, swig sounds cooler. + +2. The SWIG_LIB environment variable can be set to change the + location where SWIG looks for library files. + +3. C++ support has been added. You should use the -c++ option + to enable it. + +4. The %init directive has been replaced by the %module directive. + %module constructs a valid name for the initialization function + for whatever target language you're using (actually this makes + SWIG files a little cleaner). The old %init directive still works. + +5. The syntax of the %name directive has been changed. Use of the + old one should generate a warning message, but may still work. + +6. To support Tcl/Tk on non-unix platforms, SWIG imports a file called + swigtcl.cfg from the $(SWIG_LIB)/tcl directory. I don't have access + to an NT machine, but this file is supposedly allows SWIG to + produce wrapper code that compiles on both UNIX and non UNIX machines. + If this doesn't work, you'll have to edit the file swigtcl.cfg. Please + let me know if this doesn't work so I can update the file as + necessary. + +7. The SWIG run-time typechecker has been improved. You can also + now redefine how it works by supplying a file called "swigptr.cfg" + in the same directory as your SWIG interface files. By default, + SWIG reads this file from $(SWIG_LIB)/config. + +8. The documentation system has been changed to support the following : + + - Documentation order is printed in interface file order by + default. This can be overridden by putting an %alpha + directive in the beginning of the interface file. + + - You can supply additional documentation text using + + %text %{ put your text here %} + + - A few minor bugs were fixed. + +9. A few improvements have been made to the handling of command line + options (but it's still not finished). + +10. Lots of minor bug fixes in most of the language modules have been + made. + +11. Filenames have been changed to 8.3 for compatibility with a SWIG + port to non-unix platforms (work in progress). + +12. C++ file suffix is now .cxx (for same reason). + +13. The documentation has been upgraded significantly and is now + around 100 pages. I added new examples and a section on + C++. The documentation now includes a Table of Contents. + +14. The SWIG Examples directory is still woefully sparse, but is + getting better. + +Special notice about C++ +------------------------ +This is the first version of SWIG to support C++ parsing. Currently +the C++ is far from complete, but seems to work for simple cases. +No work has been done to add special C++ processing to any of +the target languages. See the user manual for details about how +C++ is handled. If you find problems with the C++ implementation, +please let me know. Expect major improvements in this area. + +Note : I have only successfully used SWIG and C++ with Tcl and +Python. + +Notice about Version 1.0Final +----------------------------- + +Version 1.0B3 is the last Beta release before version 1.0 Final is +released. I have frozen the list of features supported in version 1.0 +and will only fix bugs as they show up. Work on SWIG version 2.0 is +already in progress, but is going to result in rather significant +changes to SWIG's internal structure (hopefully for the better). No +anticipated date for version 2.0 is set, but if you've got an idea, +let me know. + +Version 1.0 Beta 2 (April 26, 1996) +=================================== + +This release is identical to Beta1 except a few minor bugs are +fixed and the SWIG library has been updated to work with Tcl 7.5/Tk 4.1. +A tcl7.5 examples directory is now included. + +- Fixed a bug in the Makefile that didn't install the libraries + correctly. + +- SWIG Library files are now updated to work with Tcl 7.5 and Tk 4.1. + +- Minor bug fixes in other modules. + + +Version 1.0 Beta 1 (April 10, 1996). +===================================== + +This is the first "semi-official" release of SWIG. It has a +number of substantial improvements over the Alpha release. These +notes are in no particular order--hope I remembered everything.... + +1. Tcl/Tk + +SWIG is known to work with Tcl7.3, Tk3.6 and later versions. +I've also tested SWIG with expect-5.19. + +Normally SWIG expects to use the header files "tcl.h" and "tk.h". +Newer versions of Tcl/Tk use version numbers. You can specify these +in SWIG as follows : + + % wrap -htcl tcl7.4.h -htk tk4.0.h example.i + +Of course, I prefer to simply set up symbolic links between "tcl.h" and +the most recent stable version on the machine. + +2. Perl4 + +This implementation has been based on Perl-4.035. SWIG's interface to +Perl4 is based on the documentation provided in the "Programming Perl" +book by Larry Wall, and files located in the "usub" directory of the +Perl4 distribution. + +In order to compile with Perl4, you'll need to link with the uperl.o +file found in the Perl4 source directory. You may want to move this +file to a more convenient location. + +3. Perl5 + +This is a somewhat experimental implementation, but is alot less +buggy than the alpha release. SWIG operates independently of +the XS language and xsubpp supplied with Perl5. Currently SWIG +produces the necessary C code and .pm file needed to dynamically +load a module into Perl5. + +To support Perl5's notion of modules and packages (as with xsubpp), +you can use the following command line options : + + % wrap -perl5 -module MyModule -package MyPackage example.i + +Note : In order for dynamic loading to be effective, you need to be +careful about naming. For a module named "MyModule", you'll need to +create a shared object file called "MyModule.so" using something like + + % ld -shared my_obj.o -o MyModule.so + +The use of the %init directive must match the module name since Perl5 +calls a function "boot_ModuleName" in order to initialize things. +See the Examples directory for some examples of how to get things +to work. + +4. Python1.3 + +This is the first release supporting Python. The Python port is +experimental and may be rewritten. Variable linkage is done through +functions which is sort of a kludge. I also think it would be nice +to import SWIG pointers into Python as a new object (instead of strings). +Of course, this needs a little more work. + +5. Guile3 + +If you really want to live on the edge, pick up a copy of Guile-iii and +play around with this. This is highly experimental---especially since +I'm not sure what the official state of Guile is these days. This +implementation may change at any time should I suddenly figure out better +ways to do things. + +6. Extending SWIG + +SWIG is written in C++ although I tend to think of the code as mostly +being ANSI C with a little inheritance thrown in. Each target language +is implemented as a C++ class that can be plugged into the system. +If you want to add your own modifications, see Appendix C of the user +manual. Then take a look at the "user" directory which contains some +code for building your own extenions. + +7. The SWIG library + +The SWIG library is still incomplete. Some of the files mentioned in +the user manual are unavailable. These files will be made available +when they are ready. Subscribe to the SWIG mailing list for announcements +and updates. + +8. SWIG Documentation + +I have sometimes experienced problems viewing the SWIG documentation in +some postscript viewers. However, the documentation seems to print +normally. I'm working on making much of the documentation online, +but this takes time. + +Version 0.1 Alpha (February 9, 1996) +==================================== + +1. Run-time type-checking of SWIG pointers. Pointers are now represented + as strings with both numeric and encoded type information. This makes + it a little harder to shoot yourself in the foot (and it eliminates + some segmentation faults and other oddities). + +2. Python 1.3 now supported. + +3. #define and enum can be used to install constants. + +4. Completely rewrote the %include directive and made it alot more powerful. + +5. Restructured the SWIG library to make it work better. + +6. Various bug fixes to Tcl, Perl4, Perl5, and Guile implementations. + +7. Better implementation of %typedef directive. + +8. Made some changes to SWIG's class structure to make it easier to expand. + SWIG is now built into a library file that you can use to make your + own extenions. + +9. Made extensive changes to the documentation. + +10. Minor changes to the SWIG parser to make it use less memory. + Also took out some extraneous rules that were undocumented and + didn't work in the first place. + +11. The SWIG library files "tclsh", "wish", "expect", etc... in the first + release have been restructured and renamed to "tclsh.i", "wish.i", + and so on. diff --git a/CHANGES.current b/CHANGES.current new file mode 100644 index 0000000..e41f17d --- /dev/null +++ b/CHANGES.current @@ -0,0 +1,257 @@ +Version 1.3.40 (18 August 2009) +=============================== + +2009-08-17: olly + [Perl] Add "#undef do_exec" to our clean up of Perl global + namespace pollution. + +2009-08-17: olly + [PHP] Fix to wrap a resource returned by __get() in a PHP object (SF#2549217). + +2009-08-17: wsfulton + Fix #2797485 After doing a 'make clean', install fails if yodl2man or yodl2html + is not available. + +2009-08-16: wsfulton + [Octave] Caught exceptions display the type of the C++ exception instead of the + generic "c++-side threw an exception" message. + +2009-08-16: wsfulton + [Java] When %catches is used, fix so that any classes specified in the "throws" + attribute of the "throws" typemap are generated into the Java method's throws clause. + +2009-08-16: wsfulton + [C#] Fix exception handling when %catches is used, reported by Juan Manuel Alvarez. + +2009-08-15: wsfulton + Fix %template seg fault on some cases of overloading the templated method. + Bug reported by Jan Kupec. + +2009-08-15: wsfulton + [Ruby] Add numerous missing wrapped methods for std::vector specialization + as reported by Youssef Jones. + +2009-08-14: wsfulton + [Perl] Add SWIG_ConvertPtrAndOwn() method into the runtime for smart pointer + memory ownership control. shared_ptr support still to be added. Patch from + David Fletcher. + +2009-08-14: olly + [PHP] PHP5 now wraps static member variables as documented. + +2009-08-14: olly + [PHP] Update the PHP "class" example to work with PHP5 and use + modern wrapping features. + +2009-08-13: wsfulton + [PHP] std::vector wrappers overhaul. They no longer require the + specialize_std_vector() macro. Added wrappers for capacity() and reserve(). + +2009-08-13: wsfulton + [PHP] Add const reference typemaps. const reference primitive types are + now passed by value rather than pointer like the other target languages. + Fixes SF#2524029. + +2009-08-08: wsfulton + [Python] More user friendly AttributeError is raised when there are + no constructors generated for the proxy class in the event that the + class is abstract - the error message is now + "No constructor defined - class is abstract" whereas if there are no + public constructors for any other reason and the class is not abstract, + the message remains + "No constructor defined". + [tcl] Similarly for tcl when using -itcl. + +2009-08-04: olly + [PHP] Fix generated code to work with PHP 5.3. + +2009-08-04: vmiklos + [PHP] Various mathematical functions (which would conflict + with the built-in PHP ones) are now automatically handled by + adding a 'c_' prefix. + +2009-08-03: wsfulton + [C#] The std::vector implementation is improved and now uses $typemap such + that the proxy class for T no longer has to be specified in some macros + for correct C# compilation; the following macros are deprecated, where + CSTYPE was the C# type for the C++ class CTYPE: + + SWIG_STD_VECTOR_SPECIALIZE_MINIMUM(CSTYPE, CTYPE) + usage should be removed altogether + + SWIG_STD_VECTOR_SPECIALIZE(CSTYPE, CTYPE) + should be replaced with: + SWIG_STD_VECTOR_ENHANCED(CTYPE) + + Some more details in csharp/std_vector.i + + *** POTENTIAL INCOMPATIBILITY *** + +2009-07-31: olly + [Python] Fix indentation so that we give a useful error if the + module can't be loaded. Patch from Gaetan Lehmann in SF#2829853. + +2009-07-29: wsfulton + Add $typemap(method, typelist) special variable macro. This allows + the contents of a typemap to be inserted within another typemap. + Fully documented in Typemaps.html. + +2009-07-29: vmiklos + [PHP] Static member variables are now prefixed with the + class name. This allows static member variables with the + same name in different classes. + +2009-07-29: olly + [Python] Add missing locks to std::map wrappers. Patch from + Paul Hampson in SF#2813836. + +2009-07-29: olly + [PHP] Fix memory leak in PHP OUTPUT typemaps. Reported by Hitoshi + Amano in SF#2826322. + +2009-07-29: olly + [PHP] Fix memory leak in PHP resource destructor for classes + without a destructor and non-class types. Patch from Hitoshi Amano + in SF#2825303. + +2009-07-28: olly + [PHP] Update warnings about clashes between identifiers and PHP + keywords and automatic renaming to work with the PHP5 class + wrappers. Fixes SF#1613679. + +2009-07-28: vmiklos + [PHP] If a member function is not public but it has a base + which is public, then now a warning is issued and the member + function will be public, as PHP requires this. + +2009-07-21: vmiklos + [PHP] Director support added. + +2009-07-15: olly + [Perl] Don't specify Perl prototype "()" for a constructor with a + different name to the class, as such constructors can still take + parameters. + +2009-07-12: xavier98 + [Octave] Add support for Octave 3.2 API + +2009-07-05: olly + [PHP] Update the list of PHP keywords - "cfunction" is no longer a + keyword in PHP5 and PHP 5.3 added "goto", "namespace", "__DIR__", + and "__NAMESPACE__". + +2009-07-03: olly + [Tcl] To complement USE_TCL_STUBS, add support for USE_TK_STUBS + and SWIG_TCL_STUBS_VERSION. Document all three in the Tcl chapter + of the manual. Based on patch from SF#2810380 by Christian + Gollwitzer. + +2009-07-02: vmiklos + [PHP] Added factory.i for PHP, see the li_factory testcase + for more info on how to use it. + +2009-07-02: wsfulton + Fix -Wallkw option as reported by Solomon Gibbs. + +2009-07-02: wsfulton + Fix syntax error when a nested struct contains a comment containing a * followed + eventually by a /. Regression from 1.3.37, reported by Solomon Gibbs. + +2009-07-01: vmiklos + [PHP] Unknown properties are no longer ignored in proxy + classes. + +2009-07-01: vmiklos + [PHP] Fixed %newobject behaviour, previously any method + marked with %newobject was handled as a constructor. + +2009-06-30: olly + [Ruby] Undefine close and connect macros defined by Ruby API + headers as we don't need them and they can clash with C++ methods + being wrapped. Patch from Vit Ondruch in SF#2814430. + +2009-06-26: olly + [Ruby] Fix to handle FIXNUM values greater than MAXINT passed for a + double parameter. + +2009-06-24: wsfulton + Fix wrapping methods with default arguments and the compactdefaultargs feature + where a class is passed by value and is assigned a default value. The SwigValueWrapper + template workaround for a missing default constructor is no longer used as the code + generated does not call the default constructor. + +2009-06-16: wsfulton + [Java,C#] Fix enum marshalling when %ignore is used on one of the enum items. + Incorrect enum values were being passed to the C++ layer or compilation errors resulted. + +2009-06-02: talby + [Perl] Resolved reference.i overload support problem + identified by John Potowsky. + +2009-05-26: wsfulton + [C#] Improved std::map wrappers based on patch from Yuval Baror. The C# proxy + now implements System.Collections.Generic.IDictionary<>. + + These std:map wrappers have a non-backwards compatible overhaul to make them + like a .NET IDictionary. Some method names have changed as following: + set -> setitem (use this[] property now) + get -> getitem (use this[] property now) + has_key -> ContainsKey + del -> Remove + clear -> Clear + + The following macros used for std::map wrappers are deprecated and will no longer work: + specialize_std_map_on_key + specialize_std_map_on_value + specialize_std_map_on_both + + *** POTENTIAL INCOMPATIBILITY *** + +2009-05-20: vmiklos + [PHP] Add the 'thisown' member to classes. The usage of it + is the same as the Python thisown one: it's 1 by default and + you can set it to 0 if you want to prevent freeing it. (For + example to prevent a double free.) + +2009-05-14: bhy + [Python] Fix the wrong pointer value returned by SwigPyObject_repr(). + +2009-05-13: mutandiz (Mikel Bancroft) + [allegrocl] Minor tweak when wrapping in -nocwrap mode. + +2009-05-11: wsfulton + [C#] Improved std::vector wrappers on the C# proxy side from Yuval Baror. These + implement IList<> instead of IEnumerable<> where possible. + +2009-04-29: wsfulton + [Java, C#] Add the 'notderived' attribute to the javabase and csbase typemaps. + When this attribute is set, the typemap will not apply to classes that are derived + from a C++ base class, eg + %typemap(csbase, notderived="1") SWIGTYPE "CommonBase" + +2009-04-29: olly + [Python] Don't attempt to acquire the GIL in situations where we + know that it will already be locked. This avoids some dead-locks + with mod_python (due to mod_python bugs which are apparently + unlikely to ever be fixed), and results in smaller wrappers which + run a little faster (in tests with Xapian on x86-64 Ubuntu 9.04, + the stripped wrapper library was 11% smaller and ran 2.7% faster). + +2009-04-21: wsfulton + [C#] Fix #2753469 - bool &OUTPUT and bool *OUTPUT typemaps initialisation. + +2009-04-09: wsfulton + Fix #2746858 - C macro expression using floating point numbers + +2009-03-30: olly + [PHP] The default out typemap for char[ANY] now returns the string up to a + zero byte, or the end of the array if there is no zero byte. This + is the same as Python does, and seems more generally useful than + the previous behaviour of returning the whole contents of the array + including any zero bytes. If you want the old behaviour, you can provide + your own typemap to do this: + + %typemap(out) char [ANY] + %{ + RETVAL_STRINGL($1, $1_dim0, 1); + %} diff --git a/Doc/Devel/cmdopt.html b/Doc/Devel/cmdopt.html new file mode 100644 index 0000000..c5f207c --- /dev/null +++ b/Doc/Devel/cmdopt.html @@ -0,0 +1,79 @@ + + +SWIG Command Line Handling + + + +
      +

      SWIG Command Line Handling

      + +

      +David M. Beazley
      +dave-swig@dabeaz.com
      +December, 2006
      + + +

      + +

      Introduction

      + +This document describes the functions related to the handling of +command line options passed to SWIG. These functions are defined in +the header file Source/Swig/swigopt.h. This API is +considered to be stable. + +

      Initialization

      + +Upon SWIG startup, the following function is called: + +

      +void Swig_init_args(int argc, char **argv_) + +

      +Registers command line options with the SWIG core. This creates an internal array that is used by other +functions to mark whether or not a particular command line option was used. This is ultimately used to issue error messages about unused or unknown command line options. This function is currently invoked in the SWIG main() function that is found in Source/Modules/swigmain.cxx. +
      + +

      Argument Marking

      + +As command line options are are processed by language modules, the following functions are used +to mark the arguments as used: + +

      +void Swig_mark_arg(int n) +

      +Mark argument number n as used. +
      + +

      +int Swig_check_marked(int n) +

      +Check to see if argument n has been marked. Returns 0 or 1. +
      + +

      Argument Checking

      + +The following function is used to check all of the command line options after parsing. It looks at the marked list +and issues an error message if any unconsumed arguments are found. + +

      +void Swig_check_options() +

      +Checks all command line options to see if they have all been processed. If not, an error message is generated and +execution terminates with a call to exit(). This function is currently invoked in Source/Modules/main.cxx just before SWIG starts any processing of input files. +
      + +

      Utility Function

      +

      +void Swig_arg_error()) + +

      +A generic function that issues an error message about being unable to parse command line options. SWIG is terminated by a call to exit(). + + + + + + + + diff --git a/Doc/Devel/engineering.html b/Doc/Devel/engineering.html new file mode 100644 index 0000000..b485b2d --- /dev/null +++ b/Doc/Devel/engineering.html @@ -0,0 +1,411 @@ + + +SWIG Engineering Manual + + +
      +

      SWIG Engineering Manual

      + +David Beazley
      +       +
      + +

      +(Note : This is a work in progress.) + +

      Table of Contents

      +       + + +

      1. Introduction

      +       + +The purpose of this document is to describe various coding conventions +and organizational aspects for SWIG developers. The idea for this +document is largely borrowed from John Ousterhout's Tcl/Tk Engineering +Manual. It is not my intent to overly managerial about matters--rather I'm +hoping to make life a little less chaotic for everyone. + +

      +First a little background: SWIG was started in 1995 as a one-person +project and continued in this mode of operation until about 1998. +Most of this development was driven by ideas submitted by early SWIG +users as opposed to being motivated by a grand design. As a result, +the code ended up being a pretty horrible C++ coding disaster. A +mostly working disaster perhaps, but a disaster nonetheless. + +

      +With that said, the primary goal of future SWIG development is to +reengineer the original system, fix most of its inherent design flaws, +and to produce what I hope will become a highly extensible and modular +interface compiler framework. To this do this, there are a few +critical areas of work. First, I want to restructure SWIG as a +collection of loosely coupled modules written in either ANSI C or an +scripting language. Second, I want the system to be minimalistic in +its use of data structures and interconnections. The primary reason +for this is that the fewer data structures there are, the less users +will have to remember. This will also make the system more accessible +to non-experts. Finally, I want to reevaluate the whole idea of a +SWIG module is and expand the definition to include just about +anything from parsers, preprocessors, optimizers, interface editors, +and code generators. + +

      +The rest of this document outlines a few general rules of how code +should be developed within the SWIG project. These rules are +primarily drawn from my own experience developing software and +observing the practices of other successful projects. + + +

      2. Programming Languages and Libraries

      + + +All SWIG modules must be written in either ANSI C or one of the +scripting languages for which SWIG can generate an interface (e.g., +Perl, Python, or Tcl). C++ is currently being used to write +SWIG modules, but it is only being utilized to avoid working with +a lot of pointers to functions. Advanced C++ features like namespaces, templates, +and overloading should not be used.. + +

      +Module writers should make every attempt to use only those functions +described in the POSIX.1 standard. This includes most of the +functions contained the Kernighan and Ritchie C programming book. Use +of operating system dependent functionality such as socket libraries +should always be included inside a conditional compilation block so +that it can be omitted on problematic platforms. If you are unsure +about a library call, check the man page or contact Dave. + + +

      3. The Source Directory and Module Names

      + + +All SWIG modules are contained within the "Source" directory. Within +this directory, each module is placed into its own subdirectory. The +name of this subdirectory should exactly match the name of the module. +For example, if you are creating a module called "Tcl", all of your +files should be placed in a directory "Tcl". + +

      +When choosing a module name, please pick a name that is not +currently in use. As a general convention, the first letter of a +module name is capitalized such as "Perl". Alternatives such as +"perl" or "PERL" should be avoided. In certain instances, the first +two letters may be capitalized as in "CParse." The exact usage of +this is somewhat inconsistent and isn't terribly important--just make +sure the first letter is capitalized. Also, module names should not +start with numbers, include underscores or any other special +non-alphanumeric characters. + + +

      5. File Structure

      + + +Each file in a module should be given a filename that is all lowercase letters +such as "parser.c", not "Parser.c" or "PARSER.c". Please note that filenames +are case-insensitive on Windows so this convention will prevent you from inadvertently +creating two files that differ in case-only. + +

      +Each file should include a short abstract, author information, copyright information, and +a SVN revision tag like this: + +

      +
      +/* -----------------------------------------------------------------------------
+ * See the LICENSE file for information on copyright, usage and redistribution
+ * of SWIG, and the README file for authors - http://www.swig.org/release.html.
+ *
+ * cwrap.c
+ *
+ * This file defines a variety of wrapping rules for C/C++ handling including
+ * the naming of local variables, calling conventions, and so forth.
+ * ----------------------------------------------------------------------------- */
+
+char cvsroot_cwrap_c[] = "$Id: engineering.html 10008 2007-10-17 22:10:32Z wsfulton $";
+
+#include "swig.h"
+
+/* Declarations */
+typedef struct {
+   int x, y;
+} Foo;
+
+...
+
+/* Private Declarations (used only in this file) */
+static int  avariable;
+
+...
+
+/* Functions */
+... 
+
+
      +
      + +The SVN revision tag should be placed into a static string as shown +above mangled with the name of the file. +This adds the revision information to the SWIG executable and +makes it possible to extract version information from a raw binary +(sometimes useful in debugging). + +

      +As a general rule, files start to get unmanageable once they exceed +about 2000 lines. Files larger than this should be broken up into +multiple files. Similarly, you should avoid the temptation to create +many small files as this increases compilation time and makes the +directory structure too complicated. + + +

      6. Bottom-Up Design

      + + +Within each source file, the preferred organization is to use what is +known as "bottom-up" design. Under this scheme, lower-level functions +appear first and the highest level function appears last. The easy +way to remember is that the "main" function of your module should +always appear last in the source file. For example: + +
      +
      +/* Simple bottom-up program */
+#include <stdio.h>
+
+int foo(int x, int y) {
+    /* Implement foo */
+    ...
+}
+
+int bar() {
+    ...
+    foo(i,j);
+    ...
+}
+
+...
+int main(int argc, char **argv) {
+    ...
+    bar();   
+    ...
+}
+
      +
      + +This choice of design is somewhat arbitrary however it has a number of +benefits particular to C. In particular, a bottom-up design generally +eliminates the need to include forward references--resulting in +cleaner code and fewer compilation errors. + + +

      7. Functions

      +       + +All functions should have a function header that gives the function name +and a short description like this: + +
      +
      +/* -------------------------------------------------------------------------
+ * Swig_add_directory()
+ *
+ * Adds a directory to the SWIG search path.
+ * ------------------------------------------------------------------------- */
+
+void 
+Swig_add_directory(DOH *dirname) {
+...
+
+}
+
      +
      + +In the function declaration, the return type and any specifiers +(extern or static) should appear on a separate line followed by the +function name and arguments as shown above. The left curly brace +should appear on the same line as the function name. + +

      +Function declarations should NOT use the pre-ANSI function +declaration syntax. The ANSI standard has been around long enough for +this to be a non-issue. + + +

      8. Naming Conventions

      + + +The following conventions are used to name various objects throughout SWIG. + +

      Functions

      + +Functions should consist of the module name and the function name separated by an underscore like this: + +
      +
      +Preprocessor_define()
+Swig_add_directory()
+
      +
      + +In general, the module name should match the name of the module +subdirectory and the function name should be in all lowercase with +words separated by underscores. + +

      Structures and Types

      + +If your module defines new structures, the structure name should include the name of the +module and the name of the structure appended together like this: + +
      +
      +typedef struct SwigScanner {
+   ...
+} SwigScanner;
+
+typedef struct LParseType {
+   ...
+} LParseType;
+
      +
      + +In this case, both the name of the module and the type should be capitalized. Also, whenever +possible, you should use the "typedef struct Name { ... } Name" form when defining new +data structures. + +

      Global Variables

      + +Global variables should be avoided if at all possible. However, if you must use a global +variable, please prepend the module name and use the same naming scheme as for functions. + +

      Constants

      + +Constants should be created using #define and should be in all caps like this: + +
      +
      +#define   SWIG_TOKEN_LPAREN  1
+
      +
      + +Separate words in a constant should be separated by underscores as with functions. + +

      Structure members

      + +Structure members should be in all lower-case and follow the same word-separation convention +as for function names. However, the module name does not have to be included. +For example: + +
      +
      +typedef struct SwigScanner {
+  DOH           *text;           /* Current token value */
+  DOH           *scanobjs;       /* Objects being scanned */
+  DOH           *str;            /* Current object being scanned */
+  char          *idstart;        /* Optional identifier start characters */
+  int            next_token;     /* Next token to be returned */
+  int            start_line;     /* Starting line of certain declarations */
+  int            yylen;          /* Length of text pushed into text */
+  DOH           *file;           /* Current file name */
+} SwigScanner;
+
      +
      + +

      Static Functions and Variables

      + +Static declarations are free to use any naming convention that is appropriate. However, most +existing parts of SWIG use lower-case names and follow the same convention as described for functions. + + +

      9. Visibility

      +       + +Modules should keep the following rules in mind when exposing their internals: + +
        +
      • Only publicly accessible functions should be included in the module header file. +
      • All non-static declarations must be prepended with some form of the module name +to avoid potential linker namespace conflicts with other modules. +
      • Modules should not expose global variables or use global variables in their +public interface. +
      • Similarly, modules should discourage the direct manipulation of data contained +within data structures in favor of using function calls instead. For example, +instead of providing a user with a structure like this: + +
        +
        +typedef struct Foo {
+   int line;
+} Foo;
+
        +
        + +It is better to hide the implementation of Foo and provide an +function-call interface like this: + +
        +
        +typedef struct Foo Foo;
+extern int  Foo_getline(Foo *f);
+extern void Foo_setline(Foo *f, int line);
+
        +
        + +Although this results in worse performance, there are many practical +reasons for doing this. The most important reason is that it allows +you to change the internal representation of Foo without breaking all +of the other modules or having to recompile the entire universe after +making your changes. + +
      + + +

      10. Miscellaneous Coding Guidelines

      +       +These are largely covered in the main documentation in the Extending.html file. + + +

      11. SVN Tagging Conventions

      +       + +Use svn tag to declare some set of file revisions as related in some +symbolic way. This eases reference, retrieval and manipulation of these files +later. At the moment (2001/01/16 14:02:53), the conventions are very simple; +let's hope they stay that way! + +

      +There are two types of tags, internal (aka personal) and external. +Internal tags are used by SWIG developers primarily, whereas external +tags are used when communicating with people w/ anonymous svn access. +

        +
      • Internal tags should start with the developer name and a hyphen. +
      • External tags should start with "v-". +
      + +That's all there is to it. Some example tags: + +
        +
      • ttn-pre-xml-patch +
      • ttn-post-xml-patch +
      • ttn-going-on-vacation-so-dutifully-tagging-now +
      • v-1-3-a37-fixes-bug-2432 +
      • v-1-3-a37-fixes-bug-2433 +
      • v-1-3-a37-fixes-bug-2432-again +
      • v-1-3-a37-release +
      + +
      +Copyright (C) 1999-2004 SWIG Development Team. + + diff --git a/Doc/Devel/file.html b/Doc/Devel/file.html new file mode 100644 index 0000000..77ad7ed --- /dev/null +++ b/Doc/Devel/file.html @@ -0,0 +1,181 @@ + + +SWIG File Handling + + + +
      +

      SWIG File Handling

      + +

      +David M. Beazley
      +dave-swig@dabeaz.com
      +December, 2006
      + + +

      + +

      Introduction

      + +This document describes the functions related to file and filename handling in the SWIG core. These functions are +defined in the header file Source/Swig/swigfile.h. This API is considered to be stable. + +

      File Search Path

      + +These functions manipulate the search path for locating files. + +

      +List *Swig_add_directory(const String_or_char *dirname) + +

      +Adds a new directory to the system search path. The directory is appended to +the end of the search path. Returns a list containing the current +system search path. +
      + +

      +void Swig_push_directory(const String_or_char *dirname) +

      +Pushes a temporary directory onto the search path. This directory is searched before +directories added with Swig_add_directory() except when including a system +file explicitly (either using #include <file> or calling Swig_include_sys()). +This function is normally used by the preprocessor to add temporary directories when +processing #include statements. +
      + +

      +void Swig_pop_directory() +

      +Pops off the last pushed directory with Swig_push_directory() +
      + +

      +int Swig_get_push_dir() + +

      +Returns a flag that indicates whether directory pushing is enabled or not. +
      + +

      +void Swig_set_push_dir(int dopush) +

      +Enables or disables directory pushing. By default, it is turned on. However, the -I- command line +option to SWIG disables it. +
      + +

      +List *Swig_search_path() +

      +Returns the current search path. +
      + + +

      File access functions

      + +

      +FILE *Swig_open(const String_or_char *name) + +

      +Opens a file, using the applicable search paths, and returns an open FILE * object if found. Returns NULL if the file is not found. +
      + +

      +String *Swig_read_file(FILE *f) + +

      +Reads all of the data from an open file into a string which is returned. +
      + +

      +String *Swig_include(const String_or_char *name) + +

      +Searches for an include file name and returns its contents as +a string if found. Returns NULL if not found. All of the applicable +search paths are searched when trying to locate the file. +
      + +

      +String *Swig_include_sys(const String_or_char *name) + +

      +Searches for an include file name and returns its contents as +a string if found. Returns NULL if not found. All of the applicable +search paths are searched when trying to locate the file, but +preference is given to system paths first. This mimics the behavior +of #include <file> in the preprocessor. +
      + +

      +int Swig_insert_file(const String_or_char *name, File *outfile) + +

      +Searches for a file name and dumps its contents to outfile if found. +Returns 0 on success, -1 if the file couldn't be found. +
      + +

      Query functions

      + +

      +String *Swig_last_file() + +

      +Returns the full pathname of the file last opened or included. +
      + +

      Named files

      + +

      +void *Swig_register_filebyname(const String_or_char *filename, File *outfile) + +

      +Registers a file object outfile with a specific name filename. This function is +used to implement the SWIG %insert directive and to manage different sections of the output +file such as "runtime","header","wrapper","init", etc. Different language modules may add their own +sections for generating Python code, Perl code, etc. +
      + +

      +File *Swig_filebyname(const String_or_char *filename) +

      +This looks up a file object previously registered using Swig_register_filebyname(). This +is used to implement the %insert directive. +
      + +

      Filename utilities

      + +

      +char *Swig_file_suffix(const String_or_char *filename) +

      +Returns the suffix of a filename. For instance, if the filename is "foo.txt", it returns ".txt". +
      + +

      +char *Swig_file_basename(const String_or_char *filename) +

      +Returns the filename without the suffix attached to it. For instance, if the filename is "foo.txt", it returns +"foo". The result is stored in a static variable. If you need to save it, make your own copy. +
      + +

      +char *Swig_file_filename(const String_or_char *filename) +

      +Returns the filename without any leading directories. For instance, if the filename is "/bar/spam/foo.txt", it +returns "foo.txt". This function is aware of local naming conventions on the machine (e.g., forward versus back slashes on Unix and Windows). The result is stored in a static variable. If you need to save the value, make a copy. +
      + +

      +char *Swig_file_dirname(const String_or_char *filename) +

      +Returns the directory name (if any). For instance, if the filename is "/bar/spam/foo.txt", it +returns "/bar/spam/". This function is aware of local naming conventions on the machine (e.g., forward versus back slashes on Unix and Windows). The result is stored in a static variable. If you need to save the value, make a copy. +
      + +

      +SWIG_FILE_DELIMITER +

      +This macro contains the file delimiter string for the local machine. On Unix it is "/", on Windows it is "\\". +
      + + + diff --git a/Doc/Devel/index.html b/Doc/Devel/index.html new file mode 100644 index 0000000..55c612e --- /dev/null +++ b/Doc/Devel/index.html @@ -0,0 +1,30 @@ + + +SWIG Documentation + + + +This directory contains SWIG documentation: + + + +The following documentation describe the internal APIs used by SWIG. These may be useful to module developers. + + + +
      +Copyright (C) 1999-2007 SWIG Development Team. + + + diff --git a/Doc/Devel/internals.html b/Doc/Devel/internals.html new file mode 100644 index 0000000..ea36f84 --- /dev/null +++ b/Doc/Devel/internals.html @@ -0,0 +1,1102 @@ + + +SWIG Internals + + + +
      +

      SWIG Internals Manual

      + +Thien-Thi Nguyen
      + +

      +David M. Beazley
      + +       +

      + +

      + +

      +(Note : This is a work in progress.) + +

      Table of Contents

      + + + +

      1. Introduction

      +       + +This document details SWIG internals: architecture and sometimes +implementation. The first few sections concentrate on data structures, +interfaces, conventions and code shared by all language targets. +Subsequent sections focus on a particular language. + +

      +The audience is assumed to be SWIG developers (who should also read the +SWIG Engineering Manual before starting +to code). + + +

      1.1 Directory Guide

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      DocHTML documentation. If you find a documentation bug, please +let us know.
      ExamplesThis subdir tree contains examples of using SWIG w/ different +scripting languages, including makefiles. Typically, there are the +"simple" and "matrix" examples, w/ some languages offering additional +examples. The GIFPlot example has its own set of per-language +subdirectories. See the README more index.html file in each directory +for more info. [FIXME: Ref SWIG user manual.]
      LibThese are the .i (interface) files that form the SWIG +installed library. Language-specific files are in subdirectories (for +example, guile/typemaps.i). Each language also has a .swg file +implementing runtime type support for that language. The SWIG library +is not versioned.
      MiscCurrently this subdir only contains file fileheader. See +the Engineering Manual for more +info.
      SourceSWIG source code is in this subdir tree. Directories marked w/ "(*)" +are used in building the swig executable. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      DOH (*)C library providing memory allocation, file access and generic + containers. Result: libdoh.a
      Experiment[TODO]
      Include (*)Configuration .h files
      LParseParser (lex / yacc) files and support [why not (*)?!]
      Modules[TODO]
      Modules1.1 (*)Language-specific callbacks that does actual code generation (each + language has a .cxx and a .h file). Result: libmodules11.a
      Preprocessor (*)SWIG-specialized C/C++ preprocessor. Result: libcpp.a
      SWIG1.1 (*)Parts of SWIG that are not language-specific, including option + processing and the type-mapping system. Result: libswig11.a. + Note: This directory is currently being phased out.
      SWIG1.3[TODO] [funny, nothing here is presently used for swig-1.3]. + This directory might turn into a compatibility interface between + SWIG1.3 and the SWIG1.1 modules.
      Swig (*)This directory contains the new ANSI C core of the system + and contains generic functions related to types, file handling, + scanning, and so forth.
      ToolsLibtool support and the mkdist.py script.
      WinThis improperly-named (spit spit) subdir only has README.txt.
      + + + +

      1.2 Overall Program Flow

      +       + +Here is the general control flow and where under subdir Source +to look for code: + +
        + +
      • Modules1.1/swigmain.cxx:main() is the program entry +point. It parses the language-specifying command-line option (for +example, -java), creating a new language-specific wrapping +object (each language is a C++ class derived from base class +Language). This object and the command-line is passed to +SWIG_main(), whose return value is the program exit value. + +
      • SWIG1.1/main.cxx:SWIG_main() is the "real" main. It +initializes the preprocessor and typemap machinery, defines some +preprocessor symbols, locates the SWIG library, processes common +command-line options, and then calls the language-specific command-line +parser. From here there are three paths: "help", "checkout" and +everything else. +
          +
        • In "help" mode, clean up open files and exit. +
        • In "checkout" mode, copy specified files from the SWIG library + to the current directory. Errors cause error messages but no + non-local exits. +
        • Otherwise, do wrapping: determine output file name(s), define + some preprocessor symbols and run the preprocessor, initialize + the interface-definition parser, set up the typemap for handling + new return strings, and finally do the language-specific parse + (by calling the language object's parse() method), which + creates output files by side-effect. +
        +Afterwards, remove temporary files, and clean up. If the command-line +included -freeze, go into an infinite loop; otherwise return the +error count. + +
      • The language-specific parse() (and all other +language-specific code) lives in Modules1.1/foo.{h,cxx} for +language Foo. Typically, FOO::parse() calls +FOO::headers() and then the global function yyparse(), +which uses the callbacks registered by SWIG_main() above. + +
      + + +

      2. DOH

      +       + +DOH is a collection of low-level objects such as strings, lists, and +hash tables upon which the rest of SWIG is built. The name 'DOH' +unofficially stands for "Dave's Object Hack", but it's also a good +expletive to use when things don't work (as in "SWIG core +dumped---DOH!"). + + +

      2.1 Motivation and Background

      +       + +The development of DOH is influenced heavily by the problems +encountered during earlier attempts to create a C++ based version of +SWIG2.0. In each of these attempts (over a 3 year period), the +resulting system always ended up growing into a colossal nightmare of +large inheritance hierarchies and dozens of specialized classes for +different types of objects (functions, variables, constants, etc.). +The end result was that the system was tremendously complicated, +difficult to understand, difficult to maintain, and fairly inflexible +in the grand scheme of things. + +

      +DOH takes a different approach to tackling the complexity problem. +First, rather than going overboard with dozens of types and class +definitions, DOH only defines a handful of simple yet very useful +objects that are easy to remember. Second, DOH uses dynamic +typing---one of the features that make scripting languages so useful +and which make it possible to accomplish things with much less code. +Finally, DOH utilizes a few coding tricks that allow it to perform +a limited form of function overloading for certain C datatypes (more +on that a little later). + +

      +The key point to using DOH is that instead of thinking about code in +terms of highly specialized C data structures, just about everything +ends up being represented in terms of a just a few datatypes. For +example, structures are replaced by DOH hash tables whereas arrays are +replaced by DOH lists. At first, this is probably a little strange to +most C/C++ programmers, but in the long run in makes the system +extremely flexible and highly extensible. Also, in terms of coding, +many of the newly DOH-based subsystems are less than half the size (in +lines of code) of the earlier C++ implementation. + + +

      2.2 Basic Types

      + + +The following built-in types are currently provided by DOH: + +
        +
      • String. A string of characters with automatic memory +management and high-level operations such as string replacement. In addition, +strings support file I/O operations that make it possible to use them just +about anyplace a file can be used. + +

        +

      • List. A list of arbitrary DOH objects (of possibly mixed types). + +

        +

      • Hash. A hash table that maps a set of string keys to a set of arbitrary +DOH objects. The DOH version of an associative array for all of you Perl fans. + +

        +

      • File. A DOH wrapper around the C FILE * structure. This is provided +since other objects sometimes want to behave like files (strings for instance). + +

        +

      • Void. A DOH wrapper around an arbitrary C pointer. This can be used +if you want to place arbitrary C data structures in DOH lists and hash tables. +
      + +Due to dynamic typing, all of the objects in DOH are represented by pointers +of type DOH *. Furthermore, all objects are completely +opaque--that means that the only way to access the internals of an +object is through a well-defined public API. For convenience, the following +symbolic names are sometimes used to improve readability: + +
        +
      • DOHString *. A String object. +
      • DOHList *. A list object. +
      • DOHHash *. A hash object. +
      • DOHFile *. A file object. +
      • DOHVoid *. A void object. +
      • DOHString_or_char *. A DOH String object or a raw C "char *". +
      + +It should be stressed that all of these names are merely symbolic aliases to the +type DOH * and that no compile-time type checking is performed (of course, +a runtime error may occur if you screw up). + + +

      2.3 Creating, Copying, and Destroying Objects

      +       + +The following functions can be used to create new DOH objects + +
        +
      • NewString(DOHString_or_char *value)
        +Create a new string object with contents initially +set to value. value can be either a C string or a DOH string object. + +

        +

      • NewStringf(char *fmt, ...)
        +Create a new string object with contents initially set to +a formatted string. Think of this as being sprintf() combined with an object constructor. + +

        +

      • NewList()
        +Create a new list object that is initially empty. + +

        +

      • NewHash()
        +Create a new hash object that is initially empty. + +

        +

      • NewFile(DOHString_or_char *filename, char *mode)
        +Open a file and return a file object. This is a +wrapper around the C fopen() library call. + +

        +

      • NewFileFromFile(FILE *f)
        +Create a new file object given an already opened FILE * object. + +

        +

      • NewVoid(void *obj, void (*del)(void *))
        +Create a new DOH object that is a wrapper around an +arbitrary C pointer. del is an optional destructor function that will be called when the object +is destroyed. + +
      + +Any object can be copied using the Copy() function. For example: + +
      +
      +DOH *a, *b, *c, *d;
+a = NewString("Hello World");
+b = NewList();
+c = Copy(a);         /* Copy the string a */
+d = Copy(b);         /* Copy the list b */
+
      +
      + +Copies of lists and hash tables are shallow. That is, their contents are only copied by reference. + +

      +Objects can be deleted using the Delete() function. For example: + +

      +
      +DOH *a = NewString("Hello World");
+...
+Delete(a);              /* Destroy a */
+
      +
      + +All objects are referenced counted and given a reference count of 1 when initially created. The +Delete() function only destroys an object when the reference count reaches zero. When +an object is placed in a list or hash table, it's reference count is automatically increased. For example: + +
      +
      +DOH *a, *b;
+a = NewString("Hello World");
+b = NewList();
+Append(b,a);         /* Increases refcnt of a to 2 */
+Delete(a);           /* Decreases refcnt of a to 1 */
+Delete(b);           /* Destroys b, and destroys a */
+
      +
      + +Should it ever be necessary to manually increase the reference count of an object, the DohIncref() function +can be used: + +
      +
      +DOH *a = NewString("Hello");
+DohIncref(a);
+
      +
      + + +

      2.4 A Word About Mutability and Copying

      +       + +All DOH objects are mutable regardless of their current reference +count. For example, if you create a string and then create a 1000 +references to it (in lists and hash tables), changes to the string +will be reflected in all of the references. Therefore, if you need to +make any kind of local change, you should first make a copy using the +Copy() function. Caveat: when copying lists and hash tables, elements +are copied by reference. + + +

      2.5 Strings

      +       + +The DOH String type is perhaps the most flexible object. First, it supports a variety of string-oriented +operations. Second, it supports many of the same operations as lists. Finally, strings provide file I/O +operations that allow them to be used interchangeably with DOH file objects. + +[ TODO ] + + +

      2.6 Lists

      +       + +

      +Example usage of lists: +

      + +
      +
      +/* Create and populate */
+List *list = NewList();
+Append(list, NewString("listval1"));
+Append(list, NewString("listval2"));
+Append(list, NewString("listval3"));
+Append(list, NewString("listval4"));
+Append(list, NewString("listval5"));
+
+/* Size */
+Printf(stdout, "list len: %d\n", Len(list));
+
+/* Delete */
+Delitem(list, 3);
+
+/* Replace */
+Setitem(list, 0, NewString("newlistval1"));
+
+/* Get */
+String *item = Getitem(list,1);
+if (item)
+  Printf(stdout, "get: %s\n", item);
+else
+  Printf(stdout, "get: [non-existent]\n");
+
+/* Iterate through the container */
+int len = Len(list);
+for (int i=0; i<len; i++) {
+  String *item = Getitem(list,i);
+  Printf(stdout, "list item: %s\n", item);
+}
+
      + + +

      +Resulting output: +

      + +
      +
      +hash len: 5
+get: hashval2
+hash item: hashval5 [h5]
+hash item: hashval1 [h1]
+hash item: hashval2 [h2]
+hash item: hashval3 [h3]
+
      +
      + + +

      2.7 Hash tables

      +       + +

      +Example usage of hash tables: +

      + +
      +
      +/* Create and populate */
+Hash *hash = NewHash();
+Setattr(hash, "h1", NewString("hashval1"));
+Setattr(hash, "h2", NewString("hashval2"));
+Setattr(hash, "h3", NewString("hashval3"));
+Setattr(hash, "h4", NewString("hashval4"));
+Setattr(hash, "h5", NewString("hashval5"));
+
+/* Size */
+Printf(stdout, "hash len: %d\n", Len(hash));
+
+/* Delete */
+Delattr(hash, "h4");
+
+/* Get */
+String *item = Getattr(hash, "h2");
+if (item)
+  Printf(stdout, "get: %s\n", item);
+else
+  Printf(stdout, "get: [non-existent]\n");
+
+/* Iterate through the container */
+Iterator it;
+for (it = First(hash); it.key; it= Next(it))
+  Printf(stdout, "hash item: %s [%s]\n", (it.item), (it.key));
+
      +
      + +

      +Resulting output: +

      + +
      +
      +list len: 5
+get: listval2
+list item: newlistval1
+list item: listval2
+list item: listval3
+list item: listval5
+
      +
      + + +

      2.8 Files

      +       + +[ TODO ] + + +

      2.9 Void objects

      +       + +[ TODO ] + + +

      2.10 Utility functions

      +       + +[ TODO ] + + +

      3. Types and Typemaps

      +       + +

      +The representation and manipulation of types is currently in the +process of being reorganized and (hopefully) simplified. The +following list describes the current set of functions that are used to +manipulate datatypes. These functions are different than in +SWIG1.1 and may change names in the final SWIG1.3 release. + +

        +
      • SwigType_str(SwigType *t, char *name).
        + This function produces the exact string +representation of the datatype t. name is an optional parameter that +specifies a declaration name. This is used when dealing with more complicated datatypes +such as arrays and pointers to functions where the output might look something like +"int (*name)(int, double)". + +

        +

      • SwigType_lstr(SwigType *t, char *name).
        +This function produces a string +representation of a datatype that can be safely be assigned a value (i.e., can be used as the +"lvalue" of an expression). To do this, qualifiers such as "const", arrays, and references +are stripped away or converted into pointers. For example: + +
        +
        +Original Datatype              lstr()
+------------------             --------
+const char *a                  char *a
+double a[20]                   double *a
+double a[20][30]               double *a
+double &a                      double *a
+
        +
        + +The intent of the lstr() function is to produce local variables inside wrapper functions--all +of which must be reassignable types since they are the targets of conversions from a scripting +representation. + +

        +

      • SwigType_rcaststr(SwigType *t, char *name). +
        This function produces a string +that casts a type produced by the lstr() function to the type produced by the +str() function. You might view it as the inverse of lstr(). This function only produces +output when it needs to (when str() and lstr() produce different results). Furthermore, an optional +name can be supplied when the cast is to be applied to a specific name. Examples: + +
        +
        +Original Datatype             rcaststr()
+------------------            ---------
+char *a                       
+const char *a                 (const char *) name
+double a[20]                  (double *) name
+double a[20][30]              (double (*)[30]) name
+double &a                     (double &) *name
+
        +
        + + +

        +

      • SwigType_lcaststr(SwigType *t, char *name). +
        This function produces a string +that casts a type produced by the str() function to the type produced by the +lstr() function. This function only produces +output when it needs to (when str() and lstr() produce different results). Furthermore, an optional +name can be supplied when the cast is to be applied to a specific name. + +
        +
        +Original Datatype             lcaststr()
+------------------            ---------
+char *a                       
+const char *a                 (char *) name
+double a[20]                  (double *) name
+double a[20][30]              (double *) name
+double &a                     (double *) &name
+
        +
        + +

        +

      • SwigType_manglestr(SwigType *t).
        +Produces a type-string that is used to identify this datatype in the target scripting language. +Usually this string looks something like "_p_p_double" although the target language +may redefine the output for its own purposes. Normally this function strips all qualifiers, +references, and arrays---producing a mangled version of the type produced by the lstr() function. +
      + +The following example illustrates the intended use of the above functions when creating wrapper +functions using shorthand pseudocode. Suppose you had a function like this: + +
      +
      +int foo(int a, double b[20][30], const char *c, double &d);
+
      +
      + +Here's how a wrapper function would be generated using the type generation functions above: + +
      +
      +wrapper_foo() {
+   lstr("int","result")
+   lstr("int","arg0")
+   lstr("double [20][30]", "arg1")
+   lstr("const char *", "arg2")
+   lstr("double &", "arg3")
+   ...
+   get arguments
+   ...
+   result = (lcaststr("int"))  foo(rcaststr("int","arg0"),
+                               rcaststr("double [20][30]","arg1"),
+                               rcaststr("const char *", "arg2"),
+                               rcaststr("double &", "arg3"))
+   ...
+}
+
      +
      + +Here's how it would look with the corresponding output filled in: +
      +
      +wrapper_foo() {
+   int      result;
+   int      arg0;
+   double  *arg1;
+   char    *arg2;
+   double  *arg3;
+   ...
+   get arguments
+   ...
+   result = (int) foo(arg0,
+                      (double (*)[30]) arg1,
+                      (const char *) arg2,
+                      (double &) *arg3);
+   ...
+}
+
      +
      + + +Notes: + +
        +
      • For convenience, the string generation functions return a +"char *" that points to statically allocated memory living +inside the type library. Therefore, it is never necessary (and it's +an error) to free the pointer returned by the functions. Also, if you +need to save the result, you should make a copy of it. However, with +that said, it is probably worth nothing that these functions do cache +the last 8 results. Therefore, it's fairly safe to make a handful of +repeated calls without making any copies. +
      + +[TODO] + + +

      4. Parsing

      +       + +[TODO] + + +

      5. Difference Between SWIG 1.1 and SWIG 1.3

      +       + +[TODO] + + +

      6. Plans for SWIG 2.0

      +       + +[TODO] + + +

      7. The C/C++ Wrapping Layer

      +       + +Added: Dave Beazley (July 22, 2000) + +

      +When SWIG generates wrappers, it tries to provide a mostly seamless integration +with the original code. However, there are a number of problematic features +of C/C++ programs that complicate this interface. + +

        +
      • Passing and returning structures by value. When used, SWIG converts +all pass-by-value functions into wrappers that pass by reference. For example: + +
        +
        +double dot_product(Vector a, Vector b);
+
        +
        + +gets turned into a wrapper like this: + +
        +
        +double wrap_dot_product(Vector *a, Vector *b) {
+     return dot_product(*a,*b);
+}
+
        +
        + +Functions that return by value require a memory allocation to store the result. For example: + +
        +
        +Vector cross_product(Vector *a, Vector *b);
+
        +
        + +become + +
        +
        +Vector *wrap_cross_product(Vector *a, Vector *b) {
+   Vector *result = (Vector *) malloc(sizeof(Vector));
+   *result = cross_product(a,b);
+   return result;
+}
+
        +
        + +Note: If C++ is being wrapped, the default copy constructor is used +instead of malloc() to create a copy of the return result. + +

        +

      • C++ references. C++ references are handled exactly the same as +pass/return by value except that a memory allocation is not made for functions +that return a reference. + +

        +

      • Qualifiers such as "const" and "volatile". SWIG strips all +qualifiers from the interface presented to the target language. +Besides, what in the heck is "const" in Perl anyways? + +

        +

      • Instance Methods. Method invocations are handled as a function call in which +a pointer to the object (the "this" pointer) appears as the first argument. For example, in +the following class: + +
        +
        +class Foo {
+public:
+    double bar(double);
+};
+
        +
        + +The "bar" method is wrapped by a function like this: + +
        +
        +double Foo_bar(Foo *self, double arg0) {
+   return self->bar(arg0);
+}
+
        +
        + +

        +

      • Structure/class data members. Data members are handled by creating a pair +of wrapper functions that set and get the value respectively. For example: + +
        +
        +struct Foo {
+    int x;
+};
+
        +
        + +gets wrapped as follows: + +
        +
        +int Foo_x_get(Foo *self) {
+    return self->x;
+}
+int Foo_x_set(Foo *self, int value) {
+    return (self->x = value);
+}
+
        +
        + +

        +

      • Constructors. Constructors for C/C++ data structures are wrapped by +a function like this: + +
        +
        +Foo *new_Foo() {
+    return new Foo;
+}
+
        +
        +Note: For C, new objects are created using the calloc() function. + +

        +

      • Destructors. Destructors for C/C++ data structures are wrapper like this: + +
        +
        +void delete_Foo(Foo *self) {
+    delete self;
+}
+
        +
        +Note: For C, objects are destroyed using free(). + +
      + +The creation of wrappers and various type transformations are handled by a collection of functions +found in the file Source/Swig/cwrap.c. + +
        +
      • +char *Swig_clocal(DataType *t, char *name, char *value)
        +This function creates a string containing the declaration of a local variable with +type t, name name, and default value value. This local +variable is stripped of all qualifiers and will be a pointer if the type is a reference +or user defined type. + +

        +

      • +DataType *Swig_clocal_type(DataType *t)
        +Returns a type object corresponding to the type string produced by the Swig_clocal() function. + +

        +

      • char *Swig_clocal_deref(DataType *t, char *name)
        +This function is the inverse of the clocal() function. Given a type and a name, +it produces a string containing the code needed to cast/convert the type produced by +Swig_clocal() back into it's original type. + +

        +

      • char *Swig_clocal_assign(DataType *t, char *name)
        +Given a type and name, this produces a string containing the code (and an optional cast) +needed to make an assignment from the real datatype to the local datatype produced +by Swig_clocal(). Kind of the opposite of deref(). + +

        +

      • int Swig_cargs(Wrapper *w, ParmList *l)
        +Given a wrapper function object and a list of parameters, this function declares a set +of local variables for holding all of the parameter values (using Swig_clocal()). Returns +the number of parameters. In addition, this function sets the local name of each parameter +which can be retrieved using the Parm_Getlname() function. + +

        +

      • void Swig_cresult(Wrapper *w, DataType *t, char *resultname, char *decl)
        +Generates the code needed to set the result of a wrapper function and performs all of +the needed memory allocations for ANSI C (if necessary). t is the type of the +result, resultname is the name of the result variable, and decl is +a string that contains the C code which produces the result. + +

        +

      • void Swig_cppresult(Wrapper *w, DataType *t, char *resultname, char *decl)
        +Generates the code needed to set the result of a wrapper function and performs all of +the needed memory allocations for C++ (if necessary). t is the type of the +result, resultname is the name of the result variable, and decl is +a string that contains the C code which produces the result. + +

        +

      • Wrapper *Swig_cfunction_wrapper(char *fname, DataType *rtype, ParmList *parms, char *code)
        +Create a wrapper around a normal function declaration. fname is the name of the wrapper, +rtype is the return type, parms are the function parameters, and code is a +string containing the code in the function body. + +

        +

      • Wrapper *Swig_cmethod_wrapper(char *classname, char *methodname, DataType *rtype, DataType *parms, char *code)
        + +

        +

      • char *Swig_cfunction_call(char *name, ParmList *parms) +This function produces a string containing the code needed to call a C function. +The string that is produced contains all of the transformations needed to convert +pass-by-value into pass-by-reference as well as handle C++ references. Produces +a string like "name(arg0, arg1, ..., argn)". + +
      + +Here is a short example showing how these functions could be used. Suppose you had a +C function like this: + +
      +
      +double dot_product(Vector a, Vector b);
+
      +
      + +Here's how you might write a really simple wrapper function + +
      +
      +ParmList *l = ... parameter list of the function ...
+DataType *t = ... return type of the function ...
+char     *name = ... name of the function ...
+Wrapper *w = NewWrapper();
+Printf(w->def,"void wrap_%s() {\n", name);
+
+/* Declare all of the local variables */
+Swig_cargs(w, l);
+
+/* Convert all of the arguments */
+...
+
+/* Make the function call and declare the result variable */
+Swig_cresult(w,t,"result",Swig_cfunction(name,l));
+
+/* Convert the result into whatever */
+...
+
+Printf(w->code,"}\n");
+Wrapper_print(w,out);
+
      +
      + +The output of this would appear as follows: + +
      +
      +void wrap_dot_product() {
+    Vector *arg0;
+    Vector *arg1;
+    double  result;
+
+    ...
+    result = dot_product(*arg0, *arg1);
+    ...
+}
+
      +
      + +Notice that the Swig_cargs(), Swig_cresult(), and Swig_cfunction() functions +have taken care of the type conversions for the Vector type automatically. + +

      +Notes: +

        +
      • The intent of these functions is to provide consistent handling of function parameters +and return values so that language module writers don't have to worry about it too much. + +

        +

      • These functions may be superseded by features in the new typemap system which provide hooks +for specifying local variable declarations and argument conversions. + +
      + + + + + + + + +

      8. Symbol Naming Guidelines for Generated C/C++ Code

      +       +The C++ standard (ISO/IEC 14882:1998(E)) states: +
      +
      +
+17.4.3.1.2 Global names [lib.global.names]
+
+1 Certain sets of names and function signatures are always reserved to the implementation:
+
+    * Each name that contains a double underscore (__) or begins with an underscore followed 
+      by an upper case letter (2.11) is reserved to the implementation for any use.
+    * Each name that begins with an underscore is reserved to the implementation for use as 
+      a name in the global namespace.165)
+
+    165) Such names are also reserved in namespace ::std (17.4.3.1). [back to text] 
+
+
      +
      + +When generating code it is important not to generate symbols that might clash with the code being wrapped. It is tempting to flout the standard or just use a symbol which starts with a single underscore followed by a lowercase letter in order to avoid name clashes. However even these legal symbols can also clash with symbols being wrapped. The following guidelines should be used when generating code in order to meet the standard and make it highly unlikely that symbol clashes will occur: +

      + +For C++ code that doesn't attempt to mangle a symbol being wrapped (for example SWIG convenience functions): +

        +
      • Put symbols in the Swig namespace, for example class Swig::Director. Qualify using the Swig namespace whenever the symbol is referenced, even within the Swig namespace, for example new Swig::Director() not new Director().
        • +
      • Use swig_ as a prefix for all member variables and member functions that are involved in an inheritance chain with wrapped classes, for example Swig::Director::swig_get_up() and bool Swig::Director::swig_up.
        • +
      • Alternatively class names can be prefixed with Swig in the global namespace for example template<class T> class SwigValueWrapper.
        • +
      +

      + +For code compiled as C or C++ that doesn't attempt to mangle a symbol being wrapped (for example SWIG convenience functions): +

        +
      • Use SWIG_ as a prefix for structures for example SWIG_JavaExceptions_t.
        • +
      • Use SWIG_ as a prefix for global functions for example SWIG_TypeRegister.
        • +
      • Use SWIG_ as a prefix for macros for example #define SWIG_PY_INT 1
        • +
      + +For code compiled as C or C++ that attempts to mangle a wrapped symbol: +
        +
      • Use SWIGxxx or Swigxxx as a prefix where xxx is chosen which would make SWIGxxx/Swigxxx a unique symbol in the global namespace, for example class SwigDirectorFoo when wrapping class Foo. Don't use a trailing underscore for the prefix as this may generate a double underscore when wrapping a symbol which starts with a single underscore.
        • +
      + +In the past SWIG has generated many symbols which flout the standard especially double underscores. In fact they may not all be rooted out yet, so please fix them when you see them. + + + +

      9. Debugging SWIG

      +       +Warning. Debugging SWIG is for the very patient. +

      + +The DOH types are all typedefined to void. +Consequently, it is impossible for debuggers to extract any information about DOH objects. +Most debuggers will be able to display useful variable information when an object is cast to the appropriate type. +Below are some tips for displaying some of the DOH objects. +Be sure to compile with compiler optimisations turned off before attempting the casts shown in a debugger window else they are unlikely to work. +Even displaying the underlying string in a String* doesn't work straight off in all debuggers due to the multiple definition of String as a struct and a void. +

      + +Below are a list of common SWIG types. +With each is the cast that can be used in the debugger to extract the underlying type information and the underlying char * string. + +

        + +

        +

      • String *s;
        • +
        +(String *)((DohBase *)s)->data +
        +The underlying char * string can be displayed with +
        +((String *)((DohBase *)s)->data)->str + +

        +

      • SwigType *t;
        • +
        +(String *)((DohBase *)t)->data +
        +The underlying char * string can be displayed with +
        +((String *)((DohBase *)t)->data)->str + +

        +

      • String_or_char *sc;
        • +Either
        +((String *)((DohBase *)sc)->data)->str +
        or
        +(char *)sc +
        will work depending on whether the underlying type is really a String * or char *. + +
      + +
      +Copyright (C) 1999-2004 SWIG Development Team. + + + diff --git a/Doc/Devel/migrate.txt b/Doc/Devel/migrate.txt new file mode 100644 index 0000000..b40fa36 --- /dev/null +++ b/Doc/Devel/migrate.txt @@ -0,0 +1,140 @@ +SWIG1.3 Migration Guide +(The not entirely complete guide to updating language modules to work with SWIG1.3). + +Dave Beazley +August 15, 2000 + +1. Introduction +--------------- + +Virtually all of SWIG's internal data structures have now been +rewritten. Take everything you thought you knew about SWIG1.1 and +throw it out. + +2. DataTypes +------------ +The old 'DataType' data structure is gone. Therefore, direct +manipulation of 'is_pointer', 'implicit_ptr', and 'arraystr' +attributes no longer applies. Sorry. + +Datatypes are now represented by the type 'SwigType' which has no +public attributes. Actually, if you look at it closely, 'SwigType' is +really just an alias for 'void' and if you look at it even closer than +that you will realize that it's nothing more than a string! + +The string encoding of types is described in more detail in the file +Source/Swig/stype.c and is not so important here. What is important is +the functions used to produce various types of output: + +SwigType_str(type,name = 0); + This produces an exact C representation of the datatype with all + qualifiers, arrays, references, and so forth. name is an optional + name that is given if you wanted to associate the type with a + parameter name or something. + +SwigType_lstr(type,name = 0); + This function takes a type and produces a C string containing + a type suitable for assignment (appearing as an lvalue in an + expression). To do this, certain things such as 'const', + arrays, and references are stripped away or converted into + pointers. + +SwigType_ltype(type); + Returns a SwigType object corresponding to the type created + by SwigType_lstr(). + +SwigType_lcaststr(type,name); + Produces a string casting a value 'name' from the real datatype + to the assignable type created by SwigType_lstr(). + +SwigType_rcaststr(type,name) + Produces a string that casts a value 'name' from the type + created by SwigType_lstr() to the real datatype. + +SwigType_manglestr(type) + Produces the 'mangled' version of a datatype. + + +Getting the 'type' code. Most language modules still operate by +looking at special integer type codes. This interface is a little +ragged and will probably go away at some point. However, for now the +following function can be used to get the type code: + + int SwigType_type(type) + +The codes are the same as the before, except that there are a few +special codes: + + T_STRING - The 'char *' type and variations. + T_POINTER - Any pointer type (not char * though) + T_REFERENCE - Any C++ reference + T_ARRAY - Any array + T_FUNCTION - A function (this is usually an error). + +Because of the special codes, it is no longer necessary to have code like this: + + if ((t->is_pointer == 1) and (t->type == T_CHAR)) { + ... get a string ... + } + +Instead, just use the type code above like this: + + switch(SwigType_type(type)) { + case T_STRING: + ... get a string ... + break; + case T_POINTER: + ... get a pointer ... + break; + } + +There are about 2-dozen type manipulation functions that could also be useful. +See Source/Swig/swig.h and Source/Swig/stype.c. + +3. Parameter Lists +------------------ + +The ParmList data structure is gone. In reality, parameter lists are nothing more than +a linked list of parameters. The proper way to iterate over this list and get +parameter values is as follows: + + ParmList *l; + Parm *p; + + for (p = l; p; p = Getnext(p)) { + SwigType *pt = Gettype(p); /* Get parameter type */ + String *pn = Getname(p); /* Get parameter name */ + String *value = Getvalue(p); /* Get parameter value */ + ... + do whatever + ... + } + +4. Typemaps +----------- + +Typemaps more or less work. However, the interface has changed slightly. Instead of + + typemap_lookup("in","python",type,pname,"$source","$target",wrapper); + +the function is + + Swig_typemap_lookup("in",type,pname,"$source","$target",wrapper); + +There are a variety of other changes to typemaps (see CHANGES). + +5. Use of new types +------------------- +When possible, language modules should try to use the built in String, +List, and Hash objects instead of C arrays or 'char *'. This will probably require a +detailed pass through the code with an eye towards cleanup. + +6. Miscellaneous +---------------- +Language modules no longer need to concern themselves with formatting the +wrapper code they produce (provided you are using the special Wrapper object). +The function Wrapper_print() passes everything through a pretty-printer that +automatically performs indentation and tries to clean things up. This especially +works well when there are lots of typemaps. + + diff --git a/Doc/Devel/parm.html b/Doc/Devel/parm.html new file mode 100644 index 0000000..1cab070 --- /dev/null +++ b/Doc/Devel/parm.html @@ -0,0 +1,102 @@ + + +SWIG Parameter Handling + + + +
      +

      SWIG Parameter Handling

      + +

      +David M. Beazley
      +dave-swig@dabeaz.com
      +January 9, 2007
      + + +

      + +

      Introduction

      + +This document describes the functions related to management of function parameters and parameter lists in the SWIG core. These functions are declared in Source/Swig/swigparm.h. This API is considered to be stable. + +

      Parameters

      + +The following utility functions are used to create and copy individual parameters. In their most basic form, a parameter merely contains a type, a name, and an optional default value. + +

      +Parm *NewParm(SwigType *type, const String_or_char *name) + +

      +Creates a new parameter object with type type and name name. The type is stored in the attribute "type" and the name is stored in the attribute "name". +
      + +

      +Parm *CopyParm(Parm *p) +

      +Copies a parameter object. All string attributes are copied in the +process of making the copy. However, no complex attributes (lists, +hashes, etc.) are copied. +
      + +

      Parameter Lists

      + +

      +ParmList *CopyParmList(ParmList *p) +

      +Creates a copy of a parameter list. A parameter list is merely a linked list of parameters created by NewParm(). +
      + +

      +ParmList *CopyParmListMax(ParmList *p, int count) +

      +Copies at most count parameters from the parameter list p. +
      + +

      +int ParmList_len(ParmList *p) + +

      +Returns the total number of parameters in a parameter list. +
      + +

      +int ParmList_numrequired(ParmList *p) +

      +Returns the number of required parameters in a parameter list. This pertains to invoking a function/method in C/C++. +
      + +

      +int ParmList_has_defaultargs(ParmList *p) +

      +Returns 1 if the parameter list has any default arguments. Otherwise returns 0. +
      + + +

      Code Generation Functions

      + +

      +String *ParmList_str(ParmList *p) +

      +Creates a C prototype string of the parameters, but without any default values. +
      + +

      +String *ParmList_str_defaultargs(ParmList *p) +

      +Creates a C prototype string of the parameters and includes the default values (if any). +
      + +

      +String *ParmList_protostr(ParmList *p) +

      +Creates a C prototype string of the parameters. +
      + + + + + + + + + diff --git a/Doc/Devel/runtime.txt b/Doc/Devel/runtime.txt new file mode 100644 index 0000000..f88edf7 --- /dev/null +++ b/Doc/Devel/runtime.txt @@ -0,0 +1,169 @@ +This file describes the necessary functions and interfaces a language module +needs to implement to take advantage of the run time type system. I assume you +have read the run-time section of the Typemaps chapter in the SWIG +documentation. + +Last updated: February 23, 2005 + +The file we are concerned with here should be named langrun.swg. A good example +of a simple file is the Lib/mzscheme/mzrun.swg file. First, a few requirements +and notes: + +1) Every function in this file should be declared static. + +2) It should be inserted into the runtime section of the _wrap file from your +config file. The Lib/swigrun.swg file should be included before this file. +That is, you need to have +%runtime "swigrun.swg" +%runtime "langrun.swg" + +3) You must also include the swiginit.swg file in the init section of the +wrapper. That is, you should have +%insert(init) "swiginit.swg" + +4) From module.cxx, you need to call the SwigType_emit_type_table function, as +well as register types with SwigType_remember or SwigType_remember_clientdata + +5) By convention, all functions in this file are of the form +SWIG_Language_Whatever, and #defines are used to rename SWIG API functions to +these function names + +6) You need to call void SWIG_InitializeModule(void *clientdata) from your init +function. + +7) You need to implement the runtimeCode() and defaultExternalRuntimeFilename() +functions inside module.cxx. runtimeCode should return all the language +specific runtime code as a string, and defaultExternalRuntimeFilename should +return a string for the default name of the external runtime header. This is +usually "swigpyrun.h", where "py" is replaced by the language name. These +two functions are used by the -external-runtime argument. + +------------------------------------------------------------------------------- +Required Functions +------------------------------------------------------------------------------- +swig_module_info *SWIG_GetModule(void *clientdata); +void SWIG_SetModule(void *clientdata, swig_module_info *mod); + +The SetModule function should store the mod argument into some globally +accessible variable in the target language. The action of these two functions +is to provide a way for multiple modules to share information. The SetModule +function should create a new global var named something like +"swig_runtime_data_type_pointer" SWIG_RUNTIME_VERSION SWIG_TYPE_TABLE_NAME +SWIG_RUNTIME_VERSION is currently defined as "2", and SWIG_TYPE_TABLE_NAME is +defined by the -DSWIG_TYPE_TABLE=mytable option when compiling the wrapper. + +Alternatively, if the language supports modules, a module named +"swig_runtime_data" SWIG_RUNTIME_VERSION can be created, and a global variable +named "type_table" SWIG_TYPE_TABLE_NAME can be created inside it. The most +common approach is to store the mod pointer in some global variable in the +target language, but if the language provides an alternative place to store data +(like the chicken module), then that is good too. + +The way the code is set up, SetModule should only be called when GetModule +returns NULL, and if SetModule is called a second time, the behavior is +undefined. Just make sure it doesn't crash in the random chance occurrence that +SetModule is called twice. + +There are two options here. + +1) The preferred approach is for GetModule and SetModule to not require a +clientdata pointer. If you can at all avoid it, please do so. Here, you would +write swig_module_info *SWIG_Language_GetModule(); +void SWIG_Language_SetModule(swig_module_info *mod); +and then add +#define SWIG_GetModule(clientdata) SWIG_Language_GetModule() +#define SWIG_SetModule(cd, ptr) SWIG_Language_SetModule(ptr) +You would then call +SWIG_InitializeModule(0) + +2) If GetModule and SetModule need to take a custom pointer (most notably an +environment pointer, see tcl or mzscheme), then you should write +swig_module_info *SWIG_Language_GetModule(void *clientdata) +void SWIG_Language_SetModule(void *clientdata, swig_module_info *mod); +and also define +#define SWIG_GetModule(cd) SWIG_Language_GetModule(cd) +#define SWIG_SetModule(cd, ptr) SWIG_Language_SetModule(cd, ptr) +#define SWIG_MODULE_CLIENTDATA_TYPE Whatever +SWIG_MODULE_CLIENTDATA_TYPE should be defined to whatever the type of +clientdata is. + +You would then call SWIG_InitializeModule(clientdata), and clientdata would get +passed to GetModule and SetModule. clientdata will not be stored and will only +be referenced during the InitializeModule call. After InitializeModule returns, +clientdata does not need to be valid any more. + +This method is not preferred, because it makes external access to the type +system more complicated. See the Modules chapter of the documentation, and read +the "External access to the run-time" section. Then take a look at +Lib/runtime.swg. Anybody that calls SWIG_TypeQuery needs to pass along the +clientdata pointer, and that is the reason for defining +SWIG_MODULE_CLIENTDATA_TYPE. + +------------------------------------------------------------------------------- +Standard Functions +------------------------------------------------------------------------------- +These functions are not required and their API is not formalized, but almost all +language modules implement them for consistency across languages. Throughout +this discussion, I will use LangType to represent the underlying language type +(C_word in chicken, Scheme_Object * in mzscheme, PyObject * in python, etc) + + + +LangObj SWIG_NewPointerObj(void *ptr, swig_type_info *type, int flags); +Create and return a new pointer object that has both ptr and type. For almost +all language modules, flags is used for ownership. If flags==1, then the +created pointer should be registered to be garbage collected. + + + +int SWIG_ConvertPtr(LangType obj, void **result, swig_type_info *type, int flags); +Convert a language wrapped pointer into a void *. The pointer is returned in +result, and the function should return 0 on success, non-zero on error. +A sample ConvertPtr is given here: + + swig_cast_info *cast; + + if () { + cast = SWIG_TypeCheck(, type); + cast = SWIG_TypeCheckStruct(, type); + if (cast) { + *result = SWIG_TypeCast(cast, ); + return 0; + } + } + return 1; + +Either TypeCheck or TypeCheckStruct can be called, depending on how the pointer +is wrapped in langtype. If obj stores the void pointer and the type name, then +the TypeCheck function should be used, while if obj stores the void pointer and +a pointer to the swig_type_info structure, then the TypeCheckStruct function +should be called. The TypeCheckStruct is slightly faster, since it does a +pointer comparison instead of a strcmp. + +The flag argument to ConvertPtr is used in some languages for disowning a +pointer. If the wrapped C function is taking ownership of the pointer (that +means, the wrapped C function is responsible for deleting the object), then that +pointer should be removed from the garbage collector. We do that in the +ConvertPtr function. The pointer is still valid in the target language, but +when the target language type is garbage collected, it will not call the +associated destructor. Languages have a special typemap called DISOWN that can be +applied which passes this argument. All the languages have the flags argument +for consistency, and the flags argument can be ignored or used for some other +purpose. + + +void *SWIG_MustGetPtr(LangType obj, swig_type_info *type, int flags, + int argnum, const char *func_name) { + void *result; + if (SWIG_ConvertPtr(s, &result, type, flags)) { + generate runtime type error ("Error in func_name, expected a" + + type->str ? type->str : "void *" + + "at argument number" + argnum); + } + return result; +} +This function is optional, and the number and type of parameters can be +different, but is useful for typemap purposes: +%typemap(in) SWIGTYPE *, SWIGTYPE &, SWIGTYPE [] { + $1 = ($1_ltype)SWIG_MustGetPtr($input, $descriptor, 0, $argnum, FUNC_NAME); +} diff --git a/Doc/Devel/scanner.html b/Doc/Devel/scanner.html new file mode 100644 index 0000000..2722164 --- /dev/null +++ b/Doc/Devel/scanner.html @@ -0,0 +1,288 @@ + + +SWIG C Scanner + + + +
      +

      SWIG C/C++ Scanning

      + +

      +David M. Beazley
      +dave-swig@dabeaz.com
      +January 11, 2007
      + + +

      + +

      Introduction

      + +This document describes functions that can be used to tokenize C/C++ +input text. These functions are relatively low-level and are meant to +be used in the implementation of scanners that can be plugged into yacc or used for +other purposes. For instance, the preprocessor uses these functions to evaluate and test +constant expressions. + +

      +All of these functions are declared in Source/Swig/swigscan.h. This API is considered to be stable. + +

      Creation and Deletion of Scanners

      + +The following functions are used to create and destroy a scanner object. More than one scanner object can be created and used +as necessary. + +

      +Scanner *NewScanner() + +

      +Creates a new scanner object. The scanner contains initially contains no text. To feed text to the scanner use Scanner_push(). +
      + +

      +Scanner *DelScanner() + +

      +Deletes a scanner object. +
      + +

      Scanner Functions

      + +

      +void Scanner_clear(Scanner *s) +

      +Clears all text from the scanner. This can be used to reset a scanner to its initial state, ready to receive new input text. +
      + +

      +void Scanner_push(Scanner *s, String *text) +

      +Pushes an input string into the scanner. Subsequent tokens will be +returned from the new string. If the scanner is already processing a +string, the pushed string takes precedence--in effect, interrupting +the scanning of the previous string. This behavior is used to +implement certain SWIG features such as the %inline +directive. Once the pushed string has been completely scanned, the +scanner will return to scanning the previous string (if any). The +scanning of text relies upon the DOH file interface to strings +(Getc(), Ungetc(), etc.). Prior to calling this +function, the input string should be set so that its file pointer is +in the location where you want scanning to begin. You may have to +use Seek() to set the file pointer back to the beginning of a +string prior to using this function. +
      + +

      +void Scanner_pushtoken(Scanner *s, int tokvalue, String_or_char *val) +

      +Pushes a token into the scanner. This exact token will be returned by the next call to Scanner_token(). +tokvalue is the integer token value to return and val is the token text to return. This +function is only used to handle very special parsing cases. For instance, if you need the scanner to +return a ficticious token into order to enter a special parsing case. +
      + +

      +int Scanner_token(Scanner *s) + +

      +Returns the next token. An integer token code is returned (see table below) on success. If no more input text is +available 0 is returned. If a scanning error occurred, -1 is returned. In this case, error information can be +obtained using Scanner_errinfo(). +
      + +

      +String *Scanner_text(Scanner *s) +

      +Returns the scanned text corresponding to the last token returned by Scanner_token(). The returned string +is only valid until the next call to Scanner_token(). If you need to save it, make a copy. +
      + +

      +void Scanner_skip_line(Scanner *s) +

      +Skips to the end of the current line. The text skipped can be obtained using Scanner_text() afterwards. +
      + +

      +void Scanner_skip_balanced(Scanner *s, int startchar, int endchar) +

      +Skips to the end of a block of text denoted by starting and ending characters. For example, { and }. The +function is smart about how it skips text. String literals and comments are ignored. The function also is aware of nesting. The +skipped text can be obtained using Scanner_text() afterwards. Returns 0 on success, -1 if no matching endchar could be found. +
      + + +

      +void Scanner_set_location(Scanner *s, int startchar, int endchar) +

      +Changes the current filename and line number of the scanner. +
      + +

      +String *Scanner_file(Scanner *s) +

      +Gets the current filename associated with text in the scanner. +
      + +

      +int Scanner_line(Scanner *s) +

      +Gets the current line number associated with text in the scanner. +
      + +

      +int Scanner_start_line(Scanner *s) +

      +Gets the starting line number of the last token returned by the scanner. +
      + +

      +void Scanner_idstart(Scanner *s, char *idchar) +

      +Sets additional characters (other than the C default) that may be used to start C identifiers. idchar is a string +containing the characters (e.g., "%@"). The purpose of this function is to up special keywords such as "%module" or "@directive" as +simple identifiers. +
      + +

      +String *Scanner_errmsg(Scanner *s) +

      +Returns the error message associated with the last scanner error (if any). This will only return a meaningful result +if Scanner_token() returned -1. +
      + +

      +int Scanner_errline(Scanner *s) +

      +Returns the line number associated with the last scanner error (if any). This will only return a meaningful result +if Scanner_token() returned -1. The line number usually corresponds to the starting line number of a particular +token (e.g., for unterminated strings, comments, etc.). +
      + +

      +int Scanner_isoperator(int tokval) +

      +A convenience function that returns 0 or 1 depending on whether tokval is a valid C/C++ operator (i.e., a candidate for +operator overloading). +
      + +

      +void Scanner_freeze_line(int val) +

      +Freezes the current line number depending upon whether or not val is 1 or 0. When the line number is frozen, newline characters will not result in +updates to the line number. This is sometimes useful in tracking line numbers through complicated macro expansions. +
      + + +

      Token Codes

      + +The following table shows token codes returned by the scanner. These are integer codes returned by +the Scanner_token() function. + +
      +
      +Token code                   C Token
+-------------------------    -------------
+SWIG_TOKEN_LPAREN            (
+SWIG_TOKEN_RPAREN            )
+SWIG_TOKEN_SEMI              ; 
+SWIG_TOKEN_COMMA             , 
+SWIG_TOKEN_STAR              * 
+SWIG_TOKEN_TIMES             *
+SWIG_TOKEN_LBRACE            { 
+SWIG_TOKEN_RBRACE            } 
+SWIG_TOKEN_EQUAL             = 
+SWIG_TOKEN_EQUALTO           == 
+SWIG_TOKEN_NOTEQUAL          != 
+SWIG_TOKEN_PLUS              + 
+SWIG_TOKEN_MINUS             - 
+SWIG_TOKEN_AND               & 
+SWIG_TOKEN_LAND              && 
+SWIG_TOKEN_OR                | 
+SWIG_TOKEN_LOR               || 
+SWIG_TOKEN_XOR               ^ 
+SWIG_TOKEN_LESSTHAN          < 
+SWIG_TOKEN_GREATERTHAN       > 
+SWIG_TOKEN_LTEQUAL           <= 
+SWIG_TOKEN_GTEQUAL           >= 
+SWIG_TOKEN_NOT               ~ 
+SWIG_TOKEN_LNOT              ! 
+SWIG_TOKEN_LBRACKET          [ 
+SWIG_TOKEN_RBRACKET          ] 
+SWIG_TOKEN_SLASH             / 
+SWIG_TOKEN_DIVIDE            /
+SWIG_TOKEN_BACKSLASH         \ 
+SWIG_TOKEN_POUND             # 
+SWIG_TOKEN_PERCENT           % 
+SWIG_TOKEN_MODULO            %
+SWIG_TOKEN_COLON             : 
+SWIG_TOKEN_DCOLON            :: 
+SWIG_TOKEN_DCOLONSTAR        ::*
+SWIG_TOKEN_LSHIFT            << 
+SWIG_TOKEN_RSHIFT            >> 
+SWIG_TOKEN_QUESTION          ? 
+SWIG_TOKEN_PLUSPLUS          ++ 
+SWIG_TOKEN_MINUSMINUS        -- 
+SWIG_TOKEN_PLUSEQUAL         += 
+SWIG_TOKEN_MINUSEQUAL        -= 
+SWIG_TOKEN_TIMESEQUAL        *= 
+SWIG_TOKEN_DIVEQUAL          /= 
+SWIG_TOKEN_ANDEQUAL          &= 
+SWIG_TOKEN_OREQUAL           |= 
+SWIG_TOKEN_XOREQUAL          ^= 
+SWIG_TOKEN_LSEQUAL           <<= 
+SWIG_TOKEN_RSEQUAL           >>= 
+SWIG_TOKEN_MODEQUAL          %= 
+SWIG_TOKEN_ARROW             -> 
+SWIG_TOKEN_ARROWSTAR         ->* 
+SWIG_TOKEN_PERIOD            . 
+SWIG_TOKEN_AT                @ 
+SWIG_TOKEN_DOLLAR            $ 
+SWIG_TOKEN_ENDLINE           Literal newline
+SWIG_TOKEN_ID                identifer 
+SWIG_TOKEN_FLOAT             Floating point with F suffix (e.g., 3.1415F)
+SWIG_TOKEN_DOUBLE            Floating point (e.g., 3.1415 )
+SWIG_TOKEN_INT               Integer (e.g., 314)
+SWIG_TOKEN_UINT              Unsigned integer (e.g., 314U)
+SWIG_TOKEN_LONG              Long integer (e.g., 314L) 
+SWIG_TOKEN_ULONG             Unsigned long integer (e.g., 314UL)
+SWIG_TOKEN_LONGLONG          Long long integer (e.g., 314LL )
+SWIG_TOKEN_ULONGLONG         Unsigned long long integer (e.g., 314ULL) 
+SWIG_TOKEN_CHAR              Character literal in single quotes ('c')
+SWIG_TOKEN_STRING            String literal in double quotes ("str")
+SWIG_TOKEN_RSTRING           Reverse quote string (`str`)
+SWIG_TOKEN_CODEBLOCK         SWIG code literal block %{ ... %}
+SWIG_TOKEN_COMMENT           C or C++ comment  (// or /* ... */)
+SWIG_TOKEN_ILLEGAL           Illegal character
+
      +
      + +Notes + +
        +
      • When more than one token code exist for the same token text, those codes are identical (e.g., SWIG_TOKEN_STAR and SWIG_TOKEN_TIMES). + +

        +

      • +String literals are returned in their exact representation in which escape codes (if any) have been interpreted. + +

        +

      • +All C identifiers and keywords are simply returned as SWIG_TOKEN_ID. To check for specific keywords, you will need to +add extra checking on the returned text. + +

        +

      • C and C++ comments include the comment starting and ending text (e.g., "//", "/*"). + +

        +

      • The maximum token integer value is found in the constant SWIG_MAXTOKENS. This can be used if you wanted to create +an array or table for the purposes of remapping tokens to a different set of codes. For instance, if you are +using these functions to write a yacc-compatible lexer. +
      + + + + + + + + diff --git a/Doc/Devel/tree.html b/Doc/Devel/tree.html new file mode 100644 index 0000000..64d9d19 --- /dev/null +++ b/Doc/Devel/tree.html @@ -0,0 +1,265 @@ + + +SWIG Parse Tree Handling + + + +
      +

      SWIG Parse Tree Handling

      + +

      +David M. Beazley
      +dave-swig@dabeaz.com
      +December, 2006
      + + +

      + +

      Introduction

      + +This document describes the functions related to the handling of +parse trees in SWIG. The structure of SWIG parse trees has been influenced heavily by ideas +from XML-DOM trees. In fact, the functions in the API and attribute names are nearly identical. +The header file Source/swig/swigtree.h contains the functions and macros described in +this document. This API is +considered to be stable. + +

      Parse tree navigation

      + +The following macros are used to navigate the parse tree. + +

      +nodeType(n) + +

      +Returns the type of a node as a String object. The type is stored in the "nodeType" attribute of n. +
      + +

      +parentNode(n) + +

      +Returns the parent of a node. This is found in the "parentNode" attribute of n. +
      + +

      +previousSibling(n) + +

      +Returns the previous sibling of a node (if any). This is found in the "previousSibling" attribute of n. +
      + +

      +nextSibling(n) + +

      +Returns the next sibling of a node (if any). This is found in the "nextSibling" attribute of n. +
      + +

      +firstChild(n) + +

      +Returns the first child of a node (if any). This is found in the "firstChild" attribute of n. +
      + +

      +lastChild(n) + +

      +Returns the last child of a node (if any). This is found in the "lastChild" attribute of n. +
      + + +

      Parse Tree Construction

      + +The following macros are used to construct parse trees. + +

      +set_nodeType(n, val) + +

      +Sets the nodeType attribute of n. val is a string containing the type. +
      + +

      +set_parentNode(n, parent) + +

      +Sets the parent of node n. +
      + +

      +set_previousSibling(n, prev) + +

      +Sets the previous sibling of node n. +
      + +

      +set_nextSibling(n, next) + +

      +Sets the next sibling of node n. +
      + +

      +set_firstChild(n, chd) + +

      +Sets the first child of node n. +
      + +

      +set_lastChild(n, chd) + +

      +Sets the last child of node n. +
      + +

      Tree Management Functions

      + +The following functions are used to help with the management and construction of parse trees. + +

      +void appendChild(Node *node, Node *child) +

      +Adds a new child to node. This function takes care of adjusting the "firstChild" and "lastChild" attributes of node to appropriate values. After calling this function, the "lastChild" attribute will point to child. +
      + +

      +void prependChild(Node *node, Node *child) +

      +Prepends a new child to node. The new child is added so that it becomes the first child of node. +
      + +

      +void removeNode(Node *node) +

      +Removes a node from the parse tree. The removal process detaches a node from its parent by removing it from the parent's child list. Upon return, node will have no parent and no siblings. This function does NOT delete node or modify children of node. If desired, node could be reattached to a different part of the parse tree. +
      + +

      +Node *copyNode(Node *node) +

      +Copies a node, but only copies those attributes that are simple strings. Thus, the new node will not contain any references to other nodes, lists, hashes, or other complex data structures. This function may be useful if you want to copy the data contents of a node in the process of creating a new parse tree node. +
      + + +

      Attribute Checking

      + +The following utility is provided since this is an extremely common operation. + +

      +int checkAttribute(Node *n, const String_or_char *name, const String_or_char *value) +

      +This function checks to see whether node n has a given +attribute name and that the attribute has a given value. Returns 0 or +1. +
      + + +

      Node Transformation

      + +In the course of processing, SWIG often applies a transform to a node. +This transformation process made modify many of the attributes--even +changing the type of a node. The following functions are used to help +manage this transformation process. In addition to provide sanity +checks, they save the old contents of the node so that they can be +restored later. + +

      +void Swig_save(const char *namespace, Node *n, ...) + +

      +This function takes a node and a list of attribute names and saves their contents in a specified namespace. For example, +the call + +
      +Swig_save("temp",n,"type","parms","name",NIL)
+
      + +takes the attributes "type","parms", and "name" and saves their +contents under the attribute names "temp:type","temp:parms","temp:name". In addition, this function sets +an attribute "view" to hold the name of the current namespace. In this example, the "view" attribute would be set +to "temp". The attribute names specified are all optional. If one or more of the attributes don't exist, +this function merely records that those attributes did not exist in the original node. +
      + +

      +void Swig_require(const char *namespace, Node *n, ...) + +

      +This function is similar to Swig_save() except that adds additional attribute checking. There are different interpretations +of the attribute names. A name of "attr" merely requests that the function check for the presence of an attribute. If the attribute is missing, SWIG will exit with a failed assertion. An attribute name of "?attr" specifies that the attribute "attr" is optional and +that it's old value must be saved (if any). An attribute name of "*attr" specifies that the attribute is required and that +its value must be saved. The saving of attributes is performed in the same manner as with Swig_save(). Here is an example: + +
      +Swig_require("temp",n,"type","*name","?parms",NIL);
+
      + +
      + +

      +void Swig_restore(Node *n) + +

      +This function restores a node to the state it was in prior to the last Swig_save() or Swig_require() call. This is used to undo node transformations. +
      + +

      Debugging Functions

      + +The following functions are used to help debug SWIG parse trees. + +

      +void Swig_print_tags(Node *node, String_or_char *prefix) + +

      +Prints the tag-structure of the parse tree to standard output. node is the top-level parse tree node. prefix is +a string prefix thats added to the start of each line. Normally, you would specify the empty string or NIL for prefix. +This function is called by the -dump_tags option to SWIG. + +
      +% swig -dump_tags -python example.i
+ . top (:1)
+ . top . include (/Users/beazley/Projects/share/swig/1.3.31/swig.swg:0)
+ . top . include . include (/Users/beazley/Projects/share/swig/1.3.31/swigwarnings.swg:0)
+ . top . include . include . include (/Users/beazley/Projects/share/swig/1.3.31/swigwarn.swg:0)
+...
+...
+ . top . include (example.i:0)
+ . top . include . module (example.i:2)
+ . top . include . insert (example.i:7)
+ . top . include . cdecl (example.i:5)
+ . top . include . cdecl (example.i:6)
+
      + +Since many language modules include hundreds of typemaps and other information, the output of this can be significantly more complicated than you might expect. +
      + +

      +void Swig_print_node(Node *node) + +

      +Prints the contents of a parse tree node, including all children, to standard output. The output includes all attributes +and other details. The command line option -dump_tree produces output generated by this function. +
      + +

      +void Swig_print_tree(Node *node) + +

      +Prints the same output as Swig_print_node() except that it also processes all of the siblings of node. This can +be used to dump the entire parse tree to standard output. Use the command line option -dump_tree to get +the output of this function for a SWIG input file. +
      + + + + + + + + + diff --git a/Doc/Devel/wrapobj.html b/Doc/Devel/wrapobj.html new file mode 100644 index 0000000..10e3acc --- /dev/null +++ b/Doc/Devel/wrapobj.html @@ -0,0 +1,223 @@ + + +Wrapper Objects + + + +
      +

      Wrapper Objects

      + +

      +David M. Beazley
      +dave-swig@dabeaz.com
      +January 15, 2007
      + + +

      + +

      Introduction

      + +This document describes the functions related to management of +wrapper objects. A wrapper object is a low-level +data structure used to contain the C/C++ code that is emitted during the +wrapping process. It contains not only the emitted code, but information +about local variables. These objects are a critical component of almost all +SWIG target language modules. + +

      +The functions described here are declared +in Source/Swig/swigwrap.h. This API is considered to be +stable. + +

      Creating and Destroying Wrappers

      + +The following functions create and destroy wrapper objects. + +

      +Wrapper *NewWrapper() + +

      +Creates a new wrapper object. +
      + +

      +void DelWrapper(Wrapper *w) +

      +Destroys a wrapper object. +
      + +

      Wrapper Objects

      + +The Wrapper object returned by NewWrapper() has +three public attributes. + +
      +typedef struct Wrapper {
+    String *def;
+    String *locals;
+    String *code;
+} Wrapper;
+
      + +The def attribute is a string that holds the function +definition line. This line declares the function name, return type, +and parameters. Language modules create this declaration by simply printing +the appropriate text into this attribute. + +

      +The locals attribute is a string that holds the code +related to any local variables declaration. Normally, language modules +do not emit code to this string directly. They use Wrapper_add_local() or Wrapper_new_local() to do this. + +

      +The code attribute is a string that holds code related to the body of the function. Almost all code emitted by SWIG language modules is printed into this attribute. + +

      Creating Local Variables

      + +Perhaps the most useful aspect of Wrapper objects is the +management of local variables. When creating a wrapper, it is often +necessary to emit local variables related to the API of the target +language. In addition to this, typemaps and other aspects of SWIG +rely upon their own local variables. The following functions are used +to create local variables, but also provide support for renaming +variables in order to avoid name clashes. + +

      +int Wrapper_add_local(Wrapper *w, const String_or_char *name, const String_or_char *decl) +

      +Adds a new local variable to the wrapper object. name is the +name of the local variable. decl is a string containing the +actual variable declaration code. For example, if you wanted to +declare a variable "int x = 42;", you would set name +to "x" and +decl to "int x = 42;". On success, the text in +decl is added to the locals attribute of w +and 0 is returned. -1 is returned if a variable with the given name +has already been declared. +
      + +

      +int Wrapper_add_localv(Wrapper *w, const String_or_char *name, ...) +

      +The same as Wrapper_add_local() except that instead of +passing a single string for the declaration, a NULL-terminated list of +strings can be passed. These strings are joined together when +producing the output. This convention turns out to be fairly useful +since language modules often create their output into pieces. +
      + +

      +char * Wrapper_new_local(Wrapper *w, const String_or_char *name, const String_or_char *decl) +

      +The same as Wrapper_add_local() except that if a local variable +with the given name already exists, this function picks a new name and adds +the declaration using the new name. The actual name used for the variable +is returned. This function is used when generating code originating from +typemaps. For instance, if a typemap declares a local variable, that variable +might have to be renamed if the same typemap is used more than once in the same function. +
      + +

      +char * Wrapper_new_localv(Wrapper *w, const String_or_char *name,...) +

      +The same as Wrapper_new_localv(), but accepts a NULL-terminated list +of strings as code output. +
      + +

      +int Wrapper_check_local(Wrapper *w, const String_or_char *name) +

      +Checks to see if a local variable with name name has been declared. Returns 1 if the local is defined, 0 otherwise. +
      + +

      Output

      + +

      +void Wrapper_print(Wrapper *w, File *f) +

      +This function is used to format a wrapper function for output. The +formatted wrapper function is emitted to f which may be any +file-like object including a FILE * object or a String +* object. When emitting the wrapper, the code printed to the +wrapper object is automatically formatted. By default, the formatting +is done according to a "pretty printing" style in which lines are split onto +multiple lines and indented according to reasonable C formatting rules. This produces code that is moderately readable should you want to look at the wrapper +code output. An alternative output mode is "compact printing" in which +lines are collected and compacted. This may result in multiple C statements +appearing on the same line. This mode is sometimes used when the size of +a wrapper file is too large for certain compilers. For example, some compilers +might impose a limit of 65536 lines per source file. +
      + +

      +void Wrapper_compact_print_mode_set(int flag) +

      +Sets the output mode of the Wrapper_print() +function. If flag is set to 1, then wrapper code is formatted +to be compact. +
      + +

      +void Wrapper_pretty_print(String *str, File *f) +

      +Utility function that reformats a string containing C/C++ code and outputs +it to the file-like object f. The formatting process indents the code +and structures it according to reasonable C formatting rules. +
      + +

      +void Wrapper_compact_print(String *str, File *f) +

      +Utility function that reformats a string containing C/C++ code and outputs +it to the file-like object f. The formatting process tries to +make the code as compact as possible, without going completely overboard. For +example, multiple C statements may be combined onto a single line and braces may be aligned to not use up extra lines. +
      + + +

      An Example

      + +Here is a simple example of how these functions are used. Suppose +you wanted to emit the following C function: + +
      +
      +void foo(int n) {
+   int i;
+   for (i = 0; i < n; i++) {
+       printf("%d\n", i);
+   }
+}
+
      +
      + +Here is code that generates the above function: + +
      +
      +Wrapper *w = NewWrapper();
+Printf(w->def,"void foo(int n) {");
+Wrapper_add_local(w,"n","");         /* parameter n */
+Wrapper_add_local(w,"i", "int i;");  /* local i */
+Printv(w->code,"for (i = 0; i < n; i++) {",
+               "printf(\"%d\n",i);",
+               "}\n", NIL);
+Printf(w->code,"}\n");
+
+/* Emit wrapper code */
+Wrapper_print(w,outf);
+DelWrapper(w);
+
      +
      + +Within different language modules, this process is obviously much more +involved. However, this example shows the basic idea of how C/C++ +code is prepared for output. + + + + + + + + diff --git a/Doc/Manual/Allegrocl.html b/Doc/Manual/Allegrocl.html new file mode 100644 index 0000000..cc950db --- /dev/null +++ b/Doc/Manual/Allegrocl.html @@ -0,0 +1,2150 @@ + + + + +SWIG and Allegro Common Lisp + + + + + +

      17 SWIG and Allegro Common Lisp

      + +
      + +
      + + + + +

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

      + +

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

      + +

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

      + +

      +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 (UFFI or 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. +

      + +

      17.1 Basics

      + + +

      17.1.1 Running Swig

      + + +

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

      + +

      +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 .i extension--containing any foreign declarations of +identifiers you wish to use. The most common approach is to use a 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. +

      + +

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

      + +

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

      + +
      example.i +
      +%module example
+
+%include "header.h"
+
+int fact(int n);
+
      +
      + +

      The contents of header.h are very simple:

      +
      header.h +
      +int fact(char *statement);   // pass it a fact, and it will rate it.
+
      +
      + +

      The contents of example.cl will look like this:

      + +
      example.cl +
      +(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)))
+
      +
      + +

      +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 +erroneous. Function overloading is not supported in C, and this +code will not compile even though SWIG did not complain. +

      + +

      +In order to generate a C interface to Allegro CL using this code run +swig using the -allegrocl option, as below: +

      + +
      +
      +% swig -allegrocl example.i
+
      +
      + +

      +When building an interface to C++ code, include the -c++ option: +

      + +
      +
      +% swig -allegrocl -c++ example.i
+
      +
      + +

      +As a result of running one of the above commands, a file named example.cl +will be generated containing the lisp side of the interface. As well, a file +example_wrap.cxx 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. +

      + +

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

      + +

      +The generated wrapper file is below. It contains very simple +wrappers by default, that simply pass the arguments to the +actual function. +

      + +
      example_wrap.i +
      +   ... 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;
+    }
+}
+
      +
      + +

      +And again, the generated lisp code. Note that it differs from +what is generated when parsing C code: +

      + +
      +
      +   ...
+
+(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)))
+
      +
      + +

      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 Function overloading/Parameter defaulting. + +

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

      + +

      17.1.2 Command Line Options

      + + +

      +There are three Allegro CL specific command-line option: +

      + +
      +
      +swig -allegrocl [ options ] filename
+
+   -identifier-converter [name] - Binds the variable swig:*swig-identifier-convert* 
+                                  in the generated .cl file to name.
+				  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 swig.<module-name> rather than
+	      swig. 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.
+
      +
      + +

      +See Section 17.5 Identifier converter +functions for more details. +

      + +

      17.1.3 Inserting user code into generated files

      + + +

      +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 #include "header.h" directive. This can be done +using the SWIG %insert(section) %{ ...code... %} directive: +

      + +
      +
      +%module example
+
+%{
+#include "header.h"
+%}
+
+%include "header.h"
+
+int fact(int n);
+
      +
      + +

      +Additional sections have been added for inserting into the +generated lisp interface file +

      +
        +
      • lisphead - inserts before type declarations
        • +
      • lisp - inserts after type declarations according to + where it appears in the .i file
        • +
      +

      +Note that the block %{ ... %} is effectively a shortcut for +%insert("header") %{ ... %}. +

      + + +

      17.2 Wrapping Overview

      + + +

      +New users to SWIG are encouraged to read +SWIG Basics, and +SWIG and C++, for those +interested in generating an interface to C++. +

      + +

      17.2.1 Function Wrapping

      + + +

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

      + +

      + 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: +

      + +
      + 
      +        ______________
+       |              |  (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
+
      +
      + +

      17.2.2 Foreign Wrappers

      + + +

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

      + +

      17.2.3 FFI Wrappers

      + + +

      + These are the generated ff:def-foreign-call forms. No typemaps are + applicable to this layer, but the %ffargs directive is + available for use in .i files, to specify which keyword arguments + should be specified for a given function. +

      + +
      ffargs.i: + 
      +%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();
+
      +
      + +

      Generates: +

      +
      ffargs.cl: + 
      +(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))
+
      +
      + +
      + 
      %ffargs(strings_convert="t");
      +
      + +

      + Is the only default value specified in allegrocl.swg to force + the muffling of warnings about automatic string conversion when defining + ff:def-foreign-call's. +

      + +

      17.2.4 Non-overloaded Defuns

      + + +

      + 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 + lin 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 lout typemap. +

      + +

      17.2.5 Overloaded Defuns

      + + +

      + In the case of overloaded functions, mulitple 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 lispclass 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 lout typemap. +

      + +

      17.2.6 What about constant and variable access?

      + + +

      + 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, + defconstant and ff:def-foreign-variable forms will be + generated for accessing constants and global variables. These, along with + the defuns listed above are the intended API for calling + into the foreign module. +

      + +

      17.2.7 Object Wrapping

      + + +

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

      + +

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

      + +

      17.3 Wrapping Details

      + + +

      + In this section is described how particular C/C++ constructs are + translated into lisp. +

      + +

      17.3.1 Namespaces

      + + +

      + C++ namespaces are translated into Lisp packages by SWIG. The + Global namespace is mapped to a package named by the %module + directive or the -module command-line argument. Further + namespaces are generated by the swig-defpackage utility + function and given names based on Allegro CLs nested namespace + convention. For example: +

      + +
      foo.i: + 
      +%module foo
+
+%{
+#include "foo.h"
+%}
+
+%include "foo.h"
+
+namespace car {
+   ...
+   namespace tires {
+      int do_something(int n);
+   }
+}
+
      +
      +

      Generates the following code. +

      +
      foo.cl + 
      +(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)))
+
      +
      + +

      + 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(*). +

      + +

      (*) Except for the package named by the module, all + namespace names are passed to the identifier-converter-function + as strings with a :type of :namespace. It is the + job of this function to generate the desired symbol, accounting for + case preferences, additional naming cues, etc. +

      + +

      + Note that packages created by swig-defpackage do not + use the COMMON-LISP or EXCL package. This reduces possible + conflicts when defining foreign types via the SWIG interface + in all but the toplevel modules package. This may + lead to confusion if, for example, the current package is + foo.car.tires and you attempt to use a common-lisp + function such as (car '(1 2 3). +

      + +

      17.3.2 Constants

      + + + +

      + Constants, as declared by the preprocessor #define macro or SWIG + %constant directive, are included in SWIGs 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). +

      +

      + Here are examples of simple preprocessor constants when using -nocwrap. +

      +
      + 
      +#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
+
      +
      + +

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

      + +

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

      + +
      + 
      +#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
+
      +
      +

      + Users are cautioned to get to know their constants before use, or + not use the -nocwrap command-line option. +

      + +

      17.3.3 Variables

      + + +

      + For C wrapping, a def-foreign-variable call is generated for access + to global variables. +

      +

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

      + +
      vars.h + 
      +namespace nnn {
+  int const global_var = 2;
+  float glob_float = 2.0;
+}
+
      +
      + +

      + Generated code: +

      +
      vars.cl + 
      +(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))
+
      +
      + +

      + Note also, that where applicable, setter wrappers are implemented + as setf methods on the getter function, providing a lispy interface + to the foreign code. +

      + +
      + 
      +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
+
      +
      + +

      17.3.4 Enumerations

      + + +

      + 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 it's 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 typemaps. +

      + +

      + 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 it's value into lisp. +

      + +

      For example, the following header file +

      enum.h: + 
      +enum COL { RED, GREEN, BLUE };	
+enum FOO { FOO1 = 10, FOO2, FOO3 };
+
      +
      +

      + In -nocwrap mode, generates +

      +
      enum.cl: + 
      +(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))
+
      +
      + +

      And when generating a .cxx wrapper +

      enum_wrap.cxx: + 
      +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;
+
      +
      +

      + and +

      +
      enum.cl: + 
      +(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)
+
+
      +
      + +

      17.3.5 Arrays

      + + +

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

      + +

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

      +
      array.h + 
      +#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];
+}
+
      +
      + +

      + Generates: +

      + +
      array.cl + 
      +(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)))
+
      +
      + +

      17.3.6 Classes and Structs and Unions (oh my!)

      + + +

      17.3.6.1 CLOS wrapping of

      + + +

      + 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 X, the wrapping defun (or defmethod) on the Lisp + side will automatically wrap the pointer returned in an instance + of the apropriate class. This makes it much easier to write and + debug code than if pointers were passed around as a jumble of + integer values. +

      + +

      17.3.6.2 CLOS Inheritance

      + + +

      + 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. It's 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. +

      + +

      17.3.6.3 Member fields and functions

      + + +

      + All public fields will have accessor getter/setter functions + generated for them, as appropriate. All public member functions + will have wrapper functions generated. +

      + +

      + We currently ignore anything that isn't public (i.e. + private or protected), because the C++ compiler + won't allow the wrapper functions to access such fields. Likewise, + the interface does nothing for friend directives, +

      + +

      17.3.6.4 Why not directly access C++ classes using foreign types?

      + + +

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

      + +

      17.3.7 Templates

      + + + +

      17.3.7.1 Generating wrapper code for templates

      + + +

      + 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 + %template + directive. +

      + +

      17.3.7.2 Implicit Template instantiation

      + + +

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

      + +

      17.3.8 Typedef, Templates, and Synonym Types

      + + +

      + In C/C++ it is possible, via typedef, to have many names refer to + the same type. In general, this is not a problem, though + it can lead to confusion. Assume the below C++ header file: +

      + +
      synonyms.h + 
      +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 */
+
      +
      + +

      + The function zzz 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 A. Assuming a simple implementation, a call + to xxx(1) will return a pointer to an A object, which + will be wrapped in a CLOS instance of class A, and a + call to yyy(1) will result in a CLOS instance of + type Foo being returned. Without establishing a clear + type relationship between Foo and A, an + attempt to call zzz(yyy(1)) will result in an error. +

      + +

      + 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, intead of generating a distinct CLOS class + definition, we generate a form that expands to: +

      +
      + (setf (find-class <synonym>) <primary>) +
      +

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

      + +

      + Given the above header file, synonym.h, a Lisp session would + appear as follows: +

      +
      + 
      +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> 
+
      +
      + +

      17.3.8.1 Choosing a primary type

      + + +

      + The choice of a primary type is selected by the following + criteria from a set of synonym types. +

      +
        +
      • + If a synonym type has a class definition, it is the primary type. +
        • +
      • + If a synonym type is a class template and has been explicitly + instantiated via %template, it is the primary type. +
        • +
      • + For all other sets of synonymous types, the synonym which is + parsed first becomes the primary type. +
        • +
      + +

      17.3.9 Function overloading/Parameter defaulting

      + + +

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

      + +

      Example: +

      +
      overload.h: + 
      +
+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 */
+
      +
      + +

      Creates the following three wrappers, for each of the possible argument + combinations +

      +
      overload_wrap.cxx + 
      +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;
+    }
+}
+
      +
      + +

      + And the following foreign-function-call and method definitions on the + lisp side: +

      +
      overload.cl + 
      +(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)))
+
      +
      + +

      And their usage in a sample lisp session: +

      +
      + 
      +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> 
+
      +
      + +

      17.3.10 Operator wrapping and Operator overloading

      + + +

      + Wrappers to defined C++ Operators are automatically renamed, using + %rename, to the following defaults: +

      +
      + 
      +/* 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[];
+
      +
      + +

      + Name mangling occurs on all such renamed identifiers, so that wrapper name + generated by B::operator= will be B___eq__, i.e. + <class-or-namespace>_ has been added. Users may modify + these default names by adding %rename directives in their own .i files. +

      + +

      + 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 %extend directive is used to add an overload method + on Operator==. +

      + +
      opoverload.h + 
      +class B {
+ public:
+  int x;
+  int y;
+  bool operator==(B const& other) const;
+};
+
      +
      + +

      + and +

      +
      opoverload.i + 
      +%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;
+};
+
      +
      + +

      + Either operator can be called via a single call + to the dispatch function: +

      +
      + 
      +opoverload> (B___eq__ x1 x2)
+nil
+opoverload> (B___eq__ x1 3)
+nil
+opoverload> 
+
      +
      + +

      17.3.11 Varargs

      + + +

      + 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 %vararg + 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 printf(). It's declaration would + appear as follows: +

      + +

      + See the following section + on Variable Length arguments + provides examples on how %vararg can be used, along + with other ways such functions can be wrapped. +

      + +

      17.3.12 C++ Exceptions

      + + +

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

      + +

      17.3.13 Pass by value, pass by reference

      + + +

      + 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 typemaps, + and should not require any fine tuning by the user, even for + newly defined types. +

      + +

      17.4 Typemaps

      + + +

      + 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 Typemaps for more information. +

      + +

      17.4.1 Code Generation in the C++ Wrapper

      + + + +

      + Every C++ wrapper generated by SWIG takes the following form: +

      + +
      + 
      +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;
+   }
+
      +
      + +

      17.4.1.1 IN Typemap

      + + +

      + the in 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 + <binding locals to parameters> 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. +

      + +

      These are the default specifications for the IN typemap. Here, + $input refers to the parameter code is being generated + for, and $1 is the local variable to which it is + being assigned. The default settings of this typemap are as follows: +

      + +
      + 
      +%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;";
+
      +
      + +

      17.4.1.2 OUT Typemap

      + + +

      + The out 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. It's default mapping is as follows: +

      + +
      + 
      +%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);";
+
      +
      + +

      17.4.1.3 CTYPE Typemap

      + + +

      + This typemap is not used for code generation, but purely for the + transformation of types in the parameter list of the wrapper function. + It's primary use is to handle by-value to by-reference conversion in the + wrappers parameter list. Its default settings are: +

      + +
      + 
      +%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";
+
      +
      + +

      + These three typemaps are specifically employed by the 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 common typemaps here. +

      + +

      17.4.2 Code generation in Lisp wrappers

      + + +

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

      + +

      + 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 + 16.3.1 Namespaces for details. +

      + +

      17.4.2.1 LIN Typemap

      + + +

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

      + +

      The LIN typemap accepts the following $variable references. +

      +
        +
      • $in - expands to the name of the parameter being + applied to this typemap +
        • +
      • $out - expands to the name of the local variable + assigned to this typemap +
        • +
      • $in_fftype - the foreign function type of the C type.
        • +
      • $*in_fftype - 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. +
        • +
      • $body - very important. Instructs SWIG where + subsequent code generation steps should be inserted into the + current typemap. Leaving out a $body reference + will result in lisp wrappers that do very little by way of + calling into foreign code. Not recommended. +
        • +
      + +
      + 
      +%typemap(lin)	SWIGTYPE 	"(cl:let (($out $in))\n  $body)";
+
      +
      + +

      17.4.2.2 LOUT Typemap

      + + +

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

      + +

      The LOUT typemap uses the following $variable +

      +
        +
      • $lclass - Expands to the CLOS class that + represents foreign-objects of the return type matching this + typemap. +
        • +
      • $body - Same as for the LIN map. Place this + variable where you want the foreign-function call to occur. +
        • +
      • $ldestructor - 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). +
        • +
      + +
      + 
      +%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)";
+
      +
      + +

      17.4.2.3 FFITYPE Typemap

      + + + +

      + 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: +

      + +
      + 
      +%typemap(ffitype) bool ":unsigned-char";
+
      +
      + +

      + 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: +

      + +
      + 
      +%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)";
+
      +
      + +

      17.4.2.4 LISPTYPE Typemap

      + + +

      + 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: +

      + +
      + 
      +%typemap(lisptype) bool "cl:boolean";
+%typemap(lisptype) char "cl:character";
+%typemap(lisptype) unsigned char "cl:integer";
+%typemap(lisptype) signed char "cl:integer";
+
      +
      + +

      17.4.2.5 LISPCLASS Typemap

      + + +

      + 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: +

      + +
      + 
      +%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";
+
      +
      + +

      17.4.3 Modifying SWIG behavior using typemaps

      + + +

      + The following example shows how we made use of the above + typemaps to add support for the wchar_t type. +

      + +
      + 
      +%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";
+
      +
      + +

      17.5 Identifier Converter functions

      + + +

      17.5.1 Creating symbols in the lisp environment

      + + +

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

      + +

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

      + +

      17.5.2 Existing identifier-converter functions

      + + +

      Two basic identifier routines have been defined. +

      17.5.2.1 identifier-convert-null

      + + +

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

      + +

      17.5.2.2 identifier-convert-lispify

      + + +

      + All underscores in the identifier string are converted to + hyphens. Otherwise, identifier-convert-lispify performs the + same symbol transformations. +

      + +

      17.5.2.3 Default identifier to symbol conversions

      + + +

      + Check the definitions of the above two default + identifier-converters in Lib/allegrocl/allegrocl.swg for + default naming conventions. +

      + +

      17.5.3 Defining your own identifier-converter

      + + +

      + A user-defined identifier-converter function should conform to the following + specification: +

      + +
      +
      +(defun identifier-convert-fn (id &key type class arity) ...body...)
+result ==> symbol or (setf symbol)
+
      +
      + +

      The ID argument is a string representing an identifier in the +foreign environment. +

      + +

      +The :type keyword argument provides more information on the type of +identifier. It's 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. +

      + +
        +
      • :class - names a CLOS class.
        • +
      • :constant - names a defconstant
        • +
      • :constructor - names a function for creating a foreign object
        • +
      • :destructor - names a function for freeing a foreign object
        • +
      • :function - names a CLOS wrapping defmethod or defun.
        • +
      • :ff-operator - names a foreign call defined via ff:def-foreign-call
        • +
      • :getter - getter function
        • +
      • :namespace - names a C++ namespace
        • +
      • :setter - names a setter function. May return a (setf symbol) reference
        • +
      • :operator - names a C++ operator, such as Operator=, Operator*.
        • +
      • :slot - names a slot in a struct/class/union declaration.
        • +
      • :type - names a foreign-type defined via ff:def-foreign-type.
        • +
      • :variable - names a variable defined via ff:def-foreign-variable.
        • +
      + +

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

      + +

      +The :arity keyword argument only appears in swig:swig-defmethod forms +generated for overloaded functions. It's value is an integer +indicating the number of arguments passed to the routine indicated by +this identifier. +

      + +

      17.5.4 Instructing SWIG to use a particular identifier-converter

      + + +

      + By default, SWIG will use identifier-converter-null. To specify + another convert function, use the -identifier-converter + command-line argument. The value should be a string naming the + function you wish the interface to use instead, when generating + symbols. ex: +

      + +
      +
      +% swig -allegrocl -c++ -module mymodule -identifier-converter my-identifier-converter
+
      +
      + + + + diff --git a/Doc/Manual/Arguments.html b/Doc/Manual/Arguments.html new file mode 100644 index 0000000..8ab51fa --- /dev/null +++ b/Doc/Manual/Arguments.html @@ -0,0 +1,496 @@ + + + +Argument Handling + + + + +

      9 Argument Handling

      + +
      + +
      + + + + +

      +In Chapter 3, SWIG's treatment of basic datatypes and pointers was +described. In particular, primitive types such as int and +double are mapped to corresponding types in the target +language. For everything else, pointers are used to refer to +structures, classes, arrays, and other user-defined datatypes. +However, in certain applications it is desirable to change SWIG's +handling of a specific datatype. For example, you might want to +return multiple values through the arguments of a function. This chapter +describes some of the techniques for doing this. +

      + +

      9.1 The typemaps.i library

      + + +

      +This section describes the typemaps.i library file--commonly used to +change certain properties of argument conversion. +

      + +

      9.1.1 Introduction

      + + +

      +Suppose you had a C function like this: +

      + +
      +void add(double a, double b, double *result) {
+	*result = a + b;
+}
+
      + +

      +From reading the source code, it is clear that the function is storing +a value in the double *result parameter. However, since SWIG +does not examine function bodies, it has no way to know that this is +the underlying behavior. +

      + +

      +One way to deal with this is to use the +typemaps.i library file and write interface code like this: +

      + +
      +// Simple example using typemaps
+%module example
+%include "typemaps.i"
+
+%apply double *OUTPUT { double *result };
+%inlne %{
+extern void add(double a, double b, double *result);
+%}
+
      + +

      +The %apply directive tells SWIG that you are going to apply +a special type handling rule to a type. The "double *OUTPUT" specification is the +name of a rule that defines how to return an output value from an argument of type +double *. This rule gets applied to all of the datatypes +listed in curly braces-- in this case "double *result".

      + +

      +When the resulting module is created, you can now use the function +like this (shown for Python): +

      + +
      +>>> a = add(3,4)
+>>> print a
+7
+>>>
+
      + +

      +In this case, you can see how the output value normally returned in +the third argument has magically been transformed into a function +return value. Clearly this makes the function much easier to use +since it is no longer necessary to manufacture a special double +* object and pass it to the function somehow. +

      + +

      +Once a typemap has been applied to a type, it stays in effect for all future occurrences +of the type and name. For example, you could write the following: +

      + +
      +%module example
+%include "typemaps.i"
+
+%apply double *OUTPUT { double *result };
+
+%inline %{
+extern void add(double a, double b, double *result);
+extern void sub(double a, double b, double *result);
+extern void mul(double a, double b, double *result);
+extern void div(double a, double b, double *result);
+%}
+...
+
      + +

      +In this case, the double *OUTPUT rule is applied to all of the functions that follow. +

      + +

      +Typemap transformations can even be extended to multiple return values. +For example, consider this code: +

      + +
      +
      +%include "typemaps.i"
+%apply int *OUTPUT { int *width, int *height };
+
+// Returns a pair (width,height)
+void getwinsize(int winid, int *width, int *height);
+
      +
      + +

      +In this case, the function returns multiple values, allowing it to be used like this: +

      + +
      +>>> w,h = genwinsize(wid)
+>>> print w
+400
+>>> print h
+300
+>>>
+
      +
      + +

      +It should also be noted that although the %apply directive is +used to associate typemap rules to datatypes, you can also use the +rule names directly in arguments. For example, you could write this: +

      + +
      +// Simple example using typemaps
+%module example
+%include "typemaps.i"
+
+%{
+extern void add(double a, double b, double *OUTPUT);
+%}
+extern void add(double a, double b, double *OUTPUT);
+
      + +

      +Typemaps stay in effect until they are explicitly deleted or redefined to something +else. To clear a typemap, the %clear directive should be used. For example: +

      + +
      +
      +%clear double *result;      // Remove all typemaps for double *result
+
      +
      + +

      9.1.2 Input parameters

      + + +

      +The following typemaps instruct SWIG that a pointer really only holds a single +input value: +

      + +
      +int *INPUT		
+short *INPUT
+long *INPUT
+unsigned int *INPUT
+unsigned short *INPUT
+unsigned long *INPUT
+double *INPUT
+float *INPUT
+
      + +

      +When used, it allows values to be passed instead of pointers. For example, consider this +function: +

      + +
      +double add(double *a, double *b) {
+	return *a+*b;
+}
+
      + +

      +Now, consider this SWIG interface: +

      + +
      +%module example
+%include "typemaps.i"
+...
+%{
+extern double add(double *, double *);
+%}
+extern double add(double *INPUT, double *INPUT);
+
+
      + +

      +When the function is used in the scripting language interpreter, it will work like this: +

      + +
      +result = add(3,4)
+
      + +

      9.1.3 Output parameters

      + + +

      +The following typemap rules tell SWIG that pointer is the output value of a +function. When used, you do not need to supply the argument when +calling the function. Instead, one or more output values are returned. +

      + +
      +int *OUTPUT
+short *OUTPUT
+long *OUTPUT
+unsigned int *OUTPUT
+unsigned short *OUTPUT
+unsigned long *OUTPUT
+double *OUTPUT
+float *OUTPUT
+
+
      +

      +These methods can be used as shown in an earlier example. For example, if you have this C function :

      + +
      +void add(double a, double b, double *c) {
+	*c = a+b;
+}
+
      + +

      +A SWIG interface file might look like this :

      + +
      +%module example
+%include "typemaps.i"
+...
+%inline %{
+extern void add(double a, double b, double *OUTPUT);
+%}
+
+
      + +

      +In this case, only a single output value is returned, but this is not +a restriction. An arbitrary number of output values can be returned by applying +the output rules to more than one argument (as shown previously). +

      + +

      +If the function also returns a value, it is returned along with the argument. For example, +if you had this: +

      + +
      +extern int foo(double a, double b, double *OUTPUT);
+
      + +

      +The function will return two values like this: +

      + +
      +
      +iresult, dresult = foo(3.5, 2)
+
      +
      + +

      9.1.4 Input/Output parameters

      + + +

      +When a pointer serves as both an input and output value you can use +the following typemaps :

      + +
      +int *INOUT
+short *INOUT
+long *INOUT
+unsigned int *INOUT
+unsigned short *INOUT
+unsigned long *INOUT
+double *INOUT
+float *INOUT
+
+
      + +

      +A C function that uses this might be something like this:

      + +
      +void negate(double *x) {
+	*x = -(*x);
+}
+
+
      + +

      +To make x function as both and input and output value, declare the +function like this in an interface file :

      + +
      +%module example
+%include "typemaps.i"
+...
+%{
+extern void negate(double *);
+%}
+extern void negate(double *INOUT);
+
+
      + +

      +Now within a script, you can simply call the function normally :

      + +
      +a = negate(3);         # a = -3 after calling this
+
      + +

      +One subtle point of the INOUT rule is that many scripting languages +enforce mutability constraints on primitive objects (meaning that simple objects +like integers and strings aren't supposed to change). Because of this, you can't +just modify the object's value in place as the underlying C function does in this example. +Therefore, the INOUT rule returns the modified value as a new object +rather than directly overwriting the value of the original input object. +

      + +

      +Compatibility note : The INOUT rule used to be known as BOTH in earlier versions of +SWIG. Backwards compatibility is preserved, but deprecated. +

      + +

      9.1.5 Using different names

      + + +

      +As previously shown, the %apply directive can be used to apply the INPUT, OUTPUT, and +INOUT typemaps to different argument names. For example: +

      + +
      +// Make double *result an output value
+%apply double *OUTPUT { double *result };
+
+// Make Int32 *in an input value
+%apply int *INPUT { Int32 *in };
+
+// Make long *x inout
+%apply long *INOUT {long *x};
+
+
      + +

      +To clear a rule, the %clear directive is used: +

      + +
      +%clear double *result;
+%clear Int32 *in, long *x;
+
      + +

      +Typemap declarations are lexically scoped so a typemap takes effect from the point of definition to the end of the +file or a matching %clear declaration. +

      + +

      9.2 Applying constraints to input values

      + + +

      +In addition to changing the handling of various input values, it is +also possible to use typemaps to apply constraints. For example, maybe you want to +insure that a value is positive, or that a pointer is non-NULL. This +can be accomplished including the constraints.i library file. +

      + +

      9.2.1 Simple constraint example

      + + +

      +The constraints library is best illustrated by the following interface +file :

      + +
      +// Interface file with constraints
+%module example
+%include "constraints.i"
+
+double exp(double x);
+double log(double POSITIVE);         // Allow only positive values
+double sqrt(double NONNEGATIVE);     // Non-negative values only
+double inv(double NONZERO);          // Non-zero values
+void   free(void *NONNULL);          // Non-NULL pointers only
+
+
      + +

      +The behavior of this file is exactly as you would expect. If any of +the arguments violate the constraint condition, a scripting language +exception will be raised. As a result, it is possible to catch bad +values, prevent mysterious program crashes and so on.

      + +

      9.2.2 Constraint methods

      + + +

      +The following constraints are currently available

      + +
      +POSITIVE                     Any number > 0 (not zero)
+NEGATIVE                     Any number < 0 (not zero)
+NONNEGATIVE                  Any number >= 0
+NONPOSITIVE                  Any number <= 0
+NONZERO                      Nonzero number
+NONNULL                      Non-NULL pointer (pointers only).
+
+
      + +

      9.2.3 Applying constraints to new datatypes

      + + +

      +The constraints library only supports the primitive C datatypes, but it +is easy to apply it to new datatypes using %apply. For +example :

      + +
      +// Apply a constraint to a Real variable
+%apply Number POSITIVE { Real in };
+
+// Apply a constraint to a pointer type
+%apply Pointer NONNULL { Vector * };
+
+
      + +

      +The special types of "Number" and "Pointer" can be applied to any +numeric and pointer variable type respectively. To later remove a +constraint, the %clear directive can be used :

      + +
      +%clear Real in;
+%clear Vector *;
+
      + + + diff --git a/Doc/Manual/CCache.html b/Doc/Manual/CCache.html new file mode 100644 index 0000000..7db5583 --- /dev/null +++ b/Doc/Manual/CCache.html @@ -0,0 +1,475 @@ + + + +ccache-swig(1) manpage + + + + +

      16 Using SWIG with ccache - ccache-swig(1) manpage

      + +
      + +
      + + + + +

      +

      16.1 NAME

      + + +

      + +ccache-swig - a fast compiler cache + +

      +

      16.2 SYNOPSIS

      + + +

      +ccache-swig [OPTION] +

      +ccache-swig <compiler> [COMPILER OPTIONS] +

      +<compiler> [COMPILER OPTIONS] +

      +

      16.3 DESCRIPTION

      + + +

      +ccache-swig is a compiler cache. It speeds up re-compilation of C/C++/SWIG code +by caching previous compiles and detecting when the same compile is +being done again. ccache-swig is ccache plus support for SWIG. ccache +and ccache-swig are used interchangeably in this document. +

      +

      16.4 OPTIONS SUMMARY

      + + +

      +Here is a summary of the options to ccache-swig. +

      +

      +
+-s                      show statistics summary
+-z                      zero statistics
+-c                      run a cache cleanup
+-C                      clear the cache completely
+-F <n>                  set maximum files in cache
+-M <n>                  set maximum size of cache (use G, M or K)
+-h                      this help page
+-V                      print version number
+
+
      + +

      +

      16.5 OPTIONS

      + + +

      +These options only apply when you invoke ccache as "ccache-swig". When +invoked as a compiler none of these options apply. In that case your +normal compiler options apply and you should refer to your compilers +documentation. +

      +

      +

      -h
      Print a options summary page +

      +

      -s
      Print the current statistics summary for the cache. The +statistics are stored spread across the subdirectories of the +cache. Using "ccache-swig -s" adds up the statistics across all +subdirectories and prints the totals. +

      +

      -z
      Zero the cache statistics. +

      +

      -V
      Print the ccache version number +

      +

      -c
      Clean the cache and re-calculate the cache file count and +size totals. Normally the -c option should not be necessary as ccache +keeps the cache below the specified limits at runtime and keeps +statistics up to date on each compile. This option is mostly useful +if you manually modify the cache contents or believe that the cache +size statistics may be inaccurate. +

      +

      -C
      Clear the entire cache, removing all cached files. +

      +

      -F <maxfiles>
      This sets the maximum number of files allowed in +the cache. The value is stored inside the cache directory and applies +to all future compiles. Due to the way the value is stored the actual +value used is always rounded down to the nearest multiple of 16. +

      +

      -M <maxsize>
      This sets the maximum cache size. You can specify +a value in gigabytes, megabytes or kilobytes by appending a G, M or K +to the value. The default is gigabytes. The actual value stored is +rounded down to the nearest multiple of 16 kilobytes. +

      +

      +

      +

      16.6 INSTALLATION

      + + +

      +There are two ways to use ccache. You can either prefix your compile +commands with "ccache-swig" or you can create a symbolic link between +ccache-swig and the names of your compilers. The first method is most +convenient if you just want to try out ccache or wish to use it for +some specific projects. The second method is most useful for when you +wish to use ccache for all your compiles. +

      +To install for usage by the first method just copy ccache-swig to somewhere +in your path. +

      +To install for the second method do something like this: +

      +
+  cp ccache-swig /usr/local/bin/
+  ln -s /usr/local/bin/ccache-swig /usr/local/bin/gcc
+  ln -s /usr/local/bin/ccache-swig /usr/local/bin/g++
+  ln -s /usr/local/bin/ccache-swig /usr/local/bin/cc
+  ln -s /usr/local/bin/ccache-swig /usr/local/bin/swig
+
+
      + +This will work as long as /usr/local/bin comes before the path to gcc +(which is usually in /usr/bin). After installing you may wish to run +"which gcc" to make sure that the correct link is being used. +

      +Note! Do not use a hard link, use a symbolic link. A hardlink will +cause "interesting" problems. +

      +

      16.7 EXTRA OPTIONS

      + + +

      +When run as a compiler front end ccache usually just takes the same +command line options as the compiler you are using. The only exception +to this is the option '--ccache-skip'. That option can be used to tell +ccache that the next option is definitely not a input filename, and +should be passed along to the compiler as-is. +

      +The reason this can be important is that ccache does need to parse the +command line and determine what is an input filename and what is a +compiler option, as it needs the input filename to determine the name +of the resulting object file (among other things). The heuristic +ccache uses in this parse is that any string on the command line that +exists as a file is treated as an input file name (usually a C +file). By using --ccache-skip you can force an option to not be +treated as an input file name and instead be passed along to the +compiler as a command line option. +

      +

      16.8 ENVIRONMENT VARIABLES

      + + +

      +ccache uses a number of environment variables to control operation. In +most cases you won't need any of these as the defaults will be fine. +

      +

      +

      +

      CCACHE_DIR
      the CCACHE_DIR environment variable specifies +where ccache will keep its cached compiler output. The default is +"$HOME/.ccache". +

      +

      CCACHE_TEMPDIR
      the CCACHE_TEMPDIR environment variable specifies +where ccache will put temporary files. The default is the same as +CCACHE_DIR. Note that the CCACHE_TEMPDIR path must be on the same +filesystem as the CCACHE_DIR path, so that renames of files between +the two directories can work. +

      +

      CCACHE_LOGFILE
      If you set the CCACHE_LOGFILE environment +variable then ccache will write some log information on cache hits +and misses in that file. This is useful for tracking down problems. +

      +

      CCACHE_VERBOSE
      If you set the CCACHE_VERBOSE environment +variable then ccache will display on stdout all the compiler invocations +that it makes. This can useful for debugging unexpected problems. +

      +

      CCACHE_PATH
      You can optionally set CCACHE_PATH to a colon +separated path where ccache will look for the real compilers. If you +don't do this then ccache will look for the first executable matching +the compiler name in the normal PATH that isn't a symbolic link to +ccache itself. +

      +

      CCACHE_CC
      You can optionally set CCACHE_CC to force the name +of the compiler to use. If you don't do this then ccache works it out +from the command line. +

      +

      CCACHE_PREFIX
      This option adds a prefix to the command line +that ccache runs when invoking the compiler. Also see the section +below on using ccache with distcc. +

      +

      CCACHE_DISABLE
      If you set the environment variable +CCACHE_DISABLE then ccache will just call the real compiler, +bypassing the cache completely. +

      +

      CCACHE_READONLY
      the CCACHE_READONLY environment variable +tells ccache to attempt to use existing cached object files, but not +to try to add anything new to the cache. If you are using this because +your CCACHE_DIR is read-only, then you may find that you also need to +set CCACHE_TEMPDIR as otherwise ccache will fail to create the +temporary files. +

      +

      CCACHE_CPP2
      If you set the environment variable CCACHE_CPP2 +then ccache will not use the optimisation of avoiding the 2nd call to +the pre-processor by compiling the pre-processed output that was used +for finding the hash in the case of a cache miss. This is primarily a +debugging option, although it is possible that some unusual compilers +will have problems with the intermediate filename extensions used in +this optimisation, in which case this option could allow ccache to be +used. +

      +

      CCACHE_NOCOMPRESS
      If you set the environment variable +CCACHE_NOCOMPRESS then there is no compression used on files that go +into the cache. However, this setting has no effect on how files are +retrieved from the cache, compressed results will still be usable. +

      +

      CCACHE_NOSTATS
      If you set the environment variable +CCACHE_NOSTATS then ccache will not update the statistics files on +each compile. +

      +

      CCACHE_NLEVELS
      The environment variable CCACHE_NLEVELS allows +you to choose the number of levels of hash in the cache directory. The +default is 2. The minimum is 1 and the maximum is 8. +

      +

      CCACHE_HARDLINK
      If you set the environment variable +CCACHE_HARDLINK then ccache will attempt to use hard links from the +cache directory when creating the compiler output rather than using a +file copy. Using hard links is faster, but can confuse programs like +'make' that rely on modification times. Hard links are never made for +compressed cache files. +

      +

      CCACHE_RECACHE
      This forces ccache to not use any cached +results, even if it finds them. New results are still cached, but +existing cache entries are ignored. +

      +

      CCACHE_UMASK
      This sets the umask for ccache and all child +processes (such as the compiler). This is mostly useful when you wish +to share your cache with other users. Note that this also affects the +file permissions set on the object files created from your +compilations. +

      +

      CCACHE_HASHDIR
      This tells ccache to hash the current working +directory when calculating the hash that is used to distinguish two +compiles. This prevents a problem with the storage of the current +working directory in the debug info of a object file, which can lead +ccache to give a cached object file that has the working directory in +the debug info set incorrectly. This option is off by default as the +incorrect setting of this debug info rarely causes problems. If you +strike problems with gdb not using the correct directory then enable +this option. +

      +

      CCACHE_UNIFY
      If you set the environment variable CCACHE_UNIFY +then ccache will use the C/C++ unifier when hashing the pre-processor +output if -g is not used in the compile. The unifier is slower than a +normal hash, so setting this environment variable loses a little bit +of speed, but it means that ccache can take advantage of not +recompiling when the changes to the source code consist of +reformatting only. Note that using CCACHE_UNIFY changes the hash, so +cached compiles with CCACHE_UNIFY set cannot be used when +CCACHE_UNIFY is not set and vice versa. The reason the unifier is off +by default is that it can give incorrect line number information in +compiler warning messages. +

      +

      CCACHE_EXTENSION
      Normally ccache tries to automatically +determine the extension to use for intermediate C pre-processor files +based on the type of file being compiled. Unfortunately this sometimes +doesn't work, for example when using the aCC compiler on HP-UX. On +systems like this you can use the CCACHE_EXTENSION option to override +the default. On HP-UX set this environment variable to "i" if you use +the aCC compiler. +

      +

      CCACHE_STRIPC
      If you set the environment variable +CCACHE_STRIPC then ccache will strip the -c option when invoking +the preprocessor. This option is primarily for the Sun Workshop +C++ compiler as without this option an unwarranted warning is displayed: +CC: Warning: "-E" redefines product from "object" to "source (stdout)" +when -E and -c is used together. +

      +

      CCACHE_SWIG
      When using SWIG as the compiler and it does not +have 'swig' in the executable name, then the CCACHE_SWIG environment +variable needs to be set in order for ccache to work correctly with +SWIG. The use of CCACHE_CPP2 is also recommended for SWIG due to some +preprocessor quirks, however, use of CCACHE_CPP2 can often be skipped +-- check your generated code with and without this option set. Known +problems are using preprocessor directives within %inline blocks and +the use of '#pragma SWIG'. +

      +

      +

      +

      16.9 CACHE SIZE MANAGEMENT

      + + +

      +By default ccache has a one gigabyte limit on the cache size and no +maximum number of files. You can set a different limit using the +"ccache -M" and "ccache -F" options, which set the size and number of +files limits. +

      +When these limits are reached ccache will reduce the cache to 20% +below the numbers you specified in order to avoid doing the cache +clean operation too often. +

      +

      16.10 CACHE COMPRESSION

      + + +

      +By default on most platforms ccache will compress all files it puts +into the cache +using the zlib compression. While this involves a negligible +performance slowdown, it significantly increases the number of files +that fit in the cache. You can turn off compression setting the +CCACHE_NOCOMPRESS environment variable. +

      +

      16.11 HOW IT WORKS

      + + +

      +The basic idea is to detect when you are compiling exactly the same +code a 2nd time and use the previously compiled output. You detect +that it is the same code by forming a hash of: +

      +

        +
      • the pre-processor output from running the compiler with -E +
      • the command line options +
      • the real compilers size and modification time +
      • any stderr output generated by the compiler +
      +

      +These are hashed using md4 (a strong hash) and a cache file is formed +based on that hash result. When the same compilation is done a second +time ccache is able to supply the correct compiler output (including +all warnings etc) from the cache. +

      +ccache has been carefully written to always produce exactly the same +compiler output that you would get without the cache. If you ever +discover a case where ccache changes the output of your compiler then +please let me know. +

      +

      16.12 USING CCACHE WITH DISTCC

      + + +

      +distcc is a very useful program for distributing compilation across a +range of compiler servers. It is often useful to combine distcc with +ccache, so that compiles that are done are sped up by distcc, but that +ccache avoids the compile completely where possible. +

      +To use distcc with ccache I recommend using the CCACHE_PREFIX +option. You just need to set the environment variable CCACHE_PREFIX to +'distcc' and ccache will prefix the command line used with the +compiler with the command 'distcc'. +

      +

      16.13 SHARING A CACHE

      + + +

      +A group of developers can increase the cache hit rate by sharing a +cache directory. The hard links however cause unwanted side effects, +as all links to a cached file share the file's modification timestamp. +This results in false dependencies to be triggered by timestamp-based +build systems whenever another user links to an existing +file. Typically, users will see that their libraries and binaries are +relinked without reason. To share a cache without side effects, the +following conditions need to be met: +

      +

        +
      • Use the same CCACHE_DIR environment variable setting +
      • Unset the CCACHE_HARDLINK environment variable +
      • Make sure everyone sets the CCACHE_UMASK environment variable + to 002, this ensures that cached files are accessible to everyone in + the group. +
      • Make sure that all users have write permission in the entire + cache directory (and that you trust all users of the shared cache). +
      • Make sure that the setgid bit is set on all directories in the + cache. This tells the filesystem to inherit group ownership for new + directories. The command "chmod g+s `find $CCACHE_DIR -type d`" might + be useful for this. +
      • Set CCACHE_NOCOMPRESS for all users, if there are users with + versions of ccache that do not support compression. +
      +

      +

      16.14 HISTORY

      + + +

      +ccache was inspired by the compilercache shell script script written +by Erik Thiele and I would like to thank him for an excellent piece of +work. See +http://www.erikyyy.de/compilercache/ +for the Erik's scripts. +ccache-swig is a port of the original ccache with support added for use +with SWIG. +

      +I wrote ccache because I wanted to get a bit more speed out of a +compiler cache and I wanted to remove some of the limitations of the +shell-script version. +

      +

      16.15 DIFFERENCES FROM COMPILERCACHE

      + + +

      +The biggest differences between Erik's compilercache script and ccache +are: +

        +
      • ccache is written in C, which makes it a bit faster (calling out to + external programs is mostly what slowed down the scripts). +
      • ccache can automatically find the real compiler +
      • ccache keeps statistics on hits/misses +
      • ccache can do automatic cache management +
      • ccache can cache compiler output that includes warnings. In many + cases this gives ccache a much higher cache hit rate. +
      • ccache can handle a much wider ranger of compiler options +
      • ccache avoids a double call to cpp on a cache miss +
      +

      +

      16.16 CREDITS

      + + +

      +Thanks to the following people for their contributions to ccache +

        +
      • Erik Thiele for the original compilercache script +
      • Luciano Rocha for the idea of compiling the pre-processor output + to avoid a 2nd cpp pass +
      • Paul Russell for many suggestions and the debian packaging +
      +

      +

      16.17 AUTHOR

      + + +

      +ccache was written by Andrew Tridgell +http://samba.org/~tridge/. +ccache was adapted to create ccache-swig for use with SWIG by William Fulton. +

      +If you wish to report a problem or make a suggestion then please email +the SWIG developers on the swig-devel mailing list, see +http://www.swig.org/mail.html +

      +ccache is released under the GNU General Public License version 2 or +later. Please see the file COPYING for license details. +

      + + + + + + diff --git a/Doc/Manual/CSharp.html b/Doc/Manual/CSharp.html new file mode 100644 index 0000000..f747fc2 --- /dev/null +++ b/Doc/Manual/CSharp.html @@ -0,0 +1,2360 @@ + + + +SWIG and C# + + + +

      18 SWIG and C#

      + +
      + +
      + + + + +

      18.1 Introduction

      + + +

      +The purpose of the C# module is to offer an automated way of accessing existing C/C++ code from .NET languages. +The wrapper code implementation uses C# and the Platform Invoke (PInvoke) interface to access natively compiled C/C++ code. +The PInvoke interface has been chosen over Microsoft's Managed C++ interface as it is portable to both Microsoft Windows and non-Microsoft platforms. +PInvoke is part of the ECMA/ISO C# specification. +It is also better suited for robust production environments due to the Managed C++ flaw called the +Mixed DLL Loading Problem. +Swig C# works equally well on non-Microsoft operating systems such as Linux, Solaris and Apple Mac using +Mono and Portable.NET. +

      + +

      +To get the most out of this chapter an understanding of interop is required. +The Microsoft Developer Network (MSDN) has a good reference guide in a section titled "Interop Marshaling". +Monodoc, available from the Mono project, has a very useful section titled Interop with native libraries. +

      + +

      18.2 Differences to the Java module

      + + +

      +The C# module is very similar to the Java module, so until some more complete documentation has been written, +please use the Java documentation as a guide to using SWIG with C#. +The C# module has the same major SWIG features as the Java module. +The rest of this section should be read in conjunction with the Java documentation as it lists the main differences. + +The most notable differences to Java are the following: +

        + +
      • +When invoking SWIG use the -csharp command line option instead of -java. +
        • + +
      • +The -nopgcpp command line option does not exist. +
        • + +
      • +The -package command line option does not exist. +
        • + +
      • +The -namespace <name> commandline option will generate all code into the namespace specified by <name>. +C# supports nested namespaces that are not lexically nested, so nested namespaces will of course also work. For example: +-namespace com.bloggs.widget, will generate code into C# namespaces: + +
        +namespace com.bloggs.widget {
+  ...
+}
+
        +Note that by default, the generated C# classes have no namespace and the module name is unrelated to namespaces. The module name is just like in Java and is merely used to name some of the generated classes. +
        • + +
      • +The -dllimport <name> commandline option specifies the name of the DLL for the DllImport attribute for every PInvoke method. If this commandline option is not given, the DllImport DLL name is the same as the module name. This option is useful for when one wants to invoke SWIG multiple times on different modules, yet compile all the resulting code into a single DLL. +
        • + +
      • +C/C++ variables are wrapped with C# properties and not JavaBean style getters and setters. +
        • + +
      • +Global constants are generated into the module class. There is no constants interface. +
        • + +
      • +There is no implementation for type unsafe enums - not deemed necessary. +
        • + +
      • +The default enum wrapping approach is proper C# enums, not typesafe enums. +
        +Note that %csconst(0) will be ignored when wrapping C/C++ enums with proper C# enums. +This is because C# enum items must be initialised from a compile time constant. +If an enum item has an initialiser and the initialiser doesn't compile as C# code, +then the %csconstvalue directive must be used as %csconst(0) will have no effect. +If it was used, it would generate an illegal runtime initialisation via a PInvoke call. +
        • + +
      • +C# doesn't support the notion of throws clauses. +Therefore there is no 'throws' typemap attribute support for adding exception classes to a throws clause. +Likewise there is no need for an equivalent to %javaexception. +In fact, throwing C# exceptions works quite differently, see C# Exceptions below. +
        • + +
      • +The majority of the typemaps are in csharp.swg, not java.swg. +
        • + +
      • +

        Typemap equivalent names:

        + +
        +jni                         -> ctype
+jtype                       -> imtype
+jstype                      -> cstype
+javain                      -> csin
+javaout                     -> csout
+javadirectorin              -> csdirectorin
+javadirectorout             -> csdirectorout
+javainterfaces              -> csinterfaces and csinterfaces_derived
+javabase                    -> csbase
+javaclassmodifiers          -> csclassmodifiers
+javacode                    -> cscode
+javaimports                 -> csimports
+javabody                    -> csbody
+javafinalize                -> csfinalize
+javadestruct                -> csdestruct
+javadestruct_derived        -> csdestruct_derived
+
        + +
        • + +
      • +

        Additional typemaps:

        + +
        +csvarin                     C# code property set typemap
+csvarout                    C# code property get typemap
+csattributes                C# attributes for attaching to proxy classes/enums
+
        + +
        • + +
      • +

        Feature equivalent names:

        +
        +%javaconst                  -> %csconst
+%javaconstvalue             -> %csconstvalue
+%javamethodmodifiers        -> %csmethodmodifiers
+
        +
        • + +
      • +

        Pragma equivalent names:

        +
        +%pragma(java)               -> %pragma(csharp)
+jniclassbase                -> imclassbase
+jniclassclassmodifiers      -> imclassclassmodifiers
+jniclasscode                -> imclasscode
+jniclassimports             -> imclassimports
+jniclassinterfaces          -> imclassinterfaces
+
        +
        • + +
      • +

        Special variable equivalent names:

        +
        +$javaclassname              -> $csclassname
+$&javaclassname             -> $&csclassname
+$*javaclassname             -> $*csclassname
+$javainput                  -> $csinput
+$jnicall                    -> $imcall
+
        +
        • + +
      • +

        +Unlike the "javain" typemap, the "csin" typemap does not support the 'pgcpp' attribute as the C# module does not have a premature garbage collection prevention parameter. +The "csin" typemap supports additional optional attributes called 'cshin' and 'terminator'. +The 'cshin' attribute should contain the parameter type and name whenever a constructor helper function is generated due to the 'pre' or 'post' attributes. +The 'terminator' attribute normally just contains a closing brace for when the 'pre' attribute contains an opening brace, such as when a C# using or fixed block is started. +Note that 'pre', 'post', 'terminator' and 'cshin' attributes are not used for marshalling the property set. +Please see the Date marshalling example and Date marshalling of properties example for further understanding of these "csin" applicable attributes. +

        +
        • + +
      • +

        +Support for asymmetric type marshalling. The 'ctype', 'imtype' and 'cstype' typemaps support an optional out attribute which is used for output types. +If this typemap attribute is specified, then the type specified in the attribute is used for output types and +the type specified in the typemap itself is used for the input type. +If this typemap attribute is not specified, then the type used for both input and output is the type specified in the typemap. +An example shows that char * could be marshalled in different ways, +

        + +
        +
        +%typemap(imtype, out="IntPtr") char * "string"
+char * function(char *);
+
        +
        + +

        +The output type is thus IntPtr and the input type is string. The resulting intermediary C# code is: +

        + +
        +
        +public static extern IntPtr function(string jarg1);
+
        +
        + +
        • + +
      • +

        +Support for type attributes. +The 'imtype' and 'cstype' typemaps can have an optional inattributes and outattributes typemap attribute. +There are C# attributes and typemap attributes, don't get confused!! +The C# attributes specified in these typemap attributes are generated wherever the type is used in the C# wrappers. +These can be used to specify any C# attribute associated with a C/C++ type, but are more typically used for the C# MarshalAs attribute. +For example: +

        + +
        +
        +%typemap(imtype,
+         inattributes="[MarshalAs(UnmanagedType.LPStr)]",
+         outattributes="[return: MarshalAs(UnmanagedType.LPStr)]") const char * "String"
+
+const char * GetMsg() {}
+void SetMsg(const char *msg) {}
+
        +
        + +

        +The intermediary class will then have the marshalling as specified by everything in the 'imtype' typemap: +

        + +
        +
        +class examplePINVOKE {
+  ...
+  [DllImport("example", EntryPoint="CSharp_GetMsg")]
+  [return: MarshalAs(UnmanagedType.LPStr)]
+  public static extern String GetMsg();
+
+  [DllImport("example", EntryPoint="CSharp_SetMsg")]
+  public static extern void SetMsg([MarshalAs(UnmanagedType.LPStr)]String jarg1);
+}
+
        +
        + +

        +Note that the DllImport attribute is always generated, irrespective of any additional attributes specified. +

        + +

        +These attributes are associated with the C/C++ parameter type or return type, which is subtly different to +the attribute features and typemaps covered next. +Note that all these different C# attributes can be combined so that a method has more than one attribute. +

        +
        • + +
      • +

        +Support for attaching C# attributes to wrapped methods and variables. +This is done using the %csattributes feature, see %feature directives. +Note that C# attributes are attached to proxy classes and enums using the csattributes typemap. +For example, imagine we have a custom attribute class, ThreadSafeAttribute, for labelling thread safety. +The following SWIG code shows how to attach this C# attribute to some methods and the class declaration itself: +

        + +
        +
        +%typemap(csattributes) AClass          "[ThreadSafe]"
+%csattributes AClass::AClass(double d) "[ThreadSafe(false)]"
+%csattributes AClass::AMethod()        "[ThreadSafe(true)]"
+
+%inline %{
+class AClass {
+public:
+  AClass(double a) {}
+  void AMethod() {}
+};
+%}
+
        +
        + +

        +will generate a C# proxy class: +

        + +
        +
        +[ThreadSafe]
+public class AClass : IDisposable {
+  ...
+  [ThreadSafe(false)]
+  public AClass(double a) ...
+
+  [ThreadSafe(true)]
+  public void AMethod() ...
+}
+
        +
        + +

        +If C# attributes need adding to the set or get part of C# properties, when wrapping C/C++ variables, +they can be added using the 'csvarin' and 'csvarout' typemaps respectively. +Note that the type used for the property is specified in the 'cstype' typemap. +If the 'out' attribute exists in this typemap, then the type used is from the 'out' attribute. +

        +
        • + +
      • +

        +The intermediary classname has PINVOKE appended after the module name instead of JNI, for example modulenamePINVOKE. +

        +
        • + +
      • +

        +The %csmethodmodifiers feature can also be applied to variables as well as methods. +In addition to the default public modifier that SWIG generates when %csmethodmodifiers is not +specified, the feature will also replace the virtual/new/override modifiers that SWIG thinks is appropriate. +This feature is useful for some obscure cases where SWIG might get the virtual/new/override modifiers incorrect, for example with multiple inheritance. +

        +
        • + +
      • + +

        +The name of the intermediary class can be changed from its default, that is, the module name with PINVOKE appended after it. +The module directive attribute imclassname is used to achieve this: +

        + +
        +
        +%module (imclassname="name") modulename
+
        +
        + +

        +If name is the same as modulename then the module class name gets changed +from modulename to modulenameModule. +

        +
        • + +
      • +There is no additional 'premature garbage collection prevention parameter' as the marshalling of the HandleRef object +takes care of ensuring a reference to the proxy class is held until the unmanaged call completed. +
        • + +
      + +

      +$dllimport
      +This is a C# only special variable that can be used in typemaps, pragmas, features etc. +The special variable will get translated into the value specified by the -dllimport commandline option +if specified, otherwise it is equivalent to the $module special variable. +

      + +

      +$imclassname
      +This special variable expands to the intermediary class name. For C# this is usually the same as '$modulePINVOKE' ('$moduleJNI' for Java), +unless the imclassname attribute is specified in the %module directive. +

      + +

      +The directory Examples/csharp has a number of simple examples. +Visual Studio .NET 2003 solution and project files are available for compiling with the Microsoft .NET C# compiler on Windows. +If your SWIG installation went well on a Unix environment and your C# compiler was detected, you should be able to type make in each example directory, +then ilrun runme.exe (Portable.NET C# compiler) or mono runme.exe (Mono C# compiler) to run the examples. +Windows users can also get the examples working using a +Cygwin or MinGW environment for automatic configuration of the example makefiles. +Any one of the three C# compilers (Portable.NET, Mono or Microsoft) can be detected from within a Cygwin or Mingw environment if installed in your path. + +

      18.3 C# Arrays

      + + +

      +There are various ways to pass arrays from C# to C/C++. +The default wrapping treats arrays as pointers and as such simple type wrapper classes are generated, +eg SWIGTYPE_p_int when wrapping the C type int [] or int *. +This gives a rather restricted use of the underlying unmanaged code and the most practical way to use arrays is to enhance or customise +with one of the following three approaches; namely the SWIG C arrays library, P/Invoke default array marshalling or +pinned arrays. +

      + +

      18.3.1 The SWIG C arrays library

      + + +

      +The C arrays library keeps all the array memory in the unmanaged layer. +The library is available to all language modules and is documented in the carrays.i library section. +Please refer to this section for details, but for convenience, the C# usage for the two examples outlined there is shown below. +

      + +

      +For the %array_functions example, the equivalent usage would be: +

      + +
      +
      +SWIGTYPE_p_double a = example.new_doubleArray(10);  // Create an array
+for (int i=0; i<10; i++)
+  example.doubleArray_setitem(a,i,2*i);             // Set a value
+example.print_array(a);                             // Pass to C
+example.delete_doubleArray(a);                      // Destroy array
+
      +
      + +

      +and for the %array_class example, the equivalent usage would be: +

      + +
      +
      +doubleArray c = new doubleArray(10);    // Create double[10]
+for (int i=0; i<10; i++)
+  c.setitem(i, 2*i);                    // Assign values
+example.print_array(c.cast());          // Pass to C
+
      +
      + + +

      18.3.2 Managed arrays using P/Invoke default array marshalling

      + + +

      +In the P/Invoke default marshalling scheme, one needs to designate whether the invoked function will treat a managed +array parameter as input, output, or both. When the function is invoked, the CLR allocates a separate chunk of memory as big as the given managed array, +which is automatically released at the end of the function call. If the array parameter is marked as being input, the content of the managed array is copied +into this buffer when the call is made. Correspondingly, if the array parameter is marked as being output, the contents of the reserved buffer are copied +back into the managed array after the call returns. A pointer to to this buffer +is passed to the native function. +

      + +

      +The reason for allocating a separate buffer is to leave the CLR free to relocate the managed array object +during garbage collection. If the overhead caused by the copying is causing a significant performance penalty, consider pinning the managed array and +passing a direct reference as described in the next section. +

      + +

      +For more information on the subject, see the +Default Marshaling for Arrays article +on MSDN. +

      + + +

      +The P/Invoke default marshalling is supported by the arrays_csharp.i library via the INPUT, OUTPUT and INOUT typemaps. +Let's look at some example usage. Consider the following C function: +

      +
      +
      +void myArrayCopy(int *sourceArray, int *targetArray, int nitems);
+
      +
      + +

      +We can now instruct SWIG to use the default marshalling typemaps by +

      + +
      +
      +%include "arrays_csharp.i"
+
+%apply int INPUT[]  {int *sourceArray}
+%apply int OUTPUT[] {int *targetArray}
+
      +
      + +

      +As a result, we get the following method in the module class: +

      + +
      +
      +public static void myArrayCopy(int[] sourceArray, int[] targetArray, int nitems) {
+    examplePINVOKE.myArrayCopy(sourceArray, targetArray, nitems);
+}
+
      +
      + +

      +If we look beneath the surface at the corresponding intermediary class code, we see +that SWIG has generated code that uses attributes +(from the System.Runtime.InteropServices namespace) to tell the CLR to use default +marshalling for the arrays: +

      + +
      +
      +[DllImport("example", EntryPoint="CSharp_myArrayCopy")]
+public static extern void myArrayCopy([In, MarshalAs(UnmanagedType.LPArray)]int[] jarg1, 
+                                      [Out, MarshalAs(UnmanagedType.LPArray)]int[] jarg2, int jarg3);
+
      +
      + +

      +As an example of passing an inout array (i.e. the target function will both read from and +write to the array), consider this C function that swaps a given number of elements +in the given arrays: +

      + +
      +
      +void myArraySwap(int *array1, int *array2, int nitems);
+
      +
      + +

      +Now, we can instruct SWIG to wrap this by +

      + +
      +
      +%include "arrays_csharp.i"
+
+%apply int INOUT[] {int *array1}
+%apply int INOUT[] {int *array2}
+
      +
      + +

      +This results in the module class method +

      + +
      +
      +  public static void myArraySwap(int[] array1, int[] array2, int nitems) {
+    examplePINVOKE.myArraySwap(array1, array2, nitems);
+  }
+
      +
      + +

      +and intermediate class method +

      + +
      +
      +  [DllImport("example", EntryPoint="CSharp_myArraySwap")]
+  public static extern void myArraySwap([In, Out, MarshalAs(UnmanagedType.LPArray)]int[] jarg1, 
+                                        [In, Out, MarshalAs(UnmanagedType.LPArray)]int[] jarg2, int jarg3);
+
      +
      + + +

      18.3.3 Managed arrays using pinning

      + + +

      +It is also possible to pin a given array in memory (i.e. fix its location in memory), obtain a +direct pointer to it, and then pass this pointer to the wrapped C/C++ function. This approach +involves no copying, but it makes the work of the garbage collector harder as +the managed array object can not be relocated before the fix on the array is released. You should avoid +fixing arrays in memory in cases where the control may re-enter the managed side via a callback and/or +another thread may produce enough garbage to trigger garbage collection. +

      + +

      +For more information, see the fixed statement in the C# language reference. +

      + + +

      +Now let's look at an example using pinning, thus avoiding the CLR making copies +of the arrays passed as parameters. The arrays_csharp.i library file again provides the required support via the FIXED typemaps. +Let's use the same function from the previous section: +

      + +
      +
      +void myArrayCopy(int *sourceArray, int *targetArray, int nitems);
+
      +
      + +

      +We now need to declare the module class method unsafe, as we are using pointers: +

      + +
      +
      +%csmethodmodifiers myArrayCopy "public unsafe";
+
      +
      + +

      +Apply the appropriate typemaps to the array parameters: +

      + +
      +
      +%include "arrays_csharp.i"
+
+%apply int FIXED[] {int *sourceArray}
+%apply int FIXED[] {int *targetArray}
+
      +
      + +

      +Notice that there is no need for separate in, out or inout typemaps as is the +case when using P/Invoke default marshalling. +

      + +

      +As a result, we get the following method in the module class: +

      + +
      +
      +  public unsafe static void myArrayCopy(int[] sourceArray, int[] targetArray, int nitems) {
+    fixed ( int *swig_ptrTo_sourceArray = sourceArray ) {
+    fixed ( int *swig_ptrTo_targetArray = targetArray ) {
+    {
+      examplePINVOKE.myArrayCopy((IntPtr)swig_ptrTo_sourceArray, (IntPtr)swig_ptrTo_targetArray, nitems);
+    }
+    }
+    }
+  }
+
      +
      + +

      +On the method signature level the only difference to the version using P/Invoke default +marshalling is the "unsafe" quantifier, which is required because we are handling pointers. +

      + +

      +Also the intermediate class method looks a little different from the default marshalling +example - the method is expecting an IntPtr as the parameter type. +

      + +
      +
      +[DllImport("example", EntryPoint="CSharp_myArrayCopy")]
+public static extern void myArrayCopy(IntPtr jarg1, IntPtr jarg2, int jarg3);
+
      +
      + + + +

      18.4 C# Exceptions

      + + +

      +It is possible to throw a C# Exception from C/C++ code. +SWIG already provides the framework for throwing C# exceptions if it is able to detect that a C++ exception could be thrown. +Automatically detecting that a C++ exception could be thrown is only possible when a C++ exception specification is used, +see Exception specifications. +The Exception handling with %exception section details the %exception feature. +Customised code for handling exceptions with or without a C++ exception specification is possible and the details follow. +However anyone wishing to do this should be familiar with the contents of the sections referred to above. +

      + +

      +Unfortunately a C# exception cannot simply be thrown from unmanaged code for a variety of reasons. +Most notably being that throwing a C# exception results in exceptions being thrown across the C PInvoke interface and C does not understand exceptions. +The design revolves around a C# exception being constructed and stored as a pending exception, to be thrown only when the unmanaged code has completed. +Implementing this is a tad involved and there are thus some unusual typemap constructs. +Some practical examples follow and they should be read in conjunction with the rest of this section. +

      + +

      +First some details about the design that must be followed. +Each typemap or feature that generates unmanaged code supports an attribute called canthrow. +This is simply a flag which when set indicates that the code in the typemap/feature has code which might want to throw a C# exception. +The code in the typemap/feature can then raise a C# exception by calling one of the C functions, +SWIG_CSharpSetPendingException() or SWIG_CSharpSetPendingExceptionArgument(). +When called, the function makes a callback into the managed world via a delegate. +The callback creates and stores an exception ready for throwing when the unmanaged code has finished. +The typemap/feature unmanaged code is then expected to force an immediate return from the unmanaged wrapper function, +so that the pending managed exception can then be thrown. +The support code has been carefully designed to be efficient as well as thread-safe. +However to achieve the goal of efficiency requires some optional code generation in the managed code typemaps. +Code to check for pending exceptions is generated if and only if the unmanaged code has code to set a pending exception, +that is if the canthrow attribute is set. +The optional managed code is generated using the excode typemap attribute and $excode special variable in the relevant managed code typemaps. +Simply, if any relevant unmanaged code has the canthrow attribute set, then any occurrences of $excode +is replaced with the code in the excode attribute. +If the canthrow attribute is not set, then any occurrences of $excode are replaced with nothing. +

      + +

      +The prototypes for the SWIG_CSharpSetPendingException() and SWIG_CSharpSetPendingExceptionArgument() functions are +

      + +
      +
      +static void SWIG_CSharpSetPendingException(SWIG_CSharpExceptionCodes code,
+                                           const char *msg);
+
+static void SWIG_CSharpSetPendingExceptionArgument(SWIG_CSharpExceptionArgumentCodes code,
+                                                   const char *msg,
+                                                   const char *param_name);
+
      +
      + +

      +The first parameter defines which .NET exceptions can be thrown: +

      + +
      +
      +typedef enum {
+  SWIG_CSharpApplicationException,
+  SWIG_CSharpArithmeticException,
+  SWIG_CSharpDivideByZeroException,
+  SWIG_CSharpIndexOutOfRangeException,
+  SWIG_CSharpInvalidCastException,
+  SWIG_CSharpInvalidOperationException,
+  SWIG_CSharpIOException,
+  SWIG_CSharpNullReferenceException,
+  SWIG_CSharpOutOfMemoryException,
+  SWIG_CSharpOverflowException,
+  SWIG_CSharpSystemException
+} SWIG_CSharpExceptionCodes;
+
+typedef enum {
+  SWIG_CSharpArgumentException,
+  SWIG_CSharpArgumentNullException,
+  SWIG_CSharpArgumentOutOfRangeException,
+} SWIG_CSharpExceptionArgumentCodes;
+
      +
      + +

      +where, for example, SWIG_CSharpApplicationException corresponds to the .NET exception, ApplicationException. +The msg and param_name parameters contain the C# exception message and parameter name associated with the exception. +

      + + +

      +The %exception feature in C# has the canthrow attribute set. +The %csnothrowexception feature is like %exception, but it does not have the canthrow attribute +set so should only be used when a C# exception is not created. +

      + + +

      18.4.1 C# exception example using "check" typemap

      + + +

      +Lets say we have the following simple C++ method: +

      + + +
      +
      +void positivesonly(int number);
+
      +
      + +

      +and we want to check that the input number is always positive and if not throw a C# ArgumentOutOfRangeException. +The "check" typemap is designed for checking input parameters. Below you will see the canthrow attribute is set because +the code contains a call to SWIG_CSharpSetPendingExceptionArgument(). The full example follows: +

      + +
      +
      +%module example
+
+%typemap(check, canthrow=1) int number %{
+if ($1 < 0) {
+  SWIG_CSharpSetPendingExceptionArgument(SWIG_CSharpArgumentOutOfRangeException,
+                                         "only positive numbers accepted", "number");
+  return $null;
+}
+// SWIGEXCODE is a macro used by many other csout typemaps
+%define SWIGEXCODE
+ "\n    if ($modulePINVOKE.SWIGPendingException.Pending)"
+ "\n      throw $modulePINVOKE.SWIGPendingException.Retrieve();"
+%enddef
+%typemap(csout, excode=SWIGEXCODE) void {
+    $imcall;$excode
+  }
+%}
+
+%inline %{
+
+void positivesonly(int number) {
+}
+
+%}
+
      +
      + +

      +When the following C# code is executed: +

      + +
      +
      +public class runme {
+    static void Main() {
+      example.positivesonly(-1);
+    }
+}
+
      +
      + +

      +The exception is thrown: +

      + +
      +
      +Unhandled Exception: System.ArgumentOutOfRangeException: only positive numbers accepted
+Parameter name: number
+in <0x00034> example:positivesonly (int)
+in <0x0000c> runme:Main ()
+
      +
      + +

      +Now let's analyse the generated code to gain a fuller understanding of the typemaps. The generated unmanaged C++ code is: +

      + + +
      +
      +SWIGEXPORT void SWIGSTDCALL CSharp_positivesonly(int jarg1) {
+    int arg1 ;
+    
+    arg1 = (int)jarg1; 
+    
+    if (arg1 < 0) {
+        SWIG_CSharpSetPendingExceptionArgument(SWIG_CSharpArgumentOutOfRangeException,
+                                               "only positive numbers accepted", "number");
+        return ;
+    }
+    
+    positivesonly(arg1);
+    
+}
+
      +
      + +

      +This largely comes from the "check" typemap. The managed code in the module class is: +

      + +
      +
      +public class example {
+  public static void positivesonly(int number) {
+    examplePINVOKE.positivesonly(number);
+    if (examplePINVOKE.SWIGPendingException.Pending)
+      throw examplePINVOKE.SWIGPendingException.Retrieve();
+  }
+
+}
+
      +
      + +

      +This comes largely from the "csout" typemap. +

      + +

      +The "csout" typemap is the same as the default void "csout" typemap so is not strictly necessary for the example. +However, it is shown to demonstrate what managed output code typemaps should contain, +that is, a $excode special variable and an excode attribute. +Also note that $excode is expanded into the code held in the excode attribute. +The $imcall as always expands into examplePINVOKE.positivesonly(number). +The exception support code in the intermediary class, examplePINVOKE, is not shown, but is contained within the inner classes, +SWIGPendingException and SWIGExceptionHelper and is always generated. +These classes can be seen in any of the generated wrappers. +However, all that is required of a user is as demonstrated in the "csin" typemap above. +That is, is to check SWIGPendingException.Pending and to throw the exception returned by SWIGPendingException.Retrieve(). +

      + +

      +If the "check" typemap did not exist, then +the following module class would instead be generated: +

      + +
      +
      +public class example {
+  public static void positivesonly(int number) {
+    examplePINVOKE.positivesonly(number);
+  }
+
+}
+
      +
      + +

      +Here we see the pending exception checking code is omitted. +In fact, the code above would be generated if the canthrow attribute was not in the "check" typemap, such as: +

      + +
      +
      +%typemap(check) int number %{
+if ($1 < 0) {
+  SWIG_CSharpSetPendingExceptionArgument(SWIG_CSharpArgumentOutOfRangeException,
+                                         "only positive numbers accepted", "number");
+  return $null;
+}
+%}
+
      +
      + +

      +Note that if SWIG detects you have used SWIG_CSharpSetPendingException() or SWIG_CSharpSetPendingExceptionArgument() +without setting the canthrow attribute you will get a warning message similar to +

      + +
      +
      +example.i:21: Warning(845): Unmanaged code contains a call to a SWIG_CSharpSetPendingException
+method and C# code does not handle pending exceptions via the canthrow attribute.
+
      +
      +

      +Actually it will issue this warning for any function beginning with SWIG_CSharpSetPendingException. +

      + +

      18.4.2 C# exception example using %exception

      + + +

      +Let's consider a similar, but more common example that throws a C++ exception from within a wrapped function. +We can use %exception as mentioned in Exception handling with %exception. +

      + +
      +
      +%exception negativesonly(int value) %{
+try {
+  $action
+} catch (std::out_of_range e) {
+  SWIG_CSharpSetPendingException(SWIG_CSharpApplicationException, e.what());
+}
+%}
+
+%inline %{
+#include <stdexcept>
+void negativesonly(int value) {
+  if (value >= 0)
+    throw std::out_of_range("number should be negative");
+}
+%}
+
      +
      + +

      +The generated unmanaged code this time catches the C++ exception and converts it into a C# ApplicationException. +

      + +
      +
      +SWIGEXPORT void SWIGSTDCALL CSharp_negativesonly(int jarg1) {
+    int arg1 ;
+    
+    arg1 = (int)jarg1; 
+    
+    try {
+        negativesonly(arg1);
+        
+    } catch (std::out_of_range e) {
+        SWIG_CSharpSetPendingException(SWIG_CSharpApplicationException, e.what());
+        return ;
+    }
+    
+}
+
      +
      + +

      +The managed code generated does check for the pending exception as mentioned earlier as the C# version of %exception has the canthrow attribute set by default: +

      + +
      +
      +  public static void negativesonly(int value) {
+    examplePINVOKE.negativesonly(value);
+    if (examplePINVOKE.SWIGPendingException.Pending)
+      throw examplePINVOKE.SWIGPendingException.Retrieve();
+  }
+
      +
      + +

      18.4.3 C# exception example using exception specifications

      + + +

      +When C++ exception specifications are used, SWIG is able to detect that the method might throw an exception. +By default SWIG will automatically generate code to catch the exception and convert it into a managed ApplicationException, +as defined by the default "throws" typemaps. +The following example has a user supplied "throws" typemap which is used whenever an exception specification contains a std::out_of_range, +such as the evensonly method below. +

      + +
      +
      +%typemap(throws, canthrow=1) std::out_of_range {
+  SWIG_CSharpSetPendingExceptionArgument(SWIG_CSharpArgumentException, $1.what(), NULL);
+  return $null;
+}
+
+%inline %{
+#include <stdexcept>
+void evensonly(int input) throw (std::out_of_range) {
+  if (input%2 != 0)
+    throw std::out_of_range("number is not even");
+}
+%}
+
      +
      + +

      +Note that the type for the throws typemap is the type in the exception specification. +SWIG generates a try catch block with the throws typemap code in the catch handler. +

      + +
      +
      +SWIGEXPORT void SWIGSTDCALL CSharp_evensonly(int jarg1) {
+    int arg1 ;
+    
+    arg1 = (int)jarg1; 
+    try {
+        evensonly(arg1);
+    }
+    catch(std::out_of_range &_e) {
+      {
+          SWIG_CSharpSetPendingExceptionArgument(SWIG_CSharpArgumentException, (&_e)->what(), NULL);
+          return ;
+      }
+    }
+    
+}
+
      +
      + +

      +Multiple catch handlers are generated should there be more than one exception specifications declared. +

      + +

      18.4.4 Custom C# ApplicationException example

      + + +

      +This example involves a user defined exception. +The conventional .NET exception handling approach is to create a custom ApplicationException and throw it in your application. +The goal in this example is to convert the STL std::out_of_range exception into one of these custom .NET exceptions. +

      + + +

      +The default exception handling is quite easy to use as the SWIG_CSharpSetPendingException() and SWIG_CSharpSetPendingExceptionArgument() +methods are provided by SWIG. +However, for a custom C# exception, the boiler plate code that supports these functions needs replicating. +In essence this consists of some C/C++ code and C# code. +The C/C++ code can be generated into the wrapper file using the %insert(runtime) directive and +the C# code can be generated into the intermediary class using the imclasscode pragma as follows: + +

      + +
      +
      +%insert(runtime) %{
+  // Code to handle throwing of C# CustomApplicationException from C/C++ code.
+  // The equivalent delegate to the callback, CSharpExceptionCallback_t, is CustomExceptionDelegate
+  // and the equivalent customExceptionCallback instance is customDelegate
+  typedef void (SWIGSTDCALL* CSharpExceptionCallback_t)(const char *);
+  CSharpExceptionCallback_t customExceptionCallback = NULL;
+
+  extern "C" SWIGEXPORT
+  void SWIGSTDCALL CustomExceptionRegisterCallback(CSharpExceptionCallback_t customCallback) {
+    customExceptionCallback = customCallback;
+  }
+
+  // Note that SWIG detects any method calls named starting with
+  // SWIG_CSharpSetPendingException for warning 845
+  static void SWIG_CSharpSetPendingExceptionCustom(const char *msg) {
+    customExceptionCallback(msg);
+  }
+%}
+
+%pragma(csharp) imclasscode=%{
+  class CustomExceptionHelper {
+    // C# delegate for the C/C++ customExceptionCallback
+    public delegate void CustomExceptionDelegate(string message);
+    static CustomExceptionDelegate customDelegate =
+                                   new CustomExceptionDelegate(SetPendingCustomException);
+
+    [DllImport("$dllimport", EntryPoint="CustomExceptionRegisterCallback")]
+    public static extern
+           void CustomExceptionRegisterCallback(CustomExceptionDelegate customCallback);
+
+    static void SetPendingCustomException(string message) {
+      SWIGPendingException.Set(new CustomApplicationException(message));
+    }
+
+    static CustomExceptionHelper() {
+      CustomExceptionRegisterCallback(customDelegate);
+    }
+  }
+  static CustomExceptionHelper exceptionHelper = new CustomExceptionHelper();
+%}
+
      +
      + +

      +The method stored in the C# delegate instance, customDelegate is what gets called by the C/C++ callback. +However, the equivalent to the C# delegate, that is the C/C++ callback, needs to be assigned before any unmanaged code is executed. +This is achieved by putting the initialisation code in the intermediary class. +Recall that the intermediary class contains all the PInvoke methods, so the static variables in the intermediary class will be initialised +before any of the PInvoke methods in this class are called. +The exceptionHelper static variable ensures the C/C++ callback is initialised with the value in customDelegate by calling +the CustomExceptionRegisterCallback method in the CustomExceptionHelper static constructor. +Once this has been done, unmanaged code can make callbacks into the managed world as customExceptionCallback will be initialised with a valid callback/delegate. +Any calls to SWIG_CSharpSetPendingExceptionCustom() will make the callback to create the pending exception in the same way that +SWIG_CSharpSetPendingException() and SWIG_CSharpSetPendingExceptionArgument() does. +In fact the method has been similarly named so that SWIG can issue the warning about missing canthrow attributes as discussed earlier. +It is an invaluable warning as it is easy to forget the canthrow attribute when writing typemaps/features. +

      + +

      +The SWIGPendingException helper class is not shown, but is generated as an inner class into the intermediary class. +It stores the pending exception in Thread Local Storage so that the exception handling mechanism is thread safe. +

      + +

      +The boiler plate code above must be used in addition to a handcrafted CustomApplicationException: +

      + +
      +
      +// Custom C# Exception
+class CustomApplicationException : System.ApplicationException {
+  public CustomApplicationException(string message) 
+    : base(message) {
+  }
+}
+
      +
      + +

      +and the SWIG interface code: +

      + +
      +
      +%typemap(throws, canthrow=1) std::out_of_range {
+  SWIG_CSharpSetPendingExceptionCustom($1.what());
+  return $null;
+}
+
+%inline %{
+void oddsonly(int input) throw (std::out_of_range) {
+  if (input%2 != 1)
+    throw std::out_of_range("number is not odd");
+}
+%}
+
      +
      + +

      +The "throws" typemap now simply calls our new SWIG_CSharpSetPendingExceptionCustom() function so that the exception can be caught, as such: +

      + +
      +
      +try {
+  example.oddsonly(2);
+} catch (CustomApplicationException e) {
+  ...
+}
+
      +
      + +

      18.5 C# Directors

      + + +

      +The SWIG directors feature adds extra code to the generated C# proxy classes that enable these classes to be used in cross-language polymorphism. +Essentially, it enables unmanaged C++ code to call back into managed code for virtual methods so that a C# class can derive from a wrapped C++ class. +

      + +

      +The following sections provide information on the C# director implementation and contain most of the information required to use the C# directors. +However, the Java directors section should also be read in order to gain more insight into directors. +

      + +

      18.5.1 Directors example

      + + +

      +Imagine we are wrapping a C++ base class, Base, from which we would like to inherit in C#. +Such a class is shown below as well as another class, Caller, which calls the virtual method UIntMethod +from pure unmanaged C++ code. +

      + + +
      +
      +// file: example.h
+class Base {
+public:
+  virtual ~Base() {}
+
+  virtual unsigned int UIntMethod(unsigned int x) {
+    std::cout << "Base - UIntMethod(" << x << ")" << std::endl;
+    return x;
+  }
+  virtual void BaseBoolMethod(const Base &b, bool flag) {}
+};
+
+class Caller {
+public:
+  Caller(): m_base(0) {}
+  ~Caller() { delBase(); }
+  void set(Base *b) { delBase(); m_base = b; }
+  void reset() { m_base = 0; }
+  unsigned int UIntMethodCall(unsigned int x) { return m_base->UIntMethod(x); }
+
+private:
+  Base *m_base;
+  void delBase() { delete m_base; m_base = 0; }
+};
+
      +
      + +

      +The director feature is turned off by default and the following simple interface file shows how directors are enabled +for the class Base. +

      + +
      +
      +/* File : example.i */
+%module(directors="1") example
+%{
+#include "example.h"
+%}
+
+%feature("director") Base;
+
+%include "example.h"
+
      +
      + +

      +The following is a C# class inheriting from Base: +

      + +
      +
      +public class CSharpDerived : Base
+{
+  public override uint UIntMethod(uint x)
+  {
+    Console.WriteLine("CSharpDerived - UIntMethod({0})", x);
+    return x;
+  }
+}
+
      +
      + +

      +The Caller class can demonstrate the UIntMethod method being called from unmanaged code using the following C# code: +

      + +
      +
      +public class runme
+{
+  static void Main() 
+  {
+    Caller myCaller = new Caller();
+
+    // Test pure C++ class
+    using (Base myBase = new Base())
+    {
+      makeCalls(myCaller, myBase);
+    }
+
+    // Test director / C# derived class
+    using (Base myBase = new CSharpDerived())
+    {
+      makeCalls(myCaller, myBase);
+    }
+  }
+
+  static void makeCalls(Caller myCaller, Base myBase)
+  {
+    myCaller.set(myBase);
+    myCaller.UIntMethodCall(123);
+    myCaller.reset();
+  }
+}
+
      +
      + +

      +If the above is run, the output is then: +

      + +
      +
      +Base - UIntMethod(123)
+CSharpDerived - UIntMethod(123)
+
      +
      + +

      18.5.2 Directors implementation

      + + +

      +The previous section demonstrated a simple example where the virtual UIntMethod method was called from +C++ code, even when the overridden method is implemented in C#. +The intention of this section is to gain an insight into how the director feature works. +It shows the generated code for the two virtual methods, UIntMethod and BaseBoolMethod, +when the director feature is enabled for the Base class. +

      + +

      +Below is the generated C# Base director class. +

      + +
      +
      +using System;
+using System.Runtime.InteropServices;
+
+public class Base : IDisposable {
+  private HandleRef swigCPtr;
+  protected bool swigCMemOwn;
+
+  internal Base(IntPtr cPtr, bool cMemoryOwn) {
+    swigCMemOwn = cMemoryOwn;
+    swigCPtr = new HandleRef(this, cPtr);
+  }
+
+  internal static HandleRef getCPtr(Base obj) {
+    return (obj == null) ? new HandleRef(null, IntPtr.Zero) : obj.swigCPtr;
+  }
+
+  ~Base() {
+    Dispose();
+  }
+
+  public virtual void Dispose() {
+    lock(this) {
+      if(swigCPtr.Handle != IntPtr.Zero && swigCMemOwn) {
+        swigCMemOwn = false;
+        examplePINVOKE.delete_Base(swigCPtr);
+      }
+      swigCPtr = new HandleRef(null, IntPtr.Zero);
+      GC.SuppressFinalize(this);
+    }
+  }
+
+  public virtual uint UIntMethod(uint x) {
+    uint ret = examplePINVOKE.Base_UIntMethod(swigCPtr, x);
+    return ret;
+  }
+
+  public virtual void BaseBoolMethod(Base b, bool flag) {
+    examplePINVOKE.Base_BaseBoolMethod(swigCPtr, Base.getCPtr(b), flag);
+    if (examplePINVOKE.SWIGPendingException.Pending)
+      throw examplePINVOKE.SWIGPendingException.Retrieve();
+  }
+
+  public Base() : this(examplePINVOKE.new_Base(), true) {
+    SwigDirectorConnect();
+  }
+
+  private void SwigDirectorConnect() {
+    if (SwigDerivedClassHasMethod("UIntMethod", swigMethodTypes0))
+      swigDelegate0 = new SwigDelegateBase_0(SwigDirectorUIntMethod);
+    if (SwigDerivedClassHasMethod("BaseBoolMethod", swigMethodTypes1))
+      swigDelegate1 = new SwigDelegateBase_1(SwigDirectorBaseBoolMethod);
+    examplePINVOKE.Base_director_connect(swigCPtr, swigDelegate0, swigDelegate1);
+  }
+
+  private bool SwigDerivedClassHasMethod(string methodName, Type[] methodTypes) {
+    System.Reflection.MethodInfo methodInfo = this.GetType().GetMethod(methodName, methodTypes);
+    bool hasDerivedMethod = methodInfo.DeclaringType.IsSubclassOf(typeof(Base));
+    return hasDerivedMethod;
+  }
+
+  private uint SwigDirectorUIntMethod(uint x) {
+    return UIntMethod(x);
+  }
+
+  private void SwigDirectorBaseBoolMethod(IntPtr b, bool flag) {
+    BaseBoolMethod(new Base(b, false), flag);
+  }
+
+  internal delegate uint SwigDelegateBase_0(uint x);
+  internal delegate void SwigDelegateBase_1(IntPtr b, bool flag);
+
+  private SwigDelegateBase_0 swigDelegate0;
+  private SwigDelegateBase_1 swigDelegate1;
+
+  private static Type[] swigMethodTypes0 = new Type[] { typeof(uint) };
+  private static Type[] swigMethodTypes1 = new Type[] { typeof(Base), typeof(bool) };
+}
+
      +
      + +

      +Everything from the SwigDirectorConnect() method and below is code that is only generated when +directors are enabled. +The design comprises a C# delegate being initialised for each virtual method on construction of the class. +Let's examine the BaseBoolMethod. +

      + +

      +In the Base constructor a call is made to SwigDirectorConnect() which contains the initialisation code for all the virtual methods. +It uses a support method, SwigDerivedClassHasMethod(), which simply uses reflection to determine if the named method, +BaseBoolMethod, with the list of required parameter types, exists in a subclass. +If it does not exist, the delegate is not initialised as there is no need for unmanaged code to call back into managed C# code. +However, if there is an overridden method in any subclass, the delegate is required. +It is then initialised to the SwigDirectorBaseBoolMethod which in turn will call BaseBoolMethod if invoked. +The delegate is not initialised to the BaseBoolMethod directly as quite often types will need marshalling from the unmanaged type +to the managed type in which case an intermediary method (SwigDirectorBaseBoolMethod) is required for the marshalling. +In this case, the C# Base class needs to be created from the unmanaged IntPtr type. +

      + +

      +The last thing that SwigDirectorConnect() does is to pass the delegates to the unmanaged code. +It calls the intermediary method Base_director_connect() which is really a call to the C function CSharp_Base_director_connect(). +This method simply maps each C# delegate onto a C function pointer. +

      + +
      +
      +SWIGEXPORT void SWIGSTDCALL CSharp_Base_director_connect(void *objarg, 
+                                        SwigDirector_Base::SWIG_Callback0_t callback0,
+                                        SwigDirector_Base::SWIG_Callback1_t callback1) {
+  Base *obj = (Base *)objarg;
+  SwigDirector_Base *director = dynamic_cast<SwigDirector_Base *>(obj);
+  if (director) {
+    director->swig_connect_director(callback0, callback1);
+  }
+}
+
+class SwigDirector_Base : public Base, public Swig::Director {
+public:
+    SwigDirector_Base();
+    virtual unsigned int UIntMethod(unsigned int x);
+    virtual ~SwigDirector_Base();
+    virtual void BaseBoolMethod(Base const &b, bool flag);
+
+    typedef unsigned int (SWIGSTDCALL* SWIG_Callback0_t)(unsigned int);
+    typedef void (SWIGSTDCALL* SWIG_Callback1_t)(void *, unsigned int);
+    void swig_connect_director(SWIG_Callback0_t callbackUIntMethod, 
+                               SWIG_Callback1_t callbackBaseBoolMethod);
+
+private:
+    SWIG_Callback0_t swig_callbackUIntMethod;
+    SWIG_Callback1_t swig_callbackBaseBoolMethod;
+    void swig_init_callbacks();
+};
+
+void SwigDirector_Base::swig_connect_director(SWIG_Callback0_t callbackUIntMethod, 
+                                              SWIG_Callback1_t callbackBaseBoolMethod) {
+  swig_callbackUIntMethod = callbackUIntMethod;
+  swig_callbackBaseBoolMethod = callbackBaseBoolMethod;
+}
+
      +
      + +

      +Note that for each director class SWIG creates an unmanaged director class for making the callbacks. For example Base has SwigDirector_Base and SwigDirector_Base +is derived from Base. +Should a C# class be derived from Base, the underlying C++ SwigDirector_Base is created rather than Base. +The SwigDirector_Base class then implements all the virtual methods, redirecting calls up to managed code if the callback/delegate is non-zero. +The implementation of SwigDirector_Base::BaseBoolMethod shows this - the callback is made by invoking the swig_callbackBaseBoolMethod function pointer: +

      + +
      +
      +void SwigDirector_Base::BaseBoolMethod(Base const &b, bool flag) {
+  void * jb = 0 ;
+  unsigned int jflag  ;
+  
+  if (!swig_callbackBaseBoolMethod) {
+    Base::BaseBoolMethod(b,flag);
+    return;
+  } else {
+    jb = (Base *) &b; 
+    jflag = flag;
+    swig_callbackBaseBoolMethod(jb, jflag);
+  }
+}
+
      +
      + +

      18.5.3 Director caveats

      + + +

      +There is a subtle gotcha with directors. +If default parameters are used, it is recommended to follow a pattern of always calling a single method in any C# derived class. +An example will clarify this and the reasoning behind the recommendation. Consider the following C++ class wrapped as a director class: +

      + +
      +
      +class Defaults {
+public:
+  virtual ~Defaults();
+  virtual void DefaultMethod(int a=-100);
+};
+
      +
      + +

      +Recall that C++ methods with default parameters generate overloaded methods for each defaulted parameter, so a C# derived class can be created +with two DefaultMethod override methods: +

      + +
      +
      +public class CSharpDefaults : Defaults
+{
+  public override void DefaultMethod()
+  {
+    DefaultMethod(-100); // note C++ default value used
+  }
+  public override void DefaultMethod(int x)
+  {
+  }
+}
+
      +
      + +

      +It may not be clear at first, but should a user intend to call CSharpDefaults.DefaultMethod() from C++, a call is actually made to CSharpDefaults.DefaultMethod(int). +This is because the initial call is made in C++ and therefore the DefaultMethod(int) method will be called as is expected with C++ calls to methods with defaults, +with the default being set to -100. +The callback/delegate matching this method is of course the overloaded method DefaultMethod(int). +However, a call from C# to CSharpDefaults.DefaultMethod() will of course call this exact method and in order for behaviour to be consistent with calls from C++, the implementation +should pass the call on to CSharpDefaults.DefaultMethod(int)using the C++ default value, as shown above. +

      + +

      18.6 C# Typemap examples

      + + +This section includes a few examples of typemaps. For more examples, you +might look at the files "csharp.swg" and "typemaps.i" in +the SWIG library. + + +

      18.6.1 Memory management when returning references to member variables

      + + +

      +This example shows how to prevent premature garbage collection of objects when the underlying C++ class returns a pointer or reference to a member variable. +The example is a direct equivalent to this Java equivalent. +

      + +

      +Consider the following C++ code: +

      + +
      +
      +struct Wheel {
+  int size;
+  Wheel(int sz) : size(sz) {}
+};
+
+class Bike {
+  Wheel wheel;
+public:
+  Bike(int val) : wheel(val) {}
+  Wheel& getWheel() { return wheel; }
+};
+
      +
      + +

      +and the following usage from C# after running the code through SWIG: +

      + + +
      +
      +      Wheel wheel = new Bike(10).getWheel();
+      Console.WriteLine("wheel size: " + wheel.size);
+      // Simulate a garbage collection
+      System.GC.Collect();
+      System.GC.WaitForPendingFinalizers();
+      Console.WriteLine("wheel size: " + wheel.size);
+
      +
      + +

      +Don't be surprised that if the resulting output gives strange results such as... +

      + +
      +
      +wheel size: 10
+wheel size: 135019664
+
      +
      + +

      +What has happened here is the garbage collector has collected the Bike instance as it doesn't think it is needed any more. +The proxy instance, wheel, contains a reference to memory that was deleted when the Bike instance was collected. +In order to prevent the garbage collector from collecting the Bike instance a reference to the Bike must +be added to the wheel instance. You can do this by adding the reference when the getWheel() method +is called using the following typemaps. +

      + + +
      +
      +%typemap(cscode) Wheel %{
+  // Ensure that the GC doesn't collect any Bike instance set from C#
+  private Bike bikeReference;
+  internal void addReference(Bike bike) {
+    bikeReference = bike;
+  }
+%}
+
+// Add a C# reference to prevent premature garbage collection and resulting use
+// of dangling C++ pointer. Intended for methods that return pointers or
+// references to a member variable.
+%typemap(csout, excode=SWIGEXCODE) Wheel& getWheel {
+    IntPtr cPtr = $imcall;$excode
+    $csclassname ret = null;
+    if (cPtr != IntPtr.Zero) {
+      ret = new $csclassname(cPtr, $owner);
+      ret.addReference(this);
+    }
+    return ret;
+  }
+
      +
      + +

      +The code in the first typemap gets added to the Wheel proxy class. +The code in the second typemap constitutes the bulk of the code in the generated getWheel() function: +

      + +
      +
      +public class Wheel : IDisposable {
+  ...
+  // Ensure that the GC doesn't collect any Bike instance set from C#
+  private Bike bikeReference;
+  internal void addReference(Bike bike) {
+    bikeReference = bike;
+  }
+}
+
+public class Bike : IDisposable {
+  ...
+  public Wheel getWheel() {
+    IntPtr cPtr = examplePINVOKE.Bike_getWheel(swigCPtr);
+    Wheel ret = null;
+    if (cPtr != IntPtr.Zero) {
+      ret = new Wheel(cPtr, false);
+      ret.addReference(this);
+    }
+    return ret;
+  }
+}
+
      +
      + +

      +Note the addReference call. +

      + +

      18.6.2 Memory management for objects passed to the C++ layer

      + + +

      +The example is a direct equivalent to this Java equivalent. +Managing memory can be tricky when using C++ and C# proxy classes. +The previous example shows one such case and this example looks at memory management for a class passed to a C++ method which expects the object to remain in scope +after the function has returned. Consider the following two C++ classes: +

      + +
      +
      +struct Element {
+  int value;
+  Element(int val) : value(val) {}
+};
+class Container {
+  Element* element;
+public:
+  Container() : element(0) {}
+  void setElement(Element* e) { element = e; }
+  Element* getElement() { return element; }
+};
+
      +
      + +

      +and usage from C++ +

      + +
      +
      +    Container container;
+    Element element(20);
+    container.setElement(&element);
+    cout << "element.value: " << container.getElement()->value << endl;
+
      +
      + +

      +and more or less equivalent usage from C# +

      + +
      +
      +      Container container = new Container();
+      Element element = new Element(20);
+      container.setElement(element);
+
      +
      + +

      +The C++ code will always print out 20, but the value printed out may not be this in the C# equivalent code. +In order to understand why, consider a garbage collection occuring... +

      + +
      +
      +      Container container = new Container();
+      Element element = new Element(20);
+      container.setElement(element);
+      Console.WriteLine("element.value: " + container.getElement().value);
+      // Simulate a garbage collection
+      System.GC.Collect();
+      System.GC.WaitForPendingFinalizers();
+      Console.WriteLine("element.value: " + container.getElement().value);
+
      +
      + +

      +The temporary element created with new Element(20) could get garbage collected +which ultimately means the container variable is holding a dangling pointer, thereby printing out any old random value instead of the expected value of 20. +One solution is to add in the appropriate references in the C# layer... +

      + +
      +
      +public class Container : IDisposable {
+
+  ...
+
+  // Ensure that the GC doesn't collect any Element set from C#
+  // as the underlying C++ class stores a shallow copy
+  private Element elementReference;
+  private HandleRef getCPtrAndAddReference(Element element) {
+    elementReference = element;
+    return Element.getCPtr(element);
+  }
+
+  public void setElement(Element e) {
+    examplePINVOKE.Container_setElement(swigCPtr, getCPtrAndAddReference(e));
+  }
+}
+
      +
      + +

      +The following typemaps will generate the desired code. +The 'csin' typemap matches the input parameter type for the setElement method. +The 'cscode' typemap simply adds in the specified code into the C# proxy class. +

      + +
      +
      +%typemap(csin) Element *e "getCPtrAndAddReference($csinput)"
+
+%typemap(cscode) Container %{
+  // Ensure that the GC doesn't collect any Element set from C#
+  // as the underlying C++ class stores a shallow copy
+  private Element elementReference;
+  private HandleRef getCPtrAndAddReference(Element element) {
+    elementReference = element;
+    return Element.getCPtr(element);
+  }
+%}
+
      +
      + + +

      18.6.3 Date marshalling using the csin typemap and associated attributes

      + + +

      +The NaN Exception example is a simple example of the "javain" typemap and its 'pre' attribute. +This example demonstrates how a C++ date class, say CDate, can be mapped onto the standard .NET date class, +System.DateTime by using the 'pre', 'post' and 'pgcppname' attributes of the "csin" typemap (the C# equivalent to the "javain" typemap). +The example is an equivalent to the Java Date marshalling example. +The idea is that the System.DateTime is used wherever the C++ API uses a CDate. +Let's assume the code being wrapped is as follows: +

      + +
      +
      +class CDate {
+public:
+  CDate();
+  CDate(int year, int month, int day);
+  int getYear();
+  int getMonth();
+  int getDay();
+  ...
+};
+struct Action {
+  static int doSomething(const CDate &dateIn, CDate &dateOut);
+  Action(const CDate &date, CDate &dateOut);
+};
+
      +
      + +

      +Note that dateIn is const and therefore read only and dateOut is a non-const output type. +

      + +

      +First let's look at the code that is generated by default, where the C# proxy class CDate is used in the proxy interface: +

      + +
      +
      +public class Action : IDisposable {
+  ...
+  public Action(CDate dateIn, CDate dateOut) 
+      : this(examplePINVOKE.new_Action(CDate.getCPtr(dateIn), CDate.getCPtr(dateOut)), true) {
+    if (examplePINVOKE.SWIGPendingException.Pending) 
+      throw examplePINVOKE.SWIGPendingException.Retrieve();
+  }
+
+  public int doSomething(CDate dateIn, CDate dateOut) {
+    int ret = examplePINVOKE.Action_doSomething(swigCPtr, 
+                                                CDate.getCPtr(dateIn), 
+                                                CDate.getCPtr(dateOut));
+    if (examplePINVOKE.SWIGPendingException.Pending) 
+      throw examplePINVOKE.SWIGPendingException.Retrieve();
+    return ret;
+  }
+}
+
      +
      + +

      +The CDate & and const CDate & C# code is generated from the following two default typemaps: +

      + +
      +
      +%typemap(cstype) SWIGTYPE & "$csclassname"
+%typemap(csin) SWIGTYPE & "$csclassname.getCPtr($csinput)"
+
      +
      + +

      +where '$csclassname' is translated into the proxy class name, CDate and '$csinput' is translated into the name of the parameter, eg dateIn. +From C#, the intention is then to call into a modifed API with something like: +

      + +
      +
      +System.DateTime dateIn = new System.DateTime(2011, 4, 13);
+System.DateTime dateOut = new System.DateTime();
+
+// Note in calls below, dateIn remains unchanged and dateOut 
+// is set to a new value by the C++ call
+Action action = new Action(dateIn, out dateOut);
+dateIn = new System.DateTime(2012, 7, 14);
+
      +
      + +

      +To achieve this mapping, we need to alter the default code generation slightly so that at the C# layer, +a System.DateTime is converted into a CDate. +The intermediary layer will still take a pointer to the underlying CDate class. +The typemaps to achieve this are shown below. +

      + +
      +
      +%typemap(cstype) const CDate& "System.DateTime"
+%typemap(csin, 
+         pre="    CDate temp$csinput = new CDate($csinput.Year, $csinput.Month, $csinput.Day);"
+        ) const CDate &
+         "$csclassname.getCPtr(temp$csinput)"
+
+%typemap(cstype) CDate& "out System.DateTime"
+%typemap(csin, 
+         pre="    CDate temp$csinput = new CDate();", 
+         post="      $csinput = new System.DateTime(temp$csinput.getYear(),"
+              " temp$csinput.getMonth(), temp$csinput.getDay(), 0, 0, 0);", 
+         cshin="out $csinput"
+        ) CDate &
+         "$csclassname.getCPtr(temp$csinput)"
+
+
      +
      + +

      +The resulting generated proxy code in the Action class follows: +

      + +
      +
      +public class Action : IDisposable {
+  ...
+  public int doSomething(System.DateTime dateIn, out System.DateTime dateOut) {
+    CDate tempdateIn = new CDate(dateIn.Year, dateIn.Month, dateIn.Day);
+    CDate tempdateOut = new CDate();
+    try {
+      int ret = examplePINVOKE.Action_doSomething(swigCPtr, 
+                                                  CDate.getCPtr(tempdateIn), 
+                                                  CDate.getCPtr(tempdateOut));
+      if (examplePINVOKE.SWIGPendingException.Pending) 
+        throw examplePINVOKE.SWIGPendingException.Retrieve();
+      return ret;
+    } finally {
+      dateOut = new System.DateTime(tempdateOut.getYear(), 
+                                    tempdateOut.getMonth(), tempdateOut.getDay(), 0, 0, 0);
+    }
+  }
+
+  static private IntPtr SwigConstructAction(System.DateTime dateIn, out System.DateTime dateOut) {
+    CDate tempdateIn = new CDate(dateIn.Year, dateIn.Month, dateIn.Day);
+    CDate tempdateOut = new CDate();
+    try {
+      return examplePINVOKE.new_Action(CDate.getCPtr(tempdateIn), CDate.getCPtr(tempdateOut));
+    } finally {
+      dateOut = new System.DateTime(tempdateOut.getYear(), 
+                                    tempdateOut.getMonth(), tempdateOut.getDay(), 0, 0, 0);
+    }
+  }
+
+  public Action(System.DateTime dateIn, out System.DateTime dateOut) 
+      : this(Action.SwigConstructAction(dateIn, out dateOut), true) {
+    if (examplePINVOKE.SWIGPendingException.Pending) 
+      throw examplePINVOKE.SWIGPendingException.Retrieve();
+  }
+}
+
      +
      + +

      +A few things to note: +

      +
        +
      • The "cstype" typemap has changed the parameter type to System.DateTime instead of the default generated CDate proxy. +
      • The non-const CDate & type is marshalled as a reference parameter in C# as the date cannot be explicitly set once the object has been created, so a new object is created instead. +
      • The code in the 'pre' attribute appears before the intermediary call (examplePINVOKE.new_Action / examplePINVOKE.Action_doSomething). +
      • The code in the 'post' attribute appears after the intermediary call. +
      • A try .. finally block is generated with the intermediary call in the try block and 'post' code in the finally block. + The alternative of just using a temporary variable for the return value from the intermediary call and the 'post' code being inserted before the + return statement is not possible given that the intermediary call and method return comes from a single source (the "csout" typemap). +
      • The temporary variables in the "csin" typemaps are called temp$csin, where "$csin" is replaced with the parameter name. + "$csin" is used to mangle the variable name so that more than one CDate & type can be used as a parameter in a method, otherwise two or + more local variables with the same name would be generated. +
      • The use of the "csin" typemap causes a constructor helper function (SwigConstructAction) to be generated. + This allows C# code to be called before the intermediary call made in the constructor initialization list. +
      • The 'cshin' attribute is required for the SwigConstructAction constructor helper function so that the 2nd parameter is declared as out dateOut instead of just dateOut. +
      + +

      +So far we have considered the date as an input only and an output only type. +Now let's consider CDate * used as an input/output type. Consider the following C++ function which modifies the date passed in: +

      + +
      +
      +void addYears(CDate *pDate, int years) {
+  *pDate = CDate(pDate->getYear() + years, pDate->getMonth(), pDate->getDay());
+}
+
      +
      + +

      +If usage of CDate * commonly follows this input/output pattern, usage from C# like the following +

      + +
      +
      +System.DateTime christmasEve = new System.DateTime(2000, 12, 24);
+example.addYears(ref christmasEve, 10); // christmasEve now contains 2010-12-24
+
      +
      + +

      +will be possible with the following CDate * typemaps +

      + +
      +
      +%typemap(cstype, out="System.DateTime") CDate * "ref System.DateTime"
+
+%typemap(csin,
+         pre="    CDate temp$csinput = new CDate($csinput.Year, $csinput.Month, $csinput.Day);",
+         post="      $csinput = new System.DateTime(temp$csinput.getYear(),"
+              " temp$csinput.getMonth(), temp$csinput.getDay(), 0, 0, 0);", 
+         cshin="ref $csinput"
+        ) CDate *
+         "$csclassname.getCPtr(temp$csinput)"
+
      +
      + +

      +Globals are wrapped by the module class and for a module called example, the typemaps result in the following code: +

      + +
      +
      +public class example {
+  public static void addYears(ref System.DateTime pDate, int years) {
+    CDate temppDate = new CDate(pDate.Year, pDate.Month, pDate.Day);
+    try {
+      examplePINVOKE.addYears(CDate.getCPtr(temppDate), years);
+    } finally {
+      pDate = new System.DateTime(temppDate.getYear(), temppDate.getMonth(), temppDate.getDay(), 0, 0, 0);
+    }
+  }
+  ...
+}
+
      +
      + +

      +The following typemap is the same as the previous but demonstrates how a using block can be used for the temporary variable. +The only change to the previous typemap is the introduction of the 'terminator' attribute to terminate the using block. +The subtractYears method is nearly identical to the above addYears method. +

      + +
      +
      +%typemap(csin,
+         pre="    using (CDate temp$csinput = new CDate($csinput.Year, $csinput.Month, $csinput.Day)) {",
+         post="      $csinput = new System.DateTime(temp$csinput.getYear(),"
+              " temp$csinput.getMonth(), temp$csinput.getDay(), 0, 0, 0);", 
+         terminator="    } // terminate temp$csinput using block",
+         cshin="ref $csinput"
+        ) CDate *
+         "$csclassname.getCPtr(temp$csinput)"
+
+void subtractYears(CDate *pDate, int years) {
+  *pDate = CDate(pDate->getYear() - years, pDate->getMonth(), pDate->getDay());
+}
+
      +
      + +

      +The resulting generated code shows the termination of the using block: +

      + +
      +
      +public class example {
+  public static void subtractYears(ref System.DateTime pDate, int years) {
+    using (CDate temppDate = new CDate(pDate.Year, pDate.Month, pDate.Day)) {
+    try {
+      examplePINVOKE.subtractYears(CDate.getCPtr(temppDate), years);
+    } finally {
+      pDate = new System.DateTime(temppDate.getYear(), temppDate.getMonth(), temppDate.getDay(), 0, 0, 0);
+    }
+    } // terminate temppDate using block
+  }
+  ...
+}
+
      +
      + +

      18.6.4 A date example demonstrating marshalling of C# properties

      + + +

      +The previous section looked at converting a C++ date class to System.DateTime for parameters. +This section extends this idea so that the correct marshalling is obtained when wrapping C++ variables. +Consider the same CDate class from the previous section and a global variable: +

      + +
      +
      +CDate ImportantDate = CDate(1999, 12, 31);
+
      +
      + +

      +The aim is to use System.DateTime from C# when accessing this date as shown in the following usage where the module name is 'example': +

      + +
      +
      +example.ImportantDate = new System.DateTime(2000, 11, 22);
+System.DateTime importantDate = example.ImportantDate;
+Console.WriteLine("Important date: " + importantDate);
+
      +
      + +

      +When SWIG wraps a variable that is a class/struct/union, it is wrapped using a pointer to the type for the reasons given in Stucture data members. +The typemap type required is thus CDate *. Given that the previous section already designed CDate * typemaps, we'll use those same typemaps plus the 'csvarin' and 'csvarout' typemaps. + +

      +
      +%typemap(cstype, out="System.DateTime") CDate * "ref System.DateTime"
+
+%typemap(csin,
+         pre="    CDate temp$csinput = new CDate($csinput.Year, $csinput.Month, $csinput.Day);",
+         post="      $csinput = new System.DateTime(temp$csinput.getYear(),"
+              " temp$csinput.getMonth(), temp$csinput.getDay(), 0, 0, 0);", 
+         cshin="ref $csinput"
+        ) CDate *
+         "$csclassname.getCPtr(temp$csinput)"
+
+%typemap(csvarin, excode=SWIGEXCODE2) CDate * %{
+    /* csvarin typemap code */
+    set {
+      CDate temp$csinput = new CDate($csinput.Year, $csinput.Month, $csinput.Day);
+      $imcall;$excode
+    } %}
+
+%typemap(csvarout, excode=SWIGEXCODE2) CDate * %{
+    /* csvarout typemap code */
+    get {
+      IntPtr cPtr = $imcall;
+      CDate tempDate = (cPtr == IntPtr.Zero) ? null : new CDate(cPtr, $owner);$excode
+      return new System.DateTime(tempDate.getYear(), tempDate.getMonth(), tempDate.getDay(),
+                                 0, 0, 0);
+    } %}
+
      +
      + +

      +For a module called example, the typemaps result in the following code: +

      + +
      +
      +public class example {
+  public static System.DateTime ImportantDate {
+    /* csvarin typemap code */
+    set {
+      CDate tempvalue = new CDate(value.Year, value.Month, value.Day);
+      examplePINVOKE.ImportantDate_set(CDate.getCPtr(tempvalue));
+    } 
+    /* csvarout typemap code */
+    get {
+      IntPtr cPtr = examplePINVOKE.ImportantDate_get();
+      CDate tempDate = (cPtr == IntPtr.Zero) ? null : new CDate(cPtr, false);
+      return new System.DateTime(tempDate.getYear(), tempDate.getMonth(), tempDate.getDay(),
+                                 0, 0, 0);
+    } 
+  }
+  ...
+}
+
      +
      + +

      +Some points to note: +

      + +
        +
      • The property set comes from the 'csvarin' typemap and the property get comes from the 'csvarout' typemap. +
      • The type used for the property comes from the 'cstype' typemap. This particular example has the 'out' attribute set in the typemap and as it is specified, it is used in preference to the type in the typemap body. This is because the type in the 'out' attribute can never include modifiers such as 'ref', thereby avoiding code such as public static ref System.DateTime ImportantDate { ..., which would of course not compile. +
      • The $excode special variable expands to nothing as there are no exception handlers specified in any of the unmanaged code typemaps (in fact the marshalling was done using the default unmanaged code typemaps.) +
      • The $imcall typemap expands to the appropriate intermediary method call in the examplePINVOKE class. +
      • The $csinput special variable in the 'csin' typemap always expands to value for properties. In this case $csclassname.getCPtr(temp$csinput) expands to CDate.getCPtr(tempvalue). +
      • The 'csin' typemap has 'pre', 'post' and 'cshin' attributes, and these are all ignored in the property set. The code in these attributes must instead be replicated within the 'csvarin' typemap. The line creating the temp$csinput variable is such an example; it is identical to what is in the 'pre' attribute. +
      + + +

      18.6.5 Turning wrapped classes into partial classes

      + + +

      +C# supports the notion of partial classes whereby a class definition can be split into more than one file. +It is possible to turn the wrapped C++ class into a partial C# class using the csclassmodifiers typemap. +Consider a C++ class called ExtendMe: +

      + +
      +
      +class ExtendMe {
+public:
+  int Part1() { return 1; }
+};
+
      +
      + +

      +The default C# proxy class generated is: +

      + +
      +
      +public class ExtendMe : IDisposable {
+  ...
+  public int Part1() {
+    ...
+  }
+}
+
      +
      + +

      +The default csclassmodifiers typemap shipped with SWIG is +

      + +
      +
      +%typemap(csclassmodifiers) SWIGTYPE "public class"
+
      +
      + +

      +Note that the type used is the special catch all type SWIGTYPE. +If instead we use the following typemap to override this for just the ExtendMe class: +

      + +
      +
      +%typemap(csclassmodifiers) ExtendMe "public partial class"
+
      +
      + +

      +The C# proxy class becomes a partial class: +

      + +
      +
      +public partial class ExtendMe : IDisposable {
+  ...
+  public int Part1() {
+    ...
+  }
+}
+
      +
      + +

      +You can then of course declare another part of the partial class elsewhere, for example: +

      + +
      +
      +public partial class ExtendMe : IDisposable {
+  public int Part2() {
+    return 2;
+  }
+}
+
      +
      + +

      +and compile the following code: +

      + +
      +
      +ExtendMe em = new ExtendMe();
+Console.WriteLine("part1: {0}", em.Part1());
+Console.WriteLine("part2: {0}", em.Part2());
+
      +
      + +

      +demonstrating that the class contains methods calling both unmanaged code - Part1() and managed code - Part2(). +The following example is an alternative approach to adding managed code to the generated proxy class. +

      + +

      18.6.6 Extending proxy classes with additional C# code

      + + +

      +The previous example showed how to use partial classes to add functionality to a generated C# proxy class. +It is also possible to extend a wrapped struct/class with C/C++ code by using the %extend directive. +A third approach is to add some C# methods into the generated proxy class with the cscode typemap. +If we declare the following typemap before SWIG parses the ExtendMe class used in the previous example +

      + +
      +
      +%typemap(cscode) ExtendMe %{
+  public int Part3() {
+    return 3;
+  }
+%}
+
+
      +
      + +

      +The generated C# proxy class will instead be: +

      + +
      +
      +public class ExtendMe : IDisposable {
+  ...
+  public int Part3() {
+    return 3;
+  }
+  public int Part1() {
+    ...
+  }
+}
+
      +
      + + + + diff --git a/Doc/Manual/Chicken.html b/Doc/Manual/Chicken.html new file mode 100644 index 0000000..98372a0 --- /dev/null +++ b/Doc/Manual/Chicken.html @@ -0,0 +1,598 @@ + + + + +SWIG and Chicken + + + + + +

      19 SWIG and Chicken

      + +
      + +
      + + + + +

      + 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 Revised^5 Report on Scheme. Its main + attributes are that it +

      + +
        +
      1. generates portable C code
        2. +
      2. includes a customizable interpreter
        3. +
      3. links to C libraries with a simple Foreign Function Interface
        4. +
      4. supports full tail-recursion and first-class continuations
        5. +
      + +

      + 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 + support for C++ -- object-oriented code is + difficult to wrap by hand in CHICKEN -- and its typed + pointer representation, essential for C and C++ + libraries involving structures or classes. + +

      + +

      19.1 Preliminaries

      + + +

      + CHICKEN support was introduced to SWIG in version 1.3.18. SWIG + relies on some recent additions to CHICKEN, which are only + present in releases of CHICKEN with version number + greater than or equal to 1.89. + To use a chicken version between 1.40 and 1.89, see the Garbage collection + section below. +

      + +

      + You may want to look at any of the examples in Examples/chicken/ + or Examples/GIFPlot/Chicken for the basic steps to run SWIG + CHICKEN. +

      + +

      19.1.1 Running SWIG in C mode

      + + +

      + To run SWIG CHICKEN in C mode, use + the -chicken option. +

      + +
      + 
      % swig -chicken example.i
      +
      + +

      + To allow the wrapper to take advantage of future CHICKEN code + generation improvements, part of the wrapper is direct CHICKEN + function calls (example_wrap.c) and part is CHICKEN + Scheme (example.scm). The basic Scheme code must + be compiled to C using your system's CHICKEN compiler or + both files can be compiled directly using the much simpler csc. +

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

      + So for the C mode of SWIG CHICKEN, example_wrap.c and + oexample.c are the files that must be compiled to + object files and linked into your project. +

      + +

      19.1.2 Running SWIG in C++ mode

      + + +

      + To run SWIG CHICKEN in C++ mode, use + the -chicken -c++ option. +

      + +
      + 
      % swig -chicken -c++ example.i
      +
      + +

      + This will generate example_wrap.cxx and + example.scm. 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 csc. +

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

      + So for the C++ mode of SWIG CHICKEN, example_wrap.cxx + and oexample.c are the files that must be compiled to + object files and linked into your project. +

      + +

      19.2 Code Generation

      + + +

      19.2.1 Naming Conventions

      + + +

      + Given a C variable, function or constant declaration named + Foo_Bar, the declaration will be available + in CHICKEN as an identifier ending with + Foo-Bar. That is, an underscore is converted + to a dash. +

      + +

      + You may control what the CHICKEN identifier will be by using the + %rename SWIG directive in the SWIG interface file. +

      + +

      19.2.2 Modules

      + + +

      + The name of the module must be declared one of two ways: +

        +
      • Placing %module example in the SWIG interface + file.
        • +
      • Using -module example on the SWIG command + line.
        • +
      + +

      + The generated example.scm file then exports (declare (unit modulename)). + If you do not want SWIG to export the (declare (unit modulename)), pass + the -nounit option to SWIG. + +

      + CHICKEN will be able to access the module using the (declare + (uses modulename)) CHICKEN Scheme form. +

      + +

      19.2.3 Constants and Variables

      + + +

      + Constants may be created using any of the four constructs in + the interface file: +

      +
        +
      1. #define MYCONSTANT1 ...
        2. +
      2. %constant int MYCONSTANT2 = ...
        3. +
      3. const int MYCONSTANT3 = ...
        4. +
      4. enum { MYCONSTANT4 = ... };
        5. +
      + +

      + In all cases, the constants may be accessed from within CHICKEN + using the form (MYCONSTANT1); that is, the constants + may be accessed using the read-only parameter form. +

      + +

      + Variables are accessed using the full parameter form. + For example, to set the C variable "int my_variable;", use the + Scheme form (my-variable 2345). To get the C variable, + use (my-variable). +

      + +

      + The %feature("constasvar") 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 + (set! MYCONSTANT1 (MYCONSTANT1)). See + Features and the %feature directive + for info on how to apply the %feature. +

      + +

      19.2.4 Functions

      + + +

      + 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 (sqrt 2345.0). A void return + value will give C_SCHEME_UNDEFINED as a result. +

      +

      + A function may return more than one value by using the + OUTPUT specifier (see Lib/chicken/typemaps.i). + They will be returned as multiple values using (values) 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 (call-with-values). +

      + +

      19.2.5 Exceptions

      + + +

      The SWIG chicken module has support for exceptions thrown from + C or C++ code to be caught in scheme. + See Exception handling with %exception + for more information about declaring exceptions in the interface file. +

      + +

      Chicken supports both the SWIG_exception(int code, const char *msg) interface + as well as a SWIG_ThrowException(C_word val) function for throwing exceptions from + inside the %exception blocks. SWIG_exception will throw a list consisting of the code + (as an integer) and the message. Both of these will throw an exception using (abort), + which can be handled by (handle-exceptions). See + Chicken manual on Exceptions + and SFRI-12. Since the exception values are thrown + directly, if (condition-case) is used to catch an exception the exception will come through in the val () case. +

      + +

      The following simple module

      + +
      +%module exception_test
+
+%inline %{
+  void test_throw(int i) throws (int) { 
+    if (i == 1) throw 15; 
+  }
+%}
+
      + +

      could be run with

      + +
      +(handle-exceptions exvar 
+  (if (= exvar 15)
+    (print "Correct!") 
+    (print "Threw something else " exvar))
+  (test-throw 1))
+
      + + +

      19.3 TinyCLOS

      + + +

      + 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." +

      + +

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

      + +

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

      + + 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:" + +

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

      + +

      19.4 Linkage

      + + +

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

      + +

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

      + + +

      19.4.1 Static binary or shared library linked at compile time

      + + +

      We can easily use csc to build a static binary.

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

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

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

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

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

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

      + +

      19.4.2 Building chicken extension libraries

      + + +

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

      + +

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

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

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

      + +

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

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

      Which would then be compiled with

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

      Then the extension library can be loaded with (require 'mod). As we can see here, +mod_load.scm contains the code that gets 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 +%import

      + +

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

      + +

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

      + +

      19.4.3 Linking multiple SWIG modules with TinyCLOS

      + + +

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

      + +

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

      + +

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

      + +

      19.5 Typemaps

      + + +

      + The Chicken module handles all types via typemaps. This information is + read from Lib/chicken/typemaps.i and + Lib/chicken/chicken.swg. +

      + +

      19.6 Pointers

      + + +

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

      +

      + To construct a Scheme object from a C pointer, the wrapper code + calls the function + SWIG_NewPointerObj(void *ptr, swig_type_info *type, int owner), + The function that calls SWIG_NewPointerObj must have a variable declared + C_word *known_space = C_alloc(C_SIZEOF_SWIG_POINTER); + It is ok to call SWIG_NewPointerObj more than once, + just make sure known_space has enough space for all the created pointers. +

      +

      + To get the pointer represented by a CHICKEN tagged pointer, the + wrapper code calls the function + SWIG_ConvertPtr(C_word s, void **result, swig_type_info *type, int flags), + passing a pointer to a struct representing the expected pointer + type. flags is either zero or SWIG_POINTER_DISOWN (see below). +

      + +

      19.6.1 Garbage collection

      + + +

      If the owner flag passed to SWIG_NewPointerObj is 1, NewPointerObj 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 %newobject directive must be specified for functions whose return values + should be garbage collected. See + Object ownership and %newobject for more information. +

      + +

      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 DISOWN input typemap. + After applying this typemap (see the Typemaps chapter 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 SWIG_POINTER_DISOWN flag to SWIG_ConvertPtr. + Warning: 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. +

      + +

      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 -nocollection 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. +

      + +

      19.7 Unsupported features and known problems

      + + +
        +
      • No director support.
        • +
      • No support for c++ standard types like std::vector.
        • +
      • The TinyCLOS wrappers for overloaded functions will not work correctly when using + %feature(compactdefaultargs).
        • +
      + +

      19.7.1 TinyCLOS problems with Chicken version <= 1.92

      + + +

      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

      + +
      +
      +class Foo {};
+int foo(int a, Foo *b);
+int foo(int a);
+
      + +

      will produce scheme code

      + +
      +
      +(define-method (foo (arg0 <top>) (arg1 <Foo>)) (call primitive function))
+(define-method (foo (arg0 <top>)) (call primitive function))
+
      + +

      Using unpatched TinyCLOS, the second (define-method) will replace the first one, +so calling (foo 3 f) will produce an error.

      + +

      There are three solutions to this. The easist is to upgrade to the latest Chicken version. Otherwise, the +file Lib/chicken/tinyclos-multi-generic.patch 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 Lib/chicken/multi-generic.scm +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.

      + + + diff --git a/Doc/Manual/Contents.html b/Doc/Manual/Contents.html new file mode 100644 index 0000000..0e7ebf4 --- /dev/null +++ b/Doc/Manual/Contents.html @@ -0,0 +1,1610 @@ + + + + +SWIG Users Manual + + +

      SWIG Users Manual

      + +

      + +

      1 Preface

      + + +
      + +
      + + +

      2 Introduction

      + + +
      + +
      + + +

      3 Getting started on Windows

      + + +
      + +
      + + +

      4 Scripting Languages

      + + +
      + +
      + + +

      5 SWIG Basics

      + + +
      + +
      + + +

      6 SWIG and C++

      + + +
      + +
      + + +

      7 Preprocessing

      + + +
      + +
      + + +

      8 SWIG library

      + + +
      + +
      + + +

      9 Argument Handling

      + + +
      + +
      + + +

      10 Typemaps

      + + +
      + +
      + + +

      11 Customization Features

      + + +
      + +
      + + +

      12 Contracts

      + + +
      + +
      + + +

      13 Variable Length Arguments

      + + +
      + +
      + + +

      14 Warning Messages

      + + +
      + +
      + + +

      15 Working with Modules

      + + +
      + +
      + + +

      16 Using SWIG with ccache - ccache-swig(1) manpage

      + + +
      + +
      + + +

      17 SWIG and Allegro Common Lisp

      + + +
      + +
      + + +

      18 SWIG and C#

      + + +
      + +
      + + +

      19 SWIG and Chicken

      + + +
      + +
      + + +

      20 SWIG and Guile

      + + +
      + +
      + + +

      21 SWIG and Java

      + + +
      + +
      + + +

      22 SWIG and Common Lisp

      + + +
      + +
      + + +

      23 SWIG and Lua

      + + +
      + +
      + + +

      24 SWIG and Modula-3

      + + +
      + +
      + + +

      25 SWIG and MzScheme

      + + +
      + +
      + + +

      26 SWIG and Ocaml

      + + +
      + +
      + + +

      27 SWIG and Octave

      + + +
      + +
      + + +

      28 SWIG and Perl5

      + + +
      + +
      + + +

      29 SWIG and PHP

      + + +
      + +
      + + +

      30 SWIG and Pike

      + + +
      + +
      + + +

      31 SWIG and Python

      + + +
      + +
      + + +

      32 SWIG and Ruby

      + + +
      + +
      + + +

      33 SWIG and Tcl

      + + +
      + +
      + + +

      34 SWIG and R

      + + +
      + +
      + + +

      35 Extending SWIG to support new languages

      + + +
      + +
      + + + + + + diff --git a/Doc/Manual/Contract.html b/Doc/Manual/Contract.html new file mode 100644 index 0000000..de390fb --- /dev/null +++ b/Doc/Manual/Contract.html @@ -0,0 +1,274 @@ + + + +Contract Checking + + + + +

      12 Contracts

      + +
      + +
      + + + + +

      +A common problem that arises when wrapping C libraries is that of maintaining +reliability and checking for errors. The fact of the matter is that many +C programs are notorious for not providing error checks. Not only that, +when you expose the internals of an application as a library, it +often becomes possible to crash it simply by providing bad inputs or +using it in a way that wasn't intended. +

      + +

      +This chapter describes SWIG's support for software contracts. In the context +of SWIG, a contract can be viewed as a runtime constraint that is attached +to a declaration. For example, you can easily attach argument checking rules, +check the output values of a function and more. +When one of the rules is violated by a script, a runtime exception is +generated rather than having the program continue to execute. +

      + +

      12.1 The %contract directive

      + + +

      +Contracts are added to a declaration using the %contract directive. Here +is a simple example: +

      + +
      +
      +%contract sqrt(double x) {
+require:
+    x >= 0;
+ensure:
+    sqrt >= 0;
+}
+
+...
+double sqrt(double);
+
      +
      + +

      +In this case, a contract is being added to the sqrt() function. +The %contract directive must always appear before the declaration +in question. Within the contract there are two sections, both of which +are optional. The require: +section specifies conditions that must hold before the function is called. +Typically, this is used to check argument values. The ensure: section +specifies conditions that must hold after the function is called. This is +often used to check return values or the state of the program. In both +cases, the conditions that must hold must be specified as boolean expressions. +

      + +

      +In the above example, we're simply making sure that sqrt() returns a non-negative +number (if it didn't, then it would be broken in some way). +

      + +

      +Once a contract has been specified, it modifies the behavior of the +resulting module. For example: +

      + +
      +
      +>>> example.sqrt(2)
+1.4142135623730951
+>>> example.sqrt(-2)
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+RuntimeError: Contract violation: require: (arg1>=0)
+>>>
+
      +
      + +

      12.2 %contract and classes

      + + +

      +The %contract directive can also be applied to class methods and constructors. For example: +

      + +
      +
      +%contract Foo::bar(int x, int y) {
+require:
+   x > 0;
+ensure:
+   bar > 0;
+}
+
+%contract Foo::Foo(int a) {
+require:
+   a > 0;
+}
+
+class Foo {
+public:
+    Foo(int);
+    int bar(int, int);
+};
+
      +
      + +

      +The way in which %contract is applied is exactly the same as the %feature directive. +Thus, any contract that you specified for a base class will also be attached to inherited methods. For example: +

      + +
      +
      +class Spam : public Foo {
+public:
+   int bar(int,int);    // Gets contract defined for Foo::bar(int,int)
+};
+
      +
      + +

      +In addition to this, separate contracts can be applied to both the base class and a derived class. For example: +

      + +
      +
      +%contract Foo::bar(int x, int) {
+require:
+    x > 0;
+}
+
+%contract Spam::bar(int, int y) {
+require:
+    y > 0;
+}
+
+class Foo {
+public:
+    int bar(int,int);   // Gets Foo::bar contract.
+};
+
+class Spam : public Foo {
+public:
+     int bar(int,int);   // Gets Foo::bar and Spam::bar contract
+};
+
      +
      + +

      +When more than one contract is applied, the conditions specified in a +"require:" section are combined together using a logical-AND operation. +In other words conditions specified for the base class and conditions +specified for the derived class all must hold. In the above example, +this means that both the arguments to Spam::bar must be positive. +

      + +

      12.3 Constant aggregation and %aggregate_check

      + + +

      +Consider an interface file that contains the following code: +

      + +
      +
      +#define  UP     1
+#define  DOWN   2
+#define  RIGHT  3
+#define  LEFT   4
+
+void move(SomeObject *, int direction, int distance);
+
      +
      + +

      +One thing you might want to do is impose a constraint on the direction parameter to +make sure it's one of a few accepted values. To do that, SWIG provides an easy to +use macro %aggregate_check() that works like this: +

      + +
      +
      +%aggregate_check(int, check_direction, UP, DOWN, LEFT, RIGHT);
+
      +
      + +

      +This merely defines a utility function of the form +

      + +
      +
      +int check_direction(int x);
+
      +
      + +

      +That checks the argument x to see if it is one of the values listed. This utility +function can be used in contracts. For example: +

      + +
      +
      +%aggregate_check(int, check_direction, UP, DOWN, RIGHT, LEFT);
+
+%contract move(SomeObject *, int direction, in) {
+require:
+     check_direction(direction);
+}
+
+#define  UP     1
+#define  DOWN   2
+#define  RIGHT  3
+#define  LEFT   4
+
+void move(SomeObject *, int direction, int distance);
+
      +
      + +

      +Alternatively, it can be used in typemaps and other directives. For example: +

      + +
      +
      +%aggregate_check(int, check_direction, UP, DOWN, RIGHT, LEFT);
+
+%typemap(check) int direction {
+    if (!check_direction($1)) SWIG_exception(SWIG_ValueError, "Bad direction");
+}
+
+#define  UP     1
+#define  DOWN   2
+#define  RIGHT  3
+#define  LEFT   4
+
+void move(SomeObject *, int direction, int distance);
+
      +
      + +

      +Regrettably, there is no automatic way to perform similar checks with enums values. Maybe in a future +release. +

      + +

      12.4 Notes

      + + +

      +Contract support was implemented by Songyan (Tiger) Feng and first appeared +in SWIG-1.3.20. +

      + + + diff --git a/Doc/Manual/Customization.html b/Doc/Manual/Customization.html new file mode 100644 index 0000000..ec73e54 --- /dev/null +++ b/Doc/Manual/Customization.html @@ -0,0 +1,1147 @@ + + + +Customization Features + + + + +

      11 Customization Features

      + +
      + +
      + + + + +

      +In many cases, it is desirable to change the default wrapping of +particular declarations in an interface. For example, you might want +to provide hooks for catching C++ exceptions, add assertions, or +provide hints to the underlying code generator. This chapter +describes some of these customization techniques. First, a discussion +of exception handling is presented. Then, a more general-purpose +customization mechanism known as "features" is described. +

      + +

      11.1 Exception handling with %exception

      + + +

      +The %exception directive allows you to define a general purpose exception +handler. For example, you can specify the following: +

      + +
      +%exception {
+    try {
+        $action
+    }
+    catch (RangeError) {
+        PyErr_SetString(PyExc_IndexError,"index out-of-bounds");
+        return NULL;
+    }
+}
+
      + +

      +When defined, the code enclosed in braces is inserted directly into the low-level wrapper +functions. The special variable $action is one of a few +%exception special variable +supported and gets replaced with the actual operation +to be performed (a function call, method invocation, attribute access, etc.). An exception handler +remains in effect until it is explicitly deleted. This is done by using either %exception +or %noexception with no code. For example: +

      + +
      +%exception;   // Deletes any previously defined handler
+
      + +

      +Compatibility note: Previous versions of SWIG used a special directive %except +for exception handling. That directive is deprecated--%exception +provides the same functionality, but is substantially more flexible. +

      + +

      11.1.1 Handling exceptions in C code

      + + +

      +C has no formal exception handling mechanism so there are several approaches that might be +used. A somewhat common technique is to simply set a special error code. For example: +

      + +
      +/* File : except.c */
+
+static char error_message[256];
+static int error_status = 0;
+
+void throw_exception(char *msg) {
+	strncpy(error_message,msg,256);
+	error_status = 1;
+}
+
+void clear_exception() {
+	error_status = 0;
+}
+char *check_exception() {
+	if (error_status) return error_message;
+	else return NULL;
+}
+
+
      + +

      +To use these functions, functions simply call +throw_exception() to indicate an error occurred. For example +:

      + +
      +double inv(double x) {
+	if (x != 0) return 1.0/x;
+	else {
+		throw_exception("Division by zero");
+		return 0;
+	}
+}
+
+
      + +

      +To catch the exception, you can write a simple exception handler such +as the following (shown for Perl5) :

      + +
      +%exception {
+    char *err;
+    clear_exception();
+    $action
+    if ((err = check_exception())) {
+       croak(err);
+    }
+}
+
      + +

      +In this case, when an error occurs, it is translated into a Perl error. +Each target language has its own approach to creating a runtime error/exception in +and for Perl it is the croak method shown above. +

      + +

      11.1.2 Exception handling with longjmp()

      + + +

      +Exception handling can also be added to C code using the +<setjmp.h> library. Here is a minimalistic implementation that +relies on the C preprocessor : +

      + +
      +/* File : except.c
+   Just the declaration of a few global variables we're going to use */
+
+#include <setjmp.h>
+jmp_buf exception_buffer;
+int exception_status;
+
+/* File : except.h */
+#include <setjmp.h>
+extern jmp_buf exception_buffer;
+extern int exception_status;
+
+#define try if ((exception_status = setjmp(exception_buffer)) == 0)
+#define catch(val) else if (exception_status == val)
+#define throw(val) longjmp(exception_buffer,val)
+#define finally else
+
+/* Exception codes */
+
+#define RangeError     1
+#define DivisionByZero 2
+#define OutOfMemory    3
+
+
      + +

      +Now, within a C program, you can do the following :

      + +
      +double inv(double x) {
+	if (x) return 1.0/x;
+	else throw(DivisionByZero);
+}
+
+
      + +

      +Finally, to create a SWIG exception handler, write the following :

      + +
      +%{
+#include "except.h"
+%}
+
+%exception {
+	try {
+		$action
+	} catch(RangeError) {
+		croak("Range Error");
+	} catch(DivisionByZero) {
+		croak("Division by zero");
+	} catch(OutOfMemory) {
+		croak("Out of memory");
+	} finally {
+		croak("Unknown exception");
+	}
+}
+
      + +

      +Note: This implementation is only intended to illustrate the general idea. To make it work better, you'll need to +modify it to handle nested try declarations. +

      + +

      11.1.3 Handling C++ exceptions

      + + +

      +Handling C++ exceptions is also straightforward. For example: +

      + +
      +%exception {
+	try {
+		$action
+	} catch(RangeError) {
+		croak("Range Error");
+	} catch(DivisionByZero) {
+		croak("Division by zero");
+	} catch(OutOfMemory) {
+		croak("Out of memory");
+	} catch(...) {
+		croak("Unknown exception");
+	}
+}
+
+
      + +

      +The exception types need to be declared as classes elsewhere, possibly +in a header file :

      + +
      +class RangeError {};
+class DivisionByZero {};
+class OutOfMemory {};
+
      +
      + +

      11.1.4 Exception handlers for variables

      + + +

      +By default all variables will ignore %exception, so it is effectively turned off for all variables wrappers. +This applies to global variables, member variables and static member variables. +The approach is certainly a logical one when wrapping variables in C. +However, in C++, it is quite possible for an exception to be thrown while the variable is being assigned. +To ensure %exception is used when wrapping variables, it needs to be 'turned on' using the %allowexception feature. +Note that %allowexception is just a macro for %feature("allowexcept"), that is, it is a feature called "allowexcept". +Any variable which has this feature attached to it, will then use the %exception feature, but of course, +only if there is a %exception attached to the variable in the first place. +The %allowexception feature works like any other feature and so can be used globally or for selective variables. +

      + +
      +
      +%allowexception;                // turn on globally
+%allowexception Klass::MyVar;   // turn on for a specific variable
+
+%noallowexception Klass::MyVar; // turn off for a specific variable
+%noallowexception;              // turn off globally
+
      +
      + +

      11.1.5 Defining different exception handlers

      + + +

      +By default, the %exception directive creates an exception +handler that is used for all wrapper functions that follow it. Unless +there is a well-defined (and simple) error handling mechanism in place, +defining one universal exception handler may be unwieldy and result +in excessive code bloat since the handler is inlined into each wrapper function. +

      + +

      +To fix this, you can be more selective about how you use the +%exception directive. One approach is to only place it around +critical pieces of code. For example: +

      + +
      +%exception {
+	... your exception handler ...
+}
+/* Define critical operations that can throw exceptions here */
+
+%exception;
+
+/* Define non-critical operations that don't throw exceptions */
+
      + +

      +More precise control over exception handling can be obtained by attaching an exception handler +to specific declaration name. For example: +

      + +
      +
      +%exception allocate {
+    try {
+        $action
+    } 
+    catch (MemoryError) {
+        croak("Out of memory");
+    }
+}
+
      +
      + +

      +In this case, the exception handler is only attached to declarations +named "allocate". This would include both global and member +functions. The names supplied to %exception follow the same +rules as for %rename described in the section on +Ambiguity resolution and renaming. +For example, if you wanted to define +an exception handler for a specific class, you might write this: +

      + +
      +
      +%exception Object::allocate {
+    try {
+        $action
+    } 
+    catch (MemoryError) {
+        croak("Out of memory");
+    }
+}
+
      +
      + +

      +When a class prefix is supplied, the exception handler is applied to the corresponding declaration +in the specified class as well as for identically named functions appearing in derived classes. +

      + +

      +%exception can even be used to pinpoint a precise declaration when overloading is used. For example: +

      + +
      +
      +%exception Object::allocate(int) {
+    try {
+        $action
+    } 
+    catch (MemoryError) {
+        croak("Out of memory");
+    }
+}
+
      +
      + +

      +Attaching exceptions to specific declarations is a good way to reduce code bloat. It can also be a useful way +to attach exceptions to specific parts of a header file. For example: +

      + +
      +
      +%module example
+%{
+#include "someheader.h"
+%}
+
+// Define a few exception handlers for specific declarations
+%exception Object::allocate(int) {
+    try {
+        $action
+    } 
+    catch (MemoryError) {
+        croak("Out of memory");
+    }
+}
+
+%exception Object::getitem {
+    try {
+       $action
+    }
+    catch (RangeError) {
+       croak("Index out of range");
+    }
+}
+...
+// Read a raw header file
+%include "someheader.h"
+
      +
      + +

      +Compatibility note: The %exception directive replaces +the functionality provided by the deprecated "except" typemap. +The typemap would allow exceptions to be thrown in the target +language based on the return type of a function and +was intended to be a mechanism for pinpointing specific +declarations. However, it never really worked that well and the new +%exception directive is much better. +

      + +

      11.1.6 Special variables for %exception

      + + +

      +The %exception directive supports a few special variables which are placeholders for +code substitution. +The following table shows the available special variables and details what the special +variables are replaced with. +

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      $actionThe actual operation to be performed (a function call, method invocation, variable access, etc.)
      $symnameThe symbol name used internally by SWIG
      $overnameThe extra mangling used in the symbol name for overloaded method. Expands to nothing if the wrapped method is not overloaded.
      $wrapnameThe language specific wrapper name (usually a C function name exported from the shared object/dll)
      $declThe fully qualified C/C++ declaration of the method being wrapped without the return type
      $fulldeclThe fully qualified C/C++ declaration of the method being wrapped including the return type
      + +

      +The special variables are often used in situations where method calls are logged. Exactly which form of the method call needs logging is up to individual requirements, but the example code below shows all the possible expansions, plus how an exception message could be tailored to show the C++ method declaration: +

      + +
      +%exception Special::something {
+  log("symname: $symname");
+  log("overname: $overname");
+  log("wrapname: $wrapname");
+  log("decl: $decl");
+  log("fulldecl: $fulldecl");
+  try {
+    $action
+  } 
+  catch (MemoryError) {
+      croak("Out of memory in $decl");
+  }
+}
+void log(const char *message);
+struct Special {
+  void something(const char *c);
+  void something(int i);
+};
+
      + +

      +Below shows the expansions for the 1st of the overloaded something wrapper methods for Perl: +

      + +
      +  log("symname: Special_something");
+  log("overname: __SWIG_0");
+  log("wrapname: _wrap_Special_something__SWIG_0");
+  log("decl: Special::something(char const *)");
+  log("fulldecl: void Special::something(char const *)");
+  try {
+    (arg1)->something((char const *)arg2);
+  } 
+  catch (MemoryError) {
+    croak("Out of memory in Special::something(char const *)");
+  }
+
      + + +

      11.1.7 Using The SWIG exception library

      + + +

      +The exception.i library file provides support for creating +language independent exceptions in your interfaces. To use it, simply +put an "%include exception.i" in your interface file. This +creates a function SWIG_exception() that can be used to raise +common scripting language exceptions in a portable manner. For example :

      + +
      +// Language independent exception handler
+%include exception.i       
+
+%exception {
+    try {
+        $action
+    } catch(RangeError) {
+        SWIG_exception(SWIG_ValueError, "Range Error");
+    } catch(DivisionByZero) {
+        SWIG_exception(SWIG_DivisionByZero, "Division by zero");
+    } catch(OutOfMemory) {
+        SWIG_exception(SWIG_MemoryError, "Out of memory");
+    } catch(...) {
+        SWIG_exception(SWIG_RuntimeError,"Unknown exception");
+    }
+}
+
+
      + +

      +As arguments, SWIG_exception() takes an error type code (an +integer) and an error message string. The currently supported error +types are :

      + +
      +SWIG_UnknownError
+SWIG_IOError
+SWIG_RuntimeError
+SWIG_IndexError
+SWIG_TypeError
+SWIG_DivisionByZero
+SWIG_OverflowError
+SWIG_SyntaxError
+SWIG_ValueError
+SWIG_SystemError
+SWIG_AttributeError
+SWIG_MemoryError
+SWIG_NullReferenceError
+
      + +

      +Since the SWIG_exception() function is defined at the C-level +it can be used elsewhere in SWIG. This includes typemaps and helper +functions. +

      + +

      11.2 Object ownership and %newobject

      + + +

      +A common problem in some applications is managing proper ownership of objects. For +example, consider a function like this: +

      + +
      +
      +Foo *blah() {
+   Foo *f = new Foo();
+   return f;
+}
+
      +
      + +

      +If you wrap the function blah(), SWIG has no idea that the +return value is a newly allocated object. As a result, the resulting +extension module may produce a memory leak (SWIG is conservative and +will never delete objects unless it knows for certain that the +returned object was newly created). +

      + +

      +To fix this, you can provide an extra hint to the code generator using +the %newobject directive. For example: +

      + +
      +
      +%newobject blah;
+Foo *blah();
+
      +
      + +

      +%newobject works exactly like %rename and %exception. In other words, +you can attach it to class members and parameterized declarations as before. For example: +

      + +
      +
      +%newobject ::blah();                   // Only applies to global blah
+%newobject Object::blah(int,double);   // Only blah(int,double) in Object
+%newobject *::copy;                    // Copy method in all classes
+...
+
      +
      + +

      +When %newobject is supplied, many language modules will +arrange to take ownership of the return value. This allows the value +to be automatically garbage-collected when it is no longer in use. However, +this depends entirely on the target language (a language module may also choose to ignore +the %newobject directive). +

      + +

      +Closely related to %newobject is a special typemap. The "newfree" typemap +can be used to deallocate a newly allocated return value. It is only available on +methods for which %newobject has been applied and is commonly used to clean-up string +results. For example: +

      + +
      +
      +%typemap(newfree) char * "free($1);";
+...
+%newobject strdup;
+...
+char *strdup(const char *s);
+
      +
      + +

      +In this case, the result of the function is a string in the target language. Since this string +is a copy of the original result, the data returned by strdup() is no longer needed. +The "newfree" typemap in the example simply releases this memory. +

      + +

      +As a complement to the %newobject, from SWIG 1.3.28, you can +use the %delobject directive. For example, if you have two +methods, one to create objects and one to destroy them, you can use: +

      + +
      +
      +%newobject create_foo;
+%delobject destroy_foo;
+...
+Foo *create_foo();
+void destroy_foo(Foo *foo);
+
      +
      + +

      or in a member method as:

      +
      +
      +%delobject Foo::destroy;
+
+class Foo {
+public:
+  void destroy() { delete this;}
+
+private:
+  ~Foo();
+};
+
      +
      + +

      +%delobject instructs SWIG that the first argument passed to +the method will be destroyed, and therefore, the target language +should not attempt to deallocate it twice. This is similar to use the +DISOWN typemap in the first method argument, and in fact, it also +depends on the target language on implementing the 'disown' mechanism +properly. +

      + +

      +Compatibility note: Previous versions of SWIG had a special %new directive. However, unlike %newobject, +it only applied to the next declaration. For example: +

      + +
      +
      +%new char *strdup(const char *s);
+
      +
      + +

      +For now this is still supported but is deprecated. +

      + +

      +How to shoot yourself in the foot: The %newobject directive is not a declaration modifier like the old +%new directive. Don't write code like this: +

      + +
      +
      +%newobject
+char *strdup(const char *s);
+
      +
      +

      +The results might not be what you expect. +

      + +

      11.3 Features and the %feature directive

      + + +

      +Both %exception and %newobject are examples of a +more general purpose customization mechanism known as "features." A +feature is simply a user-definable property that is attached to +specific declarations. Features are attached +using the %feature directive. For example: +

      + +
      +
      +%feature("except") Object::allocate {
+    try {
+        $action
+    } 
+    catch (MemoryError) {
+        croak("Out of memory");
+    }
+}
+
+%feature("new","1") *::copy;
+
      +
      + +

      +In fact, the %exception and %newobject directives are really nothing more than macros +involving %feature: +

      + +
      +
      +#define %exception %feature("except")
+#define %newobject %feature("new","1")
+
      +
      + +

      +The name matching rules outlined in the Ambiguity resolution and renaming +section applies to all %feature directives. +In fact the the %rename directive is just a special form of %feature. +The matching rules mean that features are very flexible and can be applied with +pinpoint accuracy to specific declarations if needed. +Additionally, if no declaration name is given, a global feature is said to be defined. +This feature is then +attached to every declaration that follows. This is how global exception handlers +are defined. For example: +

      + +
      +
      +/* Define a global exception handler */
+%feature("except") {
+   try {
+     $action
+   }
+   ...
+}
+
+... bunch of declarations ...
+
      +
      + +

      +The %feature directive can be used with different syntax. +The following are all equivalent: +

      + +
      +
      +%feature("except") Object::method { $action };
+%feature("except") Object::method %{ $action %};
+%feature("except") Object::method " $action ";
+%feature("except","$action") Object::method;
+
      +
      + +

      +The syntax in the first variation will generate the { } delimiters used whereas the other variations will not. +

      + +

      11.3.1 Feature attributes

      + + +

      +The %feature directive also accepts XML style attributes in the same way that typemaps do. +Any number of attributes can be specified. +The following is the generic syntax for features: +

      + +
      +
      +%feature("name","value", attribute1="AttributeValue1") symbol;
+%feature("name", attribute1="AttributeValue1") symbol {value};
+%feature("name", attribute1="AttributeValue1") symbol %{value%};
+%feature("name", attribute1="AttributeValue1") symbol "value";
+
      +
      + +

      +More than one attribute can be specified using a comma separated list. +The Java module is an example that uses attributes in %feature("except"). +The throws attribute specifies the name of a Java class to add to a proxy method's throws clause. +In the following example, MyExceptionClass is the name of the Java class for adding to the throws clause. +

      + +
      +
      +%feature("except", throws="MyExceptionClass") Object::method { 
+   try {
+     $action
+   } catch (...) {
+     ... code to throw a MyExceptionClass Java exception ...
+   }
+};
+
      +
      + +

      +Further details can be obtained from the Java exception handling section. +

      + +

      11.3.2 Feature flags

      + + +

      +Feature flags are used to enable or disable a particular feature. Feature flags are a common but simple usage of %feature +and the feature value should be either 1 to enable or 0 to disable the feature. +

      + +
      +
      +%feature("featurename")          // enables feature
+%feature("featurename", "1")     // enables feature
+%feature("featurename", "x")     // enables feature
+%feature("featurename", "0")     // disables feature
+%feature("featurename", "")      // clears feature
+
      +
      + +

      +Actually any value other than zero will enable the feature. +Note that if the value is omitted completely, the default value becomes 1, thereby enabling the feature. +A feature is cleared by specifying no value, see Clearing features. +The %immutable directive described in the Creating read-only variables section, +is just a macro for %feature("immutable"), and can be used to demonstrates feature flags: +

      + +
      +
      +                                // features are disabled by default
+int red;                        // mutable
+
+%feature("immutable");          // global enable
+int orange;                     // immutable
+
+%feature("immutable","0");      // global disable
+int yellow;                     // mutable
+
+%feature("immutable","1");      // another form of global enable
+int green;                      // immutable
+
+%feature("immutable","");       // clears the global feature
+int blue;                       // mutable
+
      +
      + +

      +Note that features are disabled by default and must be explicitly enabled either globally or by specifying a targeted declaration. +The above intersperses SWIG directives with C code. Of course you can target features explicitly, so the above could also be rewritten as: +

      + +
      +
      +%feature("immutable","1") orange;
+%feature("immutable","1") green;
+int red;                        // mutable
+int orange;                     // immutable
+int yellow;                     // mutable
+int green;                      // immutable
+int blue;                       // mutable
+
      +
      + +

      +The above approach allows for the C declarations to be separated from the SWIG directives for when the C declarations are parsed from a C header file. +The logic above can of course be inverted and rewritten as: +

      + +
      +
      +%feature("immutable","1");
+%feature("immutable","0") red;
+%feature("immutable","0") yellow;
+%feature("immutable","0") blue;
+int red;                        // mutable
+int orange;                     // immutable
+int yellow;                     // mutable
+int green;                      // immutable
+int blue;                       // mutable
+
      +
      + +

      +As hinted above for %immutable, most feature flags can also be specified via alternative syntax. The alternative syntax is just a macro +in the swig.swg Library file. The following shows the alternative syntax for the imaginary featurename feature: +

      + +
      +
      +%featurename       // equivalent to %feature("featurename", "1") ie enables feature
+%nofeaturename     // equivalent to %feature("featurename", "0") ie disables feature
+%clearfeaturename  // equivalent to %feature("featurename", "")  ie clears feature
+
      +
      + +

      +The concept of clearing features is discussed next. +

      + +

      11.3.3 Clearing features

      + + +

      +A feature stays in effect until it is explicitly cleared. A feature is cleared by +supplying a %feature directive with no value. For example %feature("name",""). +A cleared feature means that any feature exactly matching any previously defined feature is no longer used in the name matching rules. +So if a feature is cleared, it might mean that another name matching rule will apply. +To clarify, let's consider the except feature again (%exception): +

      + +
      +
      +// Define global exception handler
+%feature("except") {
+    try {
+        $action
+    } catch (...) {
+        croak("Unknown C++ exception");
+    }
+}
+
+// Define exception handler for all clone methods to log the method calls
+%feature("except") *::clone() {
+    try {
+        logger.info("$action");
+        $action
+    } catch (...) {
+        croak("Unknown C++ exception");
+    }
+}
+
+... initial set of class declarations with clone methods ...
+
+// clear the previously defined feature
+%feature("except","") *::clone();
+
+... final set of class declarations with clone methods ...
+
      +
      + +

      +In the above scenario, the initial set of clone methods will log all method invocations from the target language. +This specific feature is cleared for the final set of clone methods. +However, these clone methods will still have an exception handler (without logging) as the next best feature match for them is the global exception handler. +

      + +

      +Note that clearing a feature is not always the same as disabling it. +Clearing the feature above with %feature("except","") *::clone() is not the same as specifying +%feature("except","0") *::clone(). The former will disable the feature for clone methods - +the feature is still a better match than the global feature. +If on the other hand, no global exception handler had been defined at all, +then clearing the feature would be the same as disabling it as no other feature would have matched. +

      + +

      +Note that the feature must match exactly for it to be cleared by any previously defined feature. +For example the following attempt to clear the initial feature will not work: +

      + +
      +
      +%feature("except") clone() { logger.info("$action"); $action }
+%feature("except","") *::clone();
+
      +
      + +

      +but this will: +

      + +
      +
      +%feature("except") clone() { logger.info("$action"); $action }
+%feature("except","") clone();
+
      +
      + +

      +SWIG provides macros for disabling and clearing features. Many of these can be found in the swig.swg library file. +The typical pattern is to define three macros; one to define the feature itself, one to disable the feature and one to clear the feature. +The three macros below show this for the "except" feature: +

      + +
      +
      +#define %exception      %feature("except")
+#define %noexception    %feature("except","0")
+#define %clearexception %feature("except","")
+
      +
      + +

      11.3.4 Features and default arguments

      + + +

      +SWIG treats methods with default arguments as separate overloaded methods as detailed +in the default arguments section. +Any %feature targeting a method with default arguments +will apply to all the extra overloaded methods that SWIG generates if the +default arguments are specified in the feature. If the default arguments are +not specified in the feature, then the feature will match that exact +wrapper method only and not the extra overloaded methods that SWIG generates. +For example: +

      + +
      +
      +%feature("except") void hello(int i=0, double d=0.0) { ... }
+void hello(int i=0, double d=0.0);
+
      +
      + +

      +will apply the feature to all three wrapper methods, that is: +

      + +
      +
      +void hello(int i, double d);
+void hello(int i);
+void hello();
+
      +
      + +

      +If the default arguments are not specified in the feature: +

      + +
      +
      +%feature("except") void hello(int i, double d) { ... }
+void hello(int i=0, double d=0.0);
+
      +
      + +

      +then the feature will only apply to this wrapper method: +

      + +
      +
      +void hello(int i, double d);
+
      +
      + +

      +and not these wrapper methods: +

      + +
      +
      +void hello(int i);
+void hello();
+
      +
      + +

      +If compactdefaultargs are being used, then the difference between +specifying or not specifying default arguments in a feature is not applicable as just one wrapper is generated. +

      + +

      +Compatibility note: The different behaviour of features specified with or without default arguments was introduced +in SWIG-1.3.23 when the approach to wrapping methods with default arguments was changed. +

      + +

      11.3.5 Feature example

      + + +

      +As has been shown earlier, the intended use for the %feature directive is as a highly flexible customization mechanism that can be used to annotate +declarations with additional information for use by specific target language modules. Another example is +in the Python module. You might use %feature to rewrite proxy/shadow class code as follows: +

      + +
      +
      +%module example
+%rename(bar_id) bar(int,double);
+
+// Rewrite bar() to allow some nice overloading
+
+%feature("shadow") Foo::bar(int) %{
+def bar(*args):
+    if len(args) == 3:
+         return apply(examplec.Foo_bar_id,args)
+    return apply(examplec.Foo_bar,args)
+%}
+    
+class Foo {
+public:
+    int bar(int x);
+    int bar(int x, double y);
+}
+
      +
      + +

      +Further details of %feature usage is described in the documentation for specific language modules. +

      + + + diff --git a/Doc/Manual/Extending.html b/Doc/Manual/Extending.html new file mode 100644 index 0000000..0ebaeaa --- /dev/null +++ b/Doc/Manual/Extending.html @@ -0,0 +1,3788 @@ + + + +Extending SWIG to support new languages + + + + +

      35 Extending SWIG to support new languages

      + +
      + +
      + + + + +

      35.1 Introduction

      + + +

      +This chapter describes SWIG's internal organization and the process by which +new target languages can be developed. First, a brief word of warning---SWIG +is continually evolving. +The information in this chapter is mostly up to +date, but changes are ongoing. Expect a few inconsistencies. +

      + +

      +Also, this chapter is not meant to be a hand-holding tutorial. As a starting point, +you should probably look at one of SWIG's existing modules. +

      + +

      35.2 Prerequisites

      + + +

      +In order to extend SWIG, it is useful to have the following background: +

      + +
        +
      • An understanding of the C API for the target language. +
      • A good grasp of the C++ type system. +
      • An understanding of typemaps and some of SWIG's advanced features. +
      • Some familiarity with writing C++ (language modules are currently written in C++). +
      + +

      +Since SWIG is essentially a specialized C++ compiler, it may be useful +to have some prior experience with compiler design (perhaps even a +compilers course) to better understand certain parts of the system. A +number of books will also be useful. For example, "The C Programming +Language" by Kernighan and Ritchie (a.k.a, "K&R") and the C++ standard, +"ISO/IEC 14882 Programming Languages - C++" will be of great use. +

      + +

      +Also, it is useful to keep in mind that SWIG primarily operates as an +extension of the C++ type system. At first glance, this might not be +obvious, but almost all SWIG directives as well as the low-level generation of +wrapper code are driven by C++ datatypes. +

      + +

      35.3 The Big Picture

      + + +

      +SWIG is a special purpose compiler that parses C++ declarations to +generate wrapper code. To make this conversion possible, SWIG makes +three fundamental extensions to the C++ language: +

      + +
        +
      • Typemaps. Typemaps are used to define the +conversion/marshalling behavior of specific C++ datatypes. All type conversion in SWIG is +based on typemaps. Furthermore, the association of typemaps to datatypes utilizes an advanced pattern matching +mechanism that is fully integrated with the C++ type system. +
        • + +
      • Declaration Annotation. To customize wrapper code +generation, most declarations can be annotated with special features. +For example, you can make a variable read-only, you can ignore a +declaration, you can rename a member function, you can add exception +handling, and so forth. Virtually all of these customizations are built on top of a low-level +declaration annotator that can attach arbitrary attributes to any declaration. +Code generation modules can look for these attributes to guide the wrapping process. +
        • + +
      • Class extension. SWIG allows classes and structures to be extended with new +methods and attributes (the %extend directive). This has the effect of altering +the API in the target language and can be used to generate OO interfaces to C libraries. +
      + +

      +It is important to emphasize that virtually all SWIG features reduce to one of these three +fundamental concepts. The type system and pattern matching rules also play a critical +role in making the system work. For example, both typemaps and declaration annotation are +based on pattern matching and interact heavily with the underlying type system. +

      + +

      35.4 Execution Model

      + + +

      +When you run SWIG on an interface, processing is handled in stages by a series of system components: +

      + +
        +
      • An integrated C preprocessor reads a collection of configuration +files and the specified interface file into memory. The preprocessor +performs the usual functions including macro expansion and file +inclusion. However, the preprocessor also performs some transformations of the +interface. For instance, #define statements are sometimes transformed into +%constant declarations. In addition, information related to file/line number +tracking is inserted. +
        • + +
      • A C/C++ parser reads the preprocessed input and generates a full +parse tree of all of the SWIG directives and C declarations found. +The parser is responsible for many aspects of the system including +renaming, declaration annotation, and template expansion. However, the parser +does not produce any output nor does it interact with the target +language module as it runs. SWIG is not a one-pass compiler. +
        • + +
      • A type-checking pass is made. This adjusts all of the C++ typenames to properly +handle namespaces, typedefs, nested classes, and other issues related to type scoping. +
        • + +
      • A semantic pass is made on the parse tree to collect information +related to properties of the C++ interface. For example, this pass +would determine whether or not a class allows a default constructor. +
        • + +
      • A code generation pass is made using a specific target language +module. This phase is responsible for generating the actual wrapper +code. All of SWIG's user-defined modules are invoked during this +latter stage of compilation. +
        • +
      + +

      +The next few sections briefly describe some of these stages. +

      + +

      35.4.1 Preprocessing

      + + +

      +The preprocessor plays a critical role in the SWIG implementation. This is because a lot +of SWIG's processing and internal configuration is managed not by code written in C, but +by configuration files in the SWIG library. In fact, when you +run SWIG, parsing starts with a small interface file like this (note: this explains +the cryptic error messages that new users sometimes get when SWIG is misconfigured or installed +incorrectly): +

      + +
      +
      +%include "swig.swg"             // Global SWIG configuration
+%include "langconfig.swg"       // Language specific configuration
+%include "yourinterface.i"      // Your interface file
+
      +
      + +

      +The swig.swg file contains global configuration information. In addition, this file +defines many of SWIG's standard directives as macros. For instance, part of +of swig.swg looks like this: +

      + +
      +
      +...
+/* Code insertion directives such as %wrapper %{ ... %} */
+
+#define %begin       %insert("begin")
+#define %runtime     %insert("runtime")
+#define %header      %insert("header")
+#define %wrapper     %insert("wrapper")
+#define %init        %insert("init")
+
+/* Access control directives */
+
+#define %immutable   %feature("immutable","1")
+#define %mutable     %feature("immutable")
+
+/* Directives for callback functions */
+
+#define %callback(x) %feature("callback") `x`;
+#define %nocallback  %feature("callback");
+
+/* %ignore directive */
+
+#define %ignore         %rename($ignore)
+#define %ignorewarn(x)  %rename("$ignore:" x)
+...
+
      +
      + +

      +The fact that most of the standard SWIG directives are macros is +intended to simplify the implementation of the internals. For instance, +rather than having to support dozens of special directives, it is +easier to have a few basic primitives such as %feature or +%insert. +

      + +

      +The langconfig.swg file is supplied by the target +language. This file contains language-specific configuration +information. More often than not, this file provides run-time wrapper +support code (e.g., the type-checker) as well as a collection of +typemaps that define the default wrapping behavior. Note: the name of this +file depends on the target language and is usually something like python.swg +or perl5.swg. +

      + +

      +As a debugging aide, the text that SWIG feeds to its C++ parser can be +obtained by running swig -E interface.i. This output +probably isn't too useful in general, but it will show how macros have +been expanded as well as everything else that goes into the low-level +construction of the wrapper code. +

      + +

      35.4.2 Parsing

      + + +

      +The current C++ parser handles a subset of C++. Most incompatibilities with C are due to +subtle aspects of how SWIG parses declarations. Specifically, SWIG expects all C/C++ declarations to follow this general form: +

      + +
      +
      +storage type declarator initializer;
+
      +
      + +

      +storage is a keyword such as extern, +static, typedef, or virtual. type is a primitive +datatype such as int or void. type may be optionally +qualified with a qualifier such as const or volatile. declarator +is a name with additional type-construction modifiers attached to it (pointers, arrays, references, +functions, etc.). Examples of declarators include *x, **x, x[20], and +(*x)(int,double). The initializer may be a value assigned using = or +body of code enclosed in braces { ... }. +

      + +

      +This declaration format covers most common C++ declarations. However, the C++ standard +is somewhat more flexible in the placement of the parts. For example, it is technically legal, although +uncommon to write something like int typedef const a in your program. SWIG simply +doesn't bother to deal with this case. +

      + +

      +The other significant difference between C++ and SWIG is in the +treatment of typenames. In C++, if you have a declaration like this, +

      + +
      +
      +int blah(Foo *x, Bar *y);
+
      +
      + +

      +it won't parse correctly unless Foo and Bar have +been previously defined as types either using a class +definition or a typedef. The reasons for this are subtle, +but this treatment of typenames is normally integrated at the level of the C +tokenizer---when a typename appears, a different token is returned to the parser +instead of an identifier. +

      + +

      +SWIG does not operate in this manner--any legal identifier can be used +as a type name. The reason for this is primarily motivated by the use +of SWIG with partially defined data. Specifically, +SWIG is supposed to be easy to use on interfaces with missing type information. +

      + +

      +Because of the different treatment of typenames, the most serious +limitation of the SWIG parser is that it can't process type declarations where +an extra (and unnecessary) grouping operator is used. For example: +

      + +
      +
      +int (x);         /* A variable x */
+int (y)(int);    /* A function y */
+
      +
      + +

      +The placing of extra parentheses in type declarations like this is +already recognized by the C++ community as a potential source of +strange programming errors. For example, Scott Meyers "Effective STL" +discusses this problem in a section on avoiding C++'s "most vexing +parse." +

      + +

      +The parser is also unable to handle declarations with no return type or bare argument names. +For example, in an old C program, you might see things like this: +

      + +
      +
      +foo(a,b) {
+...
+}
+
      +
      + +

      +In this case, the return type as well as the types of the arguments +are taken by the C compiler to be an int. However, SWIG +interprets the above code as an abstract declarator for a function +returning a foo and taking types a and b as +arguments). +

      + +

      35.4.3 Parse Trees

      + + +

      +The SWIG parser produces a complete parse tree of the input file before any wrapper code +is actually generated. Each item in the tree is known as a "Node". Each node is identified +by a symbolic tag. Furthermore, a node may have an arbitrary number of children. +The parse tree structure and tag names of an interface can be displayed using swig -debug-tags. +For example: +

      + +
      +
      +$ swig -c++ -python -debug-tags example.i
+ . top (example.i:1)
+ . top . include (example.i:1)
+ . top . include . typemap (/r0/beazley/Projects/lib/swig1.3/swig.swg:71)
+ . top . include . typemap . typemapitem (/r0/beazley/Projects/lib/swig1.3/swig.swg:71)
+ . top . include . typemap (/r0/beazley/Projects/lib/swig1.3/swig.swg:83)
+ . top . include . typemap . typemapitem (/r0/beazley/Projects/lib/swig1.3/swig.swg:83)
+ . top . include (example.i:4)
+ . top . include . insert (/r0/beazley/Projects/lib/swig1.3/python/python.swg:7)
+ . top . include . insert (/r0/beazley/Projects/lib/swig1.3/python/python.swg:8)
+ . top . include . typemap (/r0/beazley/Projects/lib/swig1.3/python/python.swg:19)
+...
+ . top . include (example.i:6)
+ . top . include . module (example.i:2)
+ . top . include . insert (example.i:6)
+ . top . include . include (example.i:9)
+ . top . include . include . class (example.h:3)
+ . top . include . include . class . access (example.h:4)
+ . top . include . include . class . constructor (example.h:7)
+ . top . include . include . class . destructor (example.h:10)
+ . top . include . include . class . cdecl (example.h:11)
+ . top . include . include . class . cdecl (example.h:11)
+ . top . include . include . class . cdecl (example.h:12)
+ . top . include . include . class . cdecl (example.h:13)
+ . top . include . include . class . cdecl (example.h:14)
+ . top . include . include . class . cdecl (example.h:15)
+ . top . include . include . class (example.h:18)
+ . top . include . include . class . access (example.h:19)
+ . top . include . include . class . cdecl (example.h:20)
+ . top . include . include . class . access (example.h:21)
+ . top . include . include . class . constructor (example.h:22)
+ . top . include . include . class . cdecl (example.h:23)
+ . top . include . include . class . cdecl (example.h:24)
+ . top . include . include . class (example.h:27)
+ . top . include . include . class . access (example.h:28)
+ . top . include . include . class . cdecl (example.h:29)
+ . top . include . include . class . access (example.h:30)
+ . top . include . include . class . constructor (example.h:31)
+ . top . include . include . class . cdecl (example.h:32)
+ . top . include . include . class . cdecl (example.h:33)
+
      +
      + +

      +Even for the most simple interface, the parse tree structure is larger than you might expect. For example, in the +above output, a substantial number of nodes are actually generated by the python.swg configuration file +which defines typemaps and other directives. The contents of the user-supplied input file don't appear until the end +of the output. +

      + +

      +The contents of each parse tree node consist of a collection of attribute/value +pairs. Internally, the nodes are simply represented by hash tables. A display of +the entire parse-tree structure can be obtained using swig -debug-top <n>, where n is +the stage being processed. +There are a number of other parse tree display options, for example, swig -debug-module <n> will +avoid displaying system parse information and only display the parse tree pertaining to the user's module at +stage n of processing. +

      + +
      +
      +$ swig -c++ -python -debug-module 4 example.i
+      +++ include ----------------------------------------
+      | name         - "example.i"
+
+            +++ module ----------------------------------------
+            | name         - "example"
+            |
+            +++ insert ----------------------------------------
+            | code         - "\n#include \"example.h\"\n"
+            |
+            +++ include ----------------------------------------
+            | name         - "example.h"
+
+                  +++ class ----------------------------------------
+                  | abstract     - "1"
+                  | sym:name     - "Shape"
+                  | name         - "Shape"
+                  | kind         - "class"
+                  | symtab       - 0x40194140
+                  | sym:symtab   - 0x40191078
+
+                        +++ access ----------------------------------------
+                        | kind         - "public"
+                        |
+                        +++ constructor ----------------------------------------
+                        | sym:name     - "Shape"
+                        | name         - "Shape"
+                        | decl         - "f()."
+                        | code         - "{\n    nshapes++;\n  }"
+                        | sym:symtab   - 0x40194140
+                        |
+                        +++ destructor ----------------------------------------
+                        | sym:name     - "~Shape"
+                        | name         - "~Shape"
+                        | storage      - "virtual"
+                        | code         - "{\n    nshapes--;\n  }"
+                        | sym:symtab   - 0x40194140
+                        |
+                        +++ cdecl ----------------------------------------
+                        | sym:name     - "x"
+                        | name         - "x"
+                        | decl         - ""
+                        | type         - "double"
+                        | sym:symtab   - 0x40194140
+                        |
+                        +++ cdecl ----------------------------------------
+                        | sym:name     - "y"
+                        | name         - "y"
+                        | decl         - ""
+                        | type         - "double"
+                        | sym:symtab   - 0x40194140
+                        |
+                        +++ cdecl ----------------------------------------
+                        | sym:name     - "move"
+                        | name         - "move"
+                        | decl         - "f(double,double)."
+                        | parms        - double ,double
+                        | type         - "void"
+                        | sym:symtab   - 0x40194140
+                        |
+                        +++ cdecl ----------------------------------------
+                        | sym:name     - "area"
+                        | name         - "area"
+                        | decl         - "f(void)."
+                        | parms        - void
+                        | storage      - "virtual"
+                        | value        - "0"
+                        | type         - "double"
+                        | sym:symtab   - 0x40194140
+                        |
+                        +++ cdecl ----------------------------------------
+                        | sym:name     - "perimeter"
+                        | name         - "perimeter"
+                        | decl         - "f(void)."
+                        | parms        - void
+                        | storage      - "virtual"
+                        | value        - "0"
+                        | type         - "double"
+                        | sym:symtab   - 0x40194140
+                        |
+                        +++ cdecl ----------------------------------------
+                        | sym:name     - "nshapes"
+                        | name         - "nshapes"
+                        | decl         - ""
+                        | storage      - "static"
+                        | type         - "int"
+                        | sym:symtab   - 0x40194140
+                        |
+                  +++ class ----------------------------------------
+                  | sym:name     - "Circle"
+                  | name         - "Circle"
+                  | kind         - "class"
+                  | bases        - 0x40194510
+                  | symtab       - 0x40194538
+                  | sym:symtab   - 0x40191078
+
+                        +++ access ----------------------------------------
+                        | kind         - "private"
+                        |
+                        +++ cdecl ----------------------------------------
+                        | name         - "radius"
+                        | decl         - ""
+                        | type         - "double"
+                        |
+                        +++ access ----------------------------------------
+                        | kind         - "public"
+                        |
+                        +++ constructor ----------------------------------------
+                        | sym:name     - "Circle"
+                        | name         - "Circle"
+                        | parms        - double
+                        | decl         - "f(double)."
+                        | code         - "{ }"
+                        | sym:symtab   - 0x40194538
+                        |
+                        +++ cdecl ----------------------------------------
+                        | sym:name     - "area"
+                        | name         - "area"
+                        | decl         - "f(void)."
+                        | parms        - void
+                        | storage      - "virtual"
+                        | type         - "double"
+                        | sym:symtab   - 0x40194538
+                        |
+                        +++ cdecl ----------------------------------------
+                        | sym:name     - "perimeter"
+                        | name         - "perimeter"
+                        | decl         - "f(void)."
+                        | parms        - void
+                        | storage      - "virtual"
+                        | type         - "double"
+                        | sym:symtab   - 0x40194538
+                        |
+                  +++ class ----------------------------------------
+                  | sym:name     - "Square"
+                  | name         - "Square"
+                  | kind         - "class"
+                  | bases        - 0x40194760
+                  | symtab       - 0x40194788
+                  | sym:symtab   - 0x40191078
+
+                        +++ access ----------------------------------------
+                        | kind         - "private"
+                        |
+                        +++ cdecl ----------------------------------------
+                        | name         - "width"
+                        | decl         - ""
+                        | type         - "double"
+                        |
+                        +++ access ----------------------------------------
+                        | kind         - "public"
+                        |
+                        +++ constructor ----------------------------------------
+                        | sym:name     - "Square"
+                        | name         - "Square"
+                        | parms        - double
+                        | decl         - "f(double)."
+                        | code         - "{ }"
+                        | sym:symtab   - 0x40194788
+                        |
+                        +++ cdecl ----------------------------------------
+                        | sym:name     - "area"
+                        | name         - "area"
+                        | decl         - "f(void)."
+                        | parms        - void
+                        | storage      - "virtual"
+                        | type         - "double"
+                        | sym:symtab   - 0x40194788
+                        |
+                        +++ cdecl ----------------------------------------
+                        | sym:name     - "perimeter"
+                        | name         - "perimeter"
+                        | decl         - "f(void)."
+                        | parms        - void
+                        | storage      - "virtual"
+                        | type         - "double"
+                        | sym:symtab   - 0x40194788
+
      +
      + +

      35.4.4 Attribute namespaces

      + + +

      +Attributes of parse tree nodes are often prepended with a namespace qualifier. +For example, the attributes +sym:name and sym:symtab are attributes related to +symbol table management and are prefixed with sym:. As a +general rule, only those attributes which are directly related to the raw declaration +appear without a prefix (type, name, declarator, etc.). +

      + +

      +Target language modules may add additional attributes to nodes to assist the generation +of wrapper code. The convention for doing this is to place these attributes in a namespace +that matches the name of the target language. For example, python:foo or +perl:foo. +

      + +

      35.4.5 Symbol Tables

      + + +

      +During parsing, all symbols are managed in the space of the target +language. The sym:name attribute of each node contains the symbol name +selected by the parser. Normally, sym:name and name +are the same. However, the %rename directive can be used to +change the value of sym:name. You can see the effect of +%rename by trying it on a simple interface and dumping the +parse tree. For example: +

      + +
      +
      +%rename(foo_i) foo(int);
+%rename(foo_d) foo(double);
+
+void foo(int);
+void foo(double);
+void foo(Bar *b);
+
      +
      + +

      +There are various debug- options that can be useful for debugging and analysing the parse tree. +For example, the debug-top <n> or debug-module <n> options will +dump the entire/top of the parse tree or the module subtree at one of the four n stages of processing. +The parse tree can be viewed after the final stage of processing by running SWIG: +

      + +
      +
      +$ swig -debug-top 4 example.i
+...
+            +++ cdecl ----------------------------------------
+            | sym:name     - "foo_i"
+            | name         - "foo"
+            | decl         - "f(int)."
+            | parms        - int
+            | type         - "void"
+            | sym:symtab   - 0x40165078
+            |
+            +++ cdecl ----------------------------------------
+            | sym:name     - "foo_d"
+            | name         - "foo"
+            | decl         - "f(double)."
+            | parms        - double
+            | type         - "void"
+            | sym:symtab   - 0x40165078
+            |
+            +++ cdecl ----------------------------------------
+            | sym:name     - "foo"
+            | name         - "foo"
+            | decl         - "f(p.Bar)."
+            | parms        - Bar *
+            | type         - "void"
+            | sym:symtab   - 0x40165078
+
      +
      + +

      +All symbol-related conflicts and complaints about overloading are based on sym:name values. +For instance, the following example uses %rename in reverse to generate a name clash. +

      + +
      +
      +%rename(foo) foo_i(int);
+%rename(foo) foo_d(double;
+
+void foo_i(int);
+void foo_d(double);
+void foo(Bar *b);
+
      +
      + +

      +When you run SWIG on this you now get: +

      + +
      +
      +$ ./swig example.i
+example.i:6. Overloaded declaration ignored.  foo_d(double )
+example.i:5. Previous declaration is foo_i(int )
+example.i:7. Overloaded declaration ignored.  foo(Bar *)
+example.i:5. Previous declaration is foo_i(int )
+
      +
      + +

      35.4.6 The %feature directive

      + + +

      +A number of SWIG directives such as %exception are implemented using the +low-level %feature directive. For example: +

      + +
      +
      +%feature("except") getitem(int) {
+  try {
+     $action
+  } catch (badindex) {
+     ...
+  }
+}
+
+...
+class Foo {
+public:
+    Object *getitem(int index) throws(badindex);
+    ...
+};
+
      +
      + +

      +The behavior of %feature is very easy to describe--it simply +attaches a new attribute to any parse tree node that matches the +given prototype. When a feature is added, it shows up as an attribute in the feature: namespace. +You can see this when running with the -debug-top 4 option. For example: +

      + +
      +
      + +++ cdecl ----------------------------------------
+ | sym:name     - "getitem"
+ | name         - "getitem"
+ | decl         - "f(int).p."
+ | parms        - int
+ | type         - "Object"
+ | feature:except - "{\n    try {\n       $action\n    } catc..."
+ | sym:symtab   - 0x40168ac8
+ |
+
      +
      + +

      +Feature names are completely arbitrary and a target language module can be +programmed to respond to any feature name that it wants to recognize. The +data stored in a feature attribute is usually just a raw unparsed string. +For example, the exception code above is simply +stored without any modifications. +

      + +

      35.4.7 Code Generation

      + + +

      +Language modules work by defining handler functions that know how to respond to +different types of parse-tree nodes. These handlers simply look at the +attributes of each node in order to produce low-level code. +

      + +

      +In reality, the generation of code is somewhat more subtle than simply +invoking handler functions. This is because parse-tree nodes might be +transformed. For example, suppose you are wrapping a class like this: +

      + +
      +
      +class Foo {
+public:
+    virtual int *bar(int x);
+};
+
      +
      + +

      +When the parser constructs a node for the member bar, it creates a raw "cdecl" node with the following +attributes: +

      + +
      +
      +nodeType    : cdecl
+name        : bar
+type        : int
+decl        : f(int).p
+parms       : int x
+storage     : virtual
+sym:name    : bar
+
      +
      + +

      +To produce wrapper code, this "cdecl" node undergoes a number of transformations. First, the node is recognized as a function declaration. This adjusts some of the type information--specifically, the declarator is joined with the base datatype to produce this: +

      + +
      +
      +nodeType    : cdecl
+name        : bar
+type        : p.int        <-- Notice change in return type
+decl        : f(int).p
+parms       : int x
+storage     : virtual
+sym:name    : bar
+
      +
      + +

      +Next, the context of the node indicates that the node is really a +member function. This produces a transformation to a low-level +accessor function like this: +

      + +
      +
      +nodeType    : cdecl
+name        : bar
+type        : int.p
+decl        : f(int).p
+parms       : Foo *self, int x            <-- Added parameter
+storage     : virtual
+wrap:action : result = (arg1)->bar(arg2)  <-- Action code added
+sym:name    : Foo_bar                     <-- Symbol name changed
+
      +
      + +

      +In this transformation, notice how an additional parameter was added +to the parameter list and how the symbol name of the node has suddenly +changed into an accessor using the naming scheme described in the +"SWIG Basics" chapter. A small fragment of "action" code has also +been generated--notice how the wrap:action attribute defines +the access to the underlying method. The data in this transformed +node is then used to generate a wrapper. +

      + +

      +Language modules work by registering handler functions for dealing with +various types of nodes at different stages of transformation. This is done by +inheriting from a special Language class and defining a collection +of virtual methods. For example, the Python module defines a class as +follows: +

      + +
      +
      +class PYTHON : public Language {
+protected:
+public :
+  virtual void main(int, char *argv[]);
+  virtual int  top(Node *);
+  virtual int  functionWrapper(Node *);
+  virtual int  constantWrapper(Node *);
+  virtual int  variableWrapper(Node *);
+  virtual int  nativeWrapper(Node *);
+  virtual int  membervariableHandler(Node *);
+  virtual int  memberconstantHandler(Node *);
+  virtual int  memberfunctionHandler(Node *);
+  virtual int  constructorHandler(Node *);
+  virtual int  destructorHandler(Node *);
+  virtual int  classHandler(Node *);
+  virtual int  classforwardDeclaration(Node *);
+  virtual int  insertDirective(Node *);
+  virtual int  importDirective(Node *);
+};
+
      +
      + +

      +The role of these functions is described shortly. +

      + +

      35.4.8 SWIG and XML

      + + +

      +Much of SWIG's current parser design was originally motivated by +interest in using XML to represent SWIG parse trees. Although XML is +not currently used in any direct manner, the parse tree structure, use +of node tags, attributes, and attribute namespaces are all influenced +by aspects of XML parsing. Therefore, in trying to understand SWIG's +internal data structures, it may be useful to keep XML in the back of +your mind as a model. +

      + +

      35.5 Primitive Data Structures

      + + +

      +Most of SWIG is constructed using three basic data structures: +strings, hashes, and lists. These data structures are dynamic in same way as +similar structures found in many scripting languages. For instance, +you can have containers (lists and hash tables) of mixed types and +certain operations are polymorphic. +

      + +

      +This section briefly describes the basic structures so that later +sections of this chapter make more sense. +

      + +

      +When describing the low-level API, the following type name conventions are +used: +

      + +
        +
      • String. A string object. +
      • Hash. A hash object. +
      • List. A list object. +
      • String_or_char. A string object or a char *. +
      • Object_or_char. An object or a char *. +
      • Object. Any object (string, hash, list, etc.) +
      + +

      +In most cases, other typenames in the source are aliases for one of these +primitive types. Specifically: +

      + +
      +
      +typedef String SwigType;
+typedef Hash   Parm;
+typedef Hash   ParmList;
+typedef Hash   Node;
+typedef Hash   Symtab;
+typedef Hash   Typetab;
+
      +
      + +

      35.5.1 Strings

      + + +

      +String *NewString(const String_or_char *val) +

      + +
      +Creates a new string with initial value val. val may +be a char * or another String object. If you want +to create an empty string, use "" for val. +
      + +

      +String *NewStringf(const char *fmt, ...) +

      + +
      +Creates a new string whose initial value is set according to a C printf style +format string in fmt. Additional arguments follow depending +on fmt. +
      + +

      +String *Copy(String *s) +

      + +
      +Make a copy of the string s. +
      + +

      +void Delete(String *s) +

      + +
      +Deletes s. +
      + +

      +int Len(const String_or_char *s) +

      + +
      +Returns the length of the string. +
      + +

      +char *Char(const String_or_char *s) +

      + +
      +Returns a pointer to the first character in a string. +
      + +

      +void Append(String *s, const String_or_char *t) +

      + +
      +Appends t to the end of string s. +
      + +

      +void Insert(String *s, int pos, const String_or_char *t) +

      + +
      +Inserts t into s at position pos. The contents +of s are shifted accordingly. The special value DOH_END +can be used for pos to indicate insertion at the end of the string (appending). +
      + +

      +int Strcmp(const String_or_char *s, const String_or_char *t) +

      + +
      +Compare strings s and t. Same as the C strcmp() +function. +
      + +

      +int Strncmp(const String_or_char *s, const String_or_char *t, int len) +

      + +
      +Compare the first len characters of strings s and t. Same as the C strncmp() +function. +
      + +

      +char *Strstr(const String_or_char *s, const String_or_char *pat) +

      + +
      +Returns a pointer to the first occurrence of pat in s. +Same as the C strstr() function. +
      + +

      +char *Strchr(const String_or_char *s, char ch) +

      + +
      +Returns a pointer to the first occurrence of character ch in s. +Same as the C strchr() function. +
      + +

      +void Chop(String *s) +

      + +
      +Chops trailing whitespace off the end of s. +
      + +

      +int Replace(String *s, const String_or_char *pat, const String_or_char *rep, int flags) +

      + +
      +

      +Replaces the pattern pat with rep in string s. +flags is a combination of the following flags:

      + +
      +
      +DOH_REPLACE_ANY       - Replace all occurrences
+DOH_REPLACE_ID        - Valid C identifiers only
+DOH_REPLACE_NOQUOTE   - Don't replace in quoted strings
+DOH_REPLACE_FIRST     - Replace first occurrence only.
+
      +
      + +

      +Returns the number of replacements made (if any). +

      + +
      + +

      35.5.2 Hashes

      + + +

      +Hash *NewHash() +

      + +
      +Creates a new empty hash table. +
      + +

      +Hash *Copy(Hash *h) +

      + +
      +Make a shallow copy of the hash h. +
      + +

      +void Delete(Hash *h) +

      + +
      +Deletes h. +
      + +

      +int Len(Hash *h) +

      + +
      +Returns the number of items in h. +
      + +

      +Object *Getattr(Hash *h, const String_or_char *key) +

      + +
      +Gets an object from h. key may be a string or +a simple char * string. Returns NULL if not found. +
      + +

      +int Setattr(Hash *h, const String_or_char *key, const Object_or_char *val) +

      + +
      +Stores val in h. key may be a string or +a simple char *. If val is not a standard +object (String, Hash, or List) it is assumed to be a char * in which +case it is used to construct a String that is stored in the hash. +If val is NULL, the object is deleted. Increases the reference count +of val. Returns 1 if this operation replaced an existing hash entry, +0 otherwise. +
      + +

      +int Delattr(Hash *h, const String_or_char *key) +

      + +
      +Deletes the hash item referenced by key. Decreases the +reference count on the corresponding object (if any). Returns 1 +if an object was removed, 0 otherwise. +
      + +

      +List *Keys(Hash *h) +

      + +
      +Returns the list of hash table keys. +
      + + +

      35.5.3 Lists

      + + +

      +List *NewList() +

      + +
      +Creates a new empty list. +
      + +

      +List *Copy(List *x) +

      + +
      +Make a shallow copy of the List x. +
      + +

      +void Delete(List *x) +

      + +
      +Deletes x. +
      + +

      +int Len(List *x) +

      + +
      +Returns the number of items in x. +
      + +

      +Object *Getitem(List *x, int n) +

      + +
      +Returns an object from x with index n. If n is +beyond the end of the list, the last item is returned. If n is +negative, the first item is returned. +
      + +

      +int *Setitem(List *x, int n, const Object_or_char *val) +

      + +
      +Stores val in x. +If val is not a standard +object (String, Hash, or List) it is assumed to be a char * in which +case it is used to construct a String that is stored in the list. +n must be in range. Otherwise, an assertion will be raised. +
      + +

      +int *Delitem(List *x, int n) +

      + +
      +Deletes item n from the list, shifting items down if necessary. +To delete the last item in the list, use the special value DOH_END +for n. +
      + +

      +void Append(List *x, const Object_or_char *t) +

      + +
      +Appends t to the end of x. If t is not +a standard object, it is assumed to be a char * and is +used to create a String object. +
      + +

      +void Insert(String *s, int pos, const Object_or_char *t) +

      + +
      +Inserts t into s at position pos. The contents +of s are shifted accordingly. The special value DOH_END +can be used for pos to indicate insertion at the end of the list (appending). +If t is not a standard object, it is assumed to be a char * +and is used to create a String object. +
      + +

      35.5.4 Common operations

      + + +The following operations are applicable to all datatypes. + +

      +Object *Copy(Object *x) +

      + +
      +Make a copy of the object x. +
      + +

      +void Delete(Object *x) +

      + +
      +Deletes x. +
      + +

      +void Setfile(Object *x, String_or_char *f) +

      + +
      +Sets the filename associated with x. Used to track +objects and report errors. +
      + +

      +String *Getfile(Object *x) +

      + +
      +Gets the filename associated with x. +
      + +

      +void Setline(Object *x, int n) +

      + +
      +Sets the line number associated with x. Used to track +objects and report errors. +
      + +

      +int Getline(Object *x) +

      + +
      +Gets the line number associated with x. +
      + +

      35.5.5 Iterating over Lists and Hashes

      + + +To iterate over the elements of a list or a hash table, the following functions are used: + +

      +Iterator First(Object *x) +

      + +
      +Returns an iterator object that points to the first item in a list or hash table. The +item attribute of the Iterator object is a pointer to the item. For hash tables, the key attribute +of the Iterator object additionally points to the corresponding Hash table key. The item and key attributes +are NULL if the object contains no items or if there are no more items. +
      + +

      +Iterator Next(Iterator i) +

      + +
      +

      Returns an iterator that points to the next item in a list or hash table. + +Here are two examples of iteration:

      + +
      +
      +List *l = (some list);
+Iterator i;
+
+for (i = First(l); i.item; i = Next(i)) {
+    Printf(stdout,"%s\n", i.item);
+}
+
+Hash *h = (some hash);
+Iterator j;
+
+for (j = First(j); j.item; j= Next(j)) {
+    Printf(stdout,"%s : %s\n", j.key, j.item);
+}
+
      +
      + +
      + +

      35.5.6 I/O

      + + +Special I/O functions are used for all internal I/O. These operations +work on C FILE * objects, String objects, and special File objects +(which are merely a wrapper around FILE *). + +

      +int Printf(String_or_FILE *f, const char *fmt, ...) +

      + +
      +Formatted I/O. Same as the C fprintf() function except that output +can also be directed to a string object. Note: the %s format +specifier works with both strings and char *. All other format +operators have the same meaning. +
      + +

      +int Printv(String_or_FILE *f, String_or_char *arg1,..., NULL) +

      + +
      +Prints a variable number of strings arguments to the output. The last +argument to this function must be NULL. The other arguments can either +be char * or string objects. +
      + +

      +int Putc(int ch, String_or_FILE *f) +

      + +
      +Same as the C fputc() function. +
      + +

      +int Write(String_or_FILE *f, void *buf, int len) +

      + +
      +Same as the C write() function. +
      + +

      +int Read(String_or_FILE *f, void *buf, int maxlen) +

      + +
      +Same as the C read() function. +
      + +

      +int Getc(String_or_FILE *f) +

      + +
      +Same as the C fgetc() function. +
      + +

      +int Ungetc(int ch, String_or_FILE *f) +

      + +
      +Same as the C ungetc() function. +
      + +

      +int Seek(String_or_FILE *f, int offset, int whence) +

      + +
      +Same as the C seek() function. offset is the number +of bytes. whence is one of SEEK_SET,SEEK_CUR, +or SEEK_END.. +
      + +

      +long Tell(String_or_FILE *f) +

      + +
      +Same as the C tell() function. +
      + +

      +File *NewFile(const char *filename, const char *mode, List *newfiles) +

      + +
      +Create a File object using the fopen() library call. This +file differs from FILE * in that it can be placed in the standard +SWIG containers (lists, hashes, etc.). The filename is added to the +newfiles list if newfiles is non-zero and the file was created successfully. +
      + +

      +File *NewFileFromFile(FILE *f) +

      + +
      +Create a File object wrapper around an existing FILE * object. +
      + +

      +int Close(String_or_FILE *f) +

      + +
      +

      Closes a file. Has no effect on strings.

      + +

      +The use of the above I/O functions and strings play a critical role in SWIG. It is +common to see small code fragments of code generated using code like this: +

      + +
      +
      +/* Print into a string */
+String *s = NewString("");
+Printf(s,"Hello\n");
+for (i = 0; i < 10; i++) {
+    Printf(s,"%d\n", i);
+}
+...
+/* Print string into a file */
+Printf(f, "%s\n", s);
+
      +
      + +

      +Similarly, the preprocessor and parser all operate on string-files. +

      + +
      + +

      35.6 Navigating and manipulating parse trees

      + + +Parse trees are built as collections of hash tables. Each node is a hash table in which +arbitrary attributes can be stored. Certain attributes in the hash table provide links to +other parse tree nodes. The following macros can be used to move around the parse tree. + +

      +String *nodeType(Node *n) +

      + +
      +Returns the node type tag as a string. The returned string indicates the type of parse +tree node. +
      + +

      +Node *nextSibling(Node *n) +

      + +
      +Returns the next node in the parse tree. For example, the next C declaration. +
      + +

      +Node *previousSibling(Node *n) +

      + +
      +Returns the previous node in the parse tree. For example, the previous C declaration. +
      + +

      +Node *firstChild(Node *n) +

      + +
      +Returns the first child node. For example, if n was a C++ class node, this would +return the node for the first class member. +
      + +

      +Node *lastChild(Node *n) +

      + +
      +Returns the last child node. You might use this if you wanted to append a new +node to the of a class. +
      + +

      +Node *parentNode(Node *n) +

      + +
      +Returns the parent of node n. Use this to move up the pass tree. +
      + +

      +The following macros can be used to change all of the above attributes. +Normally, these functions are only used by the parser. Changing them without +knowing what you are doing is likely to be dangerous. +

      + +

      +void set_nodeType(Node *n, const String_or_char) +

      + +
      +Change the node type. +tree node. +
      + +

      +void set_nextSibling(Node *n, Node *s) +

      + +
      +Set the next sibling. +
      + +

      +void set_previousSibling(Node *n, Node *s) +

      + +
      +Set the previous sibling. +
      + +

      +void set_firstChild(Node *n, Node *c) +

      + +
      +Set the first child node. +
      + +

      +void set_lastChild(Node *n, Node *c) +

      + +
      +Set the last child node. +
      + +

      +void set_parentNode(Node *n, Node *p) +

      + +
      +Set the parent node. +
      + +

      +The following utility functions are used to alter the parse tree (at your own risk) +

      + +

      +void appendChild(Node *parent, Node *child) +

      + +
      +Append a child to parent. The appended node becomes the last child. +
      + +

      +void deleteNode(Node *node) +

      + +
      +Deletes a node from the parse tree. Deletion reconnects siblings and properly updates +the parent so that sibling nodes are unaffected. +
      + +

      35.7 Working with attributes

      + + +

      +Since parse tree nodes are just hash tables, attributes are accessed using the Getattr(), +Setattr(), and Delattr() operations. For example: +

      + +
      +
      +int functionHandler(Node *n) {
+    String *name    = Getattr(n,"name");
+    String *symname = Getattr(n,"sym:name");
+    SwigType *type  = Getattr(n,"type");
+    ...
+}
+
      +
      + +

      +New attributes can be freely attached to a node as needed. However, when new attributes +are attached during code generation, they should be prepended with a namespace prefix. +For example: +

      + +
      +
      +...
+Setattr(n,"python:docstring", doc);     /* Store docstring */
+...
+
      +
      + +

      +A quick way to check the value of an attribute is to use the checkAttribute() function like this: +

      + +
      +
      +if (checkAttribute(n,"storage","virtual")) {
+   /* n is virtual */
+   ...
+}
+
      +
      + +

      +Changing the values of existing attributes is allowed and is sometimes done to implement +node transformations. However, if a function/method modifies a node, it is required to restore +modified attributes to their original values. To simplify the task of saving/restoring attributes, +the following functions are used: +

      + +

      +int Swig_save(const char *ns, Node *n, const char *name1, const char *name2, ..., NIL) +

      + +
      +Saves a copy of attributes name1, name2, etc. from node n. +Copies of the attributes are actually resaved in the node in a different namespace which is +set by the ns argument. For example, if you call Swig_save("foo",n,"type",NIL), +then the "type" attribute will be copied and saved as "foo:type". The namespace name itself is stored in +the "view" attribute of the node. If necessary, this can be examined to find out where previous +values of attributes might have been saved. +
      + +

      +int Swig_restore(Node *n) +

      + +
      + +

      +Restores the attributes saved by the previous call to Swig_save(). Those +attributes that were supplied to Swig_save() will be restored to their +original values. +

      + +

      +The Swig_save() and Swig_restore() functions must always be used as a pair. +That is, every call to Swig_save() must have a matching call to Swig_restore(). +Calls can be nested if necessary. Here is an example that shows how the functions might be used: +

      + +
      +
      +int variableHandler(Node *n) {
+    Swig_save("variableHandler",n,"type","sym:name",NIL);
+    String *symname = Getattr(n,"sym:name");
+    SwigType *type  = Getattr(n,"type");
+    ...
+    Append(symname,"_global");         // Change symbol name
+    SwigType_add_pointer(type);        // Add pointer
+    ...
+    generate wrappers
+    ...
+    Swig_restore(n);                  // Restore original values
+    return SWIG_OK;
+}
+
      +
      + +
      + +

      +int Swig_require(const char *ns, Node *n, const char *name1, const char *name2, ..., NIL) +

      + +
      +This is an enhanced version of Swig_save() that adds error checking. If an attribute +name is not present in n, a failed assertion results and SWIG terminates with a fatal +error. Optionally, if an attribute name is specified as "*name", a copy of the +attribute is saved as with Swig_save(). If an attribute is specified as "?name", +the attribute is optional. Swig_restore() must always be called after using this +function. +
      + +

      35.8 Type system

      + + +

      +SWIG implements the complete C++ type system including typedef, inheritance, +pointers, references, and pointers to members. A detailed discussion of +type theory is impossible here. However, let's cover the highlights. +

      + +

      35.8.1 String encoding of types

      + + +

      +All types in SWIG consist of a base datatype and a collection of type +operators that are applied to the base. A base datatype is almost +always some kind of primitive type such as int or double. +The operators consist of things like pointers, references, arrays, and so forth. +Internally, types are represented as strings that are constructed in a very +precise manner. Here are some examples: +

      + +
      +
      +C datatype                     SWIG encoding (strings)
+-----------------------------  --------------------------
+int                            "int"
+int *                          "p.int"
+const int *                    "p.q(const).int"
+int (*x)(int,double)           "p.f(int,double).int"
+int [20][30]                   "a(20).a(30).int"
+int (F::*)(int)                "m(F).f(int).int"
+vector<int> *                  "p.vector<(int)>"
+
      +
      + +

      +Reading the SWIG encoding is often easier than figuring out the C code---just +read it from left to right. For a type of "p.f(int,double).int" is +a "pointer to a function(int,double) that returns int". +

      + +

      +The following operator encodings are used in type strings: +

      + +
      +
      +Operator              Meaning
+-------------------   -------------------------------
+p.                    Pointer to
+a(n).                 Array of dimension n
+r.                    C++ reference
+m(class).             Member pointer to class
+f(args).              Function.
+q(qlist).             Qualifiers
+
      +
      + +

      +In addition, type names may be parameterized by templates. This is +represented by enclosing the template parameters in <( +... )>. Variable length arguments are represented by the +special base type of v(...). +

      + +

      +If you want to experiment with type encodings, the raw type strings can +be inserted into an interface file using backticks `` wherever a type +is expected. For instance, here is +an extremely perverted example: +

      + +
      +
      +`p.a(10).p.f(int,p.f(int).int)` foo(int, int (*x)(int));
+
      +
      + +

      +This corresponds to the immediately obvious C declaration: +

      + +
      +
      +(*(*foo(int,int (*)(int)))[10])(int,int (*)(int));
+
      +
      + +

      +Aside from the potential use of this declaration on a C programming quiz, +it motivates the use of the special SWIG encoding of types. The SWIG +encoding is much easier to work with because types can be easily examined, +modified, and constructed using simple string operations (comparison, +substrings, concatenation, etc.). For example, in the parser, a declaration +like this +

      + +
      +
      +int *a[30];
+
      +
      + +

      +is processed in a few pieces. In this case, you have the base type +"int" and the declarator of type "a(30).p.". To +make the final type, the two parts are just joined together using +string concatenation. +

      + +

      35.8.2 Type construction

      + + +

      +The following functions are used to construct types. You should use +these functions instead of trying to build the type strings yourself. +

      + +

      +void SwigType_add_pointer(SwigType *ty) +

      + +
      +Adds a pointer to ty. +
      + +

      +void SwigType_del_pointer(SwigType *ty) +

      + +
      +Removes a single pointer from ty. +
      + +

      +void SwigType_add_reference(SwigType *ty) +

      + +
      +Adds a reference to ty. +
      + +

      +void SwigType_add_array(SwigType *ty, const String_or_char *size) +

      + +
      +Adds an array with dimension dim to ty. +
      + +

      +void SwigType_del_array(SwigType *ty) +

      + +
      +Removes a single array dimension from ty. +
      + +

      +int SwigType_array_ndim(SwigType *ty) +

      + +
      +Returns number of array dimensions of ty. +
      + +

      +String* SwigType_array_getdim(SwigType *ty,int n) +

      + +
      +Returns nth array dimension of ty. +
      + +

      +void SwigType_array_setdim(SwigType *ty, int n, const String_or_char *rep) +

      + +
      +Sets nth array dimensions of ty to rep. +
      + +

      +void SwigType_add_qualifier(SwigType *ty, const String_or_char *q) +

      + +
      +Adds a type qualifier q to ty. q is typically +"const" or "volatile". +
      + +

      +void SwigType_add_memberpointer(SwigType *ty, const String_or_char *cls) +

      + +
      +Adds a pointer to a member of class cls to ty. +
      + +

      +void SwigType_add_function(SwigType *ty, ParmList *p) +

      + +
      +Adds a function to ty. p is a linked-list of parameter +nodes as generated by the parser. See the section on parameter lists +for details about the representation. +
      + +

      +void SwigType_add_template(SwigType *ty, ParmList *p) +

      + +
      +Adds a template to ty. p is a linked-list of parameter +nodes as generated by the parser. See the section on parameter lists +for details about the representation. +
      + +

      +SwigType *SwigType_pop(SwigType *ty) +

      + +
      +Removes the last type constructor from ty and returns it. +ty is modified. +
      + +

      +void SwigType_push(SwigType *ty, SwigType *op) +

      + +
      +Pushes the type operators in op onto type ty. The +opposite of SwigType_pop(). +
      + +

      +SwigType *SwigType_pop_arrays(SwigType *ty) +

      + +
      +Removes all leading array operators from ty and returns them. +ty is modified. For example, if ty is "a(20).a(10).p.int", +then this function would return "a(20).a(10)." and modify ty +so that it has the value "p.int". +
      + +

      +SwigType *SwigType_pop_function(SwigType *ty) +

      + +
      +Removes a function operator from ty including any qualification. +ty is modified. For example, if ty is "f(int).int", +then this function would return "f(int)." and modify ty +so that it has the value "int". +
      + +

      +SwigType *SwigType_base(SwigType *ty) +

      + +
      +Returns the base type of a type. For example, if ty is +"p.a(20).int", this function would return "int". +ty is unmodified. +
      + +

      +SwigType *SwigType_prefix(SwigType *ty) +

      + +
      +Returns the prefix of a type. For example, if ty is +"p.a(20).int", this function would return "p.a(20).". +ty is unmodified. +
      + +

      35.8.3 Type tests

      + + +

      +The following functions can be used to test properties of a datatype. +

      + +

      +int SwigType_ispointer(SwigType *ty) +

      + +
      +Checks if ty is a standard pointer. +
      + +

      +int SwigType_ismemberpointer(SwigType *ty) +

      + +
      +Checks if ty is a member pointer. +
      + +

      +int SwigType_isreference(SwigType *ty) +

      + +
      +Checks if ty is a C++ reference. +
      + +

      +int SwigType_isarray(SwigType *ty) +

      + +
      +Checks if ty is an array. +
      + +

      +int SwigType_isfunction(SwigType *ty) +

      + +
      +Checks if ty is a function. +
      + +

      +int SwigType_isqualifier(SwigType *ty) +

      + +
      +Checks if ty is a qualifier. +
      + +

      +int SwigType_issimple(SwigType *ty) +

      + +
      +Checks if ty is a simple type. No operators applied. +
      + +

      +int SwigType_isconst(SwigType *ty) +

      + +
      +Checks if ty is a const type. +
      + +

      +int SwigType_isvarargs(SwigType *ty) +

      + +
      +Checks if ty is a varargs type. +
      + +

      +int SwigType_istemplate(SwigType *ty) +

      + +
      +Checks if ty is a templatized type. +
      + +

      35.8.4 Typedef and inheritance

      + + +

      +The behavior of typedef declaration is to introduce a type alias. +For instance, typedef int Integer makes the identifier +Integer an alias for int. The treatment of typedef in +SWIG is somewhat complicated due to the pattern matching rules that get applied +in typemaps and the fact that SWIG prefers to generate wrapper code +that closely matches the input to simplify debugging (a user will see the +typedef names used in their program instead of the low-level primitive C +datatypes). +

      + +

      +To handle typedef, SWIG builds a collection of trees containing typedef relations. For example, +

      + +
      +
      +typedef int Integer;
+typedef Integer *IntegerPtr;
+typedef int Number;
+typedef int Size;
+
      +
      + +

      +produces two trees like this: +

      + +
      +
      +                 int               p.Integer
+               ^  ^  ^                 ^
+              /   |   \                |
+             /    |    \               |
+        Integer  Size   Number    IntegerPtr
+
      +
      + +

      +To resolve a single typedef relationship, the following function is used: +

      + +

      +SwigType *SwigType_typedef_resolve(SwigType *ty) +

      + +
      +Checks if ty can be reduced to a new type via typedef. If so, +returns the new type. If not, returns NULL. +
      + +

      +Typedefs are only resolved in simple typenames that appear in a type. +For example, the type base name and in function parameters. When +resolving types, the process starts in the leaf nodes and moves up +the tree towards the root. Here are a few examples that show how it works: +

      + +
      +
      +Original type            After typedef_resolve()
+------------------------ -----------------------
+Integer                  int
+a(30).Integer            int
+p.IntegerPtr             p.p.Integer
+p.p.Integer              p.p.int
+
      +
      + +

      +For complicated types, the process can be quite involved. Here is the +reduction of a function pointer: +

      + +
      +
      +p.f(Integer, p.IntegerPtr, Size).Integer          : Start
+p.f(Integer, p.IntegerPtr, Size).int
+p.f(int, p.IntegerPtr, Size).int
+p.f(int, p.p.Integer, Size).int
+p.f(int, p.p.int, Size).int
+p.f(int, p.p.int, int).int                        : End
+
      +
      + +

      +Two types are equivalent if their full type reductions are the same. +The following function will fully reduce a datatype: +

      + +

      +SwigType *SwigType_typedef_resolve_all(SwigType *ty) +

      + +
      +Fully reduces ty according to typedef rules. Resulting datatype +will consist only of primitive typenames. +
      + +

      35.8.5 Lvalues

      + + +

      +When generating wrapper code, it is necessary to emit datatypes that can +be used on the left-hand side of an assignment operator (an lvalue). However, +not all C datatypes can be used in this way---especially arrays and +const-qualified types. To generate a type that can be used as an lvalue, +use the following function: +

      + +

      +SwigType *SwigType_ltype(SwigType *ty) +

      + +
      +Converts type ty to a type that can be used as an lvalue in +assignment. The resulting type is stripped of qualifiers and arrays are +converted to a pointers. +
      + +

      +The creation of lvalues is fully aware of typedef and other aspects +of the type system. Therefore, the creation of an lvalue may result in +unexpected results. Here are a few examples: +

      + +
      +
      +typedef double Matrix4[4][4];
+Matrix4 x;    // type = 'Matrix4', ltype='p.a(4).double'
+
+typedef const char * Literal;
+Literal y;    // type = 'Literal', ltype='p.char'
+
      +
      + +

      35.8.6 Output functions

      + + +

      +The following functions produce strings that are suitable for output. +

      + +

      +String *SwigType_str(SwigType *ty, const String_or_char *id = 0) +

      + +
      +Generates a C string for a datatype. id is an optional declarator. +For example, if ty is "p.f(int).int" and id is "foo", then +this function produces "int (*foo)(int)". This function is +used to convert string-encoded types back into a form that is valid C syntax. +
      + +

      +String *SwigType_lstr(SwigType *ty, const String_or_char *id = 0) +

      + +
      +This is the same as SwigType_str() except that the result +is generated from the type's lvalue (as generated from SwigType_ltype). +
      + +

      +String *SwigType_lcaststr(SwigType *ty, const String_or_char *id = 0) +

      + +
      +Generates a casting operation that converts from type ty to its +lvalue. id is an optional name to include in the cast. For example, +if ty is "q(const).p.char" and id is "foo", +this function produces the string "(char *) foo". +
      + +

      +String *SwigType_rcaststr(SwigType *ty, const String_or_char *id = 0) +

      + +
      +Generates a casting operation that converts from a type's lvalue to a +type equivalent to ty. id is an optional name to +include in the cast. For example, if ty is +"q(const).p.char" and id is "foo", this +function produces the string "(const char *) foo". +
      + +

      +String *SwigType_manglestr(SwigType *ty) +

      + +
      +Generates a mangled string encoding of type ty. The +mangled string only contains characters that are part of a valid +C identifier. The resulting string is used in various parts of +SWIG, but is most commonly associated with type-descriptor objects +that appear in wrappers (e.g., SWIGTYPE_p_double). +
      + +

      35.9 Parameters

      + + +

      +Several type-related functions involve parameter lists. These include +functions and templates. Parameter list are represented as a list of +nodes with the following attributes: +

      + +
      +
      +"type"        -  Parameter type  (required)
+"name"        -  Parameter name  (optional)
+"value"       -  Initializer     (optional)
+
      +
      + +

      +Typically parameters are denoted in the source by using a typename of +Parm * or ParmList *. To walk a parameter list, simply use +code like this: +

      + +
      +
      +Parm *parms;
+Parm *p;
+for (p = parms; p; p = nextSibling(p)) {
+    SwigType *type  = Getattr(p,"type");
+    String   *name  = Getattr(p,"name");
+    String   *value = Getattr(p,"value");
+    ...
+}
+
      +
      + +

      +Note: this code is exactly the same as what you would use to walk parse tree nodes. +

      + +

      +An empty list of parameters is denoted by a NULL pointer. +

      + +

      +Since parameter lists are fairly common, the following utility functions are provided +to manipulate them: +

      + +

      +Parm *CopyParm(Parm *p); +

      + +
      +Copies a single parameter. +
      + +

      +ParmList *CopyParmList(ParmList *p); +

      + +
      +Copies an entire list of parameters. +
      + +

      +int ParmList_len(ParmList *p); +

      + +
      +Returns the number of parameters in a parameter list. +
      + +

      +String *ParmList_str(ParmList *p); +

      + +
      +Converts a parameter list into a C string. For example, +produces a string like "(int *p, int n, double x);". +
      + +

      +String *ParmList_protostr(ParmList *p); +

      + +
      +The same as ParmList_str() except that parameter names are not +included. Used to emit prototypes. +
      + +

      +int ParmList_numrequired(ParmList *p); +

      + +
      +Returns the number of required (non-optional) arguments in p. +
      + +

      35.10 Writing a Language Module

      + + +

      +One of the easiest routes to supporting a new language module is to copy an already +supported language module implementation and modify it. +Be sure to choose a language that is similar in nature to the new language. +All language modules follow a similar structure and +this section briefly outlines the steps needed to create a bare-bones +language module from scratch. +Since the code is relatively easy to read, this section +describes the creation of a minimal Python module. You should be able to extrapolate +this to other languages. +

      + +

      35.10.1 Execution model

      + + +

      +Code generation modules are defined by inheriting from the Language class, +currently defined in the Source/Modules directory of SWIG. Starting from +the parsing of command line options, all aspects of code generation are controlled by +different methods of the Language that must be defined by your module. +

      + +

      35.10.2 Starting out

      + + +

      +To define a new language module, first create a minimal implementation using +this example as a guide: +

      + +
      +
      +#include "swigmod.h"
+
+class PYTHON : public Language {
+public:
+
+  virtual void main(int argc, char *argv[]) {
+    printf("I'm the Python module.\n");
+  }
+
+  virtual int top(Node *n) {
+    printf("Generating code.\n");
+    return SWIG_OK;
+  }
+
+};
+
+extern "C" Language *
+swig_python(void) {
+  return new PYTHON();
+}
+
      +
      + +

      +The "swigmod.h" header file contains, among other things, the declaration +of the Language base class and so you should include it at the top +of your language module's source file. Similarly, the "swigconfig.h" header +file contains some other useful definitions that you may need. Note that you +should not include any header files that are installed with the +target language. That is to say, the implementation of the SWIG Python module +shouldn't have any dependencies on the Python header files. The wrapper code +generated by SWIG will almost always depend on some language-specific C/C++ +header files, but SWIG itself does not. +

      + +

      +Give your language class a reasonable name, usually the same as the target language. +By convention, these class names are all uppercase (e.g. "PYTHON" for the Python +language module) but this is not a requirement. This class will ultimately consist +of a number of overrides of the virtual functions declared in the Language +base class, in addition to any language-specific member functions and data you +need. For now, just use the dummy implementations shown above. +

      + +

      +The language module ends with a factory function, swig_python(), that simply +returns a new instance of the language class. As shown, it should be declared with the +extern "C" storage qualifier so that it can be called from C code. It should +also return a pointer to the base class (Language) so that only the interface +(and not the implementation) of your language module is exposed to the rest of SWIG. +

      + +

      +Save the code for your language module in a file named "python.cxx" and. +place this file in the Source/Modules directory of the SWIG distribution. +To ensure that your module is compiled into SWIG along with the other language modules, +modify the file Source/Modules/Makefile.am to include the additional source +files. In addition, modify the file Source/Modules/swigmain.cxx +with an additional command line option that activates the module. Read the source---it's straightforward. +

      + +

      +Next, at the top level of the SWIG distribution, re-run the autogen.sh script +to regenerate the various build files: +

      + +
      +
      +$ ./autogen.sh
+
      +
      + +

      +Next re-run configure to regenerate all of the Makefiles: +

      + +
      +
      +$ ./configure
+
      +
      + +

      +Finally, rebuild SWIG with your module added: +

      + +
      +
      +$ make
+
      +
      + +

      +Once it finishes compiling, try running SWIG with the command-line option +that activates your module. For example, swig -python foo.i. The +messages from your new module should appear. +

      + +

      35.10.3 Command line options

      + + +

      +When SWIG starts, the command line options are passed to your language module. This occurs +before any other processing occurs (preprocessing, parsing, etc.). To capture the +command line options, simply use code similar to this: +

      + +
      +
      +void Language::main(int argc, char *argv[]) {
+  for (int i = 1; i < argc; i++) {
+      if (argv[i]) {
+          if(strcmp(argv[i],"-interface") == 0) {
+            if (argv[i+1]) {
+              interface = NewString(argv[i+1]);
+              Swig_mark_arg(i);
+              Swig_mark_arg(i+1);
+              i++;
+            } else {
+              Swig_arg_error();
+            }
+	  } else if (strcmp(argv[i],"-globals") == 0) {
+	    if (argv[i+1]) {
+	      global_name = NewString(argv[i+1]);
+	      Swig_mark_arg(i);
+	      Swig_mark_arg(i+1);
+	      i++;
+	    } else {
+	      Swig_arg_error();
+	    }
+	  } else if ( (strcmp(argv[i],"-proxy") == 0)) {
+	    proxy_flag = 1;
+	    Swig_mark_arg(i);
+	  } else if (strcmp(argv[i],"-keyword") == 0) {
+	    use_kw = 1;
+	    Swig_mark_arg(i);
+	  } else if (strcmp(argv[i],"-help") == 0) {
+	    fputs(usage,stderr);
+	  }
+          ...
+      }
+  }
+}
+
      +
      + +

      +The exact set of options depends on what you want to do in your module. Generally, +you would use the options to change code generation modes or to print diagnostic information. +

      + +

      +If a module recognizes an option, it should always call Swig_mark_arg() +to mark the option as valid. If you forget to do this, SWIG will terminate with an +unrecognized command line option error. +

      + +

      35.10.4 Configuration and preprocessing

      + + +

      +In addition to looking at command line options, the main() method is responsible +for some initial configuration of the SWIG library and preprocessor. To do this, +insert some code like this: +

      + +
      +
      +void main(int argc, char *argv[]) {
+   ... command line options ...
+
+   /* Set language-specific subdirectory in SWIG library */
+   SWIG_library_directory("python");
+
+   /* Set language-specific preprocessing symbol */
+   Preprocessor_define("SWIGPYTHON 1", 0);
+
+   /* Set language-specific configuration file */
+   SWIG_config_file("python.swg");
+
+   /* Set typemap language (historical) */
+   SWIG_typemap_lang("python");
+}
+
      +
      + +

      +The above code does several things--it registers the name of the +language module with the core, it supplies some preprocessor macro definitions +for use in input files (so that they can determine the target language), and +it registers a start-up file. In this case, the file python.swg will +be parsed before any part of the user-supplied input file. +

      + +

      +Before proceeding any further, create a directory for your module in the SWIG +library (The Lib directory). Now, create a configuration file in the +directory. For example, python.swg. +

      + +

      +Just to review, your language module should now consist of two files-- +an implementation file python.cxx and a configuration file +python.swg. +

      + +

      35.10.5 Entry point to code generation

      + + +

      +SWIG is a multi-pass compiler. Once the main() method has +been invoked, the language module does not execute again until +preprocessing, parsing, and a variety of semantic analysis passes have +been performed. When the core is ready to start generating wrappers, +it invokes the top() method of your language class. The +argument to top is a single parse tree node that corresponds to +the top of the entire parse tree. +

      + +

      +To get the code generation process started, the top() procedure needs +to do several things: +

      + +
        +
      • Initialize the wrapper code output. +
      • Set the module name. +
      • Emit common initialization code. +
      • Emit code for all of the child nodes. +
      • Finalize the wrapper module and cleanup. +
      + +

      +An outline of top() might be as follows: +

      + +
      +
      +int Python::top(Node *n) {
+
+   /* Get the module name */
+   String *module = Getattr(n,"name");
+
+   /* Get the output file name */
+   String *outfile = Getattr(n,"outfile");
+
+   /* Initialize I/O (see next section) */
+   ...
+
+   /* Output module initialization code */
+   ...
+
+   /* Emit code for children */
+   Language::top(n);
+
+   ...
+   /* Cleanup files */
+   ...
+
+   return SWIG_OK;
+}
+
      +
      + +

      35.10.6 Module I/O and wrapper skeleton

      + + + + + +

      +Within SWIG wrappers, there are four main sections. These are (in order) +

      + +
        +
      • runtime: This section has most of the common SWIG runtime code +
      • header: This section holds declarations and inclusions from the .i file +
      • wrapper: This section holds all the wrappering code +
      • init: This section holds the module initalisation function +(the entry point for the interpreter) +
      +

      +Different parts of the SWIG code will fill different sections, +then upon completion of the wrappering all the sections will be saved +to the wrapper file. +

      +

      +To perform this will require several additions to the code in various places, +such as: +

      + +
      +
      +class PYTHON : public Language {
+protected:
+   /* General DOH objects used for holding the strings */
+   File *f_begin;
+   File *f_runtime;
+   File *f_header;
+   File *f_wrappers;
+   File *f_init;
+
+public:
+   ...
+
+};
+
+int Python::top(Node *n) {
+
+   ...
+
+   /* Initialize I/O */
+   f_begin = NewFile(outfile, "w", SWIG_output_files());
+   if (!f_begin) {
+      FileErrorDisplay(outfile);
+      SWIG_exit(EXIT_FAILURE);
+   }
+   f_runtime = NewString("");
+   f_init = NewString("");
+   f_header = NewString("");
+   f_wrappers = NewString("");
+
+   /* Register file targets with the SWIG file handler */
+   Swig_register_filebyname("begin", f_begin);
+   Swig_register_filebyname("header", f_header);
+   Swig_register_filebyname("wrapper", f_wrappers);
+   Swig_register_filebyname("runtime", f_runtime);
+   Swig_register_filebyname("init", f_init);
+
+   /* Output module initialization code */
+   Swig_banner(f_begin);
+   ...
+
+   /* Emit code for children */
+   Language::top(n);
+
+   ...
+   /* Write all to the file */
+   Dump(f_runtime, f_begin);
+   Dump(f_header, f_begin);
+   Dump(f_wrappers, f_begin);
+   Wrapper_pretty_print(f_init, f_begin);
+
+   /* Cleanup files */
+   Delete(f_runtime);
+   Delete(f_header);
+   Delete(f_wrappers);
+   Delete(f_init);
+   Close(f_begin);
+   Delete(f_begin);
+
+   return SWIG_OK;
+}
+
      +
      + +

      +Using this to process a file will generate a wrapper file, however the +wrapper will only consist of the common SWIG code as well as any inline +code which was written in the .i file. It does not contain any wrappers for +any of the functions or classes. +

      + +

      +The code to generate the wrappers are the various member functions, which +currently have not been touched. We will look at functionWrapper() as this +is the most commonly used function. In fact many of the other wrapper routines +will call this to do their work. +

      +

      +A simple modification to write some basic details to the wrapper looks like this: +

      + +
      +
      +int Python::functionWrapper(Node *n) {
+  /* Get some useful attributes of this function */
+  String   *name   = Getattr(n,"sym:name");
+  SwigType *type   = Getattr(n,"type");
+  ParmList *parms  = Getattr(n,"parms");
+  String   *parmstr= ParmList_str_defaultargs(parms); // to string
+  String   *func   = SwigType_str(type, NewStringf("%s(%s)", name, parmstr));
+  String   *action = Getattr(n,"wrap:action");
+
+  Printf(f_wrappers,"functionWrapper   : %s\n", func);
+  Printf(f_wrappers,"           action : %s\n", action);
+  return SWIG_OK;
+}
+
      +
      + +

      +This will now produce some useful information within your wrapper file. +

      + +
      +
      +functionWrapper   : void delete_Shape(Shape *self)
+           action : delete arg1;
+
+functionWrapper   : void Shape_x_set(Shape *self,double x)
+           action : if (arg1) (arg1)->x = arg2;
+
+functionWrapper   : double Shape_x_get(Shape *self)
+           action : result = (double) ((arg1)->x);
+
+functionWrapper   : void Shape_y_set(Shape *self,double y)
+           action : if (arg1) (arg1)->y = arg2;
+...
+
      +
      + +

      35.10.7 Low-level code generators

      + + + + +

      +As ingenious as SWIG is, and despite all its capabilities and the power of +its parser, the Low-level code generation takes a lot of work to write +properly. Mainly because every language insists on its own manner of +interfacing to C/C++. To write the code generators you will need a good +understanding of how to manually write an interface to your chosen +language, so make sure you have your documentation handy. +

      +

      +At this point it is also probably a good idea to take a very simple file +(just one function), and try letting SWIG generate wrappers for many +different languages. Take a look at all of the wrappers generated, and decide +which one looks closest to the language you are trying to wrap. +This may help you to decide which code to look at. +

      +

      +In general most language wrappers look a little like this: +

      +
      +
      +/* wrapper for TYPE3 some_function(TYPE1,TYPE2); */
+RETURN_TYPE _wrap_some_function(ARGS){
+  TYPE1 arg1;
+  TYPE2 arg2;
+  TYPE3 result;
+
+  if(ARG1 is not of TYPE1) goto fail;
+  arg1=(convert ARG1);
+  if(ARG2 is not of TYPE2) goto fail;
+  arg2=(convert ARG2);
+
+  result=some_function(arg1,arg2);
+
+  convert 'result' to whatever the language wants;
+
+  do any tidy up;
+
+  return ALL_OK;
+
+  fail:
+  do any tidy up;
+  return ERROR;
+}
+
      +
      + +

      +Yes, it is rather vague and not very clear. But each language works differently +so this will have to do for now. +

      +

      +Tackling this problem will be done in two stages: +

      +
        +
      • The skeleton: the function wrapper, and call, but without the conversion +
      • The conversion: converting the arguments to-from what the language wants +
      +

      +The first step will be done in the code, the second will be done in typemaps. +

      +

      +Our first step will be to write the code for functionWrapper(). What is +shown below is NOT the solution, merely a step in the right direction. +There are a lot of issues to address. +

      +
        +
      • Variable length and default parameters +
      • Typechecking and number of argument checks +
      • Overloaded functions +
      • Inout and Output only arguments +
      +
      +
      +virtual int functionWrapper(Node *n) {
+  /* get useful atributes */
+  String   *name   = Getattr(n,"sym:name");
+  SwigType *type   = Getattr(n,"type");
+  ParmList *parms  = Getattr(n,"parms");
+  ...
+
+  /* create the wrapper object */
+  Wrapper *wrapper = NewWrapper();
+
+  /* create the functions wrappered name */
+  String *wname = Swig_name_wrapper(iname);
+
+  /* deal with overloading */
+  ....
+
+  /* write the wrapper function definition */
+  Printv(wrapper->def,"RETURN_TYPE ", wname, "(ARGS) {",NIL);
+
+  /* if any additional local variable needed, add them now */
+  ...
+
+  /* write the list of locals/arguments required */
+  emit_args(type, parms, wrapper);
+
+  /* check arguments */
+  ...
+
+  /* write typemaps(in) */
+  ....
+
+  /* write constriants */
+  ....
+
+  /* Emit the function call */
+  emit_action(n,wrapper);
+
+  /* return value if necessary  */
+  ....
+
+  /* write typemaps(out) */
+  ....
+
+  /* add cleanup code */
+  ....
+
+  /* Close the function(ok) */
+  Printv(wrapper->code, "return ALL_OK;\n", NIL);
+
+  /* add the failure cleanup code */
+  ...
+
+  /* Close the function(error) */
+  Printv(wrapper->code, "return ERROR;\n", "}\n", NIL);
+
+  /* final substititions if applicable */
+  ...
+
+  /* Dump the function out */
+  Wrapper_print(wrapper,f_wrappers);
+
+  /* tidy up */
+  Delete(wname);
+  DelWrapper(wrapper);
+
+  return SWIG_OK;
+}
+
      +
      + +

      +Executing this code will produce wrappers which have our basic skeleton +but without the typemaps, there is still work to do. +

      + + +

      35.10.8 Configuration files

      + + + + +

      +At the time of this writing, SWIG supports nearly a dozen languages, +which means that for continued sanity in maintaining the configuration +files, the language modules need to follow some conventions. These are +outlined here along with the admission that, yes it is ok to violate +these conventions in minor ways, as long as you know where to apply the +proper kludge to keep the overall system regular and running. +Engineering is the art of compromise, see... +

      + +

      +Much of the maintenance regularity depends on choosing a suitable +nickname for your language module (and then using it in a controlled +way). Nicknames should be all lower case letters with an optional +numeric suffix (no underscores, no dashes, no spaces). Some examples +are: foo, bar, qux99. +

      + +

      +The numeric suffix variant, as in the last example, is somewhat tricky +to work with because sometimes people expect to refer to the language +without this number but sometimes that number is extremely relevant +(especially when it corresponds to language implementation versions with +incompatible interfaces). New language modules that unavoidably require +a numeric suffix in their nickname should include that number in all +uses, or be prepared to kludge. +

      + +

      +The nickname is used in four places: +

      + + + + + + + + + +
      usagetransform
      "skip" tag(none)
      Examples/ subdir name(none)
      Examples/GIFPlot/ subdir namecapitalize (upcase first letter)
      Examples/test-suite/ subdir name(none)
      + +

      +As you can see, most usages are direct. +

      + +
      + +
      configure.in +
      This file is processed by + +

      +autoconf +to generate the configure script. This is where you +need to add shell script fragments and autoconf macros to detect the +presence of whatever development support your language module requires, +typically directories where headers and libraries can be found, and/or +utility programs useful for integrating the generated wrapper code. +

      + +

      +Use the AC_ARG_WITH, AC_MSG_CHECKING, AC_SUBST +macros and so forth (see other languages for examples). Avoid using the +[ and ] character in shell script fragments. The +variable names passed to AC_SUBST should begin with the nickname, +entirely upcased. +

      + +

      +At the end of the new section is the place to put the aforementioned +nickname kludges (should they be needed). See Perl5 for +examples of what to do. [If this is still unclear after you've read +the code, ping me and I'll expand on this further. --ttn] +

      + +
      Makefile.in +
      + +

      +Some of the variables AC_SUBSTituted are essential to the +support of your language module. Fashion these into a shell script +"test" clause and assign that to a skip tag using "-z" and "-o": +

      + +
      +skip-qux99 = [ -z "@QUX99INCLUDE@" -o -z "@QUX99LIBS" ] +
      + +

      +This means if those vars should ever be empty, qux99 support should +be considered absent and so it would be a good idea to skip actions that +might rely on it. +

      + +

      +Here is where you may also define an alias (but then you'll need to +kludge --- don't do this): +

      + +
      +skip-qux = $(skip-qux99) +
      + +

      +Lastly, you need to modify each of check-aliveness, +check-examples, check-test-suite, +check-gifplot (all targets) and lib-languages (var). +Use the nickname for these, not the alias. +Note that you can do this even before you have any tests or examples +set up; the Makefile rules do some sanity checking and skip around +these kinds of problems. +

      + +
      Examples/Makefile.in +
      Nothing special here; see comments at top the of this file +and look to the existing languages for examples. + +
      Examples/qux99/check.list +
      Do cp ../python/check.list . and modify to taste. +One subdir per line. + +
      Examples/GIFPlot/Qux99/check.list +
      Do cp ../Python/check.list . and modify to taste. +One subdir per line. + +
      Lib/qux99/extra-install.list +
      If you add your language to the top-level Makefile.in var +lib-languages, then make install will install +all *.i and *.swg files from the language-specific +subdirectory of Lib. Use (optional) file +extra-install.list in that directory to name +additional files to install (see ruby for example). + +
      Source/Modules/Makefile.am +
      Add appropriate files to this Automake file. That's it! + +

      +When you have modified these files, please make sure that the new language module is completely +ignored if it is not installed and detected on a box, that is, make check-examples and make check-test-suite +politely displays the ignoring language message. +

      + +
      + + +

      35.10.9 Runtime support

      + + +

      +Discuss the kinds of functions typically needed for SWIG runtime support (e.g. +SWIG_ConvertPtr() and SWIG_NewPointerObj()) and the names of +the SWIG files that implement those functions. +

      + +

      35.10.10 Standard library files

      + + +

      +The standard library files that most languages supply keeps growing as SWIG matures. +The following are the minimum that are usually supported: +

      + +
        +
      • typemaps.i
        • +
      • std_string.i
        • +
      • std_vector.i
        • +
      • stl.i
        • +
      + +

      +Please copy these and modify for any new language. +

      + +

      35.10.11 Examples and test cases

      + + +

      +Each of the language modules provides one or more examples. These examples +are used to demonstrate different features of the language module to SWIG +end-users, but you'll find that they're useful during development and testing +of your language module as well. You can use examples from the existing SWIG +language modules for inspiration. +

      + +

      +Each example is self-contained and consists of (at least) a Makefile, +a SWIG interface file for the example module, and a 'runme' script that demonstrates +the functionality for that module. All of these files are stored in the same +subdirectory under the Examples/[lang] directory. +There are two classic examples which should be the first to convert to a new +language module. These are the "simple" C example and the "class" C++ example. +These can be found, for example for Python, in +Examples/python/simple and Examples/python/class. +

      + +

      +By default, all of the examples are built and run when the user types +make check. To ensure that your examples are automatically run +during this process, see the section on configuration +files. +

      + +

      35.10.12 Documentation

      + + +

      +Don't forget to write end-user documentation for your language module. Currently, +each language module has a dedicated chapter +You shouldn't rehash things that are already covered in sufficient +detail in the SWIG Basics and SWIG +and C++ chapters. There is no fixed format for what, exactly, you should +document about your language module, but you'll obviously want to cover issues that +are unique to your language. +

      + +

      +Some topics that you'll want to be sure to address include: +

      + +
        +
      • Command line options unique to your language module. +
      • Non-obvious mappings between C/C++ and target language concepts. + For example, if your target language provides a single floating + point type, it should be no big surprise to find that C/C++ + float and double types are mapped to it. On the other + hand, if your target language doesn't provide support for "classes" + or something similar, you'd want to discuss how C++ classes are handled. +
      • How to compile the SWIG-generated wrapper code into shared libraries + that can actually be used. For some languages, there are well-defined + procedures for doing this, but for others it's an ad hoc process. + Provide as much detail as appropriate, and links to other resources + if available. +
      + +

      35.10.13 Prerequisites for adding a new language module to the SWIG distribution

      + + +

      +If you wish for a new language module to be distributed with SWIG, +which we encourage for all popular languages, there are a few requirements. +While we appreciate that getting all aspects of a new language working +won't happen at the outset, there are a set of minimum requirements before +a module can be committed into the SVN repository for distribution with future +versions of SWIG. The following are really a summary of this whole section with +details being outlined earlier on. +

      + +
        +
      1. + Demonstrate basic C code working by porting the "simple" example including + a runtime test, see for example Examples/python/simple. +
        2. +
      2. + Demonstrate basic C++ code working by porting the "class" example including + a runtime test, see for example Examples/python/class. +
        3. +
      3. + Modify configure.in, Makefile.in and Examples/Makefile.in to run + these examples. Please make sure that if the new language is not + installed properly on a box, make -k check should still work by + skipping the tests and examples for the new language module. +
        4. +
      4. + Get the test-suite running for the new language (make check-[lang]-test-suite). + While the test-suite tests many corner cases, + we'd expect the majority of it to work by compiling the generated code + correctly as most of the corner cases are covered in the SWIG core. Get + at least one C and one C++ runtime test running in the test-suite. +
        5. +
      5. + Provide a chapter in the html documentation on the basics of using + the language module. +
        6. +
      6. + Ensure your source code is formatted according to the coding style guidelines. +
        7. +
      7. + Finally, email the SWIG developers with a patch and a demonstration of + commitment to maintaining the language module, + certainly in the short term and ideally long term. +
        8. +
      + +

      +Once accepted into SVN, development efforts should concentrate on +getting the entire test-suite to work with plenty of runtime tests. +Runtime tests should be for existing testcases and new test cases +should be added should there be an area not already covered by +the existing tests. +

      + +

      35.10.14 Coding style guidelines

      + + +

      +The coding guidelines for the C/C++ source code are pretty much K&R C style. +The style can be inferred from the existing code base and is +largely dictated by the indent code beautifier tool set to K&R style. +The code can formatted using the make targets in the Source directory. +Below is an example of how to format the emit.cxx file: +

      + +
      +
      +$ cd Source
+$ make beautify-file INDENTFILE=Modules/emit.cxx
+
      +
      + +

      +Of particular note is indentation is set to 2 spaces and a tab is used instead of 8 spaces. +The generated C/C++ code should also follow this style as close as possible. However, tabs +should be avoided as unlike the SWIG developers, users will never have consistent tab settings. +

      + +

      35.11 Typemaps

      + + +

      35.11.1 Proxy classes

      + + +

      35.12 Guide to parse tree nodes

      + + +

      +This section describes the different parse tree nodes and their attributes. +

      + +

      +cdecl +

      + +

      +Describes general C declarations including variables, functions, and typedefs. +A declaration is parsed as "storage T D" where storage is a storage class, T is a base type, +and D is a declarator. +

      + +
      +
      +"name"          - Declarator name
+"type"          - Base type T
+"decl"          - Declarator type (abstract)
+"storage"       - Storage class (static, extern, typedef, etc.)
+"parms"         - Function parameters (if a function)
+"code"          - Function body code (if supplied)
+"value"         - Default value (if supplied)
+
      + +
      + +

      +constructor +

      + +

      +C++ constructor declaration. +

      + +
      +
      +"name"          - Name of constructor
+"parms"         - Parameters
+"decl"          - Declarator (function with parameters)
+"code"          - Function body code (if any)
+"feature:new"   - Set to indicate return of new object.
+
      +
      + + +

      +destructor +

      + +

      +C++ destructor declaration. +

      + +
      +
      +"name"          - Name of destructor
+"code"          - Function body code (if any)
+"storage"       - Storage class (set if virtual)
+"value"         - Default value (set if pure virtual).
+
      +
      + + +

      +access +

      + +

      +C++ access change. +

      + +
      +
      +"kind"          - public, protected, private
+
      +
      + + +

      +constant +

      + +

      +Constant created by %constant or #define. +

      + +
      +
      +"name"          - Name of constant.
+"type"          - Base type.
+"value"         - Value.
+"storage"       - Set to %constant
+"feature:immutable" - Set to indicate read-only
+
      +
      + +

      +class +

      + +

      +C++ class definition or C structure definition. +

      + +
      +
      +"name"          - Name of the class.
+"kind"          - Class kind ("struct", "union", "class")
+"symtab"        - Enclosing symbol table.
+"tdname"        - Typedef name. Use for typedef struct { ... } A.
+"abstract"      - Set if class has pure virtual methods.
+"baselist"      - List of base class names.
+"storage"       - Storage class (if any)
+"unnamed"       - Set if class is unnamed.
+
      +
      + + +

      +enum +

      + +

      +Enumeration. +

      + +
      +
      +"name"          - Name of the enum (if supplied).
+"storage"       - Storage class (if any)
+"tdname"        - Typedef name (typedef enum { ... } name).
+"unnamed"       - Set if enum is unnamed.
+
      +
      + + +

      +enumitem +

      + +

      +Enumeration value. +

      + +
      +
      +"name"          - Name of the enum value.
+"type"          - Type (integer or char)
+"value"         - Enum value (if given)
+"feature:immutable" - Set to indicate read-only
+
      +
      + +

      +namespace +

      + +

      +C++ namespace. +

      + +
      +
      +"name"          - Name of the namespace.
+"symtab"        - Symbol table for enclosed scope.
+"unnamed"       - Set if unnamed namespace
+"alias"         - Alias name. Set for namespace A = B;
+
      +
      + + +

      +using +

      + +

      +C++ using directive. +

      + +
      +
      +"name"          - Name of the object being referred to.
+"uname"         - Qualified name actually given to using.
+"node"          - Node being referenced.
+"namespace"     - Namespace name being reference (using namespace name)
+
      +
      + + +

      +classforward +

      + +

      +A forward C++ class declaration. +

      + +
      +
      +"name"          - Name of the class.
+"kind"          - Class kind ("union", "struct", "class")
+
      +
      + + +

      +insert +

      + +

      +Code insertion directive. For example, %{ ... %} or +%insert(section). +

      + +
      +
      +"code"          - Inserted code
+"section"       - Section name ("header", "wrapper", etc.)
+
      +
      + +

      +top +

      + +

      +Top of the parse tree. +

      + +
      +
      +"module"        - Module name
+
      +
      + +

      +extend +

      + +

      +%extend directive. +

      + +
      +
      +"name"          - Module name
+"symtab"        - Symbol table of enclosed scope.
+
      +
      + +

      +apply +

      + +

      +%apply pattern { patternlist }. +

      + +
      +
      +"pattern"       - Source pattern.
+"symtab"        - Symbol table of enclosed scope.
+
      +
      + +

      +clear +

      + +

      +%clear patternlist; +

      + +
      +
      +"firstChild"    - Patterns to clear
+
      +
      + +

      +include +

      + +

      +%include directive. +

      + +
      +
      +"name"         - Filename
+"firstChild"   - Children
+
      +
      + +

      +import +

      + +

      +%import directive. +

      + +
      +
      +"name"         - Filename
+"firstChild"   - Children
+
      +
      + + +

      +module +

      + +

      +%module directive. +

      + +
      +
      +"name"         - Name of the module
+
      +
      + + +

      +typemap +

      + +

      +%typemap directive. +

      + +
      +
      +"method"       - Typemap method name.
+"code"         - Typemap code.
+"kwargs"       - Keyword arguments (if any)
+"firstChild"   - Typemap patterns
+
      +
      + +

      +typemapcopy +

      + +

      +%typemap directive with copy. +

      + +
      +
      +"method"       - Typemap method name.
+"pattern"      - Typemap source pattern.
+"firstChild"   - Typemap patterns
+
      +
      + + +

      +typemapitem +

      + +

      +%typemap pattern. Used with %apply, %clear, %typemap. +

      + +
      +
      +"pattern"      - Typemap pattern (a parameter list)
+"parms"        - Typemap parameters.
+
      +
      + +

      +types +

      + +

      +%types directive. +

      + +
      +
      +"parms"        - List of parameter types.
+"convcode"     - Code which replaces the default casting / conversion code
+
      +
      + + +

      +extern +

      + +

      +extern "X" { ... } declaration. +

      + +
      +
      +"name"       - Name "C", "Fortran", etc.
+
      +
      + + + + + + diff --git a/Doc/Manual/Guile.html b/Doc/Manual/Guile.html new file mode 100644 index 0000000..cf7e8da --- /dev/null +++ b/Doc/Manual/Guile.html @@ -0,0 +1,895 @@ + + + + +SWIG and Guile + + + + + +

      20 SWIG and Guile

      + +
      + +
      + + + + +

      +This section details guile-specific support in SWIG. + +

      20.1 Meaning of "Module"

      + + +

      +There are three different concepts of "module" involved, defined +separately for SWIG, Guile, and Libtool. To avoid horrible confusion, +we explicitly prefix the context, e.g., "guile-module". + +

      20.2 Using the SCM or GH Guile API

      + + +

      The guile module can currently export wrapper files that use the guile GH interface or the +SCM interface. This is controlled by an argument passed to swig. The "-gh" argument causes swig +to output GH code, and the "-scm" argument causes swig to output SCM code. Right now the "-scm" argument +is the default. The "-scm" wrapper generation assumes a guile version >= 1.6 and has several advantages over +the "-gh" wrapper generation including garbage collection and GOOPS support. +The "-gh" wrapper generation can be used for older versions of guile. +The guile GH wrapper code generation is depreciated and the +SCM interface is the default. The SCM and GH interface differ greatly in how they store +pointers and have completely different run-time code. See below for more info. + +

      The GH interface to guile is deprecated. Read more about why in the +Guile manual. +The idea of the GH interface was to provide a high level API that other languages and projects +could adopt. This was a good idea, but didn't pan out well for general development. But for the +specific, minimal uses that the SWIG typemaps put the GH interface to use is ideal for +using a high level API. So even though the GH interface is depreciated, SWIG will continue to use +the GH interface and provide mappings from the GH interface to whatever API we need. +We can maintain this mapping where guile failed because SWIG uses a small subset of all the GH functions +which map easily. All the guile typemaps like typemaps.i and std_vector.i +will continue to use the GH functions to do things like create lists of values, convert strings to +integers, etc. Then every language module will define a mapping between the GH interface and +whatever custom API the language uses. This is currently implemented by the guile module to use +the SCM guile API rather than the GH guile API. +For example, here are some of the current mapping file for the SCM API

      + +
      +
+#define gh_append2(a, b) scm_append(scm_listify(a, b, SCM_UNDEFINED)) 
+#define gh_apply(a, b) scm_apply(a, b, SCM_EOL) 
+#define gh_bool2scm SCM_BOOL 
+#define gh_boolean_p SCM_BOOLP 
+#define gh_car SCM_CAR 
+#define gh_cdr SCM_CDR 
+#define gh_cons scm_cons 
+#define gh_double2scm scm_make_real 
+...
+
      + +

      This file is parsed by SWIG at wrapper generation time, so every reference to a gh_ function is replaced +by a scm_ function in the wrapper file. Thus the gh_ function calls will never be seen in the wrapper; +the wrapper will look exactly like it was generated +for the specific API. Currently only the guile language module has created a mapping policy from gh_ to scm_, +but there is no reason other languages (like mzscheme or chicken) couldn't also use this. +If that happens, there is A LOT less code duplication in the standard typemaps.

      + +

      20.3 Linkage

      + + +

      +Guile support is complicated by a lack of user community cohesiveness, +which manifests in multiple shared-library usage conventions. A set of +policies implementing a usage convention is called a linkage. + +

      20.3.1 Simple Linkage

      + + +

      +The default linkage is the simplest; nothing special is done. In this +case the function SWIG_init() is exported. Simple linkage +can be used in several ways: +

      + +
        +
      • Embedded Guile, no modules. You want to embed a Guile +interpreter into your program; all bindings made by SWIG shall show up +in the root module. Then call SWIG_init() in the +inner_main() function. See the "simple" and "matrix" examples under +Examples/guile. + +

      • Dynamic module mix-in. You want to create a Guile module +using define-module, containing both Scheme code and +bindings made by SWIG; you want to load the SWIG modules as shared +libraries into Guile.

        +
        +
        +(define-module (my module))
+(define my-so (dynamic-link "./example.so"))
+(dynamic-call "SWIG_init" my-so) ; make SWIG bindings
+;; Scheme definitions can go here
+
        +
        + +

        +Newer Guile versions provide a shorthand for dynamic-link +and dynamic-call: +

        + +
        +
        +(load-extension "./example.so" "SWIG_init")
+
        +
        + +

        +You need to explicitly export those bindings made by SWIG that you +want to import into other modules: +

        + +
        +
        +(export foo bar)
+
        +
        + +

        +In this example, the procedures foo and bar +would be exported. Alternatively, you can export all bindings with the +following module-system hack: +

        + +
        +
        +(module-map (lambda (sym var)
+	      (module-export! (current-module) (list sym)))
+	    (current-module))
+
        +
        + +

        SWIG can also generate this Scheme stub (from +define-module up to export) +semi-automagically if you pass it the command-line argument +-scmstub. The code will be exported in a file called +module.scm in the directory specified by -outdir +or the current directory if -outdir is not specified. +Since SWIG doesn't know how +to load your extension module (with dynamic-link or +load-extension), you need to supply this +information by including a directive like this in the interface file: +

        + +
        +
        +%scheme %{ (load-extension "./example.so" "SWIG_init") %}
+
        +
        + +

        +(The %scheme directive allows to insert arbitrary Scheme +code into the generated file module.scm; it is +placed between the define-module form and the +export form.) +

        +
      + +

      If you want to include several SWIG modules, you would need to rename +SWIG_init via a preprocessor define to avoid symbol +clashes. For this case, however, passive linkage is available. + +

      20.3.2 Passive Linkage

      + + +

      Passive linkage is just like simple linkage, but it generates an +initialization function whose name is derived from the module and +package name (see below). + +

      You should use passive linkage rather than simple linkage when you +are using multiple modules. + +

      20.3.3 Native Guile Module Linkage

      + + +

      SWIG can also generate wrapper code that does all the Guile module +declarations on its own if you pass it the -Linkage +module command-line option. This requires Guile 1.5.0 or later. + +

      The module name is set with the -package and +-module command-line options. Suppose you want to define +a module with name (my lib foo); then you would have to +pass the options -package my/lib -module +foo. Note that the last part of the name can also be set +via the SWIG directive %module. + +

      You can use this linkage in several ways: + +

        +
      • Embedded Guile with SWIG modules. You want to embed a Guile +interpreter into your program; the SWIG bindings shall be put into +different modules. Simply call the function +scm_init_my_modules_foo_module +in the inner_main() function. + +
      • Dynamic Guile modules. You want to load the SWIG modules as +shared libraries into Guile; all bindings are automatically put in +newly created Guile modules. +
        +
        +(define my-so (dynamic-link "./foo.so"))
+;; create new module and put bindings there:
+(dynamic-call "scm_init_my_modules_foo_module" my-so) 
+
        +
        +Newer Guile versions have a shorthand procedure for this: +
        +
        +(load-extension "./foo.so" "scm_init_my_modules_foo_module")
+
        +
        +
      + +

      20.3.4 Old Auto-Loading Guile Module Linkage

      + + +

      Guile used to support an autoloading facility for object-code +modules. This support has been marked deprecated in version 1.4.1 and +is going to disappear sooner or later. SWIG still supports building +auto-loading modules if you pass it the -Linkage ltdlmod +command-line option. + +

      Auto-loading worked like this: Suppose a module with name (my +lib foo) is required and not loaded yet. Guile will then search +all directories in its search path +for a Scheme file my/modules/foo.scm or a shared library +my/modules/libfoo.so (or +my/modules/libfoo.la; +see the GNU libtool documentation). If a +shared library is found that contains the symbol +scm_init_my_modules_foo_module, +the library is loaded, and the function at that symbol is called with +no arguments in order to initialize the module. + +

      When invoked with the -Linkage ltdlmod command-line +option, SWIG generates an exported module initialization function with +an appropriate name. + + +

      20.3.5 Hobbit4D Linkage

      + + +

      +The only other linkage supported at this time creates shared object +libraries suitable for use by hobbit's (hobbit4d link) +guile module. This is called the "hobbit" linkage, and requires also +using the "-package" command line option to set the part of the module +name before the last symbol. For example, both command lines: +

      + +
      +
      +swig -guile -package my/lib foo.i
+swig -guile -package my/lib -module foo foo.i
+
      +
      + +

      +would create module (my lib foo) (assuming in the first +case foo.i declares the module to be "foo"). The installed files are +my/lib/libfoo.so.X.Y.Z and friends. This scheme is still very +experimental; the (hobbit4d link) conventions are not well understood. +

      + +

      20.4 Underscore Folding

      + + +

      +Underscores are converted to dashes in identifiers. Guile support may +grow an option to inhibit this folding in the future, but no one has +complained so far. + +

      You can use the SWIG directives %name and +%rename to specify the Guile name of the wrapped +functions and variables (see CHANGES). + +

      20.5 Typemaps

      + + +

      +The Guile module handles all types via typemaps. This +information is read from Lib/guile/typemaps.i. + +Some non-standard typemap substitutions are supported: +

        +
      • $descriptor expands to a type descriptor for use with +the SWIG_NewPointerObj() and +SWIG_ConvertPtr functions. +
      • For pointer types, $*descriptor expands to a +descriptor for the direct base type (i.e., one pointer is stripped), +whereas $basedescriptor expands to a +descriptor for the base type (i.e., all pointers are stripped). +
      + +

      A function returning void (more precisely, a function +whose out typemap returns SCM_UNSPECIFIED) is +treated as returning no values. In argout typemaps, one +can use the macro GUILE_APPEND_RESULT in order to append +a value to the list of function return values. + +

      Multiple values can be passed up to Scheme in one of three ways: +

        +

      • Multiple values as lists. +By default, if more than one value is to +be returned, a list of the values is created and returned; to switch +back to this behavior, use

        + +
        +
        +%values_as_list;
        +
        + +

      • Multiple values as vectors. +By issuing +

        + +
        +
        +%values_as_vector;
        +
        + +

        +vectors instead of lists will be used. +

      • Multiple values for multiple-value continuations. +This is the most elegant way. By issuing +

        + +
        +
        +%multiple_values;
        +
        + +

        +multiple values are passed to the multiple-value +continuation, as created by call-with-values or the +convenience macro receive. The latter is available if you +issue (use-modules (srfi srfi-8)). Assuming that your +divide function +wants to return two values, a quotient and a remainder, you can write: +

        + +
        +
        +(receive (quotient remainder)
+    (divide 35 17)
+  body...)
+
        +
        + +

        +In body, the first result of +divide will be bound to the variable +quotient, and the second result to remainder. +

        + +
      + +

      +See also the "multivalue" example. +

      + +

      Constants are exported as a function that returns the value. The +%feature("constasvar") can be applied to any constant, immutable variable, or enum. +Instead of exporting the constant as a function that must be called, the +constant will appear as a scheme variable. See +Features and the %feature directive +for info on how to apply the %feature.

      + +

      20.6 Representation of pointers as smobs

      + + +

      +For pointer types, SWIG uses Guile smobs. SWIG smobs print +like this: #<swig struct xyzzy * 0x1234affe> Two of +them are equal? if and only if they have the same type +and value. + +

      +To construct a Scheme object from a C pointer, the wrapper code calls +the function SWIG_NewPointerObj(), passing a pointer to a +struct representing the pointer type. The type index to store in the +upper half of the CAR is read from this struct. +To get the pointer represented by a smob, the wrapper code calls the +function SWIG_ConvertPtr(), passing a pointer to a struct +representing the expected pointer type. See also +The run-time type checker. +If the Scheme object passed was not a SWIG smob representing a compatible +pointer, a wrong-type-arg exception is raised. + +

      20.6.1 GH Smobs

      + + +

      +In earlier versions of SWIG, C pointers were represented as Scheme +strings containing a hexadecimal rendering of the pointer value and a +mangled type name. As Guile allows registering user types, so-called +"smobs" (small objects), a much cleaner representation has been +implemented now. The details will be discussed in the following. +

      + +

      A smob is a cons cell where the lower half of the CAR contains the smob type +tag, while the upper half of the CAR and the whole CDR are available. Every +module creates its own smob type in the clientdata field of the module. So the +lower 16 bits of the car of the smob store the tag and the upper 16 bits store +the index this type is in the array. We can then, given a smob, find its +swig_type_info struct by using the tag (lower 16 bits of car) to find which +module this type is in (since each tag is unique for the module). Then we use +the upper 16 bits to index into the array of types attached to this module. +Looking up the module from the tag is worst case O(# of modules) but average +case O(1). This is because the modules are stored in a circularly linked list, +and when we start searching the modules for the tag, we start looking with the +module that the function doing the lookup is in. SWIG_Guile_ConvertPtr() takes +as its first argument the swig_module_info * of the calling function, which is +where we start comparing tags. Most types will be looked up in the same module +that created them, so the first module we check will most likely be correct. +Once we have a swig_type_info structure, we loop through the linked list of +casts, using pointer comparisons.

      + +

      20.6.2 SCM Smobs

      + + +

      The SCM interface (using the "-scm" argument to swig) uses swigrun.swg. +The whole type system, when it is first initialized, creates two smobs named "swig" and "collected_swig". +The swig smob is used for non-garbage collected smobs, while the collected_swig smob is used as described +below. Each smob has the same format, which is a double cell created by SCM_NEWSMOB2() +The first word of data is the pointer to the object and the second word of data is the swig_type_info * +structure describing this type. This is a lot easier than the GH interface above because we can store +a pointer to the type info structure right in the type. With the GH interface, there was not enough +room in the smob to store two whole words of data so we needed to store part of the "swig_type_info address" +in the smob tag. If a generated GOOPS module has been loaded, smobs will be wrapped by the corresponding +GOOPS class.

      + + +

      20.6.3 Garbage Collection

      + + +

      Garbage collection is a feature of the new SCM interface, and it is automatically included +if you pass the "-scm" flag to swig. Thus the swig garbage collection support requires guile >1.6. +Garbage collection works like this. Every swig_type_info structure stores in its clientdata field a pointer +to the destructor for this type. The destructor is the generated wrapper around the delete function. +So swig still exports a wrapper for the destructor, it just does not call scm_c_define_gsubr() for +the wrapped delete function. So the only way to delete an object is from the garbage collector, since the +delete function is not available to scripts. How swig determines if a type should be garbage collected +is exactly like described in +Object ownership and %newobject in the SWIG manual. All typemaps use an $owner var, and +the guile module replaces $owner with 0 or 1 depending on feature:new.

      + +

      20.7 Exception Handling

      + + +

      +SWIG code calls scm_error on exception, using the following +mapping: + +

      +
      +      MAP(SWIG_MemoryError,	"swig-memory-error");
+      MAP(SWIG_IOError,		"swig-io-error");
+      MAP(SWIG_RuntimeError,	"swig-runtime-error");
+      MAP(SWIG_IndexError,	"swig-index-error");
+      MAP(SWIG_TypeError,	"swig-type-error");
+      MAP(SWIG_DivisionByZero,	"swig-division-by-zero");
+      MAP(SWIG_OverflowError,	"swig-overflow-error");
+      MAP(SWIG_SyntaxError,	"swig-syntax-error");
+      MAP(SWIG_ValueError,	"swig-value-error");
+      MAP(SWIG_SystemError,	"swig-system-error");
+
      +
      + +

      +The default when not specified here is to use "swig-error". +See Lib/exception.i for details. + +

      20.8 Procedure documentation

      + + +

      If invoked with the command-line option -procdoc +file, SWIG creates documentation strings for the +generated wrapper functions, describing the procedure signature and +return value, and writes them to file. You need Guile 1.4 +or later to make use of the documentation files. + +

      SWIG can generate documentation strings in three formats, which are +selected via the command-line option -procdocformat +format: +

        +
      • guile-1.4 (default): Generates a format suitable for Guile 1.4. +
      • plain: Generates a format suitable for Guile 1.4.1 and +later. +
      • texinfo: Generates texinfo source, which must be run +through texinfo in order to get a format suitable for Guile 1.4.1 and +later. +
      + +

      You need to register the generated documentation file with Guile +like this: + +

      +
      +(use-modules (ice-9 documentation))
+(set! documentation-files 
+      (cons "file" documentation-files))
+
      +
      + +

      Documentation strings can be configured using the Guile-specific +typemap argument doc. See Lib/guile/typemaps.i for +details. + +

      20.9 Procedures with setters

      + + +

      For global variables, SWIG creates a single wrapper procedure +(variable :optional value), which is used for +both getting and setting the value. For struct members, SWIG creates +two wrapper procedures (struct-member-get +pointer) and (struct-member-set pointer value). + +

      If invoked with the command-line option -emit-setters +(recommended), +SWIG will additionally create procedures with setters. For global +variables, the procedure-with-setter variable +is created, so you can use (variable) to get +the value and (set! (variable) +value) to set it. For struct members, the +procedure-with-setter struct-member +is created, so you can use (struct-member +pointer) to get the value and (set! +(struct-member pointer) +value) to set it. + +

      If invoked with the command-line option -only-setters, +SWIG will only create procedures with setters, i.e., for +struct members, the procedures (struct-member-get +pointer) and (struct-member-set pointer +value) are not generated. + +

      20.10 GOOPS Proxy Classes

      + + +

      SWIG can also generate classes and generic functions for use with +Guile's Object-Oriented Programming System (GOOPS). GOOPS is a +sophisticated object system in the spirit of the Common Lisp Object +System (CLOS). + +

      GOOPS support is +only available with the new SCM interface (enabled with the +-scm command-line option of SWIG). To enable GOOPS +support, pass the -proxy argument to +swig. This will export the GOOPS wrapper definitions into the +module.scm file in the directory specified by -outdir or the +current directory. GOOPS support requires either passive or module linkage.

      + +

      The generated file will contain definitions of GOOPS classes mimicking the C++ class hierarchy. +

      Enabling GOOPS support implies -emit-setters. + +

      If -emit-slot-accessors is also passed as an argument, +then the generated file will contain accessor methods for all the +slots in the classes and for global variables. The input class

      +
      +  class Foo {
+    public:
+      Foo(int i) : a(i) {}
+      int a;
+      int getMultBy(int i) { return a * i; }
+      Foo getFooMultBy(int i) { return Foo(a * i); }
+  }; 
+  Foo getFooPlus(int i) { return Foo(a + i); }
+
      + +

      +will produce (if -emit-slot-accessors is not passed as a parameter) +

      + +
      +(define-class <Foo> (<swig>)
+  (a #:allocation #:swig-virtual 
+     #:slot-ref primitive:Foo-a-get 
+     #:slot-set! primitive:Foo-a-set)
+  #:metaclass <swig-metaclass>
+  #:new-function primitive:new-Foo
+)
+(define-method (getMultBy (swig_smob <Foo>) i)
+  (primitive:Foo-getMultBy  (slot-ref swig_smob 'smob) i))
+(define-method (getFooMultBy (swig_smob <Foo>) i)
+  (make <Foo> #:init-smob (primitive:Foo-getFooMultBy  (slot-ref swig_smob 'smob) i)))
+
+(define-method (getFooPlus i)
+  (make <Foo> #:init-smob (primitive:getFooPlus i)))
+
+(export <Foo> getMultBy getFooMultBy getFooPlus )
+
      + +

      +and will produce (if -emit-slot-accessors is passed as a parameter) +

      + +
      +(define-class <Foo> (<swig>)
+  (a #:allocation #:swig-virtual 
+     #:slot-ref primitive:Foo-a-get 
+     #:slot-set! primitive:Foo-a-set 
+     #:accessor a)
+  #:metaclass <swig-metaclass>
+  #:new-function primitive:new-Foo
+)
+(define-method (getMultBy (swig_smob <Foo>) i)
+  (primitive:Foo-getMultBy  (slot-ref swig_smob 'smob) i))
+(define-method (getFooMultBy (swig_smob <Foo>) i)
+  (make <Foo> #:init-smob (primitive:Foo-getFooMultBy  (slot-ref swig_smob 'smob) i)))
+
+(define-method (getFooPlus i)
+  (make <Foo> #:init-smob (primitive:getFooPlus i)))
+
+(export <Foo> a getMultBy getFooMultBy getFooPlus )
+
      + +

      +which can then be used by this code +

      + +
      +;; not using getters and setters
+(define foo (make <Foo> #:args '(45)))
+(slot-ref foo 'a)
+(slot-set! foo 'a 3)
+(getMultBy foo 4)
+(define foo2 (getFooMultBy foo 7))
+(slot-ref foo 'a)
+(slot-ref (getFooPlus foo 4) 'a)
+
+;; using getters and setters
+(define foo (make <Foo> #:args '(45)))
+(a foo)
+(set! (a foo) 5)
+(getMultBy foo 4)
+(a (getFooMultBy foo 7))
+
      + +

      Notice that constructor arguments are passed as a list after the #:args keyword. Hopefully in +the future the following will be valid (make <Foo> #:a 5 #:b 4)

      + +

      Also note that the order the declarations occur in the .i file make a difference. For example, +

      + +
      +%module test
+
+%{ #include "foo.h" %}
+
+%inline %{
+  int someFunc(Foo &a) {
+    ...
+  }
+%}
+
+%include "foo.h"
+
      + +

      +This is a valid SWIG file it will work as you think it will for primitive support, but the generated +GOOPS file will be broken. Since the someFunc definition is parsed by SWIG before all the +declarations in foo.h, the generated GOOPS file will contain the definition of someFunc() +before the definition of <Foo>. The generated GOOPS file would look like +

      + +
      +;;...
+
+(define-method (someFunc (swig_smob <Foo>))
+  (primitive:someFunc (slot-ref swig_smob 'smob)))
+
+;;...
+
+(define-class <Foo> (<swig>)
+  ;;...
+)
+
+;;...
+
      + +

      +Notice that <Foo> is used before it is defined. The fix is to just put the +%import "foo.h" before the %inline block. +

      + +

      20.10.1 Naming Issues

      + + +

      As you can see in the example above, there are potential naming conflicts. The default exported +accessor for the Foo::a variable is named a. The name of the wrapper global +function is getFooPlus. +If the -useclassprefix option is passed to swig, the name of all accessors and member +functions will be prepended with the class name. So the accessor will be called Foo-a and +the member functions will be called Foo-getMultBy. Also, if the +-goopsprefix goops: argument is passed to swig, every identifier will be prefixed by +goops:

      + +

      Two guile-modules are created by SWIG. The first module contains the primitive definitions +of all the wrapped functions and variables, and is located either in the _wrap.cxx file (with -Linkage +module) or in the scmstub file (if -Linkage passive -scmstub). The name of this +guile-module is the swig-module name (given on the command line with the -module argument or with the +%module directive) concatenated with the string "-primitive". For +example, if %module Test is set in the swig interface file, the name of the guile-module in +the scmstub or -Linkage module will be Test-primitive. Also, the scmstub +file will be named Test-primitive.scm. +The string "primitive" can be changed by the -primsuffix swig +argument. So the same interface, with the -primsuffix base will produce a module called +Test-base. +The second generated guile-module contains all the GOOPS class definitions and is located in +a file named module.scm in the directory specified with -outdir or the current directory. +The name of this guile-module is the name of the +swig-module (given on the command line or with the %module directive). +In the previous example, the GOOPS definitions will be in a file named Test.scm.

      + +

      Because of the naming conflicts, you can't in general use both the -primitive and the GOOPS +guile-modules at the same time. To do this, you need to rename the exported symbols from one or both +guile-modules. For example,

      +
      +(use-modules ((Test-primitive) #:renamer (symbol-prefix-proc 'primitive:)))
+(use-modules ((Test) #:renamer (symbol-prefix-proc 'goops:)))
+
      + +

      TODO: Renaming class name prefixes?

      + +

      20.10.2 Linking

      + + +

      The guile-modules generated above all need to be linked together. GOOPS support requires +either passive or module linkage. The exported GOOPS guile-module will be the name of the swig-module +and should be located in a file called Module.scm. This should be installed on the autoload +path for guile, so that (use-modules (Package Module)) will load everything needed. +Thus, the top of the GOOPS guile-module will contain code to load everything needed by the interface +(the shared library, the scmstub module, etc.). +The %goops directive inserts arbitrary code into the generated GOOPS guile-module, and +should be used to load the dependent libraries.

      + +

      This breaks up into three cases

      +
        +
      • Passive Linkage without -scmstub: Note that this linkage style has the potential for naming +conflicts, since the primitive exported function and variable names are not wrapped in a guile-module +and might conflict with names from the GOOPS guile-module (see above). Pass the -goopsprefix +argument to solve this problem. If the -exportprimitive option is passed to SWIG the +(export ...) code that would be exported into the scmstub file is exported at the bottom +of the generated GOOPS guile-module. +The %goops directive should contain code to load the .so library. + +
        +%goops %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %}
+
        + +

        +Produces the following code at the top of the generated GOOPS guile-module +(with the -package my/modules -module foo command line arguments) +

        + +
        +(define-module (my modules foo))
+
+;; %goops directive goes here
+(load-extension "./foo.so" "scm_init_my_modules_foo_module") 
+
+(use-modules (oop goops) (Swig common))
+
        +
        • + +

      • Passive Linkage with -scmstub: Here, the name of the scmstub file should be +Module-primitive.scm (with primitive replaced with whatever is given with the -primsuffix +argument. The code to load the .so library should be located in the %scheme directive, +which will then be added to the scmstub file. +Swig will automatically generate the line (use-modules (Package Module-primitive)) +into the GOOPS guile-module. So if Module-primitive.scm is on the autoload path for guile, the +%goops directive can be empty. Otherwise, the %goops directive should contain +whatever code is needed to load the Module-primitive.scm file into guile.

        + +
        +%scheme %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %}
+// only include the following definition if (my modules foo) cannot
+// be loaded automatically
+%goops %{ 
+  (primitive-load "/path/to/foo-primitive.scm") 
+  (primitive-load "/path/to/Swig/common.scm")
+%}
+
        + +

        +Produces the following code at the top of the generated GOOPS guile-module +

        + +
        +(define-module (my modules foo))
+
+;; %goops directive goes here (if any)
+(primitive-load "/path/to/foo-primitive.scm")
+(primitive-load "/path/to/Swig/common.scm")
+
+(use-modules (oop goops) (Swig common))
+(use-modules ((my modules foo-primitive) :renamer (symbol-prefix-proc
+                                                       'primitive:)))
+
+
        +
        • + +

      • Module Linkage: This is very similar to passive linkage with a scmstub file. +Swig will also automatically generate the line (use-modules +(Package Module-primitive)) into the GOOPS guile-module. Again the %goops +directive should contain whatever code is needed to get that module loaded into guile.

        + +
        +%goops %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %}
+
        + +

        +Produces the following code at the top of the generated GOOPS guile-module +

        + +
        +(define-module (my modules foo))
+
+;; %goops directive goes here (if any)
+(load-extension "./foo.so" "scm_init_my_modules_foo_module") 
+
+(use-modules (oop goops) (Swig common))
+(use-modules ((my modules foo-primitive) :renamer (symbol-prefix-proc
+                                                         'primitive:)))
+
+
        +
        • +
      + +

      (Swig common): The generated GOOPS guile-module also imports definitions from the +(Swig common) guile-module. +This module is included with SWIG and should be installed by SWIG into the autoload path for +guile (based on the configure script and whatever arguments are passed). If it is not, then the +%goops directive also needs to contain code to load the common.scm file +into guile. Also note that if you are trying to install the generated wrappers on a computer without +SWIG installed, you will need to include the common.swg file along with the install.

      + +

      Multiple Modules: Type dependencies between modules is supported. For example, if +mod1 includes definitions of some classes, and mod2 includes some classes +derived from classes in mod1, the generated GOOPS file for mod2 will declare +the correct superclasses. The only problem is that since mod2 uses symbols from +mod1, the mod2 GOOPS file must include a (use-modules (mod2)). +Currently, SWIG does not automatically export this line; it must be included in the %goops +directive of mod2. Maybe in the future SWIG can detect dependencies and export this line. +(how do other language modules handle this problem?)

      + + + diff --git a/Doc/Manual/Introduction.html b/Doc/Manual/Introduction.html new file mode 100644 index 0000000..099454c --- /dev/null +++ b/Doc/Manual/Introduction.html @@ -0,0 +1,462 @@ + + + +Introduction + + + + +

      2 Introduction

      + +
      + +
      + + + + +

      2.1 What is SWIG?

      + + +

      +SWIG is a software development tool that simplifies the task of +interfacing different languages to C and C++ programs. In a +nutshell, SWIG is a compiler that takes C declarations and creates +the wrappers needed to access those declarations from other languages including +including Perl, Python, Tcl, Ruby, Guile, and Java. SWIG normally +requires no modifications to existing code and can often be used to +build a usable interface in only a few minutes. Possible applications +of SWIG include: +

      + +
        +
      • Building interpreted interfaces to existing C programs. +
      • Rapid prototyping and application development. +
      • Interactive debugging. +
      • Reengineering or refactoring of legacy software into a scripting language components. +
      • Making a graphical user interface (using Tk for example). +
      • Testing of C libraries and programs (using scripts). +
      • Building high performance C modules for scripting languages. +
      • Making C programming more enjoyable (or tolerable depending on your point of view). +
      • Impressing your friends. +
      • Obtaining vast sums of research funding (although obviously not applicable to the author). +
      + +

      +SWIG was originally designed to make it extremely easy for scientists +and engineers to build extensible scientific software without having to get a +degree in software engineering. Because of this, the use of +SWIG tends to be somewhat informal and ad-hoc (e.g., SWIG does not +require users to provide formal interface specifications as you would find in +a dedicated IDL compiler). Although +this style of development isn't appropriate for every +project, it is particularly well suited to software development in the +small; especially the research and development work that is commonly found +in scientific and engineering projects. + +

      2.2 Why use SWIG?

      + + +

      +As stated in the previous section, the primary purpose of SWIG is to simplify +the task of integrating C/C++ with other programming languages. However, why would +anyone want to do that? To answer that question, it is useful to list a few strengths +of C/C++ programming: +

      + +
        +
      • Excellent support for writing programming libraries. +
      • High performance (number crunching, data processing, graphics, etc.). +
      • Systems programming and systems integration. +
      • Large user community and software base. +
      + +

      +Next, let's list a few problems with C/C++ programming +

      + +
        +
      • Writing a user interface is rather painful (i.e., consider programming with MFC, X11, GTK, or any number +of other libraries). +
      • Testing is time consuming (the compile/debug cycle). +
      • Not easy to reconfigure or customize without recompilation. +
      • Modularization can be tricky. +
      • Security concerns (buffer overflow for instance). +
      +

      +To address these limitations, many programmers have arrived at the +conclusion that it is much easier to use different programming +languages for different tasks. For instance, writing a graphical user +interface may be significantly easier in a scripting language like +Python or Tcl (consider the reasons why millions of programmers have used languages like +Visual Basic if you need more proof). An interactive interpreter might also serve as a +useful debugging and testing tool. Other languages like Java might +greatly simplify the task of writing distributed computing software. +The key point is that different programming languages offer different +strengths and weaknesses. Moreover, it is extremely unlikely that any +programming is ever going to be perfect. Therefore, by combining +languages together, you can utilize the best features of each language +and greatly simplify certain aspects of software development. +

      + +

      +From the standpoint of C/C++, a lot of people use SWIG because they want to break +out of the traditional monolithic C programming model which usually results +in programs that resemble this: + +

        +
      • A collection of functions and variables that do something useful. +
      • A main() program that starts everything. +
      • A horrible collection of hacks that form some kind of user interface (but +which no-one really wants to touch). +
      +

      +Instead of going down that route, incorporating C/C++ into a higher level language +often results in a more modular design, less code, better flexibility, and increased +programmer productivity. +

      + +

      +SWIG tries to make the problem of C/C++ integration as painless as possible. +This allows you to focus on the underlying C +program and using the high-level language interface, but not +the tedious and complex chore of making the two languages talk to each +other. At the same time, SWIG recognizes that all applications are different. Therefore, +it provides a wide variety of customization features that let you change almost +every aspect of the language bindings. This is the main reason why SWIG has such a large +user manual ;-). + +

      2.3 A SWIG example

      + + +

      +The best way to illustrate SWIG is with a simple example. Consider the +following C code: +

      + +
      +/* File : example.c */
+
+double  My_variable  = 3.0;
+
+/* Compute factorial of n */
+int  fact(int n) {
+	if (n <= 1) return 1;
+	else return n*fact(n-1);
+}
+
+/* Compute n mod m */
+int my_mod(int n, int m) {
+	return(n % m);
+}
+
      + +

      +Suppose that you wanted to access these functions and the global +variable My_variable from Tcl. You start by making a SWIG +interface file as shown below (by convention, these files carry a .i +suffix) : + +

      2.3.1 SWIG interface file

      + + +
      +/* File : example.i */
+%module example
+%{
+/* Put headers and other declarations here */
+extern double My_variable;
+extern int    fact(int);
+extern int    my_mod(int n, int m);
+%}
+
+extern double My_variable;
+extern int    fact(int);
+extern int    my_mod(int n, int m);
+
      + +

      +The interface file contains ANSI C function prototypes and variable +declarations. The %module directive defines the name of the +module that will be created by SWIG. The %{,%} block +provides a location for inserting additional code such as C header +files or additional C declarations. + +

      2.3.2 The swig command

      + + +

      +SWIG is invoked using the swig command. We can use this to +build a Tcl module (under Linux) as follows : +

      + +
      +unix > swig -tcl example.i
+unix > gcc -c -fpic example.c example_wrap.c -I/usr/local/include
+unix > gcc -shared example.o example_wrap.o -o example.so
+unix > tclsh
+% load ./example.so
+% fact 4
+24
+% my_mod 23 7
+2
+% expr $My_variable + 4.5
+7.5
+%
+
      +

      + +The swig command produced a new file called +example_wrap.c that should be compiled along with the +example.c file. Most operating systems and scripting +languages now support dynamic loading of modules. In our example, our +Tcl module has been compiled into a shared library that can be loaded +into Tcl. When loaded, Tcl can now access the functions +and variables declared in the SWIG interface. A look at the file +example_wrap.c reveals a hideous mess. However, you +almost never need to worry about it. + +

      2.3.3 Building a Perl5 module

      + + +

      +Now, let's turn these functions into a Perl5 module. Without making +any changes type the following (shown for Solaris): +

      + +
      +unix > swig -perl5 example.i
+unix > gcc -c example.c example_wrap.c \
+	-I/usr/local/lib/perl5/sun4-solaris/5.003/CORE
+unix > ld -G example.o example_wrap.o -o example.so		# This is for Solaris
+unix > perl5.003
+use example;
+print example::fact(4), "\n";
+print example::my_mod(23,7), "\n";
+print $example::My_variable + 4.5, "\n";
+<ctrl-d>
+24
+2
+7.5
+unix >
+
      + + +

      2.3.4 Building a Python module

      + + +

      +Finally, let's build a module for Python (shown for Irix). +

      + +
      +unix > swig -python example.i
+unix > gcc -c -fpic example.c example_wrap.c -I/usr/local/include/python2.0
+unix > gcc -shared example.o example_wrap.o -o _example.so
+unix > python
+Python 2.0 (#6, Feb 21 2001, 13:29:45)
+[GCC egcs-2.91.66 19990314/Linux (egcs-1.1.2 release)] on linux2
+Type "copyright", "credits" or "license" for more information.     
+>>> import example
+>>> example.fact(4)
+24
+>>> example.my_mod(23,7)
+2
+>>> example.cvar.My_variable + 4.5
+7.5
+
      + +

      2.3.5 Shortcuts

      + + +

      +To the truly lazy programmer, one may wonder why we needed the extra +interface file at all. As it turns out, you can often do without +it. For example, you could also build a Perl5 module by just running +SWIG on the C header file and specifying a module name as follows +

      + +
      +unix > swig -perl5 -module example example.h
+unix > gcc -c example.c example_wrap.c \
+	-I/usr/local/lib/perl5/sun4-solaris/5.003/CORE
+unix > ld -G example.o example_wrap.o -o example.so
+unix > perl5.003
+use example;
+print example::fact(4), "\n";
+print example::my_mod(23,7), "\n";
+print $example::My_variable + 4.5, "\n";
+<ctrl-d>
+24
+2
+7.5
+
      + +

      2.4 Supported C/C++ language features

      + + +

      +A primary goal of the SWIG project is to make the language binding +process extremely easy. Although a few simple examples have been shown, +SWIG is quite capable in supporting most of C++. Some of the +major features include: +

      + +
        +
      • Full C99 preprocessing. +
      • All ANSI C and C++ datatypes. +
      • Functions, variables, and constants. +
      • Classes. +
      • Single and multiple inheritance. +
      • Overloaded functions and methods. +
      • Overloaded operators. +
      • C++ templates (including member templates, specialization, and partial specialization). +
      • Namespaces. +
      • Variable length arguments. +
      • C++ smart pointers. +
      + +

      +Currently, the only major C++ feature not supported is nested classes--a limitation +that will be removed in a future release. +

      + +

      +It is important to stress that SWIG is not a simplistic C++ lexing +tool like several apparently similar wrapper generation tools. SWIG +not only parses C++, it implements the full C++ type system and it is +able to understand C++ semantics. SWIG generates its wrappers with +full knowledge of this information. As a result, you will find SWIG +to be just as capable of dealing with nasty corner cases as it is in +wrapping simple C++ code. In fact, SWIG is able handle C++ code that +stresses the very limits of many C++ compilers. + + +

      2.5 Non-intrusive interface building

      + + +

      +When used as intended, SWIG requires minimal (if any) modification to +existing C or C++ code. This makes SWIG extremely easy to use with existing +packages and promotes software reuse and modularity. By making +the C/C++ code independent of the high level interface, you can change the +interface and reuse the code in other applications. It is also +possible to support different types of interfaces depending on the application. +

      + +

      2.6 Incorporating SWIG into a build system

      + + +

      +SWIG is a command line tool and as such can be incorporated into any build system that supports invoking external tools/compilers. +SWIG is most commonly invoked from within a Makefile, but is also known to be invoked from from popular IDEs such as +Microsoft Visual Studio. +

      + +

      +If you are using the GNU Autotools +(Autoconf/ +Automake/ +Libtool) +to configure SWIG use in your project, the SWIG Autoconf macros can be used. +The primary macro is ac_pkg_swig, see +http://www.gnu.org/software/ac-archive/htmldoc/ac_pkg_swig.html. +The ac_python_devel macro is also helpful for generating Python extensions. See the +Autoconf Macro Archive +for further information on this and other Autoconf macros. +

      + +

      +There is growing support for SWIG in some build tools, for example CMake +is a cross-platform, open-source build manager with built in support for SWIG. CMake can detect the SWIG executable +and many of the target language libraries for linking against. +CMake knows how to build shared libraries and loadable modules on many different operating systems. +This allows easy cross platform SWIG development. It also can generate the custom commands necessary for +driving SWIG from IDE's and makefiles. All of this can be done from a single cross platform input file. +The following example is a CMake input file for creating a python wrapper for the SWIG interface file, example.i: +

      + +
      +
+# This is a CMake example for Python
+
+FIND_PACKAGE(SWIG REQUIRED)
+INCLUDE(${SWIG_USE_FILE})
+
+FIND_PACKAGE(PythonLibs)
+INCLUDE_DIRECTORIES(${PYTHON_INCLUDE_PATH})
+
+INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})
+
+SET(CMAKE_SWIG_FLAGS "")
+
+SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES CPLUSPLUS ON)
+SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES SWIG_FLAGS "-includeall")
+SWIG_ADD_MODULE(example python example.i example.cxx)
+SWIG_LINK_LIBRARIES(example ${PYTHON_LIBRARIES})
+
+
      +

      +The above example will generate native build files such as makefiles, nmake files and Visual Studio projects +which will invoke SWIG and compile the generated C++ files into _example.so (UNIX) or _example.pyd (Windows). +For other target languages on Windows a dll, instead of a .pyd file, is usually generated. +

      + +

      2.7 Hands off code generation

      + + +

      +SWIG is designed to produce working code that needs no +hand-modification (in fact, if you look at the output, you probably +won't want to modify it). You should think of your target language interface being +defined entirely by the input to SWIG, not the resulting output +file. While this approach may limit flexibility for hard-core hackers, +it allows others to forget about the low-level implementation +details. +

      + +

      2.8 SWIG and freedom

      + + +

      +No, this isn't a special section on the sorry state of world politics. +However, it may be useful to know that SWIG was written with a +certain "philosophy" about programming---namely that programmers are +smart and that tools should just stay out of their way. Because of +that, you will find that SWIG is extremely permissive in what it lets +you get away with. In fact, you can use SWIG to go well beyond +"shooting yourself in the foot" if dangerous programming is your goal. +On the other hand, this kind of freedom may be exactly what is needed +to work with complicated and unusual C/C++ applications. +

      + +

      +Ironically, the freedom that SWIG provides is countered by an +extremely conservative approach to code generation. At it's core, SWIG +tries to distill even the most advanced C++ code down to a small +well-defined set of interface building techniques based on ANSI C +programming. Because of this, you will find that SWIG interfaces can +be easily compiled by virtually every C/C++ compiler and that they can +be used on any platform. Again, this is an important part of staying out +of the programmer's way----the last thing any developer wants to do is +to spend their time debugging the output of a tool that relies on +non-portable or unreliable programming features. + + + diff --git a/Doc/Manual/Java.html b/Doc/Manual/Java.html new file mode 100644 index 0000000..fc5646c --- /dev/null +++ b/Doc/Manual/Java.html @@ -0,0 +1,7759 @@ + + + +SWIG and Java + + + +

      21 SWIG and Java

      + +
      + +
      + + + + +

      +This chapter describes SWIG's support of Java. +It covers most SWIG features, but certain low-level details are covered in less depth than in earlier chapters. +

      + + +

      21.1 Overview

      + + +

      +The 100% Pure Java effort is a commendable concept, however in the real world programmers often either need to re-use their existing code or in some situations +want to take advantage of Java but are forced into using some native (C/C++) code. +The Java extension to SWIG makes it very easy to plumb in existing C/C++ code for access from Java, as SWIG writes the Java Native Interface (JNI) code for you. +It is different to using the 'javah' tool as SWIG will wrap existing C/C++ code, whereas javah takes 'native' Java function declarations and creates C/C++ function prototypes. +SWIG wraps C/C++ code using Java proxy classes and is very useful if you want to have access to large amounts of C/C++ code from Java. +If only one or two JNI functions are needed then using SWIG may be overkill. +SWIG enables a Java program to easily call into C/C++ code from Java. +Historically, SWIG was not able to generate any code to call into Java code from C++. +However, SWIG now supports full cross language polymorphism and code is generated to call up from C++ to Java when wrapping C++ virtual methods. +

      + +

      +Java is one of the few non-scripting language modules in SWIG. +As SWIG utilizes the type safety that the Java language offers, it takes a somewhat different approach to that used for scripting languages. +In particular runtime type checking and the runtime library are not used by Java. +This should be borne in mind when reading the rest of the SWIG documentation. +This chapter on Java is relatively self contained and will provide you with nearly everything you need for using SWIG and Java. +However, the "SWIG Basics" chapter will be a useful read in conjunction with this one. +

      + +

      +This chapter starts with a few practicalities on running SWIG and compiling the generated code. +If you are looking for the minimum amount to read, have a look at the sections up to and including the +tour of basic C/C++ wrapping section which explains how to call the various C/C++ code constructs from Java. +Following this section are details of the C/C++ code and Java classes that SWIG generates. +Due to the complexities of C and C++ there are different ways in which C/C++ code could be wrapped and called from Java. +SWIG is a powerful tool and the rest of the chapter details how the default code wrapping can be tailored. +Various customisation tips and techniques using SWIG directives are covered. +The latter sections cover the advanced techniques of using typemaps for complete control of the wrapping process. +

      + +

      21.2 Preliminaries

      + + +

      +SWIG 1.1 works with JDKs from JDK 1.1 to JDK1.4 (Java 2 SDK1.4) and should also work with any later versions. +Given the choice, you should probably use the latest version of Sun's JDK. +The SWIG Java module is known to work using Sun's JVM on Solaris, Linux and the various flavours of Microsoft Windows including Cygwin. +The Kaffe JVM is known to give a few problems and at the time of writing was not a fully fledged JVM with full JNI support. +The generated code is also known to work on vxWorks using WindRiver's PJava 3.1. +The best way to determine whether your combination of operating system and JDK will work is to test the examples and test-suite that comes with SWIG. +Run make -k check from the SWIG root directory after installing SWIG on Unix systems.

      + +

      +The Java module requires your system to support shared libraries and dynamic loading. +This is the commonly used method to load JNI code so your system will more than likely support this.

      + +

      21.2.1 Running SWIG

      + + +

      +Suppose that you defined a SWIG module such as the following: +

      + +
      +
      +/* File: example.i */
+%module test
+%{
+#include "stuff.h"
+%}
+int fact(int n);
+
      +
      + + +

      +To build a Java module, run SWIG using the -java option :

      + +
      +%swig -java example.i
+
      + +

      +If building C++, add the -c++ option: +

      + +
      +$ swig -c++ -java example.i
+
      + +

      +This creates two different files; a C/C++ source file example_wrap.c or +example_wrap.cxx and numerous Java files. The generated +C/C++ source file contains the JNI wrapper code that needs to be compiled and linked with the +rest of your C/C++ application. +

      + +

      +The name of the wrapper file is derived from the name of the input file. For example, if the +input file is example.i, the name of the wrapper file is example_wrap.c. +To change this, you can use the -o option. +It is also possible to change the output directory that the Java files are generated into using -outdir. +

      + +

      +The module name, specified with %module, determines the name of various generated classes as discussed later. +Note that the module name does not define a Java package and by default, the generated Java classes do not have a Java package. +The -package option described below can specify a Java package name to use. +

      + +

      +The following sections have further practical examples and details on how you might go about +compiling and using the generated files. +

      + +

      21.2.2 Additional Commandline Options

      + + +

      +The following table list the additional commandline options available for the Java module. They can also be seen by using: +

      + +
      +swig -java -help 
+
      + + + + + + + + + + + + + + + + + + + + + +
      Java specific options
      -nopgcppsuppress the premature garbage collection prevention parameter
      -noproxygenerate the low-level functional interface instead of proxy classes
      -package <name>set name of the Java package to <name>
      + +

      +Their use will become clearer by the time you have finished reading this section on SWIG and Java. +

      + +

      21.2.3 Getting the right header files

      + + +

      +In order to compile the C/C++ wrappers, the compiler needs the jni.h and jni_md.h header files which are part of the JDK. +They are usually in directories like this:

      + +
      +/usr/java/include
+/usr/java/include/<operating_system>
+
      + +

      +The exact location may vary on your machine, but the above locations are typical.

      + +

      21.2.4 Compiling a dynamic module

      + + +

      +The JNI code exists in a dynamic module or shared library (DLL on Windows) and gets loaded by the JVM. +To build a shared library file, you need to compile your module in a manner similar to the following (shown for Solaris):

      + +
      +$ swig -java example.i
+$ gcc -c example_wrap.c  -I/usr/java/include -I/usr/java/include/solaris
+$ ld -G example_wrap.o  -o libexample.so
+
      + +

      +The exact commands for doing this vary from platform to platform. +However, SWIG tries to guess the right options when it is installed. Therefore, +you may want to start with one of the examples in the Examples/java +directory. If that doesn't work, you will need to read the man-pages for +your compiler and linker to get the right set of options. You might also +check the SWIG Wiki for +additional information. +JNI compilation +is a useful reference for compiling on different platforms. +

      + +

      +Important
      +If you are going to use optimisations turned on with gcc (for example -O2), ensure you also compile with -fno-strict-aliasing. The GCC optimisations have become +more aggressive from gcc-4.0 onwards and will result in code that fails with strict aliasing optimisations turned on. See the C/C++ to Java typemaps section for more details. +

      + +

      +The name of the shared library output file is important. +If the name of your SWIG module is "example", the name of the corresponding shared library file should be "libexample.so" (or equivalent depending on your machine, see Dynamic linking problems for more information). +The name of the module is specified using the %module directive or -module command line option.

      + +

      21.2.5 Using your module

      + + +

      +To load your shared native library module in Java, simply use Java's System.loadLibrary method in a Java class:

      + +
      +// runme.java
+
+public class runme {
+  static {
+    System.loadLibrary("example");
+  }
+
+  public static void main(String argv[]) {
+    System.out.println(example.fact(4));
+  }
+}
+
      + +

      +Compile all the Java files and run: +

      + +
      +$ javac *.java
+$ java runme
+24
+$
+
      + +

      +If it doesn't work have a look at the following section which discusses problems loading the shared library. +

      + +

      21.2.6 Dynamic linking problems

      + + +

      +As shown in the previous section the code to load a native library (shared library) is System.loadLibrary("name"). +This can fail with an UnsatisfiedLinkError exception and can be due to a number of reasons. +

      + +

      +You may get an exception similar to this: +

      + +
      +$ java runme
+Exception in thread "main" java.lang.UnsatisfiedLinkError: no example in java.library.path
+        at java.lang.ClassLoader.loadLibrary(ClassLoader.java:1312)
+        at java.lang.Runtime.loadLibrary0(Runtime.java:749)
+        at java.lang.System.loadLibrary(System.java:820)
+        at runme.<clinit>(runme.java:5)
+
      + +

      +The most common cause for this is an incorrect naming of the native library for the name passed to the loadLibrary function. +The string passed to the loadLibrary function must not include the file extension name in the string, that is .dll or .so. +The string must be name and not libname for all platforms. +On Windows the native library must then be called name.dll and on most Unix systems it must be called libname.so. +

      + +

      +Another common reason for the native library not loading is because it is not in your path. +On Windows make sure the path environment variable contains the path to the native library. +On Unix make sure that your LD_LIBRARY_PATH contains the path to the native library. +Adding paths to LD_LIBRARY_PATH can slow down other programs on your system so you may want to consider alternative approaches. +For example you could recompile your native library with extra path information using -rpath if you're using GNU, see the GNU linker documentation (ld man page). +You could use a command such as ldconfig (Linux) or +crle (Solaris) to add additional search paths to the default +system configuration (this requires root access and you will need to read the man pages). +

      + +

      +The native library will also not load if there are any unresolved symbols in the compiled C/C++ code. +The following exception is indicative of this: +

      + +
      +$ java runme
+Exception in thread "main" java.lang.UnsatisfiedLinkError: libexample.so: undefined
+symbol: fact
+        at java.lang.ClassLoader$NativeLibrary.load(Native Method)
+        at java.lang.ClassLoader.loadLibrary0(ClassLoader.java, Compiled Code)
+        at java.lang.ClassLoader.loadLibrary(ClassLoader.java, Compiled Code)
+        at java.lang.Runtime.loadLibrary0(Runtime.java, Compiled Code)
+        at java.lang.System.loadLibrary(System.java, Compiled Code)
+        at runme.<clinit>(runme.java:5)
+$
+
      + +

      +This error usually indicates that you forgot to include some object files or libraries in the linking of the native library file. +Make sure you compile both the SWIG wrapper file and the code you are wrapping into the native library file. +If you forget to compile and link in the SWIG wrapper file into your native library file, you will get a message similar to the following: +

      + +
      +$ java runme
+Exception in thread "main" java.lang.UnsatisfiedLinkError: exampleJNI.gcd(II)I
+	at exampleJNI.gcd(Native Method)
+	at example.gcd(example.java:12)
+	at runme.main(runme.java:18)
+
      + +

      +where gcd is the missing JNI function that SWIG generated into the wrapper file. +Also make sure you pass all of the required libraries to the linker. +The java -verbose:jni commandline switch is also a great way to get more information on unresolved symbols. +One last piece of advice is to beware of the common faux pas of having more than one native library version in your path. +

      + +

      +In summary, ensure that you are using the correct C/C++ compiler and linker combination and options for successful native library loading. +If you are using the examples that ship with SWIG, then the Examples/Makefile must have these set up correctly for your system. +The SWIG installation package makes a best attempt at getting these correct but does not get it right 100% of the time. +The SWIG Wiki also has some settings for commonly used compiler and operating system combinations. +The following section also contains some C++ specific linking problems and solutions. +

      + + +

      21.2.7 Compilation problems and compiling with C++

      + + +

      +On most machines, shared library files should be linked using the C++ +compiler. For example: +

      + +
      +% swig -c++ -java example.i
+% g++ -c -fpic example.cxx
+% g++ -c -fpic example_wrap.cxx -I/usr/java/j2sdk1.4.1/include -I/usr/java/
+j2sdk1.4.1/include/linux
+% g++ -shared example.o example_wrap.o -o libexample.so
+
      + +

      +In addition to this, you may need to include additional library +files to make it work. For example, if you are using the Sun C++ compiler on +Solaris, you often need to add an extra library -lCrun like this: +

      + +
      +% swig -c++ -java example.i
+% CC -c example.cxx
+% CC -c example_wrap.cxx -I/usr/java/include -I/usr/java/include/solaris
+% CC -G example.o example_wrap.o -L/opt/SUNWspro/lib -o libexample.so -lCrun
+
      + +

      +If you aren't entirely sure about the linking for C++, you +might look at an existing C++ program. On many Unix machines, the +ldd command will list library dependencies. This should give +you some clues about what you might have to include when you link your +shared library. For example: +

      + +
      +
      +$ ldd swig
+        libstdc++-libc6.1-1.so.2 => /usr/lib/libstdc++-libc6.1-1.so.2 (0x40019000)
+        libm.so.6 => /lib/libm.so.6 (0x4005b000)
+        libc.so.6 => /lib/libc.so.6 (0x40077000)
+        /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
+$
+
      +
      + +

      +Finally make sure the version of JDK header files matches the version of Java that you are running as incompatibilities could lead to compilation problems or unpredictable behaviour. +

      + + +

      21.2.8 Building on Windows

      + + +

      +Building on Windows is roughly similar to the process used with Unix. +You will want to produce a DLL that can be loaded by the Java Virtual Machine. +This section covers the process of using SWIG with Microsoft Visual C++ 6 although the procedure may be similar with other compilers. +In order for everything to work, you will need to have a JDK installed on your machine in order to read the JNI header files.

      + +

      21.2.8.1 Running SWIG from Visual Studio

      + + +

      +If you are developing your application within Microsoft Visual studio, SWIG can be invoked as a custom build option. +The Examples\java directory has a few Windows Examples containing Visual Studio project (.dsp) files. +The process to re-create the project files for a C project are roughly:

      + +
        +
      • Open up a new workspace and use the AppWizard to select a DLL project. +
      • Add both the SWIG interface file (the .i file), any supporting C files, and the name of the wrapper file that will be created by SWIG (ie. example_wrap.c). +Don't worry if the wrapper file doesn't exist yet--Visual Studio will keep a reference to it. +
      • Select the SWIG interface file and go to the settings menu. Under settings, select the "Custom Build" option. +
      • Enter "SWIG" in the description field. +
      • Enter "swig -java -o $(ProjDir)\$(InputName)_wrap.c $(InputPath)" in the "Build command(s) field" +
      • Enter "$(ProjDir)\$(InputName)_wrap.c" in the "Output files(s) field". +
      • Next, select the settings for the entire project and go to C/C++ tab and select the Preprocessor category . Add the include directories to the JNI header files under "Additional include directories", eg "C:\jdk1.3\include,C:\jdk1.3\include\win32". +
      • Next, select the settings for the entire project and go to Link tab and select the General category. Set the name of the output file to match the name of your Java module (ie. example.dll). +
      • Next, select the example.c and example_wrap.c files and go to the C/C++ tab and select the Precompiled Headers tab in the project settings. Disabling precompiled headers for these files will overcome any precompiled header errors while building. +
      • Finally, add the java compilation as a post build rule in the Post-build step tab in project settings, eg, "c:\jdk1.3\bin\javac *.java" +
      • Build your project. +
      + +

      +Note: If using C++, choose a C++ suffix for the wrapper file, for example example_wrap.cxx. +Use _wrap.cxx instead of _wrap.c in the instructions above and add -c++ when invoking swig. +

      + +

      +Now, assuming all went well, SWIG will be automatically invoked when you build your project. +When doing a build, any changes made to the interface file will result in SWIG being automatically invoked to produce a new version of the wrapper file. +

      + +

      +The Java classes that SWIG output should also be compiled into .class files. +To run the native code in the DLL (example.dll), make sure that it is in your path then run your Java program which uses it, as described in the previous section. +If the library fails to load have a look at Dynamic linking problems. +

      + +

      21.2.8.2 Using NMAKE

      + + +

      +Alternatively, a Makefile for use by NMAKE can be written. +Make sure the environment variables for MSVC++ are available and the MSVC++ tools are in your path. +Now, just write a short Makefile like this :

      + +
      +# Makefile for using SWIG and Java for C code
+
+SRCS          = example.c
+IFILE         = example
+INTERFACE     = $(IFILE).i
+WRAPFILE      = $(IFILE)_wrap.c
+
+# Location of the Visual C++ tools (32 bit assumed)
+
+TOOLS         = c:\msdev
+TARGET        = example.dll
+CC            = $(TOOLS)\bin\cl.exe
+LINK          = $(TOOLS)\bin\link.exe
+INCLUDE32     = -I$(TOOLS)\include
+MACHINE       = IX86
+
+# C Library needed to build a DLL
+
+DLLIBC        = msvcrt.lib oldnames.lib  
+
+# Windows libraries that are apparently needed
+WINLIB        = kernel32.lib advapi32.lib user32.lib gdi32.lib comdlg32.lib winspool.lib
+
+# Libraries common to all DLLs
+LIBS          = $(DLLIBC) $(WINLIB) 
+
+# Linker options
+LOPT      = -debug:full -debugtype:cv /NODEFAULTLIB /RELEASE /NOLOGO \
+             /MACHINE:$(MACHINE) -entry:_DllMainCRTStartup@12 -dll
+
+# C compiler flags
+
+CFLAGS        = /Z7 /Od /c /nologo
+JAVA_INCLUDE    = -ID:\jdk1.3\include -ID:\jdk1.3\include\win32
+
+java::
+	swig -java -o $(WRAPFILE) $(INTERFACE)
+	$(CC) $(CFLAGS) $(JAVA_INCLUDE) $(SRCS) $(WRAPFILE)
+	set LIB=$(TOOLS)\lib
+	$(LINK) $(LOPT) -out:example.dll $(LIBS) example.obj example_wrap.obj
+	javac *.java
+
      + +

      +To build the DLL and compile the java code, run NMAKE (you may need to run vcvars32 first). +This is a pretty simplistic Makefile, but hopefully its enough to get you started. +Of course you may want to make changes for it to work for C++ by adding in the -c++ command line switch for swig and replacing .c with .cxx. +

      + + +

      21.3 A tour of basic C/C++ wrapping

      + + +

      +By default, SWIG attempts to build a natural Java interface +to your C/C++ code. Functions are wrapped as functions, classes are wrapped as classes, +variables are wrapped with JavaBean type getters and setters and so forth. +This section briefly covers the essential aspects of this wrapping. +

      + +

      21.3.1 Modules, packages and generated Java classes

      + + +

      +The SWIG %module directive specifies the name of the Java +module. When you specify `%module example', the module name +determines the name of some of the generated files in the module. +The generated code consists of a module class file example.java, an +intermediary JNI class file, exampleJNI.java as well as numerous other Java proxy class files. +Each proxy class is named after the structs, unions and classes you are wrapping. +You may also get a constants interface file if you are wrapping any unnamed enumerations or constants, for example exampleConstants.java. +When choosing a module name, make sure you don't use the same name as one of the generated +proxy class files nor a Java keyword. Sometimes a C/C++ type cannot be wrapped by a proxy class, for +example a pointer to a primitive type. In these situations a type wrapper class is generated. +Wrapping an enum generates an enum class, either a proper Java enum or a Java class that simulates the enums pattern. +Details of all these generated classes will unfold as you read this section. +

      + +

      +The JNI (C/C++) code is generated into a file which also contains the module name, for example example_wrap.cxx +or example_wrap.c. These C or C++ files complete the contents of the module. +

      + +

      +The generated Java classes can be placed into a Java package by using the -package commandline option. +This is often combined with the -outdir to specify a package directory for generating the Java files. +

      + +
      +swig -java -package com.bloggs.swig -outdir com/bloggs/swig example.i
+
      + +SWIG won't create the directory, so make sure it exists beforehand. + +

      21.3.2 Functions

      + + +

      +There is no such thing as a global Java function so global C functions are wrapped as static methods in +the module class. For example, +

      + +
      +%module example
+int fact(int n);
+
+
      + +

      +creates a static function that works exactly like you think it might:

      + +
      +public class example {
+  public static int fact(int n) {
+    // makes call using JNI to the C function
+  }
+}
+
      + + +

      +The Java class example is the module class. The function can be used as follows from Java:

      + +
      +System.out.println(example.fact(4));
+
      + + +

      21.3.3 Global variables

      + + +

      +C/C++ global variables are fully supported by SWIG. +Java does not allow the overriding of the dot operator so all variables are accessed through getters and setters. +Again because there is no such thing as a +Java global variable, access to C/C++ global variables is done through static getter and setter functions in the module class. +

      + +
      +// SWIG interface file with global variables
+%module example
+...
+%inline %{
+extern int My_variable;
+extern double density;
+%}
+...
+
      + +

      +Now in Java :

      + +
      +// Print out value of a C global variable
+System.out.println("My_variable = " + example.getMy_variable());
+// Set the value of a C global variable
+example.setDensity(0.8442);
+
      + +

      +The value returned by the getter will always be up to date even if the value is changed in C. +Note that the getters and setters produced follow the JavaBean property design pattern. +That is the first letter of the variable name is capitalized and preceded with set or get. +If you have the misfortune of wrapping two variables that differ only in the capitalization of their first letters, +use %rename to change one of the variable names. For example: +

      + +
      +%rename Clash RenamedClash;
+float Clash;
+int clash;
+
      + +

      +If a variable is declared as const, it is wrapped as a read-only variable. +That is only a getter is produced. +

      + +

      +To make ordinary variables read-only, you can use the %immutable directive. For example: +

      + +
      +
      +%{
+extern char *path;
+%}
+%immutable;
+extern char *path;
+%mutable;
+
      +
      + +

      +The %immutable directive stays in effect until it is explicitly disabled or cleared using +%mutable. +See the Creating read-only variables section for further details. +

      + +

      +If you just want to make a specific variable immutable, supply a declaration name. For example: +

      + +
      +
      +%{
+extern char *path;
+%}
+%immutable path;
+...
+extern char *path;      // Read-only (due to %immutable)
+
      +
      + + +

      21.3.4 Constants

      + + +

      +C/C++ constants are wrapped as Java static final variables. +To create a constant, use #define or the +%constant directive. For example: +

      + +
      +
      +#define PI 3.14159
+#define VERSION "1.0"
+%constant int FOO = 42;
+%constant const char *path = "/usr/local";
+
      +
      + +

      +By default the generated static final variables are initialized by making a JNI call to get their value. +The constants are generated into the constants interface and look like this: +

      + +
      +public interface exampleConstants {
+  public final static double PI = exampleJNI.PI_get();
+  public final static String VERSION = exampleJNI.VERSION_get();
+  public final static int FOO = exampleJNI.FOO_get();
+  public final static String path = exampleJNI.path_get();
+}
+
      + +

      +Note that SWIG has inferred the C type and used an appropriate Java type that will fit the range of all possible values for the C type. +By default SWIG generates runtime constants. They are not compiler constants that can, for example, be used +in a switch statement. This can be changed by using the %javaconst(flag) directive. It works like all +the other %feature directives. The default is %javaconst(0). +It is possible to initialize all wrapped constants from pure Java code by placing a %javaconst(1) before SWIG parses the constants. +Putting it at the top of your interface file would ensure this. +Here is an example: +

      + +
      +%javaconst(1);
+%javaconst(0) BIG;
+%javaconst(0) LARGE;
+
+#define EXPRESSION (0x100+5)
+#define BIG 1000LL
+#define LARGE 2000ULL
+
      + +

      +generates: +

      + +
      +public interface exampleConstants {
+  public final static int EXPRESSION = (0x100+5);
+  public final static long BIG = exampleJNI.BIG_get();
+  public final static java.math.BigInteger LARGE = exampleJNI.LARGE_get();
+}
+
      + +

      +Note that SWIG has inferred the C long long type from BIG and used an appropriate Java type (long) as +a Java long is the smallest sized Java type that will take all possible values for a C long long. +Similarly for LARGE. +

      + +

      +Be careful using the %javaconst(1) directive as not all C code will compile as Java code. For example neither the +1000LL value for BIG nor 2000ULL for LARGE above would generate valid Java code. +The example demonstrates how you can target particular constants (BIG and LARGE) with %javaconst. +SWIG doesn't use %javaconst(1) as the default as it tries to generate code that will always compile. +However, using a %javaconst(1) at the top of your interface file is strongly recommended as the preferred compile time constants +will be generated and most C constants will compile as Java code and in any case the odd constant that doesn't can be fixed using %javaconst(0). +

      + +

      +There is an alternative directive which can be used for these rare constant values that won't compile as Java code. +This is the %javaconstvalue(value) directive, where value is a Java code replacement for the C constant and can be either a string or a number. +This is useful if you do not want to use either the parsed C value nor a JNI call, +such as when the C parsed value will not compile as Java code and a compile time constant is required. +The same example demonstrates this: +

      + +
      +%javaconst(1);
+%javaconstvalue("new java.math.BigInteger(\"2000\")") LARGE;
+%javaconstvalue(1000) BIG;
+
+#define EXPRESSION (0x100+5)
+#define BIG 1000LL
+#define LARGE 2000ULL
+
      + +

      +Note the string quotes for "2000" are escaped. The following is then generated: +

      + +
      +public interface exampleConstants {
+  public final static int EXPRESSION = (0x100+5);
+  public final static long BIG = 1000;
+  public final static java.math.BigInteger LARGE = new java.math.BigInteger("2000");
+}
+
      + +

      +Note: declarations declared as const are wrapped as read-only variables and +will be accessed using a getter as described in the previous section. They +are not wrapped as constants. +The exception to this rule are static const integral values defined within a class/struct, where they are wrapped as constants, eg:. +

      + +
      +struct Maths {
+  static const int FIVE = 5;
+};
+
      + + +

      +Compatibility Note: In SWIG-1.3.19 and earlier releases, the constants were generated into the module class and the constants interface didn't exist. +Backwards compatibility is maintained as the module class implements the constants interface (even though some consider this type of interface implementation to be bad practice): +

      + +
      +public class example implements exampleConstants {
+}
+
      + +

      +You thus have the choice of accessing these constants from either the module class or the constants interface, for example, +example.EXPRESSION or exampleConstants.EXPRESSION. +Or if you decide this practice isn't so bad and your own class implements exampleConstants, you can of course just use EXPRESSION. +

      + + +

      21.3.5 Enumerations

      + + +

      +SWIG handles both named and unnamed (anonymous) enumerations. +There is a choice of approaches to wrapping named C/C++ enums. +This is due to historical reasons as SWIG's initial support for enums was limited and Java did not originally have support for enums. +Each approach has advantages and disadvantages and it is important for the user to decide which is the most appropriate solution. +There are four approaches of which the first is the default approach based on the so called Java typesafe enum pattern. +The second generates proper Java enums. +The final two approaches use simple integers for each enum item. +Before looking at the various approaches for wrapping named C/C++ enums, anonymous enums are considered. +

      + +

      21.3.5.1 Anonymous enums

      + + +

      +There is no name for anonymous enums and so they are handled like constants. For example: +

      + +
      +
      +enum { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
+
      +
      + +

      +is wrapped into the constants interface, in a similar manner as constants (see previous section): +

      + +
      +public interface exampleConstants {
+  public final static int ALE = exampleJNI.ALE_get();
+  public final static int LAGER = exampleJNI.LAGER_get();
+  public final static int STOUT = exampleJNI.STOUT_get();
+  public final static int PILSNER = exampleJNI.PILSNER_get();
+  public final static int PILZ = exampleJNI.PILZ_get();
+}
+
      + +

      +The %javaconst(flag) and %javaconstvalue(value) directive introduced in the previous section on constants can also be used with enums. +As is the case for constants, the default is %javaconst(0) as not all C values will compile as Java code. +However, it is strongly recommended to add in a %javaconst(1) directive at the top of your +interface file as it is only on very rare occasions that this will produce code that won't compile under Java. +Using %javaconst(1) will ensure compile time constants are generated, thereby allowing the enum values to be used in Java switch statements. +Example usage: +

      + +
      +
      +%javaconst(1);
+%javaconst(0) PILSNER;
+enum { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
+
      +
      + +

      +generates: +

      + +
      +public interface exampleConstants {
+  public final static int ALE = 0;
+  public final static int LAGER = 10;
+  public final static int STOUT = LAGER + 1;
+  public final static int PILSNER = exampleJNI.PILSNER_get();
+  public final static int PILZ = PILSNER;
+}
+
      + +

      +As in the case of constants, you can access them through either the module class or the constants interface, for example, example.ALE or exampleConstants.ALE. +

      + + +

      21.3.5.2 Typesafe enums

      + + +

      +This is the default approach to wrapping named enums. +The typesafe enum pattern is a relatively well known construct to work around the lack of enums in versions of Java prior to JDK 1.5. +It basically defines a class for the enumeration and permits a limited number of final static instances of the class. +Each instance equates to an enum item within the enumeration. +The implementation is in the "enumtypesafe.swg" file. +Let's look at an example: +

      + +
      +
      +%include "enumtypesafe.swg" // optional as typesafe enums are the default
+enum Beverage { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
+
      +
      + +

      will generate:

      + +
      +
      +public final class Beverage {
+  public final static Beverage ALE = new Beverage("ALE");
+  public final static Beverage LAGER = new Beverage("LAGER", exampleJNI.LAGER_get());
+  public final static Beverage STOUT = new Beverage("STOUT");
+  public final static Beverage PILSNER = new Beverage("PILSNER");
+  public final static Beverage PILZ = new Beverage("PILZ", exampleJNI.PILZ_get());
+  [... additional support methods omitted for brevity ...]
+}
+
      +
      + +

      +See Typesafe enum classes to see the omitted support methods. +Note that the enum item with an initializer (LAGER) is initialized with the enum value obtained via a JNI call. +However, as with anonymous enums and constants, use of the %javaconst directive is strongly recommended to change this behaviour: +

      + +
      +
      +%include "enumtypesafe.swg" // optional as typesafe enums are the default
+%javaconst(1);
+enum Beverage { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
+
      +
      + +

      +will generate: +

      + +
      +
      +public final class Beverage {
+  public final static Beverage ALE = new Beverage("ALE");
+  public final static Beverage LAGER = new Beverage("LAGER", 10);
+  public final static Beverage STOUT = new Beverage("STOUT");
+  public final static Beverage PILSNER = new Beverage("PILSNER");
+  public final static Beverage PILZ = new Beverage("PILZ", PILSNER);
+  [... additional support methods omitted for brevity ...]
+}
+
      +
      + +

      +The generated code is easier to read and more efficient as a true constant is used instead of a JNI call. +As is the case for constants, the default is %javaconst(0) as not all C values will compile as Java code. +However, it is recommended to add in a %javaconst(1) directive at the top of your +interface file as it is only on very rare occasions that this will produce code that won't compile under Java. +The %javaconstvalue(value) directive can also be used for typesafe enums. +Note that global enums are generated into a Java class within whatever package you are using. +C++ enums defined within a C++ class are generated into a static final inner Java class within the Java proxy class. +

      + +

      +Typesafe enums have their advantages over using plain integers in that they they can be used in a typesafe manner. +However, there are limitations. For example, they cannot be used in switch statements and serialization is an issue. +Please look at the following references for further information: + +Replace Enums with Classes in Effective Java Programming on the Sun website, +Create enumerated constants in Java JavaWorld article, +Java Tip 133: More on typesafe enums and +Java Tip 122: Beware of Java typesafe enumerations JavaWorld tips. +

      + +

      +Note that the syntax required for using typesafe enums is the same as that for proper Java enums. +This is useful during the period that a project has to support legacy versions of Java. +When upgrading to JDK 1.5 or later, proper Java enums could be used instead, without users having to change their code. +The following section details proper Java enum generation. +

      + +

      21.3.5.3 Proper Java enums

      + + +

      +Proper Java enums were only introduced in JDK 1.5 so this approach is only compatible with more recent versions of Java. +Java enums have been designed to overcome all the limitations of both typesafe and type unsafe enums +and should be the choice solution, provided older versions of Java do not have to be supported. +In this approach, each named C/C++ enum is wrapped by a Java enum. +Java enums, by default, do not support enums with initializers. +Java enums are in many respects similar to Java classes in that they can be customised with additional methods. +SWIG takes advantage of this feature to facilitate wrapping C/C++ enums that have initializers. +In order to wrap all possible C/C++ enums using proper Java enums, the "enums.swg" file must be used. +Let's take a look at an example. +

      + +
      +
      +%include "enums.swg"
+%javaconst(1);
+enum Beverage { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
+
      +
      + +

      +will generate: +

      + +
      +
      +public enum Beverage {
+  ALE,
+  LAGER(10),
+  STOUT,
+  PILSNER,
+  PILZ(PILSNER);
+  [... additional support methods omitted for brevity ...]
+}
+
      +
      + +

      +See Proper Java enum classes to see the omitted support methods. +The generated Java enum has numerous additional methods to support enums with initializers, such as LAGER above. +Note that as with the typesafe enum pattern, enum items with initializers are by default initialized with the enum value obtained via a JNI call. +However, this is not the case above as we have used the recommended %javaconst(1) to avoid the JNI call. +The %javaconstvalue(value) directive covered in the Constants section can also be used for proper Java enums. +

      + +

      +The additional support methods need not be generated if none of the enum items have initializers and this is covered later in the +Simpler Java enums for enums without initializers section. +

      + +

      21.3.5.4 Type unsafe enums

      + + +

      +In this approach each enum item in a named enumeration is wrapped as a static final integer in a class named after the C/C++ enum name. +This is a commonly used pattern in Java to simulate C/C++ enums, but it is not typesafe. +However, the main advantage over the typesafe enum pattern is enum items can be used in switch statements. +In order to use this approach, the "enumtypeunsafe.swg" file must be used. +Let's take a look at an example. +

      + +
      +
      +%include "enumtypeunsafe.swg"
+%javaconst(1);
+enum Beverage { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
+
      +
      + +

      +will generate: +

      + +
      +
      +public final class Beverage {
+  public final static int ALE = 0;
+  public final static int LAGER = 10;
+  public final static int STOUT = LAGER + 1;
+  public final static int PILSNER = STOUT + 1;
+  public final static int PILZ = PILSNER;
+}
+
      +
      + +

      +As is the case previously, the default is %javaconst(0) as not all C/C++ values will compile as Java code. +However, again it is recommended to add in a %javaconst(1) directive. +and the %javaconstvalue(value) directive covered in the Constants section can also be used for type unsafe enums. +Note that global enums are generated into a Java class within whatever package you are using. +C++ enums defined within a C++ class are generated into a static final inner Java class within the Java proxy class. +

      + +

      +Note that unlike typesafe enums, this approach requires users to mostly use different syntax compared with proper Java enums. +Thus the upgrade path to proper enums provided in JDK 1.5 is more painful. +

      + +

      21.3.5.5 Simple enums

      + + +

      +This approach is similar to the type unsafe approach. +Each enum item is also wrapped as a static final integer. +However, these integers are not generated into a class named after the C/C++ enum. +Instead, global enums are generated into the constants interface. +Also, enums defined in a C++ class have their enum items generated directly into the Java proxy class rather than an inner class within the Java proxy class. +In fact, this approach is effectively wrapping the enums as if they were anonymous enums and the resulting code is as per anonymous enums. +The implementation is in the "enumsimple.swg" file. +

      + +

      +Compatibility Note: +SWIG-1.3.21 and earlier versions wrapped all enums using this approach. +The type unsafe approach is preferable to this one and this simple approach is only included for backwards compatibility with these earlier versions of SWIG. +

      + +

      21.3.6 Pointers

      + + +

      +C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no problem working with +incomplete type information. Here is a rather simple interface: +

      + +
      +
      +%module example
+
+FILE *fopen(const char *filename, const char *mode);
+int fputs(const char *, FILE *);
+int fclose(FILE *);
+
      +
      + +

      +When wrapped, you will be able to use the functions in a natural way from Java. For example: +

      + +
      +
      +SWIGTYPE_p_FILE f = example.fopen("junk","w");
+example.fputs("Hello World\n", f);
+example.fclose(f);
+
      +
      + +

      +C pointers in the Java module are stored in a Java long and cross the JNI boundary held within this 64 bit number. +Many other SWIG language modules use an encoding of the pointer in a string. +These scripting languages use the SWIG runtime type checker for dynamic type checking as they do not support static type checking by a compiler. +In order to implement static type checking of pointers within Java, they are wrapped by a simple Java class. +In the example above the FILE * pointer is wrapped with a type wrapper class +called SWIGTYPE_p_FILE. +

      + +

      +Once obtained, a type wrapper object can be freely passed around to different C functions that +expect to receive an object of that type. The only thing you can't do is +dereference the pointer from Java. Of course, that isn't much of a concern in this example. +

      + +

      +As much as you might be inclined to modify a pointer value directly +from Java, don't. The value is not necessarily the +same as the logical memory address of the underlying object. The value will +vary depending on the native byte-ordering of the platform (i.e., +big-endian vs. little-endian). +Most JVMs are 32 bit applications so any JNI code must also be compiled as 32 bit. +The net result is pointers in JNI code are also 32 bits and +are stored in the high order 4 bytes on big-endian machines and in the low order 4 bytes on little-endian machines. +By design it is also not possible to manually cast +a pointer to a new type by using Java casts as it is particularly dangerous especially when +casting C++ objects. If you need to cast a pointer or +change its value, consider writing some helper functions instead. For +example: +

      + +
      +
      +%inline %{
+/* C-style cast */
+Bar *FooToBar(Foo *f) {
+   return (Bar *) f;
+}
+
+/* C++-style cast */
+Foo *BarToFoo(Bar *b) {
+   return dynamic_cast<Foo*>(b);
+}
+
+Foo *IncrFoo(Foo *f, int i) {
+    return f+i;
+}
+%}
+
      +
      + +

      +Also, if working with C++, you should always try +to use the new C++ style casts. For example, in the above code, the +C-style cast may return a bogus result whereas as the C++-style cast will return +a NULL pointer if the conversion can't be performed. +

      + +

      21.3.7 Structures

      + + +

      +If you wrap a C structure, it is wrapped by a Java class with getters and setters for access to the +member variables. For example, +

      + +
      +struct Vector {
+	double x,y,z;
+};
+
+
      + +

      +is used as follows: +

      + +
      +Vector v = new Vector();
+v.setX(3.5);
+v.setY(7.2);
+double x = v.getX();
+double y = v.getY();
+
      + +

      +The variable setters and getters are also based on the JavaBean design pattern already covered under the Global variables section. +Similar access is provided for unions and the public data members of C++ classes.

      + +

      +This object is actually an instance of a Java class that has been wrapped around a pointer to the C structure. +This instance doesn't actually do anything--it just serves as a proxy. +The pointer to the C object is held in the Java proxy class in much the same way as pointers are held by type wrapper classes. +Further details about Java proxy classes are covered a little later. +

      + +

      +const members of a structure are read-only. Data members +can also be forced to be read-only using the %immutable directive. For example: +

      + +
      +
      +struct Foo {
+   ...
+   %immutable;
+   int x;        /* Read-only members */
+   char *name;
+   %mutable;
+   ...
+};
+
      +
      + +

      +When char * members of a structure are wrapped, the contents are assumed to be +dynamically allocated using malloc or new (depending on whether or not +SWIG is run with the -c++ option). When the structure member is set, the old contents will be +released and a new value created. If this is not the behavior you want, you will have to use +a typemap (described later). +

      + +

      +If a structure contains arrays, access to those arrays is managed through pointers. For +example, consider this: +

      + +
      +
      +struct Bar {
+    int  x[16];
+};
+
      +
      + +

      +If accessed in Java, you will see behavior like this: +

      + +
      +
      +Bar b = new Bar();
+SWIGTYPE_p_int x = b.getX();
+
      +
      + +

      +This pointer can be passed around to functions that expect to receive +an int * (just like C). You can also set the value of an array member using +another pointer. For example: +

      + +
      +
      +Bar b = new Bar();
+SWIGTYPE_p_int x = b.getX();
+Bar c = new Bar();
+c.setX(x);                    // Copy contents of b.x to c.x
+
      +
      + +

      +For array assignment (setters not getters), SWIG copies the entire contents of the array starting with the data pointed +to by b.x. In this example, 16 integers would be copied. Like C, SWIG makes +no assumptions about bounds checking---if you pass a bad pointer, you may get a segmentation +fault or access violation. +The default wrapping makes it hard to set or get just one element of the array and so array access from Java is somewhat limited. +This can be changed easily though by using the approach outlined later in the Wrapping C arrays with Java arrays and +Unbounded C Arrays sections. +

      + +

      +When a member of a structure is itself a structure, it is handled as a +pointer. For example, suppose you have two structures like this: +

      + +
      +
      +struct Foo {
+   int a;
+};
+
+struct Bar {
+   Foo f;
+};
+
      +
      + +

      +Now, suppose that you access the f member of Bar like this: +

      + +
      +
      +Bar b = new Bar();
+Foo x = b.getF();
+
      +
      + +

      +In this case, x is a pointer that points to the Foo that is inside b. +This is the same value as generated by this C code: +

      + +
      +
      +Bar b;
+Foo *x = &b->f;       /* Points inside b */
+
      +
      + +

      +Because the pointer points inside the structure, you can modify the contents and +everything works just like you would expect. For example: +

      + +
      +
      +Bar b = new Bar();
+b.getF().setA(3);   // Modify b.f.a
+Foo x = b.getF();                   
+x.setA(3);          // Modify x.a - this is the same as b.f.a
+
      +
      + + +

      21.3.8 C++ classes

      + + +

      +C++ classes are wrapped by Java classes as well. For example, if you have this class, +

      + +
      +class List {
+public:
+  List();
+  ~List();
+  int  search(char *item);
+  void insert(char *item);
+  void remove(char *item);
+  char *get(int n);
+  int  length;
+};
+
      + +

      +you can use it in Java like this: +

      + +
      +List l = new List();
+l.insert("Ale");
+l.insert("Stout");
+l.insert("Lager");
+String item = l.get(2);
+int length = l.getLength();
+
      + +

      +Class data members are accessed in the same manner as C structures. +

      + +

      +Static class members are unsurprisingly wrapped as static members of the Java class: +

      + +
      +
      +class Spam {
+public:
+   static void foo();
+   static int bar;
+};
+
      +
      + +

      +The static members work like any other Java static member: +

      + +
      +
      +Spam.foo();
+int bar = Spam.getBar();
+
      +
      + + +

      21.3.9 C++ inheritance

      + + +

      +SWIG is fully aware of issues related to C++ inheritance. Therefore, if you have +classes like this +

      + +
      +
      +class Foo {
+...
+};
+
+class Bar : public Foo {
+...
+};
+
      +
      + +

      +those classes are wrapped into a hierarchy of Java classes that reflect the same inheritance +structure: +

      + +
      +
      +Bar b = new Bar();
+Class c = b.getClass();
+System.out.println(c.getSuperclass().getName());
+
      +
      + +

      +will of course display: +

      + +
      +Foo
+
      + + +

      +Furthermore, if you have functions like this +

      + +
      +
      +void spam(Foo *f);
+
      +
      + +

      +then the Java function spam() accepts instances of Foo or instances of any other proxy classes derived from Foo. +

      + +

      +Note that Java does not support multiple inheritance so any multiple inheritance in the C++ code is not going to work. +A warning is given when multiple inheritance is detected and only the first base class is used. +

      + +

      21.3.10 Pointers, references, arrays and pass by value

      + + +

      +In C++, there are many different ways a function might receive +and manipulate objects. For example: +

      + +
      +
      +void spam1(Foo *x);      // Pass by pointer
+void spam2(Foo &x);      // Pass by reference
+void spam3(Foo x);       // Pass by value
+void spam4(Foo x[]);     // Array of objects
+
      +
      + +

      +In Java, there is no detailed distinction like this--specifically, +there are only instances of classes. There are no pointers nor references. +Because of this, SWIG unifies all of these types +together in the wrapper code. For instance, if you actually had the +above functions, it is perfectly legal to do this from Java: +

      + +
      +
      +Foo f = new Foo();  // Create a Foo
+example.spam1(f);   // Ok. Pointer
+example.spam2(f);   // Ok. Reference
+example.spam3(f);   // Ok. Value.
+example.spam4(f);   // Ok. Array (1 element)
+
      +
      + +

      +Similar behavior occurs for return values. For example, if you had +functions like this, +

      + +
      +
      +Foo *spam5();
+Foo &spam6();
+Foo  spam7();
+
      +
      + +

      +then all three functions will return a pointer to some Foo object. +Since the third function (spam7) returns a value, newly allocated memory is used +to hold the result and a pointer is returned (Java will release this memory +when the returned object's finalizer is run by the garbage collector). +

      + +

      21.3.10.1 Null pointers

      + + +

      +Working with null pointers is easy. +A Java null can be used whenever a method expects a proxy class or typewrapper class. +However, it is not possible to pass null to C/C++ functions that take parameters by value or by reference. +If you try you will get a NullPointerException. +

      + +
      +
      +example.spam1(null);   // Pointer - ok
+example.spam2(null);   // Reference - NullPointerException
+example.spam3(null);   // Value - NullPointerException
+example.spam4(null);   // Array - ok
+
      +
      + +

      +For spam1 and spam4 above the Java null gets translated into a NULL pointer for passing to the C/C++ function. +The converse also occurs, that is, NULL pointers are translated into null Java objects when returned from a C/C++ function. +

      + +

      21.3.11 C++ overloaded functions

      + + +

      +C++ overloaded functions, methods, and constructors are mostly supported by SWIG. For example, +if you have two functions like this: +

      + +
      +
      +%module example
+
+void foo(int);
+void foo(char *c);
+
      +
      + +

      +You can use them in Java in a straightforward manner: +

      + +
      +
      +example.foo(3);           // foo(int)
+example.foo("Hello");     // foo(char *c)
+
      +
      + +

      +Similarly, if you have a class like this, +

      + +
      +
      +class Foo {
+public:
+    Foo();
+    Foo(const Foo &);
+    ...
+};
+
      +
      + +

      +you can write Java code like this: +

      + +
      +
      +Foo f = new Foo();        // Create a Foo
+Foo g = new Foo(f);       // Copy f
+
      +
      + +

      +Overloading support is not quite as flexible as in C++. Sometimes there are methods that SWIG +cannot disambiguate as there can be more than one C++ type mapping onto a single Java type. For example: +

      + +
      +
      +void spam(int);
+void spam(unsigned short);
+
      +
      + +

      +Here both int and unsigned short map onto a Java int. +Here is another example: +

      + +
      +
      +void foo(Bar *b);
+void foo(Bar &b);
+
      +
      + +

      +If declarations such as these appear, you will get a warning message like this: +

      + +
      +
      +example.i:12: Warning(515): Overloaded method spam(unsigned short) ignored.
+Method spam(int) at example.i:11 used.
+
      +
      + +

      +To fix this, you either need to either rename or ignore one of the methods. For example: +

      + +
      +
      +%rename(spam_ushort) spam(unsigned short);
+...
+void spam(int);    
+void spam(unsigned short);   // Now renamed to spam_ushort
+
      +
      + +

      +or +

      + +
      +
      +%ignore spam(unsigned short);
+...
+void spam(int);    
+void spam(unsigned short);   // Ignored
+
      +
      + +

      21.3.12 C++ default arguments

      + + +

      +Any function with a default argument is wrapped by generating an additional function for each argument that is defaulted. +For example, if we have the following C++: +

      + +
      +
      +%module example
+
+void defaults(double d=10.0, int i=0);
+
      +
      + +

      +The following methods are generated in the Java module class: +

      + +
      +
      +public class example {
+  public static void defaults(double d, int i) { ... }
+  public static void defaults(double d) { ... }
+  public static void defaults() { ... }
+}
+
      +
      + +

      +It is as if SWIG had parsed three separate overloaded methods. +The same approach is taken for static methods, constructors and member methods. +

      + +

      +Compatibility note: Versions of SWIG prior to SWIG-1.3.23 wrapped these with a +single wrapper method and so the default values could not be taken advantage of from Java. +Further details on default arguments and how to restore this approach are given in the more general +Default arguments section. +

      + + +

      21.3.13 C++ namespaces

      + + +

      +SWIG is aware of C++ namespaces, but namespace names do not appear in +the module nor do namespaces result in a module that is broken up into +submodules or packages. For example, if you have a file like this, +

      + +
      +
      +%module example
+
+namespace foo {
+   int fact(int n);
+   struct Vector {
+       double x,y,z;
+   };
+};
+
      +
      + +

      +it works in Java as follows: +

      + +
      +
      +int f = example.fact(3);
+Vector v = new Vector();
+v.setX(3.4);
+double y = v.getY();
+
      +
      + +

      +If your program has more than one namespace, name conflicts (if any) can be resolved using %rename +For example: +

      + +
      +
      +%rename(Bar_spam) Bar::spam;
+
+namespace Foo {
+    int spam();
+}
+
+namespace Bar {
+    int spam();
+}
+
      +
      + +

      +If you have more than one namespace and you want to keep their +symbols separate, consider wrapping them as separate SWIG modules. +Each SWIG module can be placed into a separate package. +

      + +

      21.3.14 C++ templates

      + + +

      +C++ templates don't present a huge problem for SWIG. However, in order +to create wrappers, you have to tell SWIG to create wrappers for a particular +template instantiation. To do this, you use the %template directive. +For example: +

      + +
      +
      +%module example
+%{
+#include <utility>
+%}
+
+template<class T1, class T2>
+struct pair {
+   typedef T1 first_type;
+   typedef T2 second_type;
+   T1 first;
+   T2 second;
+   pair();
+   pair(const T1&, const T2&);
+  ~pair();
+};
+
+%template(pairii) pair<int,int>;
+
      +
      + +

      +In Java: +

      + +
      +
      +pairii p = new pairii(3,4);
+int first = p.getFirst();
+int second = p.getSecond();
+
      +
      + +

      +Obviously, there is more to template wrapping than shown in this example. +More details can be found in the SWIG and C++ chapter. +

      + +

      21.3.15 C++ Smart Pointers

      + + +

      +In certain C++ programs, it is common to use classes that have been wrapped by +so-called "smart pointers." Generally, this involves the use of a template class +that implements operator->() like this: +

      + +
      +
      +template<class T> class SmartPtr {
+   ...
+   T *operator->();
+   ...
+}
+
      +
      + +

      +Then, if you have a class like this, +

      + +
      +
      +class Foo {
+public:
+     int x;
+     int bar();
+};
+
      +
      + +

      +A smart pointer would be used in C++ as follows: +

      + +
      +
      +SmartPtr<Foo> p = CreateFoo();   // Created somehow (not shown)
+...
+p->x = 3;                        // Foo::x
+int y = p->bar();                // Foo::bar
+
      +
      + +

      +To wrap this in Java, simply tell SWIG about the SmartPtr class and the low-level +Foo object. Make sure you instantiate SmartPtr using %template if necessary. +For example: +

      + +
      +
      +%module example
+...
+%template(SmartPtrFoo) SmartPtr<Foo>;
+...
+
      +
      + +

      +Now, in Java, everything should just "work": +

      + +
      +
      +SmartPtrFoo p = example.CreateFoo(); // Create a smart-pointer somehow
+p.setX(3);                           // Foo::x
+int y = p.bar();                     // Foo::bar
+
      +
      + +

      +If you ever need to access the underlying pointer returned by operator->() itself, +simply use the __deref__() method. For example: +

      + +
      +
      +Foo f = p.__deref__();               // Returns underlying Foo *
+
      +
      + +

      21.4 Further details on the generated Java classes

      + + +

      +In the previous section, a high-level view of Java wrapping was +presented. A key component of this wrapping is that structures and +classes are wrapped by Java proxy classes and type wrapper classes are used +in situations where no proxies are generated. This provides a very +natural, type safe Java interface to the C/C++ code and fits in with the Java programming paradigm. +However, a number of low-level details were omitted. This section provides a brief overview +of how the proxy classes work and then covers the type wrapper classes. +Finally enum classes are covered. +First, the crucial intermediary JNI class is considered. +

      + +

      21.4.1 The intermediary JNI class

      + + +

      +In the "SWIG basics" and "SWIG and C++" chapters, +details of low-level structure and class wrapping are described. To summarize those chapters, if you +have a global function and class like this +

      + +
      +
      +class Foo {
+public:
+     int x;
+     int spam(int num, Foo* foo);
+};
+void egg(Foo* chips);
+
      +
      + +

      +then SWIG transforms the class into a set of low-level procedural wrappers. +These procedural wrappers essentially perform the equivalent of this C++ code: +

      + +
      +
      +Foo *new_Foo() {
+    return new Foo();
+}
+void delete_Foo(Foo *f) {
+    delete f;
+}
+int Foo_x_get(Foo *f) {
+    return f->x;
+}
+void Foo_x_set(Foo *f, int value) {
+    f->x = value;
+}
+int Foo_spam(Foo *f, int num, Foo* foo) {
+    return f->spam(num, foo);
+}
+
      +
      + +

      +These procedural function names don't actually exist, but their functionality appears inside the generated +JNI functions. The JNI functions have to follow a particular naming convention so the function names are actually: +

      + +
      +
      +SWIGEXPORT jlong JNICALL Java_exampleJNI_new_1Foo(JNIEnv *jenv, jclass jcls);
+SWIGEXPORT void JNICALL Java_exampleJNI_delete_1Foo(JNIEnv *jenv, jclass jcls,
+                                                    jlong jarg1);
+SWIGEXPORT void JNICALL Java_exampleJNI_Foo_1x_1set(JNIEnv *jenv, jclass jcls,
+                                                    jlong jarg1, jobject jarg1_, jint jarg2);
+SWIGEXPORT jint JNICALL Java_exampleJNI_Foo_1x_1get(JNIEnv *jenv, jclass jcls,
+                                                    jlong jarg1, jobject jarg1_);
+SWIGEXPORT jint JNICALL Java_exampleJNI_Foo_1spam(JNIEnv *jenv, jclass jcls,
+                                                  jlong jarg1, jobject jarg1_, jint jarg2,
+                                                  jlong jarg3, jobject jarg3_);
+SWIGEXPORT void JNICALL Java_exampleJNI_egg(JNIEnv *jenv, jclass jcls,
+                                            jlong jarg1, jobject jarg1_);
+
      +
      + +

      +For every JNI C function there has to be a static native Java function. These appear in the intermediary JNI class: +

      + +
      +
      +class exampleJNI {
+  public final static native long new_Foo();
+  public final static native void delete_Foo(long jarg1);
+  public final static native void Foo_x_set(long jarg1, Foo jarg1_, int jarg2);
+  public final static native int Foo_x_get(long jarg1, Foo jarg1_);
+  public final static native int Foo_spam(long jarg1, Foo jarg1_, int jarg2,
+                                          long jarg3, Foo jarg3_);
+  public final static native void egg(long jarg1, Foo jarg1_);
+}
+
      +
      + +

      +This class contains the complete Java - C/C++ interface so all function calls go via this class. +As this class acts as a go-between for all JNI calls to C/C++ code from the Java proxy classes, type wrapper classes and module class, it is known as the intermediary JNI class. +

      + +

      +You may notice that SWIG uses a Java long wherever a pointer or class object needs to be marshalled across the Java-C/C++ boundary. +This approach leads to minimal JNI code which makes for better performance as JNI code involves a lot of string manipulation. +SWIG favours generating Java code over JNI code as Java code is compiled into byte code and avoids the costly string operations needed in JNI code. +This approach has a downside though as the proxy class might get collected before the native method has completed. +You might notice above that there is an additional parameters with a underscore postfix, eg jarg1_. +These are added in order to prevent premature garbage collection when marshalling proxy classes. +

      + +

      +The functions in the intermediary JNI class cannot be accessed outside of its package. Access to them is gained through the module class for globals otherwise the appropriate proxy class. +

      + + +

      +The name of the intermediary JNI class can be changed from its default, that is, the module name with JNI appended after it. +The module directive attribute jniclassname is used to achieve this: +

      + +
      +
      +%module (jniclassname="name") modulename
+
      +
      + +

      +If name is the same as modulename then the module class name gets changed +from modulename to modulenameModule. +

      + +

      21.4.1.1 The intermediary JNI class pragmas

      + + +

      +The intermediary JNI class can be tailored through the use of pragmas, but is not commonly done. The pragmas for this class are: +

      + + + + + + + + + + + + + + + + + + + + + + +
      PragmaDescription
      jniclassbase Base class for the intermediary JNI class
      jniclassclassmodifiers Class modifiers and class type for the intermediary JNI class
      jniclasscode Java code is copied verbatim into the intermediary JNI class
      jniclassimports Java code, usually one or more import statements, placed before the intermediary JNI class definition
      jniclassinterfaces Comma separated interface classes for the intermediary JNI class
      + +

      +The pragma code appears in the generated intermediary JNI class where you would expect: +

      + +
      +
      +[ jniclassimports pragma ]
+[ jniclassclassmodifiers pragma ] jniclassname extends [ jniclassbase pragma ]
+                                          implements [ jniclassinterfaces pragma ] {
+[ jniclasscode pragma ]
+... SWIG generated native methods ...
+}
+
      +
      + +

      +The jniclasscode pragma is quite useful for adding in a static block for loading the shared library / dynamic link library and demonstrates how pragmas work: +

      + +
      +
      +%pragma(java) jniclasscode=%{
+  static {
+    try {
+        System.loadLibrary("example");
+    } catch (UnsatisfiedLinkError e) {
+      System.err.println("Native code library failed to load. \n" + e);
+      System.exit(1);
+    }
+  }
+%}
+
      +
      + +

      +Pragmas will take either "" or %{ %} as delimiters. +For example, let's change the intermediary JNI class access to public. +

      + +
      +
      +%pragma(java) jniclassclassmodifiers="public class"
+
      +
      + +

      +All the methods in the intermediary JNI class will then be callable outside of the package as the method modifiers are public by default. +

      + +

      21.4.2 The Java module class

      + + +

      +All global functions and variable getters/setters appear in the module class. For our example, there is just one function: +

      + +
      +
      +public class example {
+  public static void egg(Foo chips) {
+    exampleJNI.egg(Foo.getCPtr(chips), chips);
+  }
+}
+
      +
      + +

      +The module class is necessary as there is no such thing as a global in Java so all the C globals are put into this class. They are generated as static functions and so must be accessed as such by using the module name in the static function call: +

      + +
      +
      +example.egg(new Foo());
+
      +
      + +

      +The primary reason for having the module class wrapping the calls in the intermediary JNI class is to implement static type checking. In this case only a Foo can be passed to the egg function, whereas any long can be passed to the egg function in the intermediary JNI class. +

      + +

      21.4.2.1 The Java module class pragmas

      + + +

      +The module class can be tailored through the use of pragmas, in the same manner as the intermediary JNI class. The pragmas are similarly named and are used in the same way. The complete list follows: +

      + + + + + + + + + + + + + + + + + + + + + + +
      PragmaDescription
      modulebase Base class for the module class
      moduleclassmodifiers Class modifiers and class type for the module class
      modulecode Java code is copied verbatim into the module class
      moduleimports Java code, usually one or more import statements, placed before the module class definition
      moduleinterfaces Comma separated interface classes for the module class
      + + +

      +The pragma code appears in the generated module class like this: +

      + +
      +
      +[ moduleimports pragma ]
+[ modulemodifiers pragma ] modulename extends [ modulebase pragma ]
+                                      implements [ moduleinterfaces pragma ] {
+[ modulecode pragma ]
+... SWIG generated wrapper functions ...
+}
+
      +
      + +

      +See The intermediary JNI class pragmas section for further details on using pragmas. +

      + + +

      21.4.3 Java proxy classes

      + + +

      +A Java proxy class is generated for each structure, union or C++ class that is wrapped. +Proxy classes have also been called peer classes. +The default proxy class for our previous example looks like this: +

      + +
      +
      +public class Foo {
+  private long swigCPtr;
+  protected boolean swigCMemOwn;
+
+  protected Foo(long cPtr, boolean cMemoryOwn) {
+    swigCMemOwn = cMemoryOwn;
+    swigCPtr = cPtr;
+  }
+
+  protected static long getCPtr(Foo obj) {
+    return (obj == null) ? 0 : obj.swigCPtr;
+  }
+
+  protected void finalize() {
+    delete();
+  }
+
+  public synchronized void delete() {
+    if(swigCPtr != 0 && swigCMemOwn) {
+      swigCMemOwn = false;
+      exampleJNI.delete_Foo(swigCPtr);
+    }
+    swigCPtr = 0;
+  }
+
+  public void setX(int value) {
+    exampleJNI.Foo_x_set(swigCPtr, this, value);
+  }
+
+  public int getX() {
+    return exampleJNI.Foo_x_get(swigCPtr, this);
+  }
+
+  public int spam(int num, Foo foo) {
+    return exampleJNI.Foo_spam(swigCPtr, this, num, Foo.getCPtr(foo), foo);
+  }
+
+  public Foo() {
+    this(exampleJNI.new_Foo(), true);
+  }
+
+}
+
      +
      + + +

      +This class merely holds a pointer to the underlying C++ object (swigCPtr). +It also contains all the methods in the C++ class it is proxying plus getters and setters for public +member variables. These functions call the native methods in the intermediary JNI class. +The advantage of having this extra layer is the type safety that the proxy class functions offer. +It adds static type checking which leads to fewer surprises at runtime. +For example, you can see that if you attempt to use the spam() +function it will only compile when the parameters passed are an int and a Foo. +From a user's point of view, it makes the class work as if it were a Java class: +

      + +
      +
      +Foo f = new Foo();
+f.setX(3);
+int y = f.spam(5, new Foo());
+
      +
      + +

      21.4.3.1 Memory management

      + + +

      +Each proxy class has an ownership flag swigCMemOwn. The value of this +flag determines who is responsible for deleting the underlying C++ object. If set to true, +the proxy class's finalizer will destroy the C++ object when the proxy class is +garbage collected. If set to false, then the destruction of the proxy class has no effect on the C++ object. +

      + +

      +When an object is created by a constructor or returned by value, Java automatically takes +ownership of the result. +On the other hand, when pointers or references are returned to Java, there is often no way to know where +they came from. Therefore, the ownership is set to false. For example: +

      + + +
      +
      +class Foo {
+public:
+    Foo();
+    Foo bar1();
+    Foo &bar2();
+    Foo *bar2();
+};
+
      +
      + +

      +In Java: +

      + +
      +
      +Foo f = new Foo();   //  f.swigCMemOwn = true
+Foo f1 = f.bar1();   // f1.swigCMemOwn = true
+Foo f2 = f.bar2();   // f2.swigCMemOwn = false
+Foo f3 = f.bar3();   // f3.swigCMemOwn = false
+
      +
      + +

      +This behavior for pointers and references is especially important for classes that act as containers. +For example, if a method returns a pointer to an object +that is contained inside another object, you definitely don't want +Java to assume ownership and destroy it! +

      + +

      +For the most part, memory management issues remain hidden. However, +there are situations where you might have to manually +change the ownership of an object. For instance, consider code like this: +

      + +
      +
      +class Obj {};
+class Node {
+   Obj *value;
+public:
+   void set_value(Obj *v) { value = v; }
+};
+
      +
      + +

      +Now, consider the following Java code: +

      + +
      +
      +Node n = new Node();    // Create a node
+{
+  Obj o = new Obj();    // Create an object
+  n.set_value(o);       // Set value
+}                       // o goes out of scope
+
      +
      + +

      +In this case, the Node n is holding a reference to +o internally. However, SWIG has no way to know that this +has occurred. The Java proxy class still thinks that it has ownership of +o. As o has gone out of scope, it could be garbage collected in which case the C++ destructor +will be invoked and n will then be holding a stale-pointer to o. If +you're lucky, you will only get a segmentation fault. +

      + +

      +To work around this, the ownership flag of o needs changing to false. +The ownership flag is a private member variable of the proxy class so this is not possible without some customization of the proxy class. +This can be achieved by using a typemap to customise the proxy class with pure Java code as detailed later in the section on +Java typemaps. +

      + +

      +Sometimes a function will create memory and return a pointer to a newly allocated object. +SWIG has no way of knowing this so by default the proxy class does not manage the returned object. +However, you can tell the proxy class to manage the memory if you specify the %newobject directive. Consider: +

      + +
      +
      +class Obj {...};
+class Factory {
+public:
+    static Obj *createObj() { return new Obj(); }
+};
+
      +
      + +

      +If we call the factory function, then we have to manually delete the memory: +

      + +
      +
      +Obj obj = Factory.createObj();   // obj.swigCMemOwn = false
+...
+obj.delete();
+
      +
      + +

      +Now add in the %newobject directive: +

      + +
      +
      +%newobject Factory::createObj();
+
+class Obj {...};
+class Factory {
+public:
+    static Obj *createObj() { return new Obj(); }
+};
+
      +
      + +

      +A call to delete() is no longer necessary as the garbage collector will make the C++ destructor call because swigCMemOwn is now true. +

      + +
      +
      +Obj obj = Factory.createObj();   // obj.swigCMemOwn = true;
+...
+
      +
      + +

      +Some memory management issues are quite tricky to fix and may only be noticeable after using for a long time. +One such issue is premature garbage collection of an object created from Java and resultant usage from C++ code. +The section on typemap examples cover two such scenarios, +Memory management for objects passed to the C++ layer +and +Memory management when returning references to member variables +

      + + +

      21.4.3.2 Inheritance

      + + +

      +Java proxy classes will mirror C++ inheritance chains. For example, given the base class Base and its derived class Derived: +

      + +
      +class Base {
+public:
+  virtual double foo();
+};
+
+class Derived : public Base {
+public:
+  virtual double foo();
+};
+
      + +

      +The base class is generated much like any other proxy class seen so far: +

      + +
      +public class Base {
+  private long swigCPtr;
+  protected boolean swigCMemOwn;
+
+  protected Base(long cPtr, boolean cMemoryOwn) {
+    swigCMemOwn = cMemoryOwn;
+    swigCPtr = cPtr;
+  }
+
+  protected static long getCPtr(Base obj) {
+    return (obj == null) ? 0 : obj.swigCPtr;
+  }
+
+  protected void finalize() {
+    delete();
+  }
+
+  public synchronized void delete() {
+    if(swigCPtr != 0 && swigCMemOwn) {
+      swigCMemOwn = false;
+      exampleJNI.delete_Base(swigCPtr);
+    }
+    swigCPtr = 0;
+  }
+
+  public double foo() {
+    return exampleJNI.Base_foo(swigCPtr, this);
+  }
+
+  public Base() {
+    this(exampleJNI.new_Base(), true);
+  }
+
+}
+
      + +

      +The Derived class extends Base mirroring the C++ class inheritance hierarchy. +

      + +
      +public class Derived extends Base {
+  private long swigCPtr;
+
+  protected Derived(long cPtr, boolean cMemoryOwn) {
+    super(exampleJNI.SWIGDerivedUpcast(cPtr), cMemoryOwn);
+    swigCPtr = cPtr;
+  }
+
+  protected static long getCPtr(Derived obj) {
+    return (obj == null) ? 0 : obj.swigCPtr;
+  }
+
+  protected void finalize() {
+    delete();
+  }
+
+  public synchronized void delete() {
+    if(swigCPtr != 0 && swigCMemOwn) {
+      swigCMemOwn = false;
+      exampleJNI.delete_Derived(swigCPtr);
+    }
+    swigCPtr = 0;
+    super.delete();
+  }
+
+  public double foo() {
+    return exampleJNI.Derived_foo(swigCPtr, this);
+  }
+
+  public Derived() {
+    this(exampleJNI.new_Derived(), true);
+  }
+
+}
+
      + +

      +Note the memory ownership is controlled by the base class. +However each class in the inheritance hierarchy has its own pointer value which is obtained during construction. +The SWIGDerivedUpcast() call converts the pointer from a Derived * to a Base *. +This is a necessity as C++ compilers are free to implement pointers in the inheritance hierarchy with different values. +

      + +

      +It is of course possible to extend Base using your own Java classes. +If Derived is provided by the C++ code, you could for example add in a pure Java class Extended derived from Base. +There is a caveat and that is any C++ code will not know about your pure Java class Extended so this type of derivation is restricted. +However, true cross language polymorphism can be achieved using the directors feature. +

      + + +

      21.4.3.3 Proxy classes and garbage collection

      + + +

      +By default each proxy class has a delete() and a finalize() method. +The finalize() method calls delete() which frees any malloc'd memory for wrapped C structs or calls the C++ class destructors. +The idea is for delete() to be called when you have finished with the C/C++ object. +Ideally you need not call delete(), but rather leave it to the garbage collector to call it from the finalizer. +When a program exits, the garbage collector does not guarantee to call all finalizers. +An insight into the reasoning behind this can be obtained from Hans Boehm's Destructors, Finalizers, and Synchronization paper. +Depending on what the finalizers do and which operating system you use, this may or may not be a problem. +

      + +

      +If the delete() call into JNI code is just for memory handling, there is not a problem when run on most operating systems, for example Windows and Unix. +Say your JNI code creates memory on the heap which your finalizers should clean up, the finalizers may or may not be called before the program exits. +In Windows and Unix all memory that a process uses is returned to the system on exit, so this isn't a problem. +This is not the case in some operating systems like vxWorks. +If however, your finalizer calls into JNI code invoking the C++ destructor which in turn releases a TCP/IP socket for example, there is no guarantee that it will be released. +Note that with long running programs the garbage collector will eventually run, thereby calling any unreferenced object's finalizers. +

      + +

      +Some not so ideal solutions are: +

      + +
        +

      1. +Call the System.runFinalizersOnExit(true) or Runtime.getRuntime().runFinalizersOnExit(true) to ensure the finalizers are called before the program exits. The catch is that this is a deprecated function call as the documentation says:

        +
        +This method is inherently unsafe. It may result in finalizers being called on live objects while other threads are concurrently manipulating those objects, resulting in erratic behavior or deadlock. +
        +

        In many cases you will be lucky and find that it works, but it is not to be advocated. +Have a look at Sun's Java web site and search for runFinalizersOnExit. +

        2. + +

      2. +From jdk1.3 onwards a new function, addShutdownHook(), was introduced which is guaranteed to be called when your program exits. +You can encourage the garbage collector to call the finalizers, for example, add this static block to the class that has the main() function:

        +
        +  static {
+    Runtime.getRuntime().addShutdownHook( 
+      new Thread() {
+        public void run() { System.gc(); System.runFinalization(); }
+      }
+    );
+  }
+
        +

        Although this usually works, the documentation doesn't guarantee that runFinalization() will actually call the finalizers. +As the the shutdown hook is guaranteed you could also make a JNI call to clean up any resources that are being tracked by the C/C++ code.

        +
        3. + +
      3. +

        Call the delete() function manually which will immediately invoke the C++ destructor. +As a suggestion it may be a good idea to set the object to null so that should the object be inadvertently used again a Java null pointer exception is thrown, the alternative would crash the JVM by using a null C pointer. +For example given a SWIG generated class A:

        +
        +A myA = new A();
+// use myA ...
+myA.delete();
+// any use of myA here would crash the JVM 
+myA=null;
+// any use of myA here would cause a Java null pointer exception to be thrown
+
        + +

        +The SWIG generated code ensures that the memory is not deleted twice, in the event the finalizers get called in addition to the manual delete() call. +

        +
        4. + +
      4. +

        +Write your own object manager in Java. +You could derive all SWIG classes from a single base class which could track which objects have had their finalizers run, then call the rest of them on program termination. +The section on Java typemaps details how to specify a pure Java base class. +

        +
        5. +
      + +

      +See the How to Handle Java Finalization's Memory-Retention Issues article for alternative approaches to managing memory by avoiding finalizers altogether. +

      + +

      21.4.3.4 The premature garbage collection prevention parameter for proxy class marshalling

      + + +

      +As covered earlier, the C/C++ struct/class pointer is stored in the proxy class as a Java long and when needed is passed +into the native method where it is cast into the appropriate type. +This approach provides very fast marshalling but could be susceptible to premature garbage collection. +Consider the following C++ code: +

      + +
      +class Wibble {
+};
+void wobble(Wibble &w);
+
      + +

      +The module class contains the Java wrapper for the global wobble method: +

      + +
      +public class example {
+  ...
+  public static void wobble(Wibble w) {
+    exampleJNI.wobble(Wibble.getCPtr(w), w);
+  }
+}
+
      + +

      +where example is the name of the module. +All native methods go through the intermediary class which has the native method declared as such: +

      + +
      +public class exampleJNI {
+  ...
+  public final static native void wobble(long jarg1, Wibble jarg1_);
+}
+
      + +

      +The second parameter, jarg1_, is the premature garbage collection prevention parameter and is added to the native method parameter list whenever a C/C++ struct or class is marshalled as a Java long. +In order to understand why, consider the alternative where the intermediary class method is declared without the additional parameter: +

      + +
      +public class exampleJNI {
+  ...
+  public final static native void wobble(long jarg1);
+}
+
      + +

      +and the following simple call to wobble: +

      + +
      +{
+  Wibble w = new Wibble();
+  example.wobble(w);
+}
+
      + +

      +The hotspot compiler effectively sees something like: +

      + +
      +{
+  Wibble w = new Wibble();
+  long w_ptr = Wibble.getCPtr(w);
+  // w is no longer reachable
+  exampleJNI.wobble(w_ptr);
+}
+
      + +

      +The Wibble object is no longer reachable after the point shown as in this bit of code, the Wibble object is not referenced again after this point. +This means that it is a candidate for garbage collection. +Should wobble be a long running method, it is quite likely that the finalizer for the Wibble instance will be called. +This in turn will call its underlying C++ destructor which +is obviously disastrous while the method wobble is running using this object. +Even if wobble is not a long running method, it is possible for the Wibble instance to be finalized. +By passing the Wibble instance into the native method, it will not be finalized as the JVM guarantees not to +finalize any objects until the native method returns. +Effectively, the code then becomes +

      + +
      +{
+  Wibble w = new Wibble();
+  long w_ptr = Wibble.getCPtr(w);
+  exampleJNI.wobble(w_ptr, w);
+  // w is no longer reachable
+}
+
      + +

      +and therefore there is no possibility of premature garbage collection. In practice, this premature garbage collection was only ever observed in Sun's server JVM from jdk-1.3 onwards and in Sun's client JVM from jdk-1.6 onwards. +

      + +

      +The premature garbage collection prevention parameter for proxy classes is generated by default whenever proxy classes are passed by value, reference or with a pointer. +The implementation for this extra parameter generation requires the "jtype" typemap to contain long and the "jstype" typemap to contain the name of a proxy class. +

      + +

      +The additional parameter does impose a slight performance overhead and the parameter generation can be suppressed globally with the -nopgcpp commandline option. +More selective suppression is possible with the 'nopgcpp' attribute in the "jtype" Java typemap. +The attribute is a flag and so should be set to "1" to enable the suppression, or it can be omitted or set to "0" to disable. +For example: +

      + +
      +%typemap(jtype, nopgcpp="1") Wibble & "long"
+
      + +

      +Compatibility note: The generation of this additional parameter did not occur in versions prior to SWIG-1.3.30. +

      + +

      21.4.3.5 Single threaded applications and thread safety

      + + +

      +Single threaded Java applications using JNI need to consider thread safety. +The same applies for the C# module where the .NET wrappers use PInvoke. +Consider the C++ class: +

      + +
      +class Test {
+  string str;
+public:
+  Test() : str("initial") {}
+};
+
      + +

      +and the Java proxy class generated by SWIG: +

      + +
      +public class Test {
+  private long swigCPtr;
+  protected boolean swigCMemOwn;
+
+  protected Test(long cPtr, boolean cMemoryOwn) {
+    swigCMemOwn = cMemoryOwn;
+    swigCPtr = cPtr;
+  }
+
+  protected static long getCPtr(Test obj) {
+    return (obj == null) ? 0 : obj.swigCPtr;
+  }
+
+  protected void finalize() {
+    delete();
+  }
+
+  // Call C++ destructor
+  public synchronized void delete() {
+    if(swigCPtr != 0 && swigCMemOwn) {
+      swigCMemOwn = false;
+      exampleJNI.delete_Test(swigCPtr);
+    }
+    swigCPtr = 0;
+  }
+
+  // Call C++ constructor
+  public Test() {
+    this(exampleJNI.new_Test(), true);
+  }
+
+}
+
      + + +

      +It has two methods that call JNI methods, namely, exampleJNI.new_Test() for the C++ constructor and exampleJNI.delete_Test() for the C++ destructor. +If the garbage collector collects an instance of this class, ie delete() is not explicitly called, then the C++ destructor will be run in a different thread to the main thread. +This is because when an object is marked for garbage collection, any objects with finalizers are added to a finalization queue +and the objects in the finalization queue have their finalize() methods run in a separate finalization thread. +Therefore, if the C memory allocator is not thread safe, then the heap will get corrupted sooner or later, when a concurrent C++ delete and new are executed. +It is thus essential, even in single threaded usage, to link to the C multi-thread runtime libraries, +for example, use the /MD option for Visual C++ on Windows. +Alternatively, lock all access to C++ functions that have heap allocation/deallocation. +

      + +

      +Note that some of the STL in Visual C++ 6 is not thread safe, so although code might be linked to the multithread runtime libraries, undefined behaviour might still occur in a single threaded Java program. +Similarly some older versions of Sun Studio have bugs in the multi-threaded implementation of the std::string class and so will lead to undefined behaviour in these supposedly single threaded Java applications. +

      + +

      +The following innocuous Java usage of Test is an example that will crash very quickly on a multiprocessor machine if the JNI compiled code is linked against the single thread C runtime libraries. +

      + +
      +for (int i=0; i<100000; i++) {
+  System.out.println("Iteration " + i);
+  for (int k=0; k<10; k++) {
+    Test test = new Test();
+  }
+  System.gc();
+}
+
      + + +

      21.4.4 Type wrapper classes

      + + +

      +The generated type wrapper class, for say an int *, looks like this: +

      + +
      +public class SWIGTYPE_p_int {
+  private long swigCPtr;
+
+  protected SWIGTYPE_p_int(long cPtr, boolean bFutureUse) {
+    swigCPtr = cPtr;
+  }
+
+  protected SWIGTYPE_p_int() {
+    swigCPtr = 0;
+  }
+
+  protected static long getCPtr(SWIGTYPE_p_int obj) {
+    return obj.swigCPtr;
+  }
+}
+
      + +

      +The methods do not have public access, so by default it is impossible to do anything with objects of this class other than +pass them around. The methods in the class are part of the inner workings of SWIG. +If you need to mess around with pointers you will have to use some typemaps specific to the Java module to achieve this. +The section on Java typemaps details how to modify the generated code. +

      + +

      +Note that if you use a pointer or reference to a proxy class in a function then no type wrapper class is generated because the proxy class can be used +as the function parameter. If however, you need anything more complicated like a pointer to a pointer to a proxy class then a typewrapper class +is generated for your use. +

      + +

      +Note that SWIG generates a type wrapper class and not a proxy class when it has not parsed the definition of a type that gets used. +For example, say SWIG has not parsed the definition of class Snazzy because it is in a header file that you may have forgotten to use the %include directive on. +Should SWIG parse Snazzy * being used in a function parameter, it will then generates a type wrapper class around a Snazzy pointer. +Also recall from earlier that SWIG will use a pointer when a class is passed by value or by reference: +

      + +
      +
      +void spam(Snazzy *x, Snazzy &y, Snazzy z);
+
      +
      + +

      +Should SWIG not know anything about Snazzy then a SWIGTYPE_p_Snazzy must be used for all 3 parameters in the spam function. +The Java function generated is: +

      + +
      +
      +public static void spam(SWIGTYPE_p_Snazzy x, SWIGTYPE_p_Snazzy y, SWIGTYPE_p_Snazzy z) {
+ ...
+}
+
      +
      + +

      +Note that typedefs are tracked by SWIG and the typedef name is used to construct the type wrapper class name. For example, consider the case where Snazzy is a typedef to an int which SWIG does parse: +

      + + +
      +
      +typedef int Snazzy;
+void spam(Snazzy *x, Snazzy &y, Snazzy z);
+
      +
      + +

      +Because the typedefs have been tracked the Java function generated is: +

      + +
      +
      +public static void spam(SWIGTYPE_p_int x, SWIGTYPE_p_int y, int z) { ... }
+
      +
      + + +

      21.4.5 Enum classes

      + + +

      +SWIG can generate three types of enum classes. +The Enumerations section discussed these but omitted all the details. +The following sub-sections detail the various types of enum classes that can be generated. +

      + +

      21.4.5.1 Typesafe enum classes

      + + +

      +The following example demonstrates the typesafe enum classes which SWIG generates: +

      + +
      +
      +%include "enumtypesafe.swg"
+%javaconst(1);
+enum Beverage { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
+
      +
      + +

      +The following is the code that SWIG generates: +

      + +
      +
      +public final class Beverage {
+  public final static Beverage ALE = new Beverage("ALE");
+  public final static Beverage LAGER = new Beverage("LAGER", 10);
+  public final static Beverage STOUT = new Beverage("STOUT");
+  public final static Beverage PILSNER = new Beverage("PILSNER");
+  public final static Beverage PILZ = new Beverage("PILZ", PILSNER);
+
+  public final int swigValue() {
+    return swigValue;
+  }
+
+  public String toString() {
+    return swigName;
+  }
+
+  public static Beverage swigToEnum(int swigValue) {
+    if (swigValue < swigValues.length && swigValue >= 0 &&
+        swigValues[swigValue].swigValue == swigValue)
+      return swigValues[swigValue];
+    for (int i = 0; i < swigValues.length; i++)
+      if (swigValues[i].swigValue == swigValue)
+        return swigValues[i];
+    throw new IllegalArgumentException("No enum " + Beverage.class + " with value " +
+                                                                         swigValue);
+  }
+
+  private Beverage(String swigName) {
+    this.swigName = swigName;
+    this.swigValue = swigNext++;
+  }
+
+  private Beverage(String swigName, int swigValue) {
+    this.swigName = swigName;
+    this.swigValue = swigValue;
+    swigNext = swigValue+1;
+  }
+
+  private Beverage(String swigName, Beverage swigEnum) {
+    this.swigName = swigName;
+    this.swigValue = swigEnum.swigValue;
+    swigNext = this.swigValue+1;
+  }
+
+  private static Beverage[] swigValues = { ALE, LAGER, STOUT, PILSNER, PILZ };
+  private static int swigNext = 0;
+  private final int swigValue;
+  private final String swigName;
+}
+
      +
      + +

      +As can be seen, there are a fair number of support methods for the typesafe enum pattern. +The typesafe enum pattern involves creating a fixed number of static instances of the enum class. +The constructors are private to enforce this. +Three constructors are available - two for C/C++ enums with an initializer and one for those without an initializer. +Note that the two enums with initializers, LAGER and PILZ, each call one the two different initializer constructors. +In order to use one of these typesafe enums, the swigToEnum static method must be called to return a reference to one of the static instances. +The JNI layer returns the enum value from the C/C++ world as an integer and this method is used to find the appropriate Java enum static instance. +The swigValue method is used for marshalling in the other direction. +The toString method is overridden so that the enum name is available. +

      + +

      21.4.5.2 Proper Java enum classes

      + + +

      +The following example demonstrates the Java enums approach: +

      + +
      +
      +%include "enums.swg"
+%javaconst(1);
+enum Beverage { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
+
      +
      + +

      +SWIG will generate the following Java enum: +

      + +
      +
      +public enum Beverage {
+  ALE,
+  LAGER(10),
+  STOUT,
+  PILSNER,
+  PILZ(PILSNER);
+
+  public final int swigValue() {
+    return swigValue;
+  }
+
+  public static Beverage swigToEnum(int swigValue) {
+    Beverage[] swigValues = Beverage.class.getEnumConstants();
+    if (swigValue < swigValues.length && swigValue >= 0 &&
+        swigValues[swigValue].swigValue == swigValue)
+      return swigValues[swigValue];
+    for (Beverage swigEnum : swigValues)
+      if (swigEnum.swigValue == swigValue)
+        return swigEnum;
+    throw new IllegalArgumentException("No enum " + Beverage.class +
+                                       " with value " + swigValue);
+  }
+
+  private Beverage() {
+    this.swigValue = SwigNext.next++;
+  }
+
+  private Beverage(int swigValue) {
+    this.swigValue = swigValue;
+    SwigNext.next = swigValue+1;
+  }
+
+  private Beverage(Beverage swigEnum) {
+    this.swigValue = swigEnum.swigValue;
+    SwigNext.next = this.swigValue+1;
+  }
+
+  private final int swigValue;
+
+  private static class SwigNext {
+    private static int next = 0;
+  }
+}
+
      +
      + +

      +The enum items appear first. +Like the typesafe enum pattern, the constructors are private. +The constructors are required to handle C/C++ enums with initializers. +The next variable is in the SwigNext inner class rather than in the enum class as static primitive variables cannot be modified from within enum constructors. +Marshalling between Java enums and the C/C++ enum integer value is handled via the swigToEnum and swigValue methods. +All the constructors and methods in the Java enum are required just to handle C/C++ enums with initializers. +These needn't be generated if the enum being wrapped does not have any initializers and the +Simpler Java enums for enums without initializers section describes how typemaps can be used to achieve this. +

      + +

      21.4.5.3 Type unsafe enum classes

      + + +

      +The following example demonstrates type unsafe enums: +

      + +
      +
      +%include "enumtypeunsafe.swg"
+%javaconst(1);
+enum Beverage { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
+
      +
      + +

      +SWIG will generate the following simple class: +

      + +
      +
      +public final class Beverage {
+  public final static int ALE = 0;
+  public final static int LAGER = 10;
+  public final static int STOUT = LAGER + 1;
+  public final static int PILSNER = STOUT + 1;
+  public final static int PILZ = PILSNER;
+}
+
      +
      + +

      21.5 Cross language polymorphism using directors

      + + +

      +Proxy classes provide a natural, object-oriented way to wrap C++ classes. +as described earlier, each proxy instance has an associated C++ instance, and method calls from Java to the proxy are passed to the C++ instance transparently via C wrapper functions. +

      + +

      +This arrangement is asymmetric in the sense that no corresponding mechanism exists to pass method calls down the inheritance chain from C++ to Java. +In particular, if a C++ class has been extended in Java (by deriving from the proxy class), these classes will not be visible from C++ code. +Virtual method calls from C++ are thus not able to access the lowest implementation in the inheritance chain. +

      + +

      +SWIG can address this problem and make the relationship between C++ classes and proxy classes more symmetric. +To achieve this goal, new classes called directors are introduced at the bottom of the C++ inheritance chain. +The job of the directors is to route method calls correctly, either to C++ implementations higher in the inheritance chain or to Java implementations lower in the inheritance chain. +The upshot is that C++ classes can be extended in Java and from C++ these extensions look exactly like native C++ classes. +Neither C++ code nor Java code needs to know where a particular method is implemented: the combination of proxy classes, director classes, and C wrapper functions transparently takes care of all the cross-language method routing. +

      + +

      21.5.1 Enabling directors

      + + +

      +The director feature is disabled by default. +To use directors you must make two changes to the interface file. +First, add the "directors" option to the %module directive, like this: +

      + +
      +
      +%module(directors="1") modulename
+
      +
      + +

      +Without this option no director code will be generated. +Second, you must use the %feature("director") directive to tell SWIG which classes and methods should get directors. +The %feature directive can be applied globally, to specific classes, and to specific methods, like this: +

      + +
      +
      +// generate directors for all classes that have virtual methods
+%feature("director");         
+
+// generate directors for all virtual methods in class Foo
+%feature("director") Foo;      
+
+// generate a director for just Foo::bar()
+%feature("director") Foo::bar; 
+
      +
      + +

      +You can use the %feature("nodirector") directive to turn off directors for specific classes or methods. +So for example, +

      + +
      +
      +%feature("director") Foo;
+%feature("nodirector") Foo::bar;
+
      +
      + +

      +will generate directors for all virtual methods of class Foo except bar(). +

      + +

      +Directors can also be generated implicitly through inheritance. +In the following, class Bar will get a director class that handles the methods one() and two() (but not three()): +

      + +
      +
      +%feature("director") Foo;
+class Foo {
+public:
+    virtual void one();
+    virtual void two();
+};
+
+class Bar: public Foo {
+public:
+    virtual void three();
+};
+
      +
      + +

      21.5.2 Director classes

      + + +

      +For each class that has directors enabled, SWIG generates a new class that derives from both the class in question and a special Swig::Director class. +These new classes, referred to as director classes, can be loosely thought of as the C++ equivalent of the Java proxy classes. +The director classes store a pointer to their underlying Java proxy classes. +

      + +

      +For simplicity let's ignore the Swig::Director class and refer to the original C++ class as the director's base class. +By default, a director class extends all virtual methods in the inheritance chain of its base class (see the preceding section for how to modify this behavior). +Thus all virtual method calls, whether they originate in C++ or in Java via proxy classes, eventually end up in at the implementation in the director class. +The job of the director methods is to route these method calls to the appropriate place in the inheritance chain. +By "appropriate place" we mean the method that would have been called if the C++ base class and its Java derived classes were seamlessly integrated. +That seamless integration is exactly what the director classes provide, transparently skipping over all the messy JNI glue code that binds the two languages together. +

      + +

      +In reality, the "appropriate place" is one of only two possibilities: C++ or Java. +Once this decision is made, the rest is fairly easy. +If the correct implementation is in C++, then the lowest implementation of the method in the C++ inheritance chain is called explicitly. +If the correct implementation is in Java, the Java API is used to call the method of the underlying Java object +(after which the usual virtual method resolution in Java automatically finds the right implementation). +

      + + +

      21.5.3 Overhead and code bloat

      + + +

      +Enabling directors for a class will generate a new director method for every virtual method in the class' inheritance chain. +This alone can generate a lot of code bloat for large hierarchies. +Method arguments that require complex conversions to and from Java types can result in large director methods. +For this reason it is recommended that directors are selectively enabled only for specific classes that are likely to be extended in Java and used in C++. +

      + +

      +Although directors make it natural to mix native C++ objects with Java objects (as director objects), +one should be aware of the obvious fact that method calls to Java objects from C++ will be much slower than calls to C++ objects. +Additionally, compared to classes that do not use directors, the call routing in the director methods adds a small overhead. +This situation can be optimized by selectively enabling director methods (using the %feature directive) for only those methods that are likely to be extended in Java. +

      + + +

      21.5.4 Simple directors example

      + + +

      +Consider the following SWIG interface file: +

      + +
      +
      +%module(directors="1") example;
+
+%feature("director") DirectorBase;
+
+class DirectorBase {
+public:
+  virtual ~DirectorBase() {}
+  virtual void upcall_method() {}
+};
+
+void callup(DirectorBase *director) {
+  director->upcall_method();
+}
+
      +
      + +

      +The following DirectorDerived Java class is derived from the Java proxy class DirectorBase and overrides upcall_method(). +When C++ code invokes upcall_method(), the SWIG-generated C++ code redirects the call via JNI to the Java DirectorDerived subclass. +Naturally, the SWIG generated C++ code and the generated Java intermediate class marshal and convert arguments between C++ and Java when needed. +

      + +
      +
      +public class DirectorDerived extends DirectorBase {
+  public DirectorDerived() {
+  }
+
+  public void upcall_method() {
+    System.out.println("DirectorDerived::upcall_method() invoked.");
+  }
+}
+
      +
      + +

      +Running the following Java code +

      + +
      +
      +DirectorDerived director = new DirectorDerived();
+example.callup(director);
+
      +
      + +

      +will result in the following being output: +

      + +
      +
      +DirectorDerived::upcall_method() invoked.
+
      +
      + +

      21.5.5 Director threading issues

      + + +

      +Depending on your operating system and version of Java and how you are using threads, you might find the JVM hangs on exit. +There are a couple of solutions to try out. The preferred solution requires jdk-1.4 and later and uses AttachCurrentThreadAsDaemon instead of AttachCurrentThread whenever a call into the JVM is required. This can be enabled by defining the SWIG_JAVA_ATTACH_CURRENT_THREAD_AS_DAEMON macro when compiling the C++ wrapper code. For older JVMs define SWIG_JAVA_NO_DETACH_CURRENT_THREAD instead, to avoid the DetachCurrentThread call but this will result in a memory leak instead. For further details inspect the source code in the java/director.swg library file. +

      + +

      +Macros can be defined on the commandline when compiling your C++ code, or alternatively added to the C++ wrapper file as shown below: +

      + +
      +
      +%insert("runtime") %{
+#define SWIG_JAVA_NO_DETACH_CURRENT_THREAD
+%}
+
      +
      + +

      21.6 Accessing protected members

      + + +

      +When using directors, the protected virtual methods are also wrapped. +These methods are wrapped with a protected Java proxy method, so the only way that Java code can access these is from within a Java class derived from the director class. +

      + +

      +Members which are protected and non-virtual can also be accessed when using the 'allprotected' mode. +The allprotected mode requires directors and is turned on by setting the allprotected option in addition to the directors option in the %module directive, like this: +

      + +
      +
      +%module(directors="1", allprotected="1") modulename
+
      +
      + +

      +Protected member variables and methods (both static and non-static) will then be wrapped with protected access in the Java proxy class. +

      + +

      +Note: Neither the directors option nor the allprotected mode support types defined with protected scope. +This includes any enums or typedefs declared in the protected section of the C++ class. +

      + +

      +The following simple example is a class with numerous protected members, including the constructor and destructor: +

      + +
      +
      +%module(directors="1", allprotected="1") example
+
+%feature("director") ProtectedBase;
+
+// Ignore use of unsupported types (those defined in the protected section)
+%ignore ProtectedBase::typedefs;
+
+%inline %{
+
+class ProtectedBase {
+protected:
+  ProtectedBase() {}
+  virtual ~ProtectedBase() {}
+  virtual void virtualMethod() const {}
+  void nonStaticMethod(double d) const {}
+  static void staticMethod(int i) {}
+  int instanceMemberVariable;
+  static int staticMemberVariable;
+
+  // unsupported: types defined with protected access and the methods/variables which use them
+  typedef int IntegerType;
+  IntegerType typedefs(IntegerType it) { return it; }
+};
+int ProtectedBase::staticMemberVariable = 10;
+
+%}
+
+
      +
      + +

      +Note that the IntegerType has protected scope and the members which use this type must be ignored as they cannot be wrapped. +

      + +

      +The proxy methods are protected, so the only way the protected members can be accessed is within a class that derives from the director class, such as the following: +

      + +
      +
      +class MyProtectedBase extends ProtectedBase
+{
+  public MyProtectedBase() {
+  }
+
+  public void accessProtected() {
+    virtualMethod();
+    nonStaticMethod(1.2);
+    staticMethod(99);
+
+    setInstanceMemberVariable(5);
+    int i = getInstanceMemberVariable();
+
+    setStaticMemberVariable(10);
+    i = getStaticMemberVariable();
+  }
+}
+
      +
      + + + +

      21.7 Common customization features

      + + +

      +An earlier section presented the absolute basics of C/C++ wrapping. If you do nothing +but feed SWIG a header file, you will get an interface that mimics the behavior +described. However, sometimes this isn't enough to produce a nice module. Certain +types of functionality might be missing or the interface to certain functions might +be awkward. This section describes some common SWIG features that are used +to improve the interface to existing C/C++ code. +

      + +

      21.7.1 C/C++ helper functions

      + + +

      +Sometimes when you create a module, it is missing certain bits of functionality. For +example, if you had a function like this +

      + +
      +
      +typedef struct Image {...};
+void set_transform(Image *im, double m[4][4]);
+
      +
      + +

      +it would be accessible from Java, but there may be no easy way to call it. +The problem here is that a type wrapper class is generated for the two dimensional array parameter so +there is no easy way to construct and manipulate a suitable +double [4][4] value. To fix this, you can write some extra C helper +functions. Just use the %inline directive. For example: +

      + +
      +
      +%inline %{
+/* Note: double[4][4] is equivalent to a pointer to an array double (*)[4] */
+double (*new_mat44())[4] {
+   return (double (*)[4]) malloc(16*sizeof(double));
+}
+void free_mat44(double (*x)[4]) {
+   free(x);
+}
+void mat44_set(double x[4][4], int i, int j, double v) {
+   x[i][j] = v;
+}
+double mat44_get(double x[4][4], int i, int j) {
+   return x[i][j];
+}
+%}
+
      +
      + +

      +From Java, you could then write code like this: +

      + +
      +
      +Image im = new Image();
+SWIGTYPE_p_a_4__double a = example.new_mat44();
+example.mat44_set(a,0,0,1.0);
+example.mat44_set(a,1,1,1.0);
+example.mat44_set(a,2,2,1.0);
+...
+example.set_transform(im,a);
+example.free_mat44(a);
+
      +
      + +

      +Admittedly, this is not the most elegant looking approach. However, it works and it wasn't too +hard to implement. It is possible to improve on this using Java code, typemaps, and other +customization features as covered in later sections, but sometimes helper functions are a quick and easy solution to difficult cases. +

      + +

      21.7.2 Class extension with %extend

      + + +

      +One of the more interesting features of SWIG is that it can extend +structures and classes with new methods or constructors. +Here is a simple example: +

      + +
      +
      +%module example
+%{
+#include "someheader.h"
+%}
+
+struct Vector {
+   double x,y,z;
+};
+
+%extend Vector {
+   char *toString() {
+       static char tmp[1024];
+       sprintf(tmp,"Vector(%g,%g,%g)", $self->x,$self->y,$self->z);
+       return tmp;
+   }
+   Vector(double x, double y, double z) {
+       Vector *v = (Vector *) malloc(sizeof(Vector));
+       v->x = x;
+       v->y = y;
+       v->z = z;
+       return v;
+   }
+};
+
      +
      + +

      +Now, in Java +

      + +
      +
      +Vector v = new Vector(2,3,4);
+System.out.println(v);
+
      +
      + +

      +will display +

      + +
      +
      +Vector(2,3,4)
+
      +
      + +

      +%extend works with both C and C++ code. It does not modify the underlying object +in any way---the extensions only show up in the Java interface. +

      + +

      21.7.3 Exception handling with %exception and %javaexception

      + + +

      +If a C or C++ function throws an error, you may want to convert that error into a Java +exception. To do this, you can use the %exception directive. The %exception directive +simply lets you rewrite part of the generated wrapper code to include an error check. +It is detailed in full in the Exception handling with %exception section. +

      + +

      +In C, a function often indicates an error by returning a status code (a negative number +or a NULL pointer perhaps). Here is a simple example of how you might handle that: +

      + +
      +
      +%exception malloc {
+  $action
+  if (!result) {
+    jclass clazz = (*jenv)->FindClass(jenv, "java/lang/OutOfMemoryError");
+    (*jenv)->ThrowNew(jenv, clazz, "Not enough memory");
+    return $null;
+  }
+}
+void *malloc(size_t nbytes);
+
      +
      + +

      +In Java, +

      + +
      +
      +SWIGTYPE_p_void a = example.malloc(2000000000);
+
      +
      + +

      +will produce a familiar looking Java exception: +

      + +
      +
      +Exception in thread "main" java.lang.OutOfMemoryError: Not enough memory
+        at exampleJNI.malloc(Native Method)
+        at example.malloc(example.java:16)
+        at runme.main(runme.java:112)
+
      +
      + +

      +If a library provides some kind of general error handling framework, you can also use +that. For example: +

      + +
      +
      +%exception malloc {
+  $action
+  if (err_occurred()) {
+    jclass clazz = (*jenv)->FindClass(jenv, "java/lang/OutOfMemoryError");
+    (*jenv)->ThrowNew(jenv, clazz, "Not enough memory");
+    return $null;
+  }
+}
+void *malloc(size_t nbytes);
+
      +
      + +

      +If no declaration name is given to %exception, it is applied to all wrapper functions. +The $action is a SWIG special variable and is replaced by the C/C++ function call being wrapped. +The return $null; handles all native method return types, namely those that have a void return and those that do not. +This is useful for typemaps that will be used in native method returning all return types. +See the section on +Java special variables for further explanation. +

      + +

      +C++ exceptions are also easy to handle. +We can catch the C++ exception and rethrow it as a Java exception like this:

      + +
      +
      +%exception getitem {
+  try {
+     $action
+  } catch (std::out_of_range &e) {
+    jclass clazz = jenv->FindClass("java/lang/Exception");
+    jenv->ThrowNew(clazz, "Range error");
+    return $null;
+   }
+}
+
+class FooClass {
+public:
+     FooClass *getitem(int index);      // Might throw std::out_of_range exception
+     ...
+};
+
      +
      + +

      +In the example above, java.lang.Exception is a checked exception class and so ought to be declared in the throws clause of getitem. +Classes can be specified for adding to the throws clause using %javaexception(classes) instead of %exception, +where classes is a string containing one or more comma separated Java classes. +The %clearjavaexception feature is the equivalent to %clearexception and clears previously declared exception handlers. +The %nojavaexception feature is the equivalent to %noexception and disables the exception handler. +See Clearing features for the difference on disabling and clearing features. +

      + +
      +
      +%javaexception("java.lang.Exception") getitem {
+  try {
+     $action
+  } catch (std::out_of_range &e) {
+    jclass clazz = jenv->FindClass("java/lang/Exception");
+    jenv->ThrowNew(clazz, "Range error");
+    return $null;
+   }
+}
+
+class FooClass {
+public:
+     FooClass *getitem(int index);      // Might throw std::out_of_range exception
+     ...
+};
+
      +
      + +

      +The generated proxy method now generates a throws clause containing java.lang.Exception: +

      + +
      +
      +public class FooClass {
+  ...
+  public FooClass getitem(int index) throws java.lang.Exception { ... }
+  ...
+}
+
      +
      + + +

      +The examples above first use the C JNI calling syntax then the C++ JNI calling syntax. The C++ calling syntax will not compile as C and also vice versa. +It is however possible to write JNI calls which will compile under both C and C++ and is covered in the Typemaps for both C and C++ compilation section. +

      + +

      +The language-independent exception.i library file can also be used +to raise exceptions. See the SWIG Library chapter. +The typemap example Handling C++ exception specifications as Java exceptions provides further exception handling capabilities. +

      + +

      21.7.4 Method access with %javamethodmodifiers

      + + +

      +A Java feature called %javamethodmodifiers can be used to change the method modifiers from the default public. It applies to both module class methods and proxy class methods. For example: +

      + +
      +
      +%javamethodmodifiers protect_me() "protected";
+void protect_me();
+
      +
      + +

      +Will produce the method in the module class with protected access. +

      + +
      +
      +protected static void protect_me() {
+  exampleJNI.protect_me();
+}
+
      +
      + +

      21.8 Tips and techniques

      + + +

      +Although SWIG is largely automatic, there are certain types of wrapping problems that +require additional user input. Examples include dealing with output parameters, +strings and arrays. This chapter discusses the common techniques for +solving these problems. +

      + +

      21.8.1 Input and output parameters using primitive pointers and references

      + + +

      +A common problem in some C programs is handling parameters passed as simple pointers or references. For +example: +

      + +
      +
      +void add(int x, int y, int *result) {
+   *result = x + y;
+}
+
      +
      + +

      +or perhaps +

      + +
      +
      +int sub(int *x, int *y) {
+   return *x-*y;
+}
+
      +
      + +

      +The typemaps.i library file will help in these situations. For example: +

      + +
      +
      +%module example
+%include "typemaps.i"
+
+void add(int, int, int *OUTPUT);
+int  sub(int *INPUT, int *INPUT);
+
      +
      + +

      +In Java, this allows you to pass simple values. For example: +

      + +
      +
      +int result = example.sub(7,4);
+System.out.println("7 - 4 = " + result);
+int[] sum = {0};
+example.add(3,4,sum);
+System.out.println("3 + 4 = " + sum[0]);
+
      +
      + +

      +Which will display: +

      + +
      +7 - 4 = 3
+3 + 4 = 7
+
      + +

      +Notice how the INPUT parameters allow integer values to be passed instead of pointers +and how the OUTPUT parameter will return the result in the first element of the integer array. +

      + +

      +If you don't want to use the names INPUT or OUTPUT, use the %apply +directive. For example: +

      + +
      +
      +%module example
+%include "typemaps.i"
+
+%apply int *OUTPUT { int *result };
+%apply int *INPUT  { int *x, int *y};
+
+void add(int x, int y, int *result);
+int  sub(int *x, int *y);
+
      +
      + +

      +If a function mutates one of its parameters like this, +

      + +
      +
      +void negate(int *x) {
+   *x = -(*x);
+}
+
      +
      + +

      +you can use INOUT like this: +

      + +
      +
      +%include "typemaps.i"
+...
+void negate(int *INOUT);
+
      +
      + +

      +In Java, the input parameter is the first element in a 1 element array and is replaced by the output of the function. For example: +

      + +
      +
      +int[] neg = {3};
+example.negate(neg);
+System.out.println("Negative of 3 = " + neg[0]);
+
      +
      + +

      +And no prizes for guessing the output: +

      + +
      +Negative of 3 = -3
+
      + +

      +These typemaps can also be applied to C++ references. +The above examples would work the same if they had been defined using references instead of pointers. +For example, the Java code to use the negate function would be the same if it were defined either as it is above: +

      + +
      +
      +void negate(int *INOUT);
+
      +
      + +

      +or using a reference: +

      + +
      +
      +void negate(int &INOUT);
+
      +
      + +

      +Note: Since most Java primitive types are immutable and are passed by value, it is not possible to +perform in-place modification of a type passed as a parameter. +

      + +

      +Be aware that the primary purpose of the typemaps.i file is to support primitive datatypes. +Writing a function like this +

      + +
      +
      +void foo(Bar *OUTPUT);
+
      +
      + +

      +will not have the intended effect since typemaps.i does not define an OUTPUT rule for Bar. +

      + +

      21.8.2 Simple pointers

      + + +

      +If you must work with simple pointers such as int * or double * another approach to using +typemaps.i is to use the cpointer.i pointer library file. For example: +

      + +
      +
      +%module example
+%include "cpointer.i"
+
+%inline %{
+extern void add(int x, int y, int *result);
+%}
+
+%pointer_functions(int, intp);
+
      +
      + +

      +The %pointer_functions(type,name) macro generates five helper functions that can be used to create, +destroy, copy, assign, and dereference a pointer. In this case, the functions are as follows: +

      + +
      +
      +int  *new_intp();
+int  *copy_intp(int *x);
+void  delete_intp(int *x);
+void  intp_assign(int *x, int value);
+int   intp_value(int *x);
+
      +
      + +

      +In Java, you would use the functions like this: +

      + +
      +
      +SWIGTYPE_p_int intPtr = example.new_intp();
+example.add(3,4,intPtr);
+int result = example.intp_value(intPtr);
+System.out.println("3 + 4 = " + result);
+
      +
      + +

      +If you replace %pointer_functions(int,intp) by %pointer_class(int,intp), the interface is more class-like. +

      + +
      +
      +intp intPtr = new intp();
+example.add(3,4,intPtr.cast());
+int result = intPtr.value();
+System.out.println("3 + 4 = " + result);
+
      +
      + +

      +See the SWIG Library chapter for further details. +

      + +

      21.8.3 Wrapping C arrays with Java arrays

      + + +

      +SWIG can wrap arrays in a more natural Java manner than the default by using the arrays_java.i library file. +Let's consider an example: +

      + +
      +
      +%include "arrays_java.i";
+int array[4];
+void populate(int x[]) {
+    int i;
+    for (i=0; i<4; i++)
+        x[i] = 100 + i;
+}
+
      +
      + +

      +These one dimensional arrays can then be used as if they were Java arrays: +

      + +
      +
      +int[] array = new int[4];
+example.populate(array);
+
+System.out.print("array: ");
+for (int i=0; i<array.length; i++)
+    System.out.print(array[i] + " ");
+
+example.setArray(array);
+
+int[] global_array = example.getArray();
+
+System.out.print("\nglobal_array: ");
+for (int i=0; i<array.length; i++)
+    System.out.print(global_array[i] + " ");
+
      +
      + +

      +Java arrays are always passed by reference, so any changes a function makes to the array will be seen by the calling function. +Here is the output after running this code: +

      + +
      +
      +array: 100 101 102 103
+global_array: 100 101 102 103
+
      +
      + +

      +Note that for assigning array variables the length of the C variable is used, so it is possible to use a Java array that is bigger than the C code will cope with. +Only the number of elements in the C array will be used. +However, if the Java array is not large enough then you are likely to get a segmentation fault or access violation, just like you would in C. +When arrays are used in functions like populate, the size of the C array passed to the function is determined by the size of the Java array. +

      + +

      +Please be aware that the typemaps in this library are not efficient as all the elements are copied from the Java array to a C array whenever the array is passed to and from JNI code. +There is an alternative approach using the SWIG array library and this is covered in the next section. +

      + +

      21.8.4 Unbounded C Arrays

      + + +

      +Sometimes a C function expects an array to be passed as a pointer. For example, +

      + +
      +
      +int sumitems(int *first, int nitems) {
+    int i, sum = 0;
+    for (i = 0; i < nitems; i++) {
+        sum += first[i];
+    }
+    return sum;
+}
+
      +
      + +

      +One of the ways to wrap this is to apply the Java array typemaps that come in the arrays_java.i library file: +

      + +
      +
      +%include "arrays_java.i"
+%apply int[] {int *};
+
      +
      + +

      +The ANY size will ensure the typemap is applied to arrays of all sizes. +You could narrow the typemap matching rules by specifying a particular array size. +Now you can use a pure Java array and pass it to the C code: +

      + +
      +
      +int[] array = new int[10000000];          // Array of 10-million integers
+for (int i=0; i<array.length; i++) {      // Set some values
+  array[i] = i;
+}
+int sum = example.sumitems(array,10000);
+System.out.println("Sum = " + sum);
+
      +
      + +

      +and the sum would be displayed: +

      + +
      +
      +Sum = 49995000
+
      +
      + +

      +This approach is probably the most natural way to use arrays. +However, it suffers from performance problems when using large arrays as a lot of copying +of the elements occurs in transferring the array from the Java world to the C++ world. +An alternative approach to using Java arrays for C arrays is to use an alternative SWIG library file carrays.i. +This approach can be more efficient for large arrays as the array is accessed one element at a time. +For example: +

      + +
      +
      +%include "carrays.i"
+%array_functions(int, intArray);
+
      +
      + +

      +The %array_functions(type,name) macro generates four helper functions that can be used to create and +destroy arrays and operate on elements. In this case, the functions are as follows: +

      + +
      +
      +int *new_intArray(int nelements);
+void delete_intArray(int *x);
+int intArray_getitem(int *x, int index);
+void intArray_setitem(int *x, int index, int value);
+
      +
      + +

      +In Java, you would use the functions like this: +

      + +
      +
      +SWIGTYPE_p_int array = example.new_intArray(10000000);  // Array of 10-million integers
+for (int i=0; i<10000; i++) {                           // Set some values
+    example.intArray_setitem(array,i,i);
+}
+int sum = example.sumitems(array,10000);
+System.out.println("Sum = " + sum);
+
      +
      + +

      +If you replace %array_functions(int,intp) by %array_class(int,intp), the interface is more class-like +and a couple more helper functions are available for casting between the array and the type wrapper class. +

      + +
      +
      +%include "carrays.i"
+%array_class(int, intArray);
+
      +
      + +

      +The %array_class(type, name) macro creates wrappers for an unbounded array object that +can be passed around as a simple pointer like int * or double *. +For instance, you will be able to do this in Java: +

      + +
      +
      +intArray array = new intArray(10000000);  // Array of 10-million integers
+for (int i=0; i<10000; i++) {             // Set some values
+    array.setitem(i,i);
+}
+int sum = example.sumitems(array.cast(),10000);
+System.out.println("Sum = " + sum);
+
      +
      + +

      +The array "object" created by %array_class() does not +encapsulate pointers inside a special array object. In fact, there is +no bounds checking or safety of any kind (just like in C). Because of +this, the arrays created by this library are extremely low-level +indeed. You can't iterate over them nor can you even query their +length. In fact, any valid memory address can be accessed if you want +(negative indices, indices beyond the end of the array, etc.). +Needless to say, this approach is not going to suit all applications. +On the other hand, this low-level approach is extremely efficient and +well suited for applications in which you need to create buffers, +package binary data, etc. +

      + +

      21.8.5 Overriding new and delete to allocate from Java heap

      + + +

      +Unlike some languages supported by SWIG, Java has a true garbage collection +subsystem. Other languages will free SWIG wrapped objects when their reference +count reaches zero. Java only schedules these objects for finalization, which +may not occur for some time. Because SWIG objects are allocated on the C +heap, Java users may find the JVM memory use +quickly exceeds the assigned limits, as memory fills with unfinalized proxy +objects. Forcing garbage collection is clearly an undesirable solution. +

      + +

      +An elegant fix for C++ users is to override new and delete using the following +code (here shown included in a SWIG interface file) +

      + +
      +
      +/* File: java_heap.i */
+%module test
+%{
+#include <stdexcept>
+#include "jni.h"
+
+/**
+ *  A stash area embedded in each allocation to hold java handles
+ */
+struct Jalloc {
+  jbyteArray jba;
+  jobject ref;
+};
+
+static JavaVM *cached_jvm = 0;
+
+JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *jvm, void *reserved) {
+  cached_jvm = jvm;
+  return JNI_VERSION_1_2;
+}
+
+static JNIEnv * JNU_GetEnv() {
+  JNIEnv *env;
+  jint rc = cached_jvm->GetEnv((void **)&env, JNI_VERSION_1_2);
+  if (rc == JNI_EDETACHED)
+    throw std::runtime_error("current thread not attached");
+  if (rc == JNI_EVERSION)
+    throw std::runtime_error("jni version not supported");
+  return env;
+}
+
+void * operator new(size_t t) {
+  if (cached_jvm != 0) {
+    JNIEnv *env = JNU_GetEnv();
+    jbyteArray jba = env->NewByteArray((int) t + sizeof(Jalloc));
+    if (env->ExceptionOccurred())
+      throw bad_alloc();
+    void *jbuffer = static_cast<void *>(env->GetByteArrayElements(jba, 0));
+    if (env->ExceptionOccurred())
+      throw bad_alloc();
+    Jalloc *pJalloc = static_cast<Jalloc *>(jbuffer);
+    pJalloc->jba = jba;
+    /* Assign a global reference so byte array will persist until delete'ed */
+    pJalloc->ref = env->NewGlobalRef(jba);
+    if (env->ExceptionOccurred())
+      throw bad_alloc();
+    return static_cast<void *>(static_cast<char *>(jbuffer) + sizeof(Jalloc));
+  }
+  else { /* JNI_OnLoad not called, use malloc and mark as special */
+    Jalloc *pJalloc = static_cast<Jalloc *>(malloc((int) t + sizeof(Jalloc)));
+    if (!pJalloc)
+      throw bad_alloc();
+    pJalloc->ref = 0;
+    return static_cast<void *>(
+        static_cast<char *>(static_cast<void *>(pJalloc)) + sizeof(Jalloc));
+  }
+}
+
+void operator delete(void *v) {
+  if (v != 0) {
+    void *buffer = static_cast<void *>( static_cast<char *>(v) - sizeof(Jalloc));
+    Jalloc *pJalloc = static_cast<Jalloc *>(buffer);
+    if (pJalloc->ref) {
+      JNIEnv *env = JNU_GetEnv();
+      env->DeleteGlobalRef(pJalloc->ref);
+      env->ReleaseByteArrayElements(pJalloc->jba, static_cast<jbyte *>(buffer), 0);
+    }
+    else {
+      free(buffer);
+    }
+  }
+}
+%}
+...
+
      +
      + +

      +This code caches the Java environment during initialization, +and when new is called, a Java ByteArray is allocated to provide the +SWIG objects with space in the Java heap. This has the combined +effect of re-asserting the Java virtual machine's limit on memory allocation, +and puts additional pressure on the garbage collection system to run more +frequently. +This code is made slightly more complicated because allowances must be made +if new is called before the JNI_OnLoad is executed. This can happen during +static class initialization, for example. +

      + +

      +Unfortunately, because most Java implementations call malloc and free, this +solution will not work for C wrapped structures. However, you are free to +make functions that allocate and free memory from the Java heap using this +model and use these functions in place of malloc and free in your own +code. +

      + +

      21.9 Java typemaps

      + + +

      +This section describes how you can modify SWIG's default wrapping behavior +for various C/C++ datatypes using the %typemap directive. +You are advised to be familiar with the the material in the "Typemaps" chapter. +While not absolutely essential knowledge, this section assumes some familiarity with the Java Native Interface (JNI). +JNI documentation can be consulted either online at Sun's Java web site or from a good JNI book. +The following two books are recommended:

      + +
        +
      • Title: 'Essential JNI: Java Native Interface.' Author: Rob Gordon. Publisher: Prentice Hall. ISBN: 0-13-679895-0.
        • +
      • Title: 'The Java Native Interface: Programmer's Guide and Specification.' Author: Sheng Liang. Publisher: Addison-Wesley. ISBN: 0-201-32577-2. Also available online at the Sun Developer Network.
        • +
      + +

      +Before proceeding, it should be stressed that typemaps are not a required +part of using SWIG---the default wrapping behavior is enough in most cases. +Typemaps are only used if you want to change some aspect of the generated code. + +

      21.9.1 Default primitive type mappings

      + + +

      +The following table lists the default type mapping from Java to C/C++.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      C/C++ typeJava typeJNI type
      bool
      const bool &       		booleanjboolean
      char
      const char &      		charjchar
      signed char
      const signed char &      		bytejbyte
      unsigned char
      const unsigned char &      		shortjshort
      short
      const short &      		shortjshort
      unsigned short
      const unsigned short &      		intjint
      int
      const int &      		intjint
      unsigned int
      const unsigned int &      		longjlong
      long
      const long &      		intjint
      unsigned long
      const unsigned long &      		longjlong
      long long
      const long long &      		longjlong
      unsigned long long
      const unsigned long long &      		java.math.BigIntegerjobject
      float
      const float &      		floatjfloat
      double
      const double &      		doublejdouble
      char *
      char []      		Stringjstring
      + +

      +Note that SWIG wraps the C char type as a character. Pointers and arrays of this type are wrapped as strings. +The signed char type can be used if you want to treat char as a signed number rather than a character. +Also note that all const references to primitive types are treated as if they are passed by value. +

      + +

      +Given the following C function: +

      + +
      +void func(unsigned short a, char *b, const long &c, unsigned long long d);
+
      + +

      +The module class method would be: +

      + +
      +public static void func(int a, String b, int c, java.math.BigInteger d) {...}
+
      + +

      +The intermediary JNI class would use the same types: +

      + +
      +public final static native void func(int jarg1, String jarg2, int jarg3,
+                                     java.math.BigInteger jarg4);
+
      + +

      +and the JNI function would look like this: +

      + +
      +SWIGEXPORT void JNICALL Java_exampleJNI_func(JNIEnv *jenv, jclass jcls,
+                jint jarg1, jstring jarg2, jint jarg3, jobject jarg4) {...}
+
      + +

      +The mappings for C int and C long are appropriate for 32 bit applications which are used in the 32 bit JVMs. +There is no perfect mapping between Java and C as Java doesn't support all the unsigned C data types. +However, the mappings allow the full range of values for each C type from Java. +

      + + +

      21.9.2 Default typemaps for non-primitive types

      + + +

      +The previous section covered the primitive type mappings. +Non-primitive types such as classes and structs are mapped using pointers on the C/C++ side and storing the pointer into a Java long variable which is held by +the proxy class or type wrapper class. This applies whether the type is marshalled as a pointer, by reference or by value. +It also applies for any unknown/incomplete types which use type wrapper classes. +

      + +

      +So in summary, the C/C++ pointer to non-primitive types is cast into the 64 bit Java long type and therefore the JNI type is a jlong. +The Java type is either the proxy class or type wrapper class. +

      + +

      21.9.3 Sixty four bit JVMs

      + + +

      +If you are using a 64 bit JVM you may have to override the C long, but probably not C int default mappings. +Mappings will be system dependent, for example long will need remapping on Unix LP64 systems (long, pointer 64 bits, int 32 bits), but not on +Microsoft 64 bit Windows which will be using a P64 IL32 (pointer 64 bits and int, long 32 bits) model. +This may be automated in a future version of SWIG. +Note that the Java write once run anywhere philosophy holds true for all pure Java code when moving to a 64 bit JVM. +Unfortunately it won't of course hold true for JNI code. +

      + + +

      21.9.4 What is a typemap?

      + + +

      +A typemap is nothing more than a code generation rule that is attached to +a specific C datatype. For example, to convert integers from Java to C, +you might define a typemap like this: +

      + +
      +%module example
+
+%typemap(in) int {
+  $1 = $input;
+  printf("Received an integer : %d\n",  $1);
+}
+%inline %{
+extern int fact(int nonnegative);
+%}
+
      + +

      +Typemaps are always associated with some specific aspect of code generation. +In this case, the "in" method refers to the conversion of input arguments +to C/C++. The datatype int is the datatype to which the typemap +will be applied. The supplied C code is used to convert values. In this +code a number of special variables prefaced by a $ are used. The +$1 variable is a placeholder for a local variable of type int. +The $input variable contains the Java data, the JNI jint in this case. +

      + +

      +When this example is compiled into a Java module, it can be used as follows: +

      + +
      +System.out.println(example.fact(6));
+
      + +

      +and the output will be: +

      + +
      +Received an integer : 6
+720
+
      + +

      +In this example, the typemap is applied to all occurrences of the int datatype. +You can refine this by supplying an optional parameter name. For example: +

      + +
      +%module example
+
+%typemap(in) int nonnegative {
+  $1 = $input;
+  printf("Received an integer : %d\n",  $1);
+}
+
+%inline %{
+extern int fact(int nonnegative);
+%}
+
      + +

      +In this case, the typemap code is only attached to arguments that exactly match int nonnegative. +

      + +

      +The application of a typemap to specific datatypes and argument names involves +more than simple text-matching--typemaps are fully integrated into the +SWIG C++ type-system. When you define a typemap for int, that typemap +applies to int and qualified variations such as const int. In addition, +the typemap system follows typedef declarations. For example: +

      + +
      +
      +%typemap(in) int nonnegative {
+  $1 = $input;
+  printf("Received an integer : %d\n",  $1);
+}
+%inline %{
+typedef int Integer;
+extern int fact(Integer nonnegative);    // Above typemap is applied
+%}
+
      +
      + +

      +However, the matching of typedef only occurs in one direction. If you +defined a typemap for Integer, it is not applied to arguments of +type int. +

      + +

      +Typemaps can also be defined for groups of consecutive arguments. For example: +

      + +
      +
      +%typemap(in) (char *str, int len) {
+...
+};
+
+int count(char c, char *str, int len);
+
      +
      + +

      +When a multi-argument typemap is defined, the arguments are always handled as a single +Java parameter. This allows the function to be used like this (notice how the length +parameter is omitted): +

      + +
      +
      +int c = example.count('e',"Hello World");
+
      +
      + +

      21.9.5 Typemaps for mapping C/C++ types to Java types

      + + +

      +The typemaps available to the Java module include the common typemaps listed in the main typemaps section. +There are a number of additional typemaps which are necessary for using SWIG with Java. +The most important of these implement the mapping of C/C++ types to Java types: +

      + +
        + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      TypemapDescription
      jniJNI C types. These provide the default mapping of types from C/C++ to JNI for use in the JNI (C/C++) code.
      jtypeJava intermediary types. These provide the default mapping of types from C/C++ to Java for use in the native functions in the intermediary JNI class. The type must be the equivalent Java type for the JNI C type specified in the "jni" typemap.
      jstypeJava types. These provide the default mapping of types from C/C++ to Java for use in the Java module class, proxy classes and type wrapper classes.
      javainConversion from jstype to jtype. + These are Java code typemaps which transform the type used in the Java module class, proxy classes and type wrapper classes (as specified in the "jstype" typemap) + to the type used in the Java intermediary JNI class (as specified in the "jtype" typemap). + In other words the typemap provides the conversion to the native method call parameter types.
      javaoutConversion from jtype to jstype. + These are Java code typemaps which transform the type used in the Java intermediary JNI class (as specified in the "jtype" typemap) to + the Java type used in the Java module class, proxy classes and type wrapper classes (as specified in the "jstype" typemap). + In other words the typemap provides the conversion from the native method call return type.
      javadirectorinConversion from jtype to jstype for director methods. + These are Java code typemaps which transform the type used in the Java intermediary JNI class (as specified in the "jtype" typemap) to + the Java type used in the Java module class, proxy classes and type wrapper classes (as specified in the "jstype" typemap). + This typemap provides the conversion for the parameters in the director methods when calling up from C++ to Java. + See Director typemaps.
      javadirectoroutConversion from jstype to jtype for director methods. + These are Java code typemaps which transform the type used in the Java module class, proxy classes and type wrapper classes (as specified in the "jstype" typemap) + to the type used in the Java intermediary JNI class (as specified in the "jtype" typemap). + This typemap provides the conversion for the return type in the director methods when returning from the C++ to Java upcall. + See Director typemaps.
      directorinConversion from C++ type to jni type for director methods. + These are C++ typemaps which convert the parameters used in the C++ director method to the appropriate JNI intermediary type. + The conversion is done in JNI code prior to calling the Java function from the JNI code. + See Director typemaps.
      directoroutConversion from jni type to C++ type for director methods. + These are C++ typemaps which convert the JNI return type used in the C++ director method to the appropriate C++ return type. + The conversion is done in JNI code after calling the Java function from the JNI code. + See Director typemaps.
      + +

      +If you are writing your own typemaps to handle a particular type, you will normally have to write a collection of them. +The default typemaps are in "java.swg" and so might be a good place for finding typemaps to base any new ones on. +

      + +

      +The "jni", "jtype" and "jstype" typemaps are usually defined together to handle the Java to C/C++ type mapping. +An "in" typemap should be accompanied by a "javain" typemap and likewise an "out" typemap by a "javaout" typemap. +If an "in" typemap is written, a "freearg" and "argout" typemap may also need to be written +as some types have a default "freearg" and/or "argout" typemap which may need overriding. +The "freearg" typemap sometimes releases memory allocated by the "in" typemap. +The "argout" typemap sometimes sets values in function parameters which are passed by reference in Java. +

      + +

      +Note that the "in" typemap marshals the JNI type held in the "jni" typemap to the real C/C++ type and for the opposite direction, +the "out" typemap marshals the real C/C++ type to the JNI type held in the "jni" typemap. +For non-primitive types +the "in" and "out" typemaps are responsible for casting between the C/C++ pointer and the 64 bit jlong type. +There is no portable way to cast a pointer into a 64 bit integer type and the approach taken by SWIG is mostly portable, but breaks C/C++ aliasing rules. +In summary, these rules state that a pointer to any type must never be dereferenced by a pointer to any other incompatible type. +The following code snippet might aid in understand aliasing rules better: +

      + +
      +    short a;
+    short* pa = 0;
+    int i = 0x1234;
+
+    a = (short)i;    /* okay */
+    a = *(short*)&i; /* breaks aliasing rules */
+
      + +

      +An email posting, Aliasing, pointer casts and gcc 3.3 elaborates further on the subject. +In SWIG, the "in" and "out" typemaps for pointers are typically +

      + +
      +    %typemap(in) struct Foo * %{
+      $1 = *(struct Foo **)&$input; /* cast jlong into C ptr */
+    %}
+    %typemap(out) struct Bar * %{
+      *(struct Bar **)&$result = $1; /* cast C ptr into jlong */
+    %} 
+    struct Bar {...};
+    struct Foo {...};
+    struct Bar * FooBar(struct Foo *f);
+
      + +

      +resulting in the following code which breaks the aliasing rules: +

      + +
      +SWIGEXPORT jlong JNICALL Java_exampleJNI_FooBar(JNIEnv *jenv, jclass jcls,
+                                                jlong jarg1, jobject jarg1_) {
+  jlong jresult = 0 ;
+  struct Foo *arg1 = (struct Foo *) 0 ;
+  struct Bar *result = 0 ;
+  
+  (void)jenv;
+  (void)jcls;
+  (void)jarg1_;
+  arg1 = *(struct Foo **)&jarg1; 
+  result = (struct Bar *)FooBar(arg1);
+  *(struct Bar **)&jresult = result; 
+  return jresult;
+}
+
      + +

      +If you are using gcc as your C compiler, you might get a "dereferencing type-punned pointer will break strict-aliasing rules" warning about this. +Please see Compiling a dynamic module to avoid runtime problems with these strict aliasing rules. +

      + +

      +The default code generated by SWIG for the Java module comes from the typemaps in the "java.swg" library file which implements the +Default primitive type mappings and +Default typemaps for non-primitive types covered earlier. +There are other type mapping typemaps in the Java library. +These are listed below: +

      + +
        + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      C TypeTypemapFileKindJava TypeFunction
      primitive pointers and referencesINPUTtypemaps.iinputJava basic typesAllows values to be used for C functions taking pointers for data input. + +
      primitive pointers and referencesOUTPUTtypemaps.ioutputJava basic type arraysAllows values held within an array to be used for C functions taking pointers for data output. + +
      primitive pointers and referencesINOUTtypemaps.iinput
      output      		Java basic type arraysAllows values held within an array to be used for C functions taking pointers for data input and output. + +
      string
      wstring      		[unnamed]std_string.iinput
      output      		StringUse for std::string mapping to Java String.
      arrays of primitive types[unnamed]arrays_java.iinput
      output      		arrays of primitive Java typesUse for mapping C arrays to Java arrays.
      arrays of classes/structs/unionsJAVA_ARRAYSOFCLASSES macroarrays_java.iinput
      output      		arrays of proxy classesUse for mapping C arrays to Java arrays.
      arrays of enumsARRAYSOFENUMSarrays_java.iinput
      output      		int[]Use for mapping C arrays to Java arrays (typeunsafe and simple enum wrapping approaches only).
      char *BYTEvarious.iinputbyte[]Java byte array is converted to char array
      char **STRING_ARRAYvarious.iinput
      output      		String[]Use for mapping NULL terminated arrays of C strings to Java String arrays
      + +

      21.9.6 Java typemap attributes

      + + +

      +There are a few additional typemap attributes that the Java module supports. +

      + +

      +The first of these is the 'throws' attribute. +The throws attribute is optional and specified after the typemap name and contains one or more comma separated classes for adding to the throws clause for any methods that use that typemap. +It is analogous to the %javaexception feature's throws attribute. +

      + +
      +
      +%typemap(typemapname, throws="ExceptionClass1, ExceptionClass2") type { ... }
+
      +
      + +

      +The attribute is necessary for supporting Java checked exceptions and can be added to just about any typemap. +The list of typemaps include all the C/C++ (JNI) typemaps in the "Typemaps" chapter and the +Java specific typemaps listed in the previous section, barring +the "jni", "jtype" and "jstype" typemaps as they could never contain code to throw an exception. +

      + +

      +The throws clause is generated for the proxy method as well as the JNI method in the JNI intermediary class. +If a method uses more than one typemap and each of those typemaps have classes specified in the throws clause, +the union of the exception classes is added to the throws clause ensuring there are no duplicate classes. +See the NaN exception example for further usage. +

      + +

      +The "jtype" typemap has the optional 'nopgcpp' attribute which can be used to suppress the generation of the premature garbage collection prevention parameter. +

      + +

      +The "javain" typemap has the optional 'pre', 'post' and 'pgcppname' attributes. These are used for generating code before and after the JNI call in the proxy class or module class. The 'pre' attribute contains code that is generated before the JNI call and the 'post' attribute contains code generated after the JNI call. The 'pgcppname' attribute is used to change the premature garbage collection prevention parameter name passed to the JNI function. This is sometimes needed when the 'pre' typemap creates a temporary variable which is then passed to the JNI function. +

      + +

      + +Note that when the 'pre' or 'post' attributes are specified and the associated type is used in a constructor, a constructor helper function is generated. This is necessary as the Java proxy constructor wrapper makes a call to a support constructor using a this call. In Java the this call must be the first statement in the constructor body. The constructor body thus calls the helper function and the helper function instead makes the JNI call, ensuring the 'pre' code is called before the JNI call is made. There is a Date marshalling example showing 'pre', 'post' and 'pgcppname' attributes in action. +

      + +

      21.9.7 Java special variables

      + + +

      +The standard SWIG special variables are available for use within typemaps as described in the Typemaps documentation, for example $1, $input,$result etc. +

      + +

      +The Java module uses a few additional special variables: +

      + +

      +$javaclassname
      +This special variable works like the other special variables +and $javaclassname is similar to $1_type. It expands to the class name for use in Java given a pointer. +SWIG wraps unions, structs and classes using pointers and in this case it expands to the Java proxy class name. +For example, $javaclassname is replaced by the proxy classname Foo when wrapping a Foo * and +$&javaclassname expands to the proxy classname when wrapping the C/C++ type Foo and $*javaclassname +expands to the proxy classname when wrapping Foo *&. +If the type does not have an associated proxy class, it expands to the type wrapper class name, for example, +SWIGTYPE_p_unsigned_short is generated when wrapping unsigned short *. +

      + +

      +$null
      +Used in input typemaps to return early from JNI functions that have either void or a non-void return type. Example: +

      + +
      +%typemap(check) int * %{ 
+  if (error) {
+    SWIG_JavaThrowException(jenv, SWIG_JavaIndexOutOfBoundsException, "Array element error");
+    return $null;
+  }
+%}
+
      + +

      +If the typemap gets put into a function with void as return, $null will expand to nothing: +

      + +
      +SWIGEXPORT void JNICALL Java_jnifn(...) {
+    if (error) {
+      SWIG_JavaThrowException(jenv, SWIG_JavaIndexOutOfBoundsException, "Array element error");
+      return ;
+    }
+  ...
+}
+
      + +

      +otherwise $null expands to NULL +

      + +
      +SWIGEXPORT jobject JNICALL Java_jnifn(...) {
+    if (error) {
+      SWIG_JavaThrowException(jenv, SWIG_JavaIndexOutOfBoundsException, "Array element error");
+      return NULL;
+    }
+  ...
+}
+
      + +

      +$javainput, $jnicall and $owner
      +The $javainput special variable is used in "javain" typemaps and $jnicall and $owner are used in "javaout" typemaps. +$jnicall is analogous to $action in %exception. It is replaced by the call to the native method in the intermediary JNI class. +$owner is replaced by either true if %newobject has been used, otherwise false. +$javainput is analogous to the $input special variable. It is replaced by the parameter name. +

      + +

      +Here is an example: +

      + +
      +%typemap(javain) Class "Class.getCPtr($javainput)"
+%typemap(javain) unsigned short "$javainput"
+%typemap(javaout) Class * {
+    return new Class($jnicall, $owner);
+  }
+
+%inline %{
+    class Class {...};
+    Class * bar(Class cls, unsigned short ush) { return new Class(); };
+%}
+
      + +

      +The generated proxy code is then: +

      + +
      +public static Class bar(Class cls, int ush) {
+  return new Class(exampleJNI.bar(Class.getCPtr(cls), cls, ush), false);
+}
+
      + +

      +Here $javainput has been replaced by cls and ush. $jnicall has been replaced by +the native method call, exampleJNI.bar(...) and $owner has been replaced by false. +If %newobject is used by adding the following at the beginning of our example: +

      + +
      +%newobject bar(Class cls, unsigned short ush);
+
      + +

      +The generated code constructs the return type using true indicating the proxy class Class is responsible for destroying the C++ memory allocated for it in bar: +

      + +
      +public static Class bar(Class cls, int ush) {
+  return new Class(exampleJNI.bar(Class.getCPtr(cls), cls, ush), true);
+}
+
      + +

      +$static
      +This special variable expands to either static or nothing depending on whether the class is an inner Java class or not. +It is used in the "javaclassmodifiers" typemap so that global classes can be wrapped as Java proxy classes and nested C++ classes/enums +can be wrapped with the Java equivalent, that is, static inner proxy classes. +

      + +

      +$jniinput, $javacall and $packagepath
      +These special variables are used in the directors typemaps. See Director specific typemaps for details. +

      + +

      +$module
      +This special variable expands to the module name, as specified by %module or the -module commandline option. +

      + +

      +$imclassname
      +This special variable expands to the intermediary class name. Usually this is the same as '$moduleJNI', +unless the jniclassname attribute is specified in the %module directive. +

      + +

      21.9.8 Typemaps for both C and C++ compilation

      + + +

      +JNI calls must be written differently depending on whether the code is being compiled as C or C++. +For example C compilation requires the pointer to a function pointer struct member syntax like +

      + +
      +const jclass clazz = (*jenv)->FindClass(jenv, "java/lang/String");
+
      + +

      +whereas C++ code compilation of the same function call is a member function call using a class pointer like +

      + +
      +const jclass clazz = jenv->FindClass("java/lang/String");
+
      + +

      +To enable typemaps to be used for either C or C++ compilation, a set of JCALLx macros have been defined in Lib/java/javahead.swg, +where x is the number of arguments in the C++ version of the JNI call. +The above JNI calls would be written in a typemap like this +

      + +
      +const jclass clazz = JCALL1(FindClass, jenv, "java/lang/String");
+
      + +

      +Note that the SWIG preprocessor expands these into the appropriate C or C++ JNI calling convention. +The C calling convention is emitted by default and the C++ calling convention is emitted when using the -c++ SWIG commandline option. +If you do not intend your code to be targeting both C and C++ then your typemaps can use the appropriate JNI calling convention and need not use the JCALLx macros. +

      + + +

      21.9.9 Java code typemaps

      + + +

      +Most of SWIG's typemaps are used for the generation of C/C++ code. +The typemaps in this section are used solely for the generation of Java code. +Elements of proxy classes and type wrapper classes come from the following typemaps (the defaults). +

      + +

      %typemap(javabase)

      +
      +base (extends) for Java class: empty default +
      +Note that this typemap accepts a replace attribute as an optional flag. When set to "1", it will replace/override any C++ base classes +that might have been parsed. If this flag is not specified and there are C++ base classes, then a multiple inheritance warning +is issued and the code in the typemap is ignored. +The typemap also accepts a notderived attribute as an optional flag. When set to "1", it will not apply to classes that +are derived from a C++ base. +When used with the SWIGTYPE type, it is useful for giving a common base for all proxy classes, that is, providing a base class that sits in between all proxy classes and the Java base class Object for example: %typemap(javabase, notderived="1") SWIGTYPE "CommonBase". +
      + +

      %typemap(javabody)

      +
      + the essential support body for proxy classes (proxy base classes only), typewrapper classes and enum classes. + Default contains extra constructors, memory ownership control member variables (swigCMemOwn, swigCPtr), the getCPtr method etc. +
      + +

      %typemap(javabody_derived)

      +
      + the essential support body for proxy classes (derived classes only). + Same as "javabody" typemap, but only used for proxy derived classes. +
      + +

      %typemap(javaclassmodifiers)

      +
      +class modifiers for the Java class: default is "public class" +
      + +

      %typemap(javacode)

      +
      +Java code is copied verbatim to the Java class: empty default +
      + +

      %typemap(javadestruct, methodname="delete", methodmodifiers="public synchronized")

      +
      +destructor wrapper - the delete() method (proxy classes only), +used for all proxy classes except those which have a base class +: default calls C++ destructor (or frees C memory) and resets swigCPtr and swigCMemOwn flags +
      +
      +Note that the delete() method name is configurable and is specified by the methodname attribute. +The method modifiers are also configurable via the methodmodifiers attribute. +
      + +

      %typemap(javadestruct_derived, methodname="delete", methodmodifiers="public synchronized")

      +
      +destructor wrapper - the delete() method (proxy classes only), +same as "javadestruct" but only used for derived proxy classes +: default calls C++ destructor (or frees C memory) and resets swigCPtr and swigCMemOwn flags +
      +
      +Note that the delete() method name is configurable and is specified by the methodname attribute. +The method modifiers are also configurable via the methodmodifiers attribute. +
      + +

      %typemap(javaimports)

      +
      +import statements for Java class: empty default +
      + +

      %typemap(javainterfaces)

      +
      +interfaces (extends) for Java class: empty default +
      + +

      %typemap(javafinalize)

      +
      +the finalize() method (proxy classes only): default calls the delete() method +
      + +

      +Compatibility Note: In SWIG-1.3.21 and earlier releases, typemaps called "javagetcptr" and "javaptrconstructormodifiers" were available. +These are deprecated and the "javabody" typemap can be used instead. +

      + +

      +In summary the contents of the typemaps make up a proxy class like this: +

      + +
      +
      +[ javaimports typemap ]
+[ javaclassmodifiers typemap ] javaclassname extends [ javabase typemap ]
+                                             implements [ javainterfaces typemap ] {
+[ javabody or javabody_derived typemap ]
+[ javafinalize typemap ]
+public synchronized void delete() [ javadestruct OR javadestruct_derived typemap ]
+[ javacode typemap ]
+... proxy functions ...
+}
+
      +
      + +

      +Note the delete() methodname and method modifiers are configurable, see "javadestruct" and "javadestruct_derived" typemaps above. +

      + +

      +The type wrapper class is similar in construction: +

      + +
      +
      +[ javaimports typemap ]
+[ javaclassmodifiers typemap ] javaclassname extends [ javabase typemap ]
+                                             implements [ javainterfaces typemap ] {
+[ javabody typemap ]
+[ javacode typemap ]
+}
+
      +
      + +

      The enum class is also similar in construction:

      +
      +
      +[ javaimports typemap ]
+[ javaclassmodifiers typemap ] javaclassname extends [ javabase typemap ]
+                                             implements [ javainterfaces typemap ] {
+... Enum values ...
+[ javabody typemap ]
+[ javacode typemap ]
+}
+
      +
      + +

      +The "javaimports" typemap is ignored if the enum class is wrapped by an inner Java class, that is when wrapping an enum declared within a C++ class. +

      + +

      +The defaults can be overridden to tailor these classes. +Here is an example which will change the getCPtr method and constructor from the default protected access to public access. +This has a practical application if you are invoking SWIG more than once and generating the wrapped classes into different packages in each invocation. +If the classes in one package are using the classes in another package, then these methods need to be public. +

      + +
      +
      +%typemap(javabody) SWIGTYPE %{
+  private long swigCPtr;
+  protected boolean swigCMemOwn;
+
+  public $javaclassname(long cPtr, boolean cMemoryOwn) {
+    swigCMemOwn = cMemoryOwn;
+    swigCPtr = cPtr;
+  }
+
+  public static long getCPtr($javaclassname obj) {
+    return (obj == null) ? 0 : obj.swigCPtr;
+  }
+%}
+
      +
      + +

      +The typemap code is the same that is in "java.swg", barring the two method modifiers. +Note that SWIGTYPE will target all proxy classes, but not the type wrapper classes. +Also the above typemap is only used for proxy classes that are potential base classes. +To target proxy classes that are derived from a wrapped class as well, the "javabody_derived" typemap should also be overridden. +

      + +

      +For the typemap to be used in all type wrapper classes, all the different types that type wrapper classes could be used for should be targeted: +

      + +
      +
      +%typemap(javabody) SWIGTYPE *, SWIGTYPE &, SWIGTYPE [], SWIGTYPE (CLASS::*) %{
+  private long swigCPtr;
+
+  public $javaclassname(long cPtr, boolean bFutureUse) {
+    swigCPtr = cPtr;
+  }
+
+  protected $javaclassname() {
+    swigCPtr = 0;
+  }
+
+  public static long getCPtr($javaclassname obj) {
+    return (obj == null) ? 0 : obj.swigCPtr;
+  }
+%}
+
      +
      + +

      +Again this is the same that is in "java.swg", barring the method modifier for getCPtr. +

      + +

      21.9.10 Director specific typemaps

      + + +

      +The Java directors feature requires the "javadirectorin", "javadirectorout", "directorin" and the "directorout" typemaps in order to work properly. +The "javapackage" typemap is an optional typemap used to identify the Java package path for individual SWIG generated proxy classes. +

      + +

      %typemap(directorin)

      +
      + +

      +The "directorin" typemap is used for converting arguments in the C++ director class to the appropriate JNI type before the upcall to Java. +This typemap also specifies the JNI field descriptor for the type in the "descriptor" attribute. +For example, integers are converted as follows: +

      + +
      +
      +%typemap(directorin,descriptor="I") int "$input = (jint) $1;"
+
      +
      + +

      +$input is the SWIG name of the JNI temporary variable passed to Java in the upcall. +The descriptor="I" will put an I into the JNI field descriptor that identifies the Java method that will be called from C++. +For more about JNI field descriptors and their importance, refer to the JNI documentation mentioned earlier. +A typemap for C character strings is: +

      + +
      +
      +%typemap(directorin,descriptor="Ljava/lang/String;") char *
+  %{ $input = jenv->NewStringUTF($1); %}
+
      +
      + + +

      +User-defined types have the default "descriptor" attribute "L$packagepath/$javaclassname;" where $packagepath +is the package name passed from the SWIG command line and $javaclassname is the Java proxy class' name. +If the -package commandline option is not used to specify the package, then '$packagepath/' will be removed from the resulting output JNI field descriptor. +Do not forget the terminating ';' for JNI field descriptors starting with 'L'. +If the ';' is left out, Java will generate a "method not found" runtime error. +

      +
      + + +

      %typemap(directorout)

      +
      + +

      +The "directorout" typemap is used for converting the JNI return type in the C++ director class to the appropriate C++ type after the upcall to Java. +For example, integers are converted as follows: +

      + +
      +
      +%typemap(directorout) int %{ $result = (int)$input; %}
+
      +
      + +

      +$input is the SWIG name of the JNI temporary variable returned from Java after the upcall. +$result is the resulting output. +A typemap for C character strings is: +

      + +
      +
      +%typemap(directorout) char * {
+  $1 = 0;
+  if ($input) {
+    $result = (char *)jenv->GetStringUTFChars($input, 0);
+    if (!$1) return $null;
+  }
+}
+
      +
      + +
      + + +

      %typemap(javadirectorin)

      +
      + +

      +Conversion from jtype to jstype for director methods. +These are Java code typemaps which transform the type used in the Java intermediary JNI class (as specified in the "jtype" typemap) to +the Java type used in the Java module class, proxy classes and type wrapper classes (as specified in the "jstype" typemap). +This typemap provides the conversion for the parameters in the director methods when calling up from C++ to Java. +

      + +

      +For primitive types, this typemap is usually specified as: +

      + +
      +
      +%typemap(javadirectorin) int "$jniinput"
+
      +
      + +

      +The $jniinput special variable is analogous to $javainput special variable. +It is replaced by the input parameter name. +

      + +
      + + +

      %typemap(javadirectorout)

      +
      + +

      +Conversion from jstype to jtype for director methods. +These are Java code typemaps which transform the type used in the Java module class, proxy classes and type wrapper classes (as specified in the "jstype" typemap) +to the type used in the Java intermediary JNI class (as specified in the "jtype" typemap). +This typemap provides the conversion for the return type in the director methods when returning from the C++ to Java upcall. +

      + +

      +For primitive types, this typemap is usually specified as: +

      + +
      +
      +%typemap(javadirectorout) int "$javacall"
+
      +
      + +

      +The $javacall special variable is analogous to the $jnicall special variable. +It is replaced by the call to the target Java method. +The target method is the method in the Java proxy class which overrides the virtual C++ method in the C++ base class. +

      + +
      + +

      %typemap(javapackage)

      +
      + + +

      +The "javapackage" typemap is optional; it serves to identify a class's Java package. +This typemap should be used in conjunction with classes that are defined outside of the current SWIG interface file. +For example: +

      + +
      +
      +// class Foo is handled in a different interface file:
+%import "Foo.i"
+
+%feature("director") Example;
+
+%inline {
+  class Bar { };
+
+  class Example {
+  public:
+    virtual ~Example();
+    void     ping(Foo *arg1, Bar *arg2);
+  };
+}
+
      +
      + +

      +Assume that the Foo class is part of the Java package com.wombat.foo but the above interface file is part of the Java package com.wombat.example. +Without the "javapackage" typemap, SWIG will assume that the Foo class belongs to com.wombat.example class. +The corrected interface file looks like: +

      + +
      +
      +// class Foo is handled in a different interface file:
+%import "Foo.i"
+%typemap("javapackage") Foo, Foo *, Foo & "com.wombat.foo";
+%feature("director") Example;
+
+%inline {
+  class Bar { };
+
+  class Example {
+  public:
+    virtual ~Example();
+    void     ping(Foo *arg1, Bar *arg2);
+  };
+}
+
      +
      + +

      +SWIG looks up the package based on the actual type (plain Foo, Foo pointer and Foo reference), so it is important to associate all three types with the desired package. +Practically speaking, you should create a separate SWIG interface file, which is %import-ed into each SWIG interface file, when you have multiple Java packages. +Note the helper macros below, OTHER_PACKAGE_SPEC and ANOTHER_PACKAGE_SPEC, which reduce the amount of extra typing. +"TYPE..." is useful when passing templated types to the macro, since multiargument template types appear to the SWIG preprocessor as multiple macro arguments. +

      + +
      +
      +%typemap("javapackage") SWIGTYPE, SWIGTYPE *, SWIGTYPE &
+                                            "package.for.most.classes";
+
+%define OTHER_PACKAGE_SPEC(TYPE...)
+%typemap("javapackage") TYPE, TYPE *, TYPE & "package.for.other.classes";
+%enddef
+
+%define ANOTHER_PACKAGE_SPEC(TYPE...)
+%typemap("javapackage") TYPE, TYPE *, TYPE & "package.for.another.set";
+%enddef
+
+OTHER_PACKAGE_SPEC(Package_2_class_one)
+ANOTHER_PACKAGE_SPEC(Package_3_class_two)
+/* etc */
+
      +
      + +

      +The basic strategy here is to provide a default package typemap for the majority of the classes, only providing "javapackage" typemaps for the exceptions. +

      + +
      + +

      21.10 Typemap Examples

      + + +

      +This section includes a few examples of typemaps. For more examples, you +might look at the files "java.swg" and "typemaps.i" in +the SWIG library. +

      + + +

      21.10.1 Simpler Java enums for enums without initializers

      + + +

      +The default Proper Java enums approach to wrapping enums is somewhat verbose. +This is to handle all possible C/C++ enums, in particular enums with initializers. +The generated code can be simplified if the enum being wrapped does not have any initializers. +

      + +

      +The following shows how to remove the support methods that are generated by default and instead use the methods in the Java +enum base class java.lang.Enum and java.lang.Class for marshalling enums between C/C++ and Java. +The type used for the typemaps below is enum SWIGTYPE which is the default type used for all enums. +The "enums.swg" file should be examined in order to see the original overridden versions of the typemaps. +

      + +
      +
      +%include "enums.swg"
+
+%typemap(javain) enum SWIGTYPE "$javainput.ordinal()"
+%typemap(javaout) enum SWIGTYPE {
+    return $javaclassname.class.getEnumConstants()[$jnicall];
+  }
+%typemap(javabody) enum SWIGTYPE ""
+
+%inline %{
+  enum HairType { blonde, ginger, brunette };
+  void setHair(HairType h);
+  HairType getHair();
+%}
+
      +
      + +

      +SWIG will generate the following Java enum, which is somewhat simpler than the default: +

      + +
      +
      +public enum HairType {
+  blonde,
+  ginger,
+  brunette;
+}
+
      +
      + +

      +and the two Java proxy methods will be: +

      + +
      +
      +public static void setHair(HairType h) {
+  exampleJNI.setHair(h.ordinal());
+}
+
+public static HairType getHair() {
+  return HairType.class.getEnumConstants()[exampleJNI.getHair()];
+}
+
      +
      + +

      +For marshalling Java enums to C/C++ enums, the ordinal method is used to convert the +Java enum into an integer value for passing to the JNI layer, see the "javain" typemap. +For marshalling C/C++ enums to Java enums, the C/C++ enum value is cast to an integer in the C/C++ typemaps (not shown). +This integer value is then used to index into the array of enum constants that the Java language provides. +See the getEnumConstants method in the "javaout" typemap. +

      + +

      +These typemaps can often be used as the default for wrapping enums as in many cases there won't be any enum initializers. +In fact a good strategy is to always use these typemaps and to specifically handle enums with initializers using %apply. +This would be done by using the original versions of these typemaps in "enums.swg" under another typemap name for applying using %apply. +

      + + +

      21.10.2 Handling C++ exception specifications as Java exceptions

      + + +

      +This example demonstrates various ways in which C++ exceptions can be tailored and converted into Java exceptions. +Let's consider a simple file class SimpleFile and an exception class FileException which it may throw on error: +

      + +
      +
      +%include "std_string.i" // for std::string typemaps
+#include <string>
+
+class FileException {
+  std::string message;
+public:
+  FileException(const std::string& msg) : message(msg) {}
+  std::string what() {
+    return message;
+  }
+};
+
+class SimpleFile {
+  std::string filename;
+public:
+  SimpleFile(const std::string& filename) : filename(filename) {}
+  void open() throw(FileException) {
+  ...
+  }
+};
+
      +
      + +

      +As the open method has a C++ exception specification, SWIG will parse this and know that the method can throw an exception. +The "throws" typemap is then used when SWIG encounters an exception specification. +The default generic "throws" typemap looks like this: +

      + +
      +
      +%typemap(throws) SWIGTYPE, SWIGTYPE &, SWIGTYPE *, SWIGTYPE [ANY] %{
+  SWIG_JavaThrowException(jenv, SWIG_JavaRuntimeException,
+                          "C++ $1_type exception thrown");
+  return $null;
+%}
+
      +
      + +

      +Basically SWIG will generate a C++ try catch block and the body of the "throws" typemap constitutes the catch block. +The above typemap calls a SWIG supplied method which throws a java.lang.RuntimeException. +This exception class is a runtime exception and therefore not a checked exception. +If, however, we wanted to throw a checked exception, say java.io.IOException, then we could use the following typemap: +

      + +
      +
      +%typemap(throws, throws="java.io.IOException") FileException {
+  jclass excep = jenv->FindClass("java/io/IOException");
+  if (excep)
+    jenv->ThrowNew(excep, $1.what().c_str());
+  return $null;
+}
+
      +
      + +

      +Note that this typemap uses the 'throws' typemap attribute to ensure a throws clause is generated. +The generated proxy method then specifies the checked exception by containing java.io.IOException in the throws clause: +

      + +
      +
      +public class SimpleFile {
+  ...
+  public void open() throws java.io.IOException { ... }
+}
+
      +
      + +

      +Lastly, if you don't want to map your C++ exception into one of the standard Java exceptions, the C++ class can be wrapped and turned into a custom Java exception class. +If we go back to our example, the first thing we must do is get SWIG to wrap FileException and ensure that it derives from java.lang.Exception. +Additionally, we might want to override the java.lang.Exception.getMessage() method. +The typemaps to use then are as follows: +

      + +
      +
      +%typemap(javabase) FileException "java.lang.Exception";
+%typemap(javacode) FileException %{
+  public String getMessage() {
+    return what();
+  }
+%}
+
      +
      + +

      +This generates: +

      + +
      +
      +public class FileException extends java.lang.Exception {
+  ...
+  public String getMessage() {
+    return what();
+  }
+
+  public FileException(String msg) { ... }
+
+  public String what() {
+    return exampleJNI.FileException_what(swigCPtr, this);
+  }
+}
+
      +
      + +

      +We could alternatively have used %rename to rename what() into getMessage(). +

      + + +

      21.10.3 NaN Exception - exception handling for a particular type

      + + +

      +A Java exception can be thrown from any Java or JNI code. +Therefore, as most typemaps contain either Java or JNI code, just about any typemap could throw an exception. +The following example demonstrates exception handling on a type by type basis by checking for 'Not a number' (NaN) whenever a parameter of type float is wrapped. +

      + +

      +Consider the following C++ code: +

      + +
      +
      +bool calculate(float first, float second);
+
      +
      + +

      +To validate every float being passed to C++, we could precede the code being wrapped by the following typemap which throws a runtime exception whenever the float is 'Not a Number': +

      + +
      +
      +%module example
+%typemap(javain) float "$module.CheckForNaN($javainput)"
+%pragma(java) modulecode=%{
+  /** Simply returns the input value unless it is not a number,
+      whereupon an exception is thrown. */
+  static protected float CheckForNaN(float num) {
+    if (Float.isNaN(num))
+      throw new RuntimeException("Not a number");
+    return num;
+  }
+%}
+
      +
      + +

      +Note that the CheckForNaN support method has been added to the module class using the modulecode pragma. +The following shows the generated code of interest: +

      + +
      +
      +public class example {
+  ...
+
+  /** Simply returns the input value unless it is not a number,
+      whereupon an exception is thrown. */
+  static protected float CheckForNaN(float num) {
+    if (Float.isNaN(num))
+      throw new RuntimeException("Not a number");
+    return num;
+  }
+
+  public static boolean calculate(float first, float second) {
+    return exampleJNI.calculate(example.CheckForNaN(first), example.CheckForNaN(second));
+  }
+}
+
      +
      + +

      +Note that the "javain" typemap is used for every occurrence of a float being used as an input. +Of course, we could have targeted the typemap at a particular parameter by using float first, say, instead of just float. +

      + +

      +The exception checking could alternatively have been placed into the 'pre' attribute that the "javain" typemap supports. +The "javain" typemap above could be replaced with the following: +

      + +
      +
      +%typemap(javain, pre="    $module.CheckForNaN($javainput);") float "$javainput"
+
      +
      + +

      +which would modify the calculate function to instead be generated as: +

      + +
      +
      +public class example {
+  ...
+  public static boolean calculate(float first, float second) {
+    example.CheckForNaN(first);
+    example.CheckForNaN(second);
+    {
+      return exampleJNI.calculate(first, second);
+    }
+  }
+}
+
      +
      + +

      +See the Date marshalling example for an example using further "javain" typemap attributes. +

      + +

      +If we decide that what we actually want is a checked exception instead of a runtime exception, we can change this easily enough. +The proxy method that uses float as an input, must then add the exception class to the throws clause. +SWIG can handle this as it supports the 'throws' typemap attribute for specifying classes for the throws clause. +Thus we can modify the pragma and the typemap for the throws clause: +

      + +
      +
      +%typemap(javain, throws="java.lang.Exception") float "$module.CheckForNaN($javainput)"
+%pragma(java) modulecode=%{
+  /** Simply returns the input value unless it is not a number,
+      whereupon an exception is thrown. */
+  static protected float CheckForNaN(float num) throws java.lang.Exception {
+    if (Float.isNaN(num))
+      throw new RuntimeException("Not a number");
+    return num;
+  }
+%}
+
      +
      + +

      +The calculate method now has a throws clause and even though the typemap is used twice for both float first and float second, +the throws clause contains a single instance of java.lang.Exception: +

      + +
      +
      +public class example {
+  ...
+
+  /** Simply returns the input value unless it is not a number,
+      whereupon an exception is thrown. */
+  static protected float CheckForNaN(float num) throws java.lang.Exception {
+    if (Float.isNaN(num))
+      throw new RuntimeException("Not a number");
+    return num;
+  }
+
+  public static boolean calculate(float first, float second) throws java.lang.Exception {
+    return exampleJNI.calculate(example.CheckForNaN(first), example.CheckForNaN(second));
+  }
+}
+
      +
      + +

      +If we were a martyr to the JNI cause, we could replace the succinct code within the "javain" typemap with a few pages of JNI code. +If we had, we would have put it in the "in" typemap which, like all JNI and Java typemaps, also supports the 'throws' attribute. +

      + +

      21.10.4 Converting Java String arrays to char **

      + + +

      +A common problem in many C programs is the processing of command line arguments, which are usually passed in an array of NULL terminated strings. +The following SWIG interface file allows a Java String array to be used as a char ** object. +

      + +
      +%module example
+
+/* This tells SWIG to treat char ** as a special case when used as a parameter
+   in a function call */
+%typemap(in) char ** (jint size) {
+    int i = 0;
+    size = (*jenv)->GetArrayLength(jenv, $input);
+    $1 = (char **) malloc((size+1)*sizeof(char *));
+    /* make a copy of each string */
+    for (i = 0; i<size; i++) {
+        jstring j_string = (jstring)(*jenv)->GetObjectArrayElement(jenv, $input, i);
+        const char * c_string = (*jenv)->GetStringUTFChars(jenv, j_string, 0);
+        $1[i] = malloc((strlen(c_string)+1)*sizeof(char));
+        strcpy($1[i], c_string);
+        (*jenv)->ReleaseStringUTFChars(jenv, j_string, c_string);
+        (*jenv)->DeleteLocalRef(jenv, j_string);
+    }
+    $1[i] = 0;
+}
+
+/* This cleans up the memory we malloc'd before the function call */
+%typemap(freearg) char ** {
+    int i;
+    for (i=0; i<size$argnum-1; i++)
+      free($1[i]);
+    free($1);
+}
+
+/* This allows a C function to return a char ** as a Java String array */
+%typemap(out) char ** {
+    int i;
+    int len=0;
+    jstring temp_string;
+    const jclass clazz = (*jenv)->FindClass(jenv, "java/lang/String");
+
+    while ($1[len]) len++;    
+    jresult = (*jenv)->NewObjectArray(jenv, len, clazz, NULL);
+    /* exception checking omitted */
+
+    for (i=0; i<len; i++) {
+      temp_string = (*jenv)->NewStringUTF(jenv, *result++);
+      (*jenv)->SetObjectArrayElement(jenv, jresult, i, temp_string);
+      (*jenv)->DeleteLocalRef(jenv, temp_string);
+    }
+}
+
+/* These 3 typemaps tell SWIG what JNI and Java types to use */
+%typemap(jni) char ** "jobjectArray"
+%typemap(jtype) char ** "String[]"
+%typemap(jstype) char ** "String[]"
+
+/* These 2 typemaps handle the conversion of the jtype to jstype typemap type
+   and vice versa */
+%typemap(javain) char ** "$javainput"
+%typemap(javaout) char ** {
+    return $jnicall;
+  }
+
+/* Now a few test functions */
+%inline %{
+
+int print_args(char **argv) {
+    int i = 0;
+    while (argv[i]) {
+         printf("argv[%d] = %s\n", i, argv[i]);
+         i++;
+    }
+    return i;
+}
+
+char **get_args() {
+  static char *values[] = { "Dave", "Mike", "Susan", "John", "Michelle", 0};
+  return &values[0];
+}
+
+%}
+
      + +

      +Note that the 'C' JNI calling convention is used. +Checking for any thrown exceptions after JNI function calls has been omitted. +When this module is compiled, our wrapped C functions can be used by the following Java program: +

      + +
      +// File runme.java
+
+public class runme {
+
+  static {
+    try {
+     System.loadLibrary("example");
+    } catch (UnsatisfiedLinkError e) {
+      System.err.println("Native code library failed to load. " + e);
+      System.exit(1);
+    }
+  }
+
+  public static void main(String argv[]) {
+    String animals[] = {"Cat","Dog","Cow","Goat"};
+    example.print_args(animals);
+    String args[] = example.get_args();
+    for (int i=0; i<args.length; i++)
+        System.out.println(i + ":" + args[i]);
+  }
+}
+
      + +

      +When compiled and run we get: +

      + +
      +$ java runme
+argv[0] = Cat
+argv[1] = Dog
+argv[2] = Cow
+argv[3] = Goat
+0:Dave
+1:Mike
+2:Susan
+3:John
+4:Michelle
+
      + +

      +In the example, a few different typemaps are used. The "in" typemap is +used to receive an input argument and convert it to a C array. Since dynamic +memory allocation is used to allocate memory for the array, the +"freearg" typemap is used to later release this memory after the execution of +the C function. The "out" typemap is used for function return values. +Lastly the "jni", "jtype" and "jstype" typemaps are also required to specify +what Java types to use. +

      + +

      21.10.5 Expanding a Java object to multiple arguments

      + + +

      +Suppose that you had a collection of C functions with arguments +such as the following: +

      + +
      +
      +int foo(int argc, char **argv);
+
      +
      + +

      +In the previous example, a typemap was written to pass a Java String array as the char **argv. This +allows the function to be used from Java as follows: +

      + +
      +
      +example.foo(4, new String[]{"red", "green", "blue", "white"});
+
      +
      + +

      +Although this works, it's a little awkward to specify the argument count. To fix this, a multi-argument +typemap can be defined. This is not very difficult--you only have to make slight modifications to the +previous example's typemaps: +

      + +
      +
      +%typemap(in) (int argc, char **argv) {
+    int i = 0;
+    $1 = (*jenv)->GetArrayLength(jenv, $input);
+    $2 = (char **) malloc(($1+1)*sizeof(char *));
+    /* make a copy of each string */
+    for (i = 0; i<$1; i++) {
+        jstring j_string = (jstring)(*jenv)->GetObjectArrayElement(jenv, $input, i);
+        const char * c_string = (*jenv)->GetStringUTFChars(jenv, j_string, 0);
+        $2[i] = malloc((strlen(c_string)+1)*sizeof(char));
+        strcpy($2[i], c_string);
+        (*jenv)->ReleaseStringUTFChars(jenv, j_string, c_string);
+        (*jenv)->DeleteLocalRef(jenv, j_string);
+    }
+    $2[i] = 0;
+}
+
+%typemap(freearg) (int argc, char **argv) {
+    int i;
+    for (i=0; i<$1-1; i++)
+      free($2[i]);
+    free($2);
+}
+
+%typemap(jni) (int argc, char **argv) "jobjectArray"
+%typemap(jtype) (int argc, char **argv) "String[]"
+%typemap(jstype) (int argc, char **argv) "String[]"
+
+%typemap(javain) (int argc, char **argv) "$javainput"
+
      +
      + +

      +When writing a multiple-argument typemap, each of the types is referenced by a variable such +as $1 or $2. The typemap code simply fills in the appropriate values from +the supplied Java parameter. +

      + +

      +With the above typemap in place, you will find it no longer necessary +to supply the argument count. This is automatically set by the typemap code. For example: +

      + +
      +
      +example.foo(new String[]{"red", "green", "blue", "white"});
+
      +
      + + +

      21.10.6 Using typemaps to return arguments

      + + +

      +A common problem in some C programs is that values may be returned in function parameters rather than in the return value of a function. +The typemaps.i file defines INPUT, OUTPUT and INOUT typemaps which can be used to solve some instances of this problem. +This library file uses an array as a means of moving data to and from Java when wrapping a C function that takes non const pointers or non const references as parameters. +

      + +

      +Now we are going to outline an alternative approach to using arrays for C pointers. +The INOUT typemap uses a double[] array for receiving and returning the double* parameters. +In this approach we are able to use a Java class myDouble instead of double[] arrays where the C pointer double* is required. +

      + +

      +Here is our example function: +

      + +
      +/* Returns a status value and two values in out1 and out2 */
+int spam(double a, double b, double *out1, double *out2);
+
      + +

      +If we define a structure MyDouble containing a double member variable and use some typemaps we can solve this problem. For example we could put the following through SWIG: +

      + +
      +%module example
+
+/* Define a new structure to use instead of double * */
+%inline %{
+typedef struct {
+    double value;
+} MyDouble;
+%}
+
+
+%{
+/* Returns a status value and two values in out1 and out2 */
+int spam(double a, double b, double *out1, double *out2) {
+  int status = 1;
+  *out1 = a*10.0;
+  *out2 = b*100.0;
+  return status;
+};
+%}
+
+/* 
+This typemap will make any double * function parameters with name OUTVALUE take an
+argument of MyDouble instead of double *. This will 
+allow the calling function to read the double * value after returning from the function.
+*/
+%typemap(in) double *OUTVALUE {
+    jclass clazz = jenv->FindClass("MyDouble");
+    jfieldID fid = jenv->GetFieldID(clazz, "swigCPtr", "J");
+    jlong cPtr = jenv->GetLongField($input, fid);
+    MyDouble *pMyDouble = NULL;
+    *(MyDouble **)&pMyDouble = *(MyDouble **)&cPtr;
+    $1 = &pMyDouble->value;
+}
+
+%typemap(jtype) double *OUTVALUE "MyDouble"
+%typemap(jstype) double *OUTVALUE "MyDouble"
+%typemap(jni) double *OUTVALUE "jobject"
+
+%typemap(javain) double *OUTVALUE "$javainput"
+
+/* Now we apply the typemap to the named variables */
+%apply double *OUTVALUE { double *out1, double *out2 };
+int spam(double a, double b, double *out1, double *out2);
+
      + +

      +Note that the C++ JNI calling convention has been used this time and so must be compiled as C++ and the -c++ commandline must be passed to SWIG. +JNI error checking has been omitted for clarity. +

      + +

      +What the typemaps do are make the named double* function parameters use our new MyDouble wrapper structure. +The "in" typemap takes this structure, gets the C++ pointer to it, takes the double value member variable and passes it to the C++ spam function. +In Java, when the function returns, we use the SWIG created getValue() function to get the output value. +The following Java program demonstrates this: +

      + +
      +// File: runme.java
+
+public class runme {
+
+  static {
+    try {
+      System.loadLibrary("example");
+    } catch (UnsatisfiedLinkError e) {
+      System.err.println("Native code library failed to load. " + e);
+      System.exit(1);
+    }
+  }
+
+  public static void main(String argv[]) {
+    MyDouble out1 = new MyDouble();
+    MyDouble out2 = new MyDouble();
+    int ret = example.spam(1.2, 3.4, out1, out2);
+    System.out.println(ret + "  " + out1.getValue() + "  " + out2.getValue());
+  }
+}
+
      + +

      +When compiled and run we get: +

      + +
      +$ java runme
+1 12.0  340.0
+
      + +

      21.10.7 Adding Java downcasts to polymorphic return types

      + + +

      +SWIG support for polymorphism works in that the appropriate virtual function is called. However, the default generated code does not allow for downcasting. +Let's examine this with the following code: +

      + +
      +%include "std_string.i"
+
+#include <iostream>
+using namespace std;
+class Vehicle {
+public:
+    virtual void start() = 0;
+...
+};
+
+class Ambulance : public Vehicle {
+    string vol;
+public:
+    Ambulance(string volume) : vol(volume) {}
+    virtual void start() {
+        cout << "Ambulance started" << endl;
+    }
+    void sound_siren() {
+        cout << vol << " siren sounded!" << endl;
+    }
+...
+};
+
+Vehicle *vehicle_factory() {
+    return new Ambulance("Very loud");
+}
+
      + +

      +If we execute the following Java code: +

      + +
      +Vehicle vehicle = example.vehicle_factory();
+vehicle.start();
+
+Ambulance ambulance = (Ambulance)vehicle;
+ambulance.sound_siren();
+
      + +

      +We get: +

      + +
      +Ambulance started
+java.lang.ClassCastException
+        at runme.main(runme.java:16)
+
      + +

      +Even though we know from examination of the C++ code that vehicle_factory returns an object of type Ambulance, +we are not able to use this knowledge to perform the downcast in Java. +This occurs because the runtime type information is not completely passed from C++ to Java when returning the type from vehicle_factory(). +Usually this is not a problem as virtual functions do work by default, such as in the case of start(). +There are a few solutions to getting downcasts to work. +

      + +

      +The first is not to use a Java cast but a call to C++ to make the cast. Add this to your code: +

      + +
      +%exception Ambulance::dynamic_cast(Vehicle *vehicle) {
+    $action
+    if (!result) {
+        jclass excep = jenv->FindClass("java/lang/ClassCastException");
+        if (excep) {
+            jenv->ThrowNew(excep, "dynamic_cast exception");
+        }
+    }
+}
+%extend Ambulance {
+    static Ambulance *dynamic_cast(Vehicle *vehicle) {
+        return dynamic_cast<Ambulance *>(vehicle);
+    }
+};
+
      + +

      +It would then be used from Java like this +

      + +
      +Ambulance ambulance = Ambulance.dynamic_cast(vehicle);
+ambulance.sound_siren();
+
      + +

      +Should vehicle not be of type ambulance then a Java ClassCastException is thrown. +The next solution is a purer solution in that Java downcasts can be performed on the types. +Add the following before the definition of vehicle_factory: +

      + +
      +%typemap(out) Vehicle * {
+    Ambulance *downcast = dynamic_cast<Ambulance *>($1);
+    *(Ambulance **)&$result = downcast;
+}
+
+%typemap(javaout) Vehicle * {
+    return new Ambulance($jnicall, $owner);
+  }
+
      + +

      +Here we are using our knowledge that vehicle_factory always returns type Ambulance so that the Java proxy is created as a type Ambulance. +If vehicle_factory can manufacture any type of Vehicle and we want to be able to downcast using Java casts for any of these types, then a different approach is needed. +Consider expanding our example with a new Vehicle type and a more flexible factory function: +

      + +
      +class FireEngine : public Vehicle {
+public:
+    FireEngine() {}
+    virtual void start() {
+        cout << "FireEngine started" << endl;
+    }
+    void roll_out_hose() {
+        cout << "Hose rolled out" << endl;
+    }
+ ...
+};
+Vehicle *vehicle_factory(int vehicle_number) {
+    if (vehicle_number == 0)
+        return new Ambulance("Very loud");
+    else
+        return new FireEngine();
+}
+
      + +

      +To be able to downcast with this sort of Java code: +

      + +
      +FireEngine fireengine = (FireEngine)example.vehicle_factory(1);
+fireengine.roll_out_hose();
+Ambulance ambulance = (Ambulance)example.vehicle_factory(0);
+ambulance.sound_siren();
+
      + +

      +the following typemaps targeted at the vehicle_factory function will achieve this. +Note that in this case, the Java class is constructed using JNI code rather than passing a pointer across the JNI boundary in a Java long for construction in Java code. +

      + +
      +%typemap(jni) Vehicle *vehicle_factory "jobject"
+%typemap(jtype) Vehicle *vehicle_factory "Vehicle"
+%typemap(jstype) Vehicle *vehicle_factory "Vehicle"
+%typemap(javaout) Vehicle *vehicle_factory {
+    return $jnicall;
+  }
+
+%typemap(out) Vehicle *vehicle_factory {
+    Ambulance *ambulance = dynamic_cast<Ambulance *>($1);
+    FireEngine *fireengine = dynamic_cast<FireEngine *>($1);
+    if (ambulance) {
+        // call the Ambulance(long cPtr, boolean cMemoryOwn) constructor
+        jclass clazz = jenv->FindClass("Ambulance");
+        if (clazz) {
+            jmethodID mid = jenv->GetMethodID(clazz, "<init>", "(JZ)V");
+            if (mid) {
+                jlong cptr = 0;
+                *(Ambulance **)&cptr = ambulance; 
+                $result = jenv->NewObject(clazz, mid, cptr, false);
+            }
+        }
+    } else if (fireengine) {
+        // call the FireEngine(long cPtr, boolean cMemoryOwn) constructor
+        jclass clazz = jenv->FindClass("FireEngine");
+        if (clazz) {
+            jmethodID mid = jenv->GetMethodID(clazz, "<init>", "(JZ)V");
+            if (mid) {
+                jlong cptr = 0;
+                *(FireEngine **)&cptr = fireengine; 
+                $result = jenv->NewObject(clazz, mid, cptr, false);
+            }
+        }
+    }
+    else {
+        cout << "Unexpected type " << endl;
+    }
+
+    if (!$result)
+        cout << "Failed to create new java object" << endl;
+}
+
      + +

      +Better error handling would need to be added into this code. +There are other solutions to this problem, but this last example demonstrates some more involved JNI code. +SWIG usually generates code which constructs the proxy classes using Java code as it is easier to handle error conditions and is faster. +Note that the JNI code above uses a number of string lookups to call a constructor, whereas this would not occur using byte compiled Java code. +

      + +

      21.10.8 Adding an equals method to the Java classes

      + + +

      +When a pointer is returned from a JNI function, it is wrapped using a new Java proxy class or type wrapper class. +Even when the pointers are the same, it will not be possible to know that the two Java classes containing those pointers are actually the same object. +It is common in Java to use the equals() method to check whether two objects are equivalent. +The equals() method is usually accompanied by a hashCode() method in order to fulfill +the requirement that the hash code is equal for equal objects. +Pure Java code methods like these can be easily added: +

      + +
      +
      +%typemap(javacode) SWIGTYPE %{
+  public boolean equals(Object obj) {
+    boolean equal = false;
+    if (obj instanceof $javaclassname)
+      equal = ((($javaclassname)obj).swigCPtr == this.swigCPtr);
+    return equal;
+  }
+  public int hashCode() {
+     return (int)getPointer();
+  }
+%}
+
+class Foo { };
+Foo* returnFoo(Foo *foo) { return foo; }
+
      +
      + +

      +The following would display false without the javacode typemap above. With the typemap defining the equals method the result is true. +

      + +
      +
      +Foo foo1 = new Foo();
+Foo foo2 = example.returnFoo(foo1);
+System.out.println("foo1? " + foo1.equals(foo2));
+
      +
      + + +

      21.10.9 Void pointers and a common Java base class

      + + +

      +One might wonder why the common code that SWIG emits for the proxy and type wrapper classes is not pushed into a base class. +The reason is that although swigCPtr could be put into a common base class for all classes +wrapping C structures, it would not work for C++ classes involved in an inheritance chain. +Each class derived from a base needs a separate swigCPtr because C++ compilers sometimes use a different pointer value when casting a derived class to a base. +Additionally as Java only supports single inheritance, it would not be possible to derive wrapped classes from your own pure Java classes if the base class has been 'used up' by SWIG. +However, you may want to move some of the common code into a base class. +Here is an example which uses a common base class for all proxy classes and type wrapper classes: +

      + +
      +
      +%typemap(javabase) SWIGTYPE, SWIGTYPE *, SWIGTYPE &, SWIGTYPE [], 
+                                                         SWIGTYPE (CLASS::*) "SWIG"
+
+%typemap(javacode) SWIGTYPE, SWIGTYPE *, SWIGTYPE &, SWIGTYPE [], 
+                                                         SWIGTYPE (CLASS::*) %{
+  protected long getPointer() {
+    return swigCPtr;
+  }
+%}
+
      +
      + +

      +Define new base class called SWIG: +

      + +
      +
      +public abstract class SWIG {
+  protected abstract long getPointer();
+
+  public boolean equals(Object obj) {
+    boolean equal = false;
+    if (obj instanceof SWIG)
+      equal = (((SWIG)obj).getPointer() == this.getPointer());
+    return equal;
+  }
+  
+  SWIGTYPE_p_void getVoidPointer() {
+    return new SWIGTYPE_p_void(getPointer(), false);
+  }
+}
+
      +
      + +

      +This example contains some useful functionality which you may want in your code. +

      + +
        +
      • It has an equals() method. Unlike the previous example, the method code isn't replicated in all classes. +
      • It also has a function which effectively implements a cast from the type of the proxy/type wrapper class to a void pointer. This is necessary for passing a proxy class or a type wrapper class to a function that takes a void pointer. +
      + +

      21.10.10 Struct pointer to pointer

      + + +

      +Pointers to pointers are often used as output parameters in C factory type functions. +These are a bit more tricky to handle. +Consider the following situation where a Butler can be hired and fired: +

      + +
      +
      +typedef struct {
+  int hoursAvailable;
+  char *greeting;
+} Butler;
+
+// Note: HireButler will allocate the memory 
+// The caller must free the memory by calling FireButler()!!
+extern int HireButler(Butler **ppButler);
+extern void FireButler(Butler *pButler);
+
      +
      + +

      +C code implementation: +

      + +
      +
      +int HireButler(Butler **ppButler) {
+  Butler *pButler = (Butler *)malloc(sizeof(Butler));
+  pButler->hoursAvailable = 24;
+  pButler->greeting = (char *)malloc(32);
+  strcpy(pButler->greeting, "At your service Sir");
+  *ppButler = pButler;
+  return 1;
+}
+void FireButler(Butler *pButler) {
+  free(pButler->greeting);
+  free(pButler);
+}
+
      +
      + +

      +Let's take two approaches to wrapping this code. +The first is to provide a functional interface, much like the original C interface. +The following Java code shows how we intend the code to be used: +

      + +
      +
      +    Butler jeeves = new Butler();
+    example.HireButler(jeeves);
+    System.out.println("Greeting:     " + jeeves.getGreeting());
+    System.out.println("Availability: " + jeeves.getHoursAvailable() + " hours per day");
+    example.FireButler(jeeves);
+
      +
      + +

      +Resulting in the following output when run: +

      + +
      +
      +Greeting:     At your service Sir
+Availability: 24 hours per day
+
      +
      + +

      +Note the usage is very much like it would be used if we were writing C code, that is, explicit memory management is needed. +No C memory is allocated in the construction of the Butler proxy class and +the proxy class will not destroy the underlying C memory when it is collected. +A number of typemaps and features are needed to implement this approach. +The following interface file code should be placed before SWIG parses the above C code. +

      + +
      +
      +%module example
+
+// Do not generate the default proxy constructor or destructor
+%nodefaultctor Butler;
+%nodefaultdtor Butler;
+
+// Add in pure Java code proxy constructor
+%typemap(javacode) Butler %{
+  /** This constructor creates the proxy which initially does not create nor own any C memory */
+  public Butler() {
+    this(0, false);
+  }
+%}
+
+// Type typemaps for marshalling Butler **
+%typemap(jni) Butler ** "jobject"
+%typemap(jtype) Butler ** "Butler"
+%typemap(jstype) Butler ** "Butler"
+
+// Typemaps for Butler ** as a parameter output type
+%typemap(in) Butler ** (Butler *ppButler = 0) %{
+  $1 = &ppButler;
+%}
+%typemap(argout) Butler ** {
+  // Give Java proxy the C pointer (of newly created object)
+  jclass clazz = (*jenv)->FindClass(jenv, "Butler");
+  jfieldID fid = (*jenv)->GetFieldID(jenv, clazz, "swigCPtr", "J");
+  jlong cPtr = 0;
+  *(Butler **)&cPtr = *$1;
+  (*jenv)->SetLongField(jenv, $input, fid, cPtr);
+}
+%typemap(javain) Butler ** "$javainput"
+
      +
      + +

      +Note that the JNI code sets the proxy's swigCPtr member variable to point to the newly created object. +The swigCMemOwn remains unchanged (at false), so that the proxy does not own the memory. +

      + +

      +Note: The old %nodefault directive disabled the default constructor +and destructor at the same time. This is unsafe in most of the cases, +and you can use the explicit %nodefaultctor and %nodefaultdtor +directives to achieve the same result if needed. +

      + +

      +The second approach offers a more object oriented interface to the Java user. +We do this by making the Java proxy class's +constructor call the HireButler() method to create the underlying C object. +Additionally we get the proxy to take ownership of the memory so that the +finalizer will call the FireButler() function. +The proxy class will thus take ownership of the memory and clean it up when no longer needed. +We will also prevent the user from being able to explicitly call the HireButler() and FireButler() functions. +Usage from Java will simply be: +

      + +
      +
      +Butler jeeves = new Butler();
+System.out.println("Greeting:     " + jeeves.getGreeting());
+System.out.println("Availability: " + jeeves.getHoursAvailable() + " hours per day");
+
      +
      + +

      +Note that the Butler class is used just like any other Java class and no extra coding by the user needs to be written to +clear up the underlying C memory as the finalizer will be called by the garbage collector which in turn will call the FireButler() function. +To implement this, we use the above interface file code but remove the javacode typemap and add the following: +

      + +
      +
      +// Don't expose the memory allocation/de-allocation functions
+%ignore FireButler(Butler *pButler);
+%ignore HireButler(Butler **ppButler);
+
+// Add in a custom proxy constructor and destructor
+%extend Butler {
+  Butler() {
+    Butler *pButler = 0;
+    HireButler(&pButler);
+    return pButler;
+  }
+  ~Butler() {
+     FireButler($self);
+   }
+}
+
      +
      + +

      +Note that the code in %extend is using a C++ type constructor and destructor, yet the generated code will still compile as C code, +see Adding member functions to C structures. +The C functional interface has been completely morphed into an object-oriented interface and +the Butler class would behave much like any pure Java class and feel more natural to Java users. +

      + +

      21.10.11 Memory management when returning references to member variables

      + + +

      +This example shows how to prevent premature garbage collection of objects when the underlying C++ class returns a pointer or reference to a member variable. +

      + +

      +Consider the following C++ code: +

      + +
      +
      +struct Wheel {
+  int size;
+  Wheel(int sz) : size(sz) {}
+};
+
+class Bike {
+  Wheel wheel;
+public:
+  Bike(int val) : wheel(val) {}
+  Wheel& getWheel() { return wheel; }
+};
+
      +
      + +

      +and the following usage from Java after running the code through SWIG: +

      + + +
      +
      +    Wheel wheel = new Bike(10).getWheel();
+    System.out.println("wheel size: " + wheel.getSize());
+    // Simulate a garbage collection
+    System.gc();
+    System.runFinalization();
+    System.out.println("wheel size: " + wheel.getSize());
+
      +
      + +

      +Don't be surprised that if the resulting output gives strange results such as... +

      + +
      +
      +wheel size: 10
+wheel size: 135019664
+
      +
      + +

      +What has happened here is the garbage collector has collected the Bike instance as it doesn't think it is needed any more. +The proxy instance, wheel, contains a reference to memory that was deleted when the Bike instance was collected. +In order to prevent the garbage collector from collecting the Bike instance a reference to the Bike must +be added to the wheel instance. You can do this by adding the reference when the getWheel() method +is called using the following typemaps. +

      + + +
      +
      +%typemap(javacode) Wheel %{
+  // Ensure that the GC doesn't collect any Bike instance set from Java
+  private Bike bikeReference;
+  protected void addReference(Bike bike) {
+    bikeReference = bike;
+  }
+%}
+
+// Add a Java reference to prevent premature garbage collection and resulting use
+// of dangling C++ pointer. Intended for methods that return pointers or
+// references to a member variable.
+%typemap(javaout) Wheel& getWheel {
+    long cPtr = $jnicall;
+    $javaclassname ret = null;
+    if (cPtr != 0) {
+      ret = new $javaclassname(cPtr, $owner);
+      ret.addReference(this);
+    }
+    return ret;
+  }
+
      +
      + +

      +The code in the first typemap gets added to the Wheel proxy class. +The code in the second typemap constitutes the bulk of the code in the generated getWheel() function: +

      + +
      +
      +public class Wheel {
+  ...
+  // Ensure that the GC doesn't collect any bike set from Java 
+  private Bike bikeReference;
+  protected void addReference(Bike bike) {
+    bikeReference = bike;
+  }
+}
+
+public class Bike {
+  ...
+  public Wheel getWheel() {
+    long cPtr = exampleJNI.Bike_getWheel(swigCPtr, this);
+    Wheel ret = null;
+    if (cPtr != 0) {
+      ret = new Wheel(cPtr, false);
+      ret.addReference(this);
+    }
+    return ret;
+  }
+}
+
      +
      + +

      +Note the addReference call. +

      + +

      21.10.12 Memory management for objects passed to the C++ layer

      + + +

      +Managing memory can be tricky when using C++ and Java proxy classes. +The previous example shows one such case and this example looks at memory management for a class passed to a C++ method which expects the object to remain in scope +after the function has returned. Consider the following two C++ classes: +

      + +
      +
      +struct Element {
+  int value;
+  Element(int val) : value(val) {}
+};
+class Container {
+  Element* element;
+public:
+  Container() : element(0) {}
+  void setElement(Element* e) { element = e; }
+  Element* getElement() { return element; }
+};
+
      +
      + +

      +and usage from C++ +

      + +
      +
      +    Container container;
+    Element element(20);
+    container.setElement(&element);
+    cout << "element.value: " << container.getElement()->value << endl;
+
      +
      + +

      +and more or less equivalent usage from Java +

      + +
      +
      +    Container container = new Container();
+    container.setElement(new Element(20));
+    System.out.println("element value: " + container.getElement().getValue());
+
      +
      + +

      +The C++ code will always print out 20, but the value printed out may not be this in the Java equivalent code. +In order to understand why, consider a garbage collection occuring... +

      + +
      +
      +    Container container = new Container();
+    container.setElement(new Element(20));
+    // Simulate a garbage collection
+    System.gc();
+    System.runFinalization();
+    System.out.println("element value: " + container.getElement().getValue());
+
      +
      + +

      +The temporary element created with new Element(20) could get garbage collected +which ultimately means the container variable is holding a dangling pointer, thereby printing out any old random value instead of the expected value of 20. +One solution is to add in the appropriate references in the Java layer... +

      + +
      +
      +public class Container {
+
+  ...
+
+  // Ensure that the GC doesn't collect any Element set from Java
+  // as the underlying C++ class stores a shallow copy
+  private Element elementReference;
+  private long getCPtrAndAddReference(Element element) {
+    elementReference = element;
+    return Element.getCPtr(element);
+  }
+
+  public void setElement(Element e) {
+    exampleJNI.Container_setElement(swigCPtr, this, getCPtrAndAddReference(e), e);
+  }
+}
+
      +
      + +

      +The following typemaps will generate the desired code. +The 'javain' typemap matches the input parameter type for the setElement method. +The 'javacode' typemap simply adds in the specified code into the Java proxy class. +

      + +
      +
      +%typemap(javain) Element *e "getCPtrAndAddReference($javainput)"
+
+%typemap(javacode) Container %{
+  // Ensure that the GC doesn't collect any element set from Java
+  // as the underlying C++ class stores a shallow copy
+  private Element elementReference;
+  private long getCPtrAndAddReference(Element element) {
+    elementReference = element;
+    return Element.getCPtr(element);
+  }
+%}
+
      +
      + + +

      21.10.13 Date marshalling using the javain typemap and associated attributes

      + + +

      +The NaN Exception example is a simple example of the "javain" typemap and its 'pre' attribute. +This example demonstrates how a C++ date class, say CDate, can be mapped onto the standard Java date class, +java.util.GregorianCalendar by using the 'pre', 'post' and 'pgcppname' attributes of the "javain" typemap. +The idea is that the GregorianCalendar is used wherever the C++ API uses a CDate. +Let's assume the code being wrapped is as follows: +

      + +
      +
      +class CDate {
+public:
+  CDate(int year, int month, int day);
+  int getYear();
+  int getMonth();
+  int getDay();
+  ...
+};
+struct Action {
+  static int doSomething(const CDate &dateIn, CDate &dateOut);
+  Action(const CDate &date, CDate &dateOut);
+};
+
      +
      + +

      +Note that dateIn is const and therefore read only and dateOut is a non-const output type. +

      + +

      +First let's look at the code that is generated by default, where the Java proxy class CDate is used in the proxy interface: +

      + +
      +
      +public class Action {
+  ...
+  public static int doSomething(CDate dateIn, CDate dateOut) {
+    return exampleJNI.Action_doSomething(CDate.getCPtr(dateIn), dateIn, 
+                                         CDate.getCPtr(dateOut), dateOut);
+  }
+
+  public Action(CDate date, CDate dateOut) {
+    this(exampleJNI.new_Action(CDate.getCPtr(date), date, 
+                               CDate.getCPtr(dateOut), dateOut), true);
+  }
+}
+
      +
      + +

      +The CDate & and const CDate & Java code is generated from the following two default typemaps: +

      + +
      +
      +%typemap(jstype) SWIGTYPE & "$javaclassname"
+%typemap(javain) SWIGTYPE & "$javaclassname.getCPtr($javainput)"
+
      +
      + +

      +where '$javaclassname' is translated into the proxy class name, CDate and '$javainput' is translated into the name of the parameter, eg dateIn. +From Java, the intention is then to call into a modifed API with something like: +

      + +
      +
      +java.util.GregorianCalendar calendarIn = 
+    new java.util.GregorianCalendar(2011, java.util.Calendar.APRIL, 13, 0, 0, 0);
+java.util.GregorianCalendar calendarOut = new java.util.GregorianCalendar();
+
+// Note in calls below, calendarIn remains unchanged and calendarOut 
+// is set to a new value by the C++ call
+Action.doSomething(calendarIn, calendarOut);
+Action action = new Action(calendarIn, calendarOut);
+
      +
      + +

      +To achieve this mapping, we need to alter the default code generation slightly so that at the Java layer, +a GregorianCalendar is converted into a CDate. +The JNI intermediary layer will still take a pointer to the underlying CDate class. +The typemaps to achieve this are shown below. +

      + +
      +
      +%typemap(jstype) const CDate& "java.util.GregorianCalendar"
+%typemap(javain, 
+         pre="    CDate temp$javainput = new CDate($javainput.get(java.util.Calendar.YEAR), "
+             "$javainput.get(java.util.Calendar.MONTH), $javainput.get(java.util.Calendar.DATE));", 
+         pgcppname="temp$javainput") const CDate &
+         "$javaclassname.getCPtr(temp$javainput)"
+
+%typemap(jstype) CDate& "java.util.Calendar"
+%typemap(javain, 
+         pre="    CDate temp$javainput = new CDate($javainput.get(java.util.Calendar.YEAR), "
+             "$javainput.get(java.util.Calendar.MONTH), $javainput.get(java.util.Calendar.DATE));", 
+         post="      $javainput.set(temp$javainput.getYear(), temp$javainput.getMonth(), "
+              "temp$javainput.getDay(), 0, 0, 0);", 
+         pgcppname="temp$javainput") CDate &
+         "$javaclassname.getCPtr(temp$javainput)"
+
      +
      + +

      +The resulting generated proxy code in the Action class follows: +

      + +
      +
      +public class Action {
+  ...
+  public static int doSomething(java.util.GregorianCalendar dateIn, 
+                                java.util.Calendar dateOut) {
+    CDate tempdateIn = new CDate(dateIn.get(java.util.Calendar.YEAR), 
+                                 dateIn.get(java.util.Calendar.MONTH), 
+                                 dateIn.get(java.util.Calendar.DATE));
+    CDate tempdateOut = new CDate(dateOut.get(java.util.Calendar.YEAR), 
+                                  dateOut.get(java.util.Calendar.MONTH), 
+                                  dateOut.get(java.util.Calendar.DATE));
+    try {
+      return exampleJNI.Action_doSomething(CDate.getCPtr(tempdateIn), tempdateIn, 
+                                           CDate.getCPtr(tempdateOut), tempdateOut);
+    } finally {
+      dateOut.set(tempdateOut.getYear(), tempdateOut.getMonth(), tempdateOut.getDay(), 0, 0, 0);
+    }
+  }
+
+  static private long SwigConstructAction(java.util.GregorianCalendar date, 
+                                          java.util.Calendar dateOut) {
+    CDate tempdate = new CDate(date.get(java.util.Calendar.YEAR), 
+                               date.get(java.util.Calendar.MONTH), 
+                               date.get(java.util.Calendar.DATE));
+    CDate tempdateOut = new CDate(dateOut.get(java.util.Calendar.YEAR), 
+                                  dateOut.get(java.util.Calendar.MONTH), 
+                                  dateOut.get(java.util.Calendar.DATE));
+    try {
+      return exampleJNI.new_Action(CDate.getCPtr(tempdate), tempdate, 
+                                   CDate.getCPtr(tempdateOut), tempdateOut);
+    } finally {
+      dateOut.set(tempdateOut.getYear(), tempdateOut.getMonth(), tempdateOut.getDay(), 0, 0, 0);
+    }
+  }
+
+  public Action(java.util.GregorianCalendar date, java.util.Calendar dateOut) {
+    this(Action.SwigConstructAction(date, dateOut), true);
+  }
+}
+
      +
      + +

      +A few things to note: +

      +
        +
      • The "javatype" typemap has changed the parameter type to java.util.GregorianCalendar or java.util.Calendar instead of the default generated CDate proxy. +
      • The code in the 'pre' attribute appears before the JNI call (exampleJNI.new_Action / exampleJNI.Action_doSomething). +
      • The code in the 'post' attribute appears after the JNI call. +
      • A try .. finally block is generated with the JNI call in the try block and 'post' code in the finally block. + The alternative of just using a temporary variable for the return value from the JNI call and the 'post' code being generated before the + return statement is not possible given that the JNI call is in one line and comes from the "javaout" typemap. +
      • The temporary variables in the "javain" typemaps are called temp$javain, where "$javain" is replaced with the parameter name. + "$javain" is used to mangle the variable name so that more than one CDate & type can be used as a parameter in a method, otherwise two or + more local variables with the same name would be generated. +
      • The use of the "javain" typemap causes a constructor helper function (SwigConstructAction) to be generated. + This allows Java code to be called before the JNI call and is required as the Java compiler won't compile code inserted before the 'this' call. +
      • The 'pgcppname' attribute is used to modify the object being passed as the premature garbage collection prevention parameter (the 2nd and 4th parameters in the JNI calls). +
      + + + + +

      21.11 Living with Java Directors

      + + +

      + This section is intended to address frequently asked questions and frequently encountered problems when using Java directors. +

      + +
        +
      1. When my program starts up, it complains that method_foo cannot + be found in a Java method called swig_module_init. How do I fix + this? + +

        + Open up the C++ wrapper source code file and look for "method_foo" (include the double quotes, they are important!) + Look at the JNI field descriptor and make sure that each class that occurs in the descriptor has the correct package name in front of it. + If the package name is incorrect, put a "javapackage" typemap in your SWIG interface file. +

        +
        2. + +
      2. I'm compiling my code and I'm using templates. I provided a + javapackage typemap, but SWIG doesn't generate the right JNI field + descriptor. +

        + Use the template's renamed name as the argument to the "javapackage" typemap: +

        +
        +
        +%typemap(javapackage)  std::vector<int>  "your.package.here"
+%template(VectorOfInt) std::vector<int>;
+
        +
        +
        3. + +

      3. When I pass class pointers or references through a C++ upcall and I + try to type cast them, Java complains with a ClassCastException. What am I + doing wrong?

        +

        + Normally, a non-director generated Java proxy class creates temporary Java objects as follows: +

        +
        +
        +public static void MyClass_method_upcall(MyClass self, long jarg1)
+{
+  Foo darg1 = new Foo(jarg1, false);
+
+  self.method_upcall(darg1);
+}
+
        +
        +

        Unfortunately, this loses the Java type information that is part of the underlying Foo director proxy class's Java object pointer causing the type cast to fail. + The SWIG Java module's director code attempts to correct the problem, but only for director-enabled classes, since the director class retains a global reference to its Java object. + Thus, for director-enabled classes and only for director-enabled classes, the generated proxy Java code looks something like: +

        + +
        +
        +public static void MyClass_method_upcall(MyClass self, long jarg1,
+                                         Foo jarg1_object)
+{
+  Foo darg1 = (jarg1_object != null ? jarg1_object : new Foo(jarg1, false));
+
+  self.method_upcall(darg1);
+}
+
        +
        + +

        + When you import a SWIG interface file containing class definitions, the classes you want to be director-enabled must be have the feature("director") enabled for type symmetry to work. + This applies even when the class being wrapped isn't a director-enabled class but takes parameters that are director-enabled classes. +

        + +

        + The current "type symmetry" design will work for simple C++ inheritance, but will most likely fail for anything more complicated such as tree or diamond C++ inheritance hierarchies. + Those who are interested in challenging problems are more than welcome to hack the Java::Java_director_declaration method in Source/Modules/java.cxx. +

        +

        + If all else fails, you can use the downcastXXXXX() method to attempt to recover the director class's Java object pointer. + For the Java Foo proxy class, the Foo director class's java object pointer can be accessed through the javaObjectFoo() method. + The generated method's signature is: +

        + +
        +
        +  public static Foo javaObjectFoo(Foo obj);
+
        +
        + +

        + From your code, this method is invoked as follows: +

        + +
        +
        +public class MyClassDerived {
+  public void method_upcall(Foo foo_object)
+  {
+    FooDerived    derived = (foo_object != null ?
+                 (FooDerived) Foo.downcastFoo(foo_object) : null);
+    /* rest of your code here */
+  }
+}
+
        +
        + +

        + An good approach for managing downcasting is placing a static method in each derived class that performs the downcast from the superclass, e.g., +

        + +
        +
        +public class FooDerived extends Foo {
+  /* ... */
+  public static FooDerived downcastFooDerived(Foo foo_object)
+  {
+    try {
+     return (foo_object != null ? (FooDerived) Foo.downcastFoo(foo_object);
+    }
+
+    catch (ClassCastException exc) {
+      // Wasn't a FooDerived object, some other subclass of Foo
+      return null;
+    }
+  }
+}
+
        +
        + +

        + Then change the code in MyClassDerived as follows: +

        + +
        +
        +public class MyClassDerived extends MyClass {
+  /* ... */
+  public void method_upcall(Foo foo_object)
+  {
+    FooDerived    derived = FooDerived.downcastFooDerived(foo_object);
+    /* rest of your code here */
+  }
+}
+
        +
        +
        4. + +

      4. Why isn't the proxy class declared abstract? Why aren't the director + upcall methods in the proxy class declared abstract?

        + +

        + Declaring the proxy class and its methods abstract would break the JNI argument marshalling and SWIG's downcall functionality (going from Java to C++.) + Create an abstract Java subclass that inherits from the director-enabled class instead. + Using the previous Foo class example: +

        + +
        +
        +public abstract class UserVisibleFoo extends Foo {
+  /** Make sure user overrides this method, it's where the upcall
+   * happens.
+   */
+  public abstract void method_upcall(Foo foo_object);
+
+  /// Downcast from Foo to UserVisibleFoo
+  public static UserVisibleFoo downcastUserVisibleFoo(Foo foo_object)
+  {
+    try {
+     return (foo_object != null ? (FooDerived) Foo.downcastFoo(foo_object) : null);
+    }
+
+    catch (ClassCastException exc) {
+      // Wasn't a FooDerived object, some other subclass of Foo
+      return null;
+    }
+  }
+}
+
        +
        +

        This doesn't prevent the user from creating subclasses derived from Foo, however, UserVisibleFoo provides the safety net that reminds the user to override the method_upcall() method.

        +
        5. +
      + +

      21.12 Odds and ends

      + + +

      21.12.1 JavaDoc comments

      + + +

      +The SWIG documentation system is currently deprecated. +When it is resurrected JavaDoc comments will be fully supported. +If you can't wait for the full documentation system a couple of workarounds are available. +The %javamethodmodifiers feature can be used for adding proxy class method comments and module class method comments. +The "javaimports" typemap can be hijacked for adding in proxy class JavaDoc comments. +The jniclassimports or jniclassclassmodifiers pragmas can also be used for adding intermediary JNI class comments and likewise the moduleimports or moduleclassmodifiers pragmas for the module class. +Here is an example adding in a proxy class and method comment: +

      + +
      +
      +%javamethodmodifiers Barmy::lose_marbles() "
+  /**
+    * Calling this method will make you mad.
+    * Use with <b>utmost</b> caution. 
+    */
+  public";
+
+%typemap(javaimports) Barmy "
+/** The crazy class. Use as a last resort. */"
+
+class Barmy {
+public:
+  void lose_marbles() {}
+};
+
      +
      + +

      +Note the "public" added at the end of the %javamethodmodifiers as this is the default for this feature. +The generated proxy class with JavaDoc comments is then as follows: +

      + +
      +
      +/** The crazy class. Use as a last resort. */
+public class Barmy {
+...
+  /**
+    * Calling this method will make you mad.
+    * Use with <b>utmost</b> caution. 
+    */
+  public void lose_marbles() {
+    ...
+  }
+...
+}
+
      +
      + + + +

      21.12.2 Functional interface without proxy classes

      + + +

      +It is possible to run SWIG in a mode that does not produce proxy classes by using the -noproxy commandline option. +The interface is rather primitive when wrapping structures or classes and is accessed through function calls to the module class. +All the functions in the module class are wrapped by functions with identical names as those in the intermediary JNI class. +

      + +

      +Consider the example we looked at when examining proxy classes: +

      + +
      +
      +class Foo {
+public:
+     int x;
+     int spam(int num, Foo* foo);
+};
+
      +
      + +

      +When using -noproxy, type wrapper classes are generated instead of proxy classes. +Access to all the functions and variables is through a C like set of functions where the first parameter passed is the pointer to the class, that is an instance of a type wrapper class. +Here is what the module class looks like: +

      + +
      +
      +public class example {
+  public static void Foo_x_get(SWIGTYPE_p_Foo self, int x) {...}
+  public static int Foo_x_get(SWIGTYPE_p_Foo self) {...}
+  public static int Foo_spam(SWIGTYPE_p_Foo self, int num, SWIGTYPE_p_Foo foo) {...}
+  public static SWIGTYPE_p_Foo new_Foo() {...}
+  public static void delete_Foo(SWIGTYPE_p_Foo self) {...}
+}
+
      +
      + +

      +This approach is not nearly as natural as using proxy classes as the functions need to be used like this: +

      + +
      +
      +SWIGTYPE_p_Foo foo = example.new_Foo();
+example.Foo_x_set(foo, 10);
+int var = example.Foo_x_get(foo);
+example.Foo_spam(foo, 20, foo);
+example.delete_Foo(foo);
+
      +
      + +

      +Unlike proxy classes, there is no attempt at tracking memory. +All destructors have to be called manually for example the delete_Foo(foo) call above. +

      + + +

      21.12.3 Using your own JNI functions

      + + +

      +You may have some hand written JNI functions that you want to use in addition to the SWIG generated JNI functions. +Adding these to your SWIG generated package is possible using the %native directive. +If you don't want SWIG to wrap your JNI function then of course you can simply use the %ignore directive. +However, if you want SWIG to generate just the Java code for a JNI function then use the %native directive. +The C types for the parameters and return type must be specified in place of the JNI types and the function name must be the native method name. +For example: +

      + +
      +%native (HandRolled) void HandRolled(int, char *);
+%{
+JNIEXPORT void JNICALL Java_packageName_moduleName_HandRolled(JNIEnv *, jclass,
+                                                              jlong, jstring);
+%}
+
      + +

      +No C JNI function will be generated and the Java_packageName_moduleName_HandRolled function will be accessible using the SWIG generated Java native method call in the intermediary JNI class which will look like this: +

      + +
      +  public final static native void HandRolled(int jarg1, String jarg2);
+
      + +

      +and as usual this function is wrapped by another which for a global C function would appear in the module class: +

      + +
      +  public static void HandRolled(int arg0, String arg1) {
+    exampleJNI.HandRolled(arg0, arg1);
+  }
+
      + +

      +The packageName and moduleName must of course be correct else you will get linker errors when the JVM dynamically loads the JNI function. +You may have to add in some "jtype", "jstype", "javain" and "javaout" typemaps when wrapping some JNI types. +Here the default typemaps work for int and char *. +

      + +

      +In summary the %native directive is telling SWIG to generate the Java code to access the JNI C code, but not the JNI C function itself. +This directive is only really useful if you want to mix your own hand crafted JNI code and the SWIG generated code into one Java class or package. +

      + + +

      21.12.4 Performance concerns and hints

      + + +

      +If you're directly manipulating huge arrays of complex objects from Java, performance may suffer greatly when using the array functions in arrays_java.i. +Try and minimise the expensive JNI calls to C/C++ functions, perhaps by using temporary Java variables instead of accessing the information directly from the C/C++ object. +

      + +

      +Java classes without any finalizers generally speed up code execution as there is less for the garbage collector to do. Finalizer generation can be stopped by using an empty javafinalize typemap: +

      + +
      +%typemap(javafinalize) SWIGTYPE ""
+
      + +

      +However, you will have to be careful about memory management and make sure that you code in a call to the delete() member function. +This method normally calls the C++ destructor or free() for C code. +

      + +

      21.12.5 Debugging

      + + +

      +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, +where it is possible to step from Java code into a JNI method within one environment. +

      + +

      +Alternatively, debugging can involve placing debug printout statements in the JNI layer using the %exception directive. +See the special variables for %exception section. +Many of the default typemaps can also be overidden and modified for adding in extra logging/debug display information. +

      + +

      +The -Xcheck:jni and -Xcheck:nabounds Java executable options are useful for debugging to make sure the JNI code is behaving. +The -verbose:jni and -verbose:gc are also useful options for monitoring code behaviour. +

      + + +

      21.13 Examples

      + + +

      +The directory Examples/java has a number of further examples. +Take a look at these if you want to see some of the techniques described in action. +The Examples/index.html file in the parent directory contains the SWIG Examples Documentation and is a useful starting point. +If your SWIG installation went well Unix users should be able to type make in each example directory, then java main to see them running. +For the benefit of Windows users, there are also Visual C++ project files in a couple of the Windows Examples. +There are also many regression tests in the Examples/test-suite directory. +Many of these have runtime tests in the java subdirectory. +

      + + + + diff --git a/Doc/Manual/Library.html b/Doc/Manual/Library.html new file mode 100644 index 0000000..7293f31 --- /dev/null +++ b/Doc/Manual/Library.html @@ -0,0 +1,1781 @@ + + + +SWIG Library + + + + +

      8 SWIG library

      + +
      + +
      + + + + +

      +To help build extension modules, SWIG is packaged with a library of +support files that you can include in your own interfaces. These +files often define new SWIG directives or provide utility +functions that can be used to access parts of the standard C and C++ libraries. +This chapter provides a reference to the current set of supported library files. +

      + +

      +Compatibility note: Older versions of SWIG included a number of +library files for manipulating pointers, arrays, and other structures. Most +these files are now deprecated and have been removed from the distribution. +Alternative libraries provide similar functionality. Please read this chapter +carefully if you used the old libraries. +

      + +

      8.1 The %include directive and library search path

      + + +

      +Library files are included using the %include directive. +When searching for files, directories are searched in the following order: +

      + +
        +
      • The current directory +
      • Directories specified with the -I command line option +
      • ./swig_lib +
      • SWIG library install location as reported by swig -swiglib, for example /usr/local/share/swig/1.3.30 +
      • On Windows, a directory Lib relative to the location of swig.exe is also searched. +
      + +

      +Within each directory, SWIG first looks for a subdirectory corresponding to a target language (e.g., python, +tcl, etc.). If found, SWIG will search the language specific directory first. This allows +for language-specific implementations of library files. +

      + +

      +You can ignore the installed SWIG library by setting the SWIG_LIB environment variable. +Set the environment variable to hold an alternative library directory. +

      + +

      +The directories that are searched are displayed when using -verbose commandline option. +

      + +

      8.2 C Arrays and Pointers

      + + +

      +This section describes library modules for manipulating low-level C arrays and pointers. +The primary use of these modules is in supporting C declarations that manipulate bare +pointers such as int *, double *, or void *. The modules can be +used to allocate memory, manufacture pointers, dereference memory, and wrap +pointers as class-like objects. Since these functions provide direct access to +memory, their use is potentially unsafe and you should exercise caution. +

      + +

      8.2.1 cpointer.i

      + + +

      +The cpointer.i module defines macros that can be used to used +to generate wrappers around simple C pointers. The primary use of +this module is in generating pointers to primitive datatypes such as +int and double. +

      + +

      +%pointer_functions(type,name) +

      + +
      +

      Generates a collection of four functions for manipulating a pointer type *:

      + +

      +type *new_name() +

      + +

      +Creates a new object of type type and returns a pointer to it. In C, the +object is created using calloc(). In C++, new is used. +

      + +

      +type *copy_name(type value) +

      + +

      +Creates a new object of type type and returns a pointer to it. +An initial value is set by copying it from value. In C, the +object is created using calloc(). In C++, new is used. +

      + +

      +type *delete_name(type *obj) +

      + +

      +Deletes an object type type. +

      + +

      +void name_assign(type *obj, type value) +

      + +

      +Assigns *obj = value. +

      + +

      +type name_value(type *obj) +

      + +

      +Returns the value of *obj. +

      + +

      +When using this macro, type may be any type and name must be a legal identifier in the target +language. name should not correspond to any other name used in the interface file. +

      + + +

      +Here is a simple example of using %pointer_functions(): +

      + +
      +
      +%module example
+%include "cpointer.i"
+
+/* Create some functions for working with "int *" */
+%pointer_functions(int, intp);
+
+/* A function that uses an "int *" */
+void add(int x, int y, int *result);
+
      +
      + +

      +Now, in Python: +

      + +
      +
      +>>> import example
+>>> c = example.new_intp()     # Create an "int" for storing result
+>>> example.add(3,4,c)         # Call function
+>>> example.intp_value(c)      # Dereference
+7
+>>> example.delete_intp(c)     # Delete
+
      +
      + +
      + +

      +%pointer_class(type,name) +

      + +
      + +

      +Wraps a pointer of type * inside a class-based interface. This +interface is as follows: +

      + +
      +
      +struct name {
+   name();                            // Create pointer object
+  ~name();                            // Delete pointer object
+   void assign(type value);           // Assign value
+   type value();                      // Get value
+   type *cast();                      // Cast the pointer to original type
+   static name *frompointer(type *);  // Create class wrapper from existing
+                                      // pointer
+};
+
      +
      + +

      +When using this macro, type is restricted to a simple type +name like int, float, or Foo. Pointers and +other complicated types are not allowed. name must be a +valid identifier not already in use. When a pointer is wrapped as a class, +the "class" may be transparently passed to any function that expects the pointer. +

      + +

      +If the target language does not support proxy classes, the use of this macro will produce the example +same functions as %pointer_functions() macro. +

      + + +

      +It should be noted that the class interface does introduce a new object or wrap a pointer inside a special +structure. Instead, the raw pointer is used directly. +

      + + + +

      +Here is the same example using a class instead: +

      + +
      +
      +%module example
+%include "cpointer.i"
+
+/* Wrap a class interface around an "int *" */
+%pointer_class(int, intp);
+
+/* A function that uses an "int *" */
+void add(int x, int y, int *result);
+
      +
      + +

      +Now, in Python (using proxy classes) +

      + +
      +
      +>>> import example
+>>> c = example.intp()         # Create an "int" for storing result
+>>> example.add(3,4,c)         # Call function
+>>> c.value()                  # Dereference
+7
+
      +
      + +

      +Of the two macros, %pointer_class is probably the most convenient when working with simple +pointers. This is because the pointers are access like objects and they can be easily garbage collected +(destruction of the pointer object destroys the underlying object). +

      + +
      + +

      +%pointer_cast(type1, type2, name) +

      + +
      + +

      +Creates a casting function that converts type1 to type2. The name of the function is name. +For example: +

      + +
      +
      +%pointer_cast(int *, unsigned int *, int_to_uint);
+
      +
      + +

      +In this example, the function int_to_uint() would be used to cast types in the target language. +

      + +
      + +

      +Note: None of these macros can be used to safely work with strings (char * or char **). +

      + +

      +Note: When working with simple pointers, typemaps can often be used to provide more seamless operation. +

      + +

      8.2.2 carrays.i

      + + +

      +This module defines macros that assist in wrapping ordinary C pointers as arrays. +The module does not provide any safety or an extra layer of wrapping--it merely +provides functionality for creating, destroying, and modifying the contents of +raw C array data. +

      + +

      +%array_functions(type,name) +

      + +
      +

      Creates four functions.

      + +

      +type *new_name(int nelements) +

      + +

      +Creates a new array of objects of type type. In C, the array is allocated using +calloc(). In C++, new [] is used. +

      + +

      +type *delete_name(type *ary) +

      + +

      +Deletes an array. In C, free() is used. In C++, delete [] is used. +

      + +

      +type name_getitem(type *ary, int index) +

      + +

      +Returns the value ary[index]. +

      + +

      +void name_setitem(type *ary, int index, type value) +

      + +

      +Assigns ary[index] = value. +

      + +

      +When using this macro, type may be any type and name +must be a legal identifier in the target language. name +should not correspond to any other name used in the interface file. +

      + +

      +Here is an example of %array_functions(). Suppose you had a +function like this: +

      + +
      +
      +void print_array(double x[10]) {
+   int i;
+   for (i = 0; i < 10; i++) {
+      printf("[%d] = %g\n", i, x[i]);
+   }
+}
+
      +
      + +

      +To wrap it, you might write this: +

      + +
      +
      +%module example
+
+%include "carrays.i"
+%array_functions(double, doubleArray);
+
+void print_array(double x[10]);
+
      +
      + +

      +Now, in a scripting language, you might write this: +

      + +
      +
      +a = new_doubleArray(10)           # Create an array
+for i in range(0,10):
+    doubleArray_setitem(a,i,2*i)  # Set a value
+print_array(a)                    # Pass to C
+delete_doubleArray(a)             # Destroy array
+
      +
      + +
      + +

      +%array_class(type,name) +

      +
      + +

      +Wraps a pointer of type * inside a class-based interface. This +interface is as follows: +

      + +
      +
      +struct name {
+   name(int nelements);                  // Create an array
+  ~name();                               // Delete array
+   type getitem(int index);              // Return item
+   void setitem(int index, type value);  // Set item
+   type *cast();                         // Cast to original type
+   static name *frompointer(type *);     // Create class wrapper from
+                                         // existing pointer
+};
+
      +
      + +

      +When using this macro, type is restricted to a simple type +name like int or float. Pointers and +other complicated types are not allowed. name must be a +valid identifier not already in use. When a pointer is wrapped as a class, +it can be transparently passed to any function that expects the pointer. +

      + + +

      +When combined with proxy classes, the %array_class() macro can be especially useful. +For example: +

      + +
      +
      +%module example
+%include "carrays.i"
+%array_class(double, doubleArray);
+
+void print_array(double x[10]);
+
      +
      + +

      +Allows you to do this: +

      + +
      +
      +import example
+c = example.doubleArray(10)  # Create double[10]
+for i in range(0,10):
+    c[i] = 2*i               # Assign values
+example.print_array(c)       # Pass to C
+
      +
      + +
      + +

      +Note: These macros do not encapsulate C arrays inside a special data structure +or proxy. There is no bounds checking or safety of any kind. If you want this, +you should consider using a special array object rather than a bare pointer. +

      + +

      +Note: %array_functions() and %array_class() should not be +used with types of char or char *. +

      + +

      8.2.3 cmalloc.i

      + + +

      +This module defines macros for wrapping the low-level C memory allocation functions +malloc(), calloc(), realloc(), and free(). +

      + +

      +%malloc(type [,name=type]) +

      + +
      + +

      +Creates a wrapper around malloc() with the following prototype: +

      + +
      +type *malloc_name(int nbytes = sizeof(type));
+
      +
      + +

      +If type is void, then the size parameter nbytes is required. +The name parameter only needs to be specified when wrapping a type that +is not a valid identifier (e.g., "int *", "double **", etc.). +

      + +
      + +

      +%calloc(type [,name=type]) +

      + +
      + +

      +Creates a wrapper around calloc() with the following prototype: +

      + +
      +type *calloc_name(int nobj =1, int sz = sizeof(type));
+
      +
      + +

      +If type is void, then the size parameter sz is required. +

      + +
      + +

      +%realloc(type [,name=type]) +

      + +
      + +

      +Creates a wrapper around realloc() with the following prototype: +

      + +
      +type *realloc_name(type *ptr, int nitems);
+
      +
      + +

      +Note: unlike the C realloc(), the wrapper generated by this macro implicitly includes the +size of the corresponding type. For example, realloc_int(p, 100) reallocates p so that +it holds 100 integers. +

      + +
      + +

      +%free(type [,name=type]) +

      + +
      + +

      +Creates a wrapper around free() with the following prototype: +

      + +
      +void free_name(type *ptr);
+
      +
      +
      + +

      +%sizeof(type [,name=type]) +

      + +
      + +

      +Creates the constant: +

      + +
      +%constant int sizeof_name = sizeof(type);
+
      +
      +
      + +

      +%allocators(type [,name=type]) +

      + +

      +Generates wrappers for all five of the above operations. +

      + +

      +Here is a simple example that illustrates the use of these macros: +

      + +
      +
      +// SWIG interface
+%module example
+%include "cmalloc.i"
+
+%malloc(int);
+%free(int);
+
+%malloc(int *, intp);
+%free(int *, intp);
+
+%allocators(double);
+
      +
      + +

      +Now, in a script: +

      + +
      +
      +>>> from example import *
+>>> a = malloc_int()
+>>> a
+'_000efa70_p_int'
+>>> free_int(a)
+>>> b = malloc_intp()
+>>> b
+'_000efb20_p_p_int'
+>>> free_intp(b)
+>>> c = calloc_double(50)
+>>> c
+'_000fab98_p_double'
+>>> c = realloc_double(100000)
+>>> free_double(c)
+>>> print sizeof_double
+8
+>>>
+
      +
      + +

      8.2.4 cdata.i

      + + +

      +The cdata.i module defines functions for converting raw C data to and from strings +in the target language. The primary applications of this module would be packing/unpacking of +binary data structures---for instance, if you needed to extract data from a buffer. +The target language must support strings with embedded binary data +in order for this to work. +

      + +

      +char *cdata(void *ptr, int nbytes) +

      + +

      +Converts nbytes of data at ptr into a string. ptr can be any +pointer. +

      + +

      +void memmove(void *ptr, char *s) +

      + +

      +Copies all of the string data in s into the memory pointed to by +ptr. The string may contain embedded NULL bytes. The length of +the string is implicitly determined in the underlying wrapper code. +

      + +

      +One use of these functions is packing and unpacking data from memory. +Here is a short example: +

      + +
      +
      +// SWIG interface
+%module example
+%include "carrays.i"
+%include "cdata.i"
+
+%array_class(int, intArray);
+
      +
      + +

      +Python example: +

      + +
      +
      +>>> a = intArray(10)
+>>> for i in range(0,10):
+...    a[i] = i
+>>> b = cdata(a,40)
+>>> b
+'\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x02\x00\x00\x00\x03\x00\x00\x00\x04
+\x00\x00\x00\x05\x00\x00\x00\x06\x00\x00\x00\x07\x00\x00\x00\x08\x00\x00\x00\t'
+>>> c = intArray(10)
+>>> memmove(c,b)
+>>> print c[4]
+4
+>>>
+
      +
      + +

      +Since the size of data is not always known, the following macro is also defined: +

      + +

      +%cdata(type [,name=type]) +

      + +
      + +

      +Generates the following function for extracting C data for a given type. +

      + +
      +
      +char *cdata_name(type* ptr, int nitems)
+
      +
      + +

      +nitems is the number of items of the given type to extract. +

      + +
      + +

      +Note: These functions provide direct access to memory and can be used to overwrite data. +Clearly they are unsafe. +

      + +

      8.3 C String Handling

      + + +

      +A common problem when working with C programs is dealing with +functions that manipulate raw character data using char *. +In part, problems arise because there are different interpretations of +char *---it could be a NULL-terminated string or it could +point to binary data. Moreover, functions that manipulate raw strings +may mutate data, perform implicit memory allocations, or utilize +fixed-sized buffers. +

      + +

      +The problems (and perils) of using char * are +well-known. However, SWIG is not in the business of enforcing +morality. The modules in this section provide basic functionality +for manipulating raw C strings. +

      + +

      8.3.1 Default string handling

      + + +

      +Suppose you have a C function with this prototype: +

      + +
      +
      +char *foo(char *s);
+
      +
      + +

      +The default wrapping behavior for this function is to set s +to a raw char * that refers to the internal string data in the +target language. In other words, if you were using a language like Tcl, +and you wrote this, +

      + +
      +
      +% foo Hello
+
      +
      + +

      +then s would point to the representation of "Hello" inside +the Tcl interpreter. When returning a char *, SWIG assumes +that it is a NULL-terminated string and makes a copy of it. This +gives the target language its own copy of the result. +

      + +

      +There are obvious problems with the default behavior. First, since +a char * argument points to data inside the target language, it is +NOT safe for a function to modify this data (doing so may corrupt the +interpreter and lead to a crash). Furthermore, the default behavior does +not work well with binary data. Instead, strings are assumed to be NULL-terminated. +

      + +

      8.3.2 Passing binary data

      + + +

      +If you have a function that expects binary data, +

      + +
      +
      +int parity(char *str, int len, int initial);
+
      +
      + +

      +you can wrap the parameters (char *str, int len) as a single +argument using a typemap. Just do this: +

      + +
      +
      +%apply (char *STRING, int LENGTH) { (char *str, int len) };
+...
+int parity(char *str, int len, int initial);
+
      +
      + +

      +Now, in the target language, you can use binary string data like this: +

      + +
      +
      +>>> s = "H\x00\x15eg\x09\x20"
+>>> parity(s,0)
+
      +
      + +

      +In the wrapper function, the passed string will be expanded to a pointer and length parameter. +

      + +

      8.3.3 Using %newobject to release memory

      + + +

      +If you have a function that allocates memory like this, +

      + +
      +
      +char *foo() {
+   char *result = (char *) malloc(...);
+   ...
+   return result;
+}
+
      +
      + +

      +then the SWIG generated wrappers will have a memory leak--the returned data will be copied +into a string object and the old contents ignored. +

      + +

      +To fix the memory leak, use the %newobject directive. +

      + +
      +
      +%newobject foo;
+...
+char *foo();
+
      +
      + +

      +This will release the result. +

      + +

      8.3.4 cstring.i

      + + +

      +The cstring.i library file provides a collection of macros +for dealing with functions that either mutate string arguments or +which try to output string data through their arguments. An +example of such a function might be this rather questionable +implementation: +

      + +
      +
      +void get_path(char *s) {
+    // Potential buffer overflow---uh, oh.
+    sprintf(s,"%s/%s", base_directory, sub_directory);
+}
+...
+// Somewhere else in the C program
+{
+    char path[1024];
+    ...
+    get_path(path);
+    ...
+}
+
      +
      + +

      +(Off topic rant: If your program really has functions like this, you +would be well-advised to replace them with safer alternatives +involving bounds checking). +

      + +

      +The macros defined in this module all expand to various combinations of +typemaps. Therefore, the same pattern matching rules and ideas apply. +

      + +

      +%cstring_bounded_output(parm, maxsize) +

      + +
      + +

      +Turns parameter parm into an output value. The +output string is assumed to be NULL-terminated and smaller than +maxsize characters. Here is an example: +

      + +
      +
      +%cstring_bounded_output(char *path, 1024);
+...
+void get_path(char *path);
+
      +
      + +

      +In the target language: +

      + +
      +
      +>>> get_path()
+/home/beazley/packages/Foo/Bar
+>>>
+
      +
      + +

      +Internally, the wrapper function allocates a small buffer (on the stack) of the +requested size and passes it as the pointer value. Data stored in the buffer is then +returned as a function return value. +If the function already returns a value, then the return value and the output string +are returned together (multiple return values). If more than maxsize +bytes are written, your program will crash with a buffer overflow! +

      + +
      + +

      +%cstring_chunk_output(parm, chunksize) +

      + +
      + +

      +Turns parameter parm into an output value. The +output string is always chunksize and may contain +binary data. Here is an example: +

      + +
      +
      +%cstring_chunk_output(char *packet, PACKETSIZE);
+...
+void get_packet(char *packet);
+
      +
      + +

      +In the target language: +

      + +
      +
      +>>> get_packet()
+'\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f\xd3\x99\x14V\xec\x06\xea\xa2\x88'
+>>>
+
      +
      + +

      +This macro is essentially identical to %cstring_bounded_output. The +only difference is that the result is always chunksize characters. +Furthermore, the result can contain binary data. +If more than maxsize +bytes are written, your program will crash with a buffer overflow! +

      + +
      + +

      +%cstring_bounded_mutable(parm, maxsize) +

      + +
      + +

      +Turns parameter parm into a mutable string argument. +The input string is assumed to be NULL-terminated and smaller than +maxsize characters. The output string is also assumed +to be NULL-terminated and less than maxsize characters. +

      + +
      +
      +%cstring_bounded_mutable(char *ustr, 1024);
+...
+void make_upper(char *ustr);
+
      +
      + +

      +In the target language: +

      + +
      +
      +>>> make_upper("hello world")
+'HELLO WORLD'
+>>>
+
      +
      + +

      +Internally, this macro is almost exactly the same as +%cstring_bounded_output. The only difference is that the +parameter accepts an input value that is used to initialize the +internal buffer. It is important to emphasize that this function +does not mutate the string value passed---instead it makes a copy of the +input value, mutates it, and returns it as a result. +If more than maxsize bytes are +written, your program will crash with a buffer overflow! +

      + +
      + +

      +%cstring_mutable(parm [, expansion]) +

      + +
      + +

      +Turns parameter parm into a mutable string argument. +The input string is assumed to be NULL-terminated. An optional +parameter expansion specifies the number of +extra characters by which the string might grow when it is modified. +The output string is assumed to be NULL-terminated and less than +the size of the input string plus any expansion characters. +

      + +
      +
      +%cstring_mutable(char *ustr);
+...
+void make_upper(char *ustr);
+
+%cstring_mutable(char *hstr, HEADER_SIZE);
+...
+void attach_header(char *hstr);
+
      +
      + +

      +In the target language: +

      + +
      +
      +>>> make_upper("hello world")
+'HELLO WORLD'
+>>> attach_header("Hello world")
+'header: Hello world'
+>>>
+
      +
      + +

      +This macro differs from %cstring_bounded_mutable() in that a +buffer is dynamically allocated (on the heap using +malloc/new). This buffer is always large enough to store a +copy of the input value plus any expansion bytes that might have been +requested. +It is important to emphasize that this function +does not directly mutate the string value passed---instead it makes a copy of the +input value, mutates it, and returns it as a result. +If the function expands the result by more than expansion extra +bytes, then the program will crash with a buffer overflow! +

      + +
      + + +

      +%cstring_output_maxsize(parm, maxparm) +

      + +
      + +

      +This macro is used to handle bounded character output functions where +both a char * and a maximum length parameter are provided. +As input, a user simply supplies the maximum length. +The return value is assumed to be a NULL-terminated string. +

      + +
      +
      +%cstring_output_maxsize(char *path, int maxpath);
+...
+void get_path(char *path, int maxpath);
+
      +
      + +

      +In the target language: +

      + +
      +
      +>>> get_path(1024)
+'/home/beazley/Packages/Foo/Bar'
+>>>
+
      +
      + +

      +This macro provides a safer alternative for functions that need to +write string data into a buffer. User supplied buffer size is +used to dynamically allocate memory on heap. Results are placed +into that buffer and returned as a string object. +

      + +
      + + + +

      +%cstring_output_withsize(parm, maxparm) +

      + +
      + +

      +This macro is used to handle bounded character output functions where +both a char * and a pointer int * are passed. Initially, +the int * parameter points to a value containing the maximum size. +On return, this value is assumed to contain the actual number of bytes. +As input, a user simply supplies the maximum length. The output value is a +string that may contain binary data. +

      + +
      +
      +%cstring_output_withsize(char *data, int *maxdata);
+...
+void get_data(char *data, int *maxdata);
+
      +
      + +

      +In the target language: +

      + +
      +
      +>>> get_data(1024)
+'x627388912'
+>>> get_data(1024)
+'xyzzy'
+>>>
+
      +
      + +

      +This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory +is dynamically allocated and can be arbitrary large. Furthermore, a function can control +how much data is actually returned by changing the value of the maxparm argument. +

      + +
      + + +

      +%cstring_output_allocate(parm, release) +

      + +
      + +

      +This macro is used to return strings that are allocated within the program and +returned in a parameter of type char **. For example: +

      + +
      +
      +void foo(char **s) {
+    *s = (char *) malloc(64);
+    sprintf(*s, "Hello world\n");
+}
+
      +
      + +

      +The returned string is assumed to be NULL-terminated. release +specifies how the allocated memory is to be released (if applicable). Here is an +example: +

      + +
      +
      +%cstring_output_allocate(char **s, free(*$1));
+...
+void foo(char **s);
+
      +
      + +

      +In the target language: +

      + +
      +
      +>>> foo()
+'Hello world\n'
+>>>
+
      +
      +
      + + +

      +%cstring_output_allocate_size(parm, szparm, release) +

      + +
      + +

      +This macro is used to return strings that are allocated within the program and +returned in two parameters of type char ** and int *. For example: +

      + +
      +
      +void foo(char **s, int *sz) {
+    *s = (char *) malloc(64);
+    *sz = 64;
+    // Write some binary data
+    ...
+}
+
      +
      + +

      +The returned string may contain binary data. release +specifies how the allocated memory is to be released (if applicable). Here is an +example: +

      + +
      +
      +%cstring_output_allocate_size(char **s, int *slen, free(*$1));
+...
+void foo(char **s, int *slen);
+
      +
      + +

      +In the target language: +

      + +
      +
      +>>> foo()
+'\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f\xd3\x99\x14V\xec\x06\xea\xa2\x88'
+>>>
+
      +
      + +

      +This is the safest and most reliable way to return binary string data in +SWIG. If you have functions that conform to another prototype, you might +consider wrapping them with a helper function. For example, if you had this: +

      + +
      +
      +char  *get_data(int *len);
+
      +
      + +

      +You could wrap it with a function like this: +

      + +
      +
      +void my_get_data(char **result, int *len) {
+   *result = get_data(len);
+}
+
      +
      +
      + +

      +Comments: +

      + +
        +
      • Support for the cstring.i module depends on the target language. Not all +SWIG modules currently support this library. +
        • + +
      • Reliable handling of raw C strings is a delicate topic. There are many ways +to accomplish this in SWIG. This library provides support for a few common techniques. +
        • + +
      • If used in C++, this library uses new and delete [] for memory +allocation. If using ANSI C, the library uses malloc() and free(). +
        • + +
      • Rather than manipulating char * directly, you might consider using a special string +structure or class instead. +
        • +
      + +

      8.4 STL/C++ Library

      + + +

      +The library modules in this section provide access to parts of the standard C++ library including the STL. +SWIG support for the STL is an ongoing effort. Support is quite comprehensive for some language modules +but some of the lesser used modules do not have quite as much library code written. +

      + +

      +The following table shows which C++ classes are supported and the equivalent SWIG interface library file for the C++ library. +

      + + + + + + + + + + + + + + + + +
      C++ classC++ Library fileSWIG Interface library file
      std::deque deque std_deque.i
      std::list list std_list.i
      std::map map std_map.i
      std::pair utility std_pair.i
      std::set set std_set.i
      std::string string std_string.i
      std::vector vector std_vector.i
      + +

      +The list is by no means complete; some language modules support a subset of the above and some support additional STL classes. +Please look for the library files in the appropriate language library directory. +

      + + +

      8.4.1 std_string.i

      + + +

      +The std_string.i library provides typemaps for converting C++ std::string +objects to and from strings in the target scripting language. For example: +

      + +
      +
      +%module example
+%include "std_string.i"
+
+std::string foo();
+void        bar(const std::string &x);
+
      +
      + +

      +In the target language: +

      + +
      +
      +x = foo();                # Returns a string object
+bar("Hello World");       # Pass string as std::string
+
      +
      + +

      +A common problem that people encounter is that of classes/structures +containing a std::string. This can be overcome by defining a typemap. +For example: +

      + +
      +
      +%module example
+%include "std_string.i"
+
+%apply const std::string& {std::string* foo};
+
+struct my_struct
+{
+  std::string foo;
+};
+
      +
      + +

      +In the target language: +

      + +
      +
      +x = my_struct();
+x.foo="Hello World";      # assign with string
+print x.foo;              # print as string
+
      +
      + +

      +This module only supports types std::string and +const std::string &. Pointers and non-const references +are left unmodified and returned as SWIG pointers. +

      + +

      +This library file is fully aware of C++ namespaces. If you export std::string or rename +it with a typedef, make sure you include those declarations in your interface. For example: +

      + +
      +
      +%module example
+%include "std_string.i"
+
+using namespace std;
+typedef std::string String;
+...
+void foo(string s, const String &t);     // std_string typemaps still applied
+
      +
      + +

      +Note: The std_string library is incompatible with Perl on some platforms. +We're looking into it. +

      + +

      8.4.2 std_vector.i

      + + +

      +The std_vector.i library provides support for the C++ vector class in the STL. +Using this library involves the use of the %template directive. All you need to do is to +instantiate different versions of vector for the types that you want to use. For example: +

      + +
      +
      +%module example
+%include "std_vector.i"
+
+namespace std {
+   %template(vectori) vector<int>;
+   %template(vectord) vector<double>;
+};
+
      +
      + +

      +When a template vector<X> is instantiated a number of things happen: +

      + +
        +
      • A class that exposes the C++ API is created in the target language . +This can be used to create objects, invoke methods, etc. This class is +currently a subset of the real STL vector class. +
        • + +
      • Input typemaps are defined for vector<X>, const vector<X> &, and +const vector<X> *. For each of these, a pointer vector<X> * may be passed or +a native list object in the target language. +
        • + +
      • An output typemap is defined for vector<X>. In this case, the values in the +vector are expanded into a list object in the target language. +
        • + +
      • For all other variations of the type, the wrappers expect to receive a vector<X> * +object in the usual manner. +
        • + +
      • An exception handler for std::out_of_range is defined. +
        • + +
      • Optionally, special methods for indexing, item retrieval, slicing, and element assignment +may be defined. This depends on the target language. +
        • +
      + +

      +To illustrate the use of this library, consider the following functions: +

      + +
      +
      +/* File : example.h */
+
+#include <vector>
+#include <algorithm>
+#include <functional>
+#include <numeric>
+
+double average(std::vector<int> v) {
+    return std::accumulate(v.begin(),v.end(),0.0)/v.size();
+}
+
+std::vector<double> half(const std::vector<double>& v) {
+    std::vector<double> w(v);
+    for (unsigned int i=0; i<w.size(); i++)
+        w[i] /= 2.0;
+    return w;
+}
+
+void halve_in_place(std::vector<double>& v) {
+    std::transform(v.begin(),v.end(),v.begin(),
+                   std::bind2nd(std::divides<double>(),2.0));
+}
+
      +
      + +

      +To wrap with SWIG, you might write the following: +

      + +
      +
      +%module example
+%{
+#include "example.h"
+%}
+
+%include "std_vector.i"
+// Instantiate templates used by example
+namespace std {
+   %template(IntVector) vector<int>;
+   %template(DoubleVector) vector<double>;
+}
+
+// Include the header file with above prototypes
+%include "example.h"
+
      +
      + +

      +Now, to illustrate the behavior in the scripting interpreter, consider this Python example: +

      + +
      +
      +>>> from example import *
+>>> iv = IntVector(4)         # Create an vector<int>
+>>> for i in range(0,4):
+...      iv[i] = i
+>>> average(iv)               # Call method
+1.5
+>>> average([0,1,2,3])        # Call with list
+1.5
+>>> half([1,2,3])             # Half a list
+(0.5,1.0,1.5)
+>>> halve_in_place([1,2,3])   # Oops
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+TypeError: Type error. Expected _p_std__vectorTdouble_t
+>>> dv = DoubleVector(4)
+>>> for i in range(0,4):
+...       dv[i] = i
+>>> halve_in_place(dv)       # Ok
+>>> for i in dv:
+...       print i
+...
+0.0
+0.5
+1.0
+1.5
+>>> dv[20] = 4.5
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+  File "example.py", line 81, in __setitem__
+    def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
+IndexError: vector index out of range
+>>>
+
      +
      + +

      +This library module is fully aware of C++ namespaces. If you use vectors with other names, +make sure you include the appropriate using or typedef directives. For example: +

      + +
      +
      +%include "std_vector.i"
+
+namespace std {
+    %template(IntVector) vector<int>;
+}
+
+using namespace std;
+typedef std::vector Vector;
+
+void foo(vector<int> *x, const Vector &x);
+
      +
      + +

      +Note: This module makes use of several advanced SWIG features including templatized typemaps +and template partial specialization. If you are trying to wrap other C++ code with templates, you +might look at the code contained in std_vector.i. Alternatively, you can show them the code +if you want to make their head explode. +

      + +

      +Note: This module is defined for all SWIG target languages. However argument conversion +details and the public API exposed to the interpreter vary. +

      + +

      +Note: std_vector.i was written by Luigi "The Amazing" Ballabio. +

      + + +

      8.4.3 STL exceptions

      + + +

      +Many of the STL wrapper functions add parameter checking and will throw a language dependent error/exception +should the values not be valid. The classic example is array bounds checking. +The library wrappers are written to throw a C++ exception in the case of error. +The C++ exception in turn gets converted into an appropriate error/exception for the target language. +By and large this handling should not need customising, however, customisation can easily be achieved by supplying appropriate "throws" typemaps. +For example: +

      + +
      +
      +%module example
+%include "std_vector.i"
+%typemap(throws) std::out_of_range {
+  // custom exception handler
+}
+%template(VectInt) std::vector<int>;
+
      +
      + +

      +The custom exception handler might, for example, log the exception then convert it into a specific error/exception for the target language. +

      + +

      +When using the STL it is advisable to add in an exception handler to catch all STL exceptions. +The %exception directive can be used by placing the following code before any other methods or libraries to be wrapped: +

      + +
      +
      +%include "exception.i"
+
+%exception {
+  try {
+    $action
+  } catch (const std::exception& e) {
+    SWIG_exception(SWIG_RuntimeError, e.what());
+  }
+}
+
      +
      + +

      +Any thrown STL exceptions will then be gracefully handled instead of causing a crash. +

      + + +

      8.5 Utility Libraries

      + + +

      8.5.1 exception.i

      + + +

      +The exception.i library provides a language-independent function for raising a run-time +exception in the target language. This library is largely used by the SWIG library writers. +If possible, use the error handling scheme available to your target language as there is greater +flexibility in what errors/exceptions can be thrown. +

      + +

      +SWIG_exception(int code, const char *message) +

      + +
      + +

      +Raises an exception in the target language. code is one of the following symbolic +constants: +

      + +
      +
      +SWIG_MemoryError
+SWIG_IOError
+SWIG_RuntimeError
+SWIG_IndexError
+SWIG_TypeError
+SWIG_DivisionByZero
+SWIG_OverflowError
+SWIG_SyntaxError
+SWIG_ValueError
+SWIG_SystemError
+
      +
      + +

      +message is a string indicating more information about the problem. +

      + +
      + +

      +The primary use of this module is in writing language-independent exception handlers. +For example: +

      + +
      +
      +%include "exception.i"
+%exception std::vector::getitem {
+    try {
+        $action
+    } catch (std::out_of_range& e) {
+        SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
+    }
+}
+
      +
      + + + + diff --git a/Doc/Manual/Lisp.html b/Doc/Manual/Lisp.html new file mode 100644 index 0000000..53cddab --- /dev/null +++ b/Doc/Manual/Lisp.html @@ -0,0 +1,802 @@ + + + +SWIG and Common Lisp + + + + +

      22 SWIG and Common Lisp

      + +
      + +
      + + + + +

      + Common Lisp is a high-level, all-purpose, object-oriented, + dynamic, functional programming language with long history. + Common Lisp is used in many fields, ranging from web development to + finance, and also common in computer science education. + There are more than 9 different implementations of common lisp which + are available, all have different foreign function + interfaces. SWIG currently supports only the Allegro Common + Lisp, Common Foreign Function Interface(CFFI), CLisp and UFFI + foreign function interfaces. +

      +

      22.1 Allegro Common Lisp

      + + +

      + Allegro Common Lisp support in SWIG has been updated to include + support for both C and C++. You can read about the interface + here +

      + +

      22.2 Common Foreign Function Interface(CFFI)

      + + +

      + CFFI, the Common Foreign Function Interface, is a portable foreign + function interface for ANSI Common Lisp systems, similar in + spirit to UFFI. Unlike UFFI, CFFI requires only a small set of + low-level functionality from the Lisp implementation, such as + calling a foreign function by name, allocating foreign memory, + and dereferencing pointers. +

      + +

      + To run the cffi module of SWIG requires very little effort, you + just need to run: +

      +
      +swig -cffi -module module-name   file-name 
+
+
      + +

      + But a better was of using all the power of SWIG is to write SWIG + interface files. Below we will explain how to write interface + files and the various things which you can do with them. +

      + +

      22.2.1 Additional Commandline Options

      + + +

      +The following table list the additional commandline options available for the CLISP module. They can also be seen by using: +

      + +
      +swig -cffi -help 
+
      +
      + + + + + + + + + + + + + + + + + + + + + +
      CFFI specific options
      -generate-typedefIf this option is given then defctype will be used to generate + shortcuts according to the typedefs in the input. +
      -[no]cwrapTurn on or turn off generation of an intermediate C file when + creating a C interface. By default this is only done for C++ code. +
      -[no]swig-lispTurns on or off generation of code for helper lisp macro, functions, + etc. which SWIG uses while generating wrappers. These macros, functions + may still be used by generated wrapper code. +
      + +

      22.2.2 Generating CFFI bindings

      + + +As we mentioned earlier the ideal way to use SWIG is to use interface + files. To illustrate the use of it, lets assume that we have a + file named test.h with the following C code: + +
      +#define y 5
+#define x (y >>  1)
+
+typedef int days;
+
+struct bar {
+  short p, q;
+    char a, b;
+    int *z[1000];
+    struct bar * n;
+};
+  
+struct   bar * my_struct;
+
+struct foo {
+    int a;
+    struct foo * b[100];
+  
+};
+
+int pointer_func(void (*ClosureFun)( void* _fun, void* _data, void* _evt ), int p);
+
+int func123(div_t * p,int **q[100],int r[][1000][10]);
+
+void lispsort_double (int n, double * array);
+
+enum color { RED, BLUE, GREEN};
+
      + +Corresponding to this we will write a simple interface file: +
      +%module test
+
+%include "test.h"
+
+
      + +The generated SWIG Code will be: + +
      +;;;SWIG wrapper code starts here
+
+(cl:defmacro defanonenum (&body enums)
+   "Converts anonymous enums to defconstants."
+  `(cl:progn ,@(cl:loop for value in enums
+                        for index = 0 then (cl:1+ index)
+                        when (cl:listp value) do (cl:setf index (cl:second value)
+                                                          value (cl:first value))
+                        collect `(cl:defconstant ,value ,index))))
+
+(cl:eval-when (:compile-toplevel :load-toplevel)
+  (cl:unless (cl:fboundp 'swig-lispify)
+    (cl:defun swig-lispify (name flag cl:&optional (package cl:*package*))
+      (cl:labels ((helper (lst last rest cl:&aux (c (cl:car lst)))
+                    (cl:cond
+                      ((cl:null lst)
+                       rest)
+                      ((cl:upper-case-p c)
+                       (helper (cl:cdr lst) 'upper
+                               (cl:case last
+                                 ((lower digit) (cl:list* c #\- rest))
+                                 (cl:t (cl:cons c rest)))))
+                      ((cl:lower-case-p c)
+                       (helper (cl:cdr lst) 'lower (cl:cons (cl:char-upcase c) rest)))
+                      ((cl:digit-char-p c)
+                       (helper (cl:cdr lst) 'digit 
+                               (cl:case last
+                                 ((upper lower) (cl:list* c #\- rest))
+                                 (cl:t (cl:cons c rest)))))
+                      ((cl:char-equal c #\_)
+                       (helper (cl:cdr lst) '_ (cl:cons #\- rest)))
+                      (cl:t
+                       (cl:error "Invalid character: ~A" c)))))
+        (cl:let ((fix (cl:case flag
+                        ((constant enumvalue) "+")
+                        (variable "*")
+                        (cl:t ""))))
+          (cl:intern
+           (cl:concatenate
+            'cl:string
+            fix
+            (cl:nreverse (helper (cl:concatenate 'cl:list name) cl:nil cl:nil))
+            fix)
+           package))))))
+
+;;;SWIG wrapper code ends here
+
+
+(cl:defconstant y 5)
+
+(cl:defconstant x (cl:ash 5 -1))
+
+(cffi:defcstruct bar
+	(p :short)
+	(q :short)
+	(a :char)
+	(b :char)
+	(z :pointer)
+	(n :pointer))
+
+(cffi:defcvar ("my_struct" my_struct)
+ :pointer)
+
+(cffi:defcstruct foo
+	(a :int)
+	(b :pointer))
+
+(cffi:defcfun ("pointer_func" pointer_func) :int
+  (ClosureFun :pointer)
+  (p :int))
+
+(cffi:defcfun ("func123" func123) :int
+  (p :pointer)
+  (q :pointer)
+  (r :pointer))
+
+(cffi:defcfun ("lispsort_double" lispsort_double) :void
+  (n :int)
+  (array :pointer))
+
+(cffi:defcenum color
+	:RED
+	:BLUE
+	:GREEN)
+
      + +

      + The SWIG wrapper code refers to the special code which SWIG + may need to use while wrapping C code. You can turn on/off the + generation of this code by using the -[no]swig-lisp + option. You must have noticed that SWIG goes one extra step to + ensure that CFFI does not do automatic lispification of the C + function names. The reason SWIG does this is because quite often + developers want to build a nice CLOS based lispy API, and this one + to one correspondence between C function names and lisp function + name helps. +

      + +

      Maybe you want to have your own convention for generating lisp + function names for corresponding C function names, or you just + want to lispify the names, also, before we forget you want to + export the generated lisp names. To do this, we will use the + SWIG feature directive. +Let's edit the interface file such that the C type "div_t*" is changed + to Lisp type ":my-pointer", we lispify all names, + export everything, and do some more stuff. + +

      +
      +%module test
+
+%typemap(cin) div_t* ":my-pointer";
+
+%feature("intern_function","1");
+%feature("export");
+
+%feature("inline") lispsort_double;
+
+%feature("intern_function", "my-lispify") lispsort_double;
+%rename func123 renamed_cool_func;
+%ignore "pointer_func";
+
+%include "test.h"
+
+
      + +

      +The typemap(cin) ensures that for all arguments which are input + to C with the type "div_t*", the ":my-pointer" type be + used. Similarly typemap(cout) are used for all types which + are returned from C. +

      +

      +The feature intern_function ensures that all C names are + interned using the swig-lispify function. The "1" given + to the feature is optional. The use of feature like + %feature("intern_function","1"); globally enables + interning for everything. If you want to target a single + function, or declaration then use the targeted version of + feature, %feature("intern_function", "my-lispify") + lispsort_double;, here we are using an additional feature + which allows us to use our lispify function. +

      +

      The export feature allows us to export the symbols. The inline + feature declaims the declared function as inline. The rename + directive allows us to change the name(it is useful when + generating C wrapper code for handling overloaded + functions). The ignore directive ignores a certain + declaration. +

      +

      There are several other things which are possible, to see some + example of usage of SWIG look at the Lispbuilder and wxCL + projects. The generated code with 'noswig-lisp' option is: +

      + +
      +(cl:defconstant #.(swig-lispify "y" 'constant) 5)
+
+(cl:export '#.(swig-lispify "y" 'constant))
+
+(cl:defconstant #.(swig-lispify "x" 'constant) (cl:ash 5 -1))
+
+(cl:export '#.(swig-lispify "x" 'constant))
+
+(cffi:defcstruct #.(swig-lispify "bar" 'classname)
+	(#.(swig-lispify "p" 'slotname) :short)
+	(#.(swig-lispify "q" 'slotname) :short)
+	(#.(swig-lispify "a" 'slotname) :char)
+	(#.(swig-lispify "b" 'slotname) :char)
+	(#.(swig-lispify "z" 'slotname) :pointer)
+	(#.(swig-lispify "n" 'slotname) :pointer))
+
+(cl:export '#.(swig-lispify "bar" 'classname))
+
+(cl:export '#.(swig-lispify "p" 'slotname))
+
+(cl:export '#.(swig-lispify "q" 'slotname))
+
+(cl:export '#.(swig-lispify "a" 'slotname))
+
+(cl:export '#.(swig-lispify "b" 'slotname))
+
+(cl:export '#.(swig-lispify "z" 'slotname))
+
+(cl:export '#.(swig-lispify "n" 'slotname))
+
+(cffi:defcvar ("my_struct" #.(swig-lispify "my_struct" 'variable))
+ :pointer)
+
+(cl:export '#.(swig-lispify "my_struct" 'variable))
+
+(cffi:defcstruct #.(swig-lispify "foo" 'classname)
+	(#.(swig-lispify "a" 'slotname) :int)
+	(#.(swig-lispify "b" 'slotname) :pointer))
+
+(cl:export '#.(swig-lispify "foo" 'classname))
+
+(cl:export '#.(swig-lispify "a" 'slotname))
+
+(cl:export '#.(swig-lispify "b" 'slotname))
+
+(cffi:defcfun ("renamed_cool_func" #.(swig-lispify "renamed_cool_func" 'function)) :int
+  (p :my-pointer)
+  (q :pointer)
+  (r :pointer))
+
+(cl:export '#.(swig-lispify "renamed_cool_func" 'function))
+
+(cl:declaim (cl:inline #.(my-lispify "lispsort_double" 'function)))
+
+(cffi:defcfun ("lispsort_double" #.(my-lispify "lispsort_double" 'function)) :void
+  (n :int)
+  (array :pointer))
+
+(cl:export '#.(my-lispify "lispsort_double" 'function))
+
+(cffi:defcenum #.(swig-lispify "color" 'enumname)
+	#.(swig-lispify "RED" 'enumvalue :keyword)
+	#.(swig-lispify "BLUE" 'enumvalue :keyword)
+	#.(swig-lispify "GREEN" 'enumvalue :keyword))
+
+(cl:export '#.(swig-lispify "color" 'enumname))
+
+
      + +

      22.2.3 Generating CFFI bindings for C++ code

      + + +

      This feature to SWIG (for CFFI) is very new and still far from + complete. Pitch in with your patches, bug reports and feature + requests to improve it. +

      +

      Generating bindings for C++ code, requires -c++ option to be + present and it first generates C binding which will wrap the C++ + code, and then generates the + corresponding CFFI wrapper code. In the generated C wrapper + code, you will often want to put your own C code, such as the + code to include various files. This can be done by making use of + "%{" and "%}" as shown below. +

      +
      +%{
+ #include "Test/test.h"
+%}
+
      +

      +Also, while parsing the C++ file and generating C wrapper code SWIG + may need to be able to understand various symbols used in other + header files. To help SWIG in doing this while ensuring that + wrapper code is generated for the target file, use the "import" + directive. The "include" directive specifies the target file for + which wrapper code will be generated. +

      +
      +
+%import "ancillary/header.h"
+
+%include "target/header.h"
+
+
      +Various features which were available for C headers can also be used + here. The target header which we are going to use here is: +
      +namespace OpenDemo {
+  class Test
+    {
+    public:
+        float x;
+        // constructors
+        Test (void) {x = 0;}
+        Test (float X) {x = X;}
+
+        // vector addition
+        Test operator+ (const Test& v) const {return Test (x+v.x);}
+
+      // length squared
+        float lengthSquared (void) const {return this->dot (*this);}
+
+        static float distance (const Test& a, const Test& b){return(a-b).length();}
+
+        inline Test parallelComponent (const Test& unitBasis) const {
+          return unitBasis * projection;
+        }
+
+        Test setYtoZero (void) const {return Test (this->x);}
+
+        static const Test zero;
+    };
+
+
+   inline Test operator* (float s, const Test& v) {return v*s;}
+
+
+    inline std::ostream& operator<< (std::ostream& o, const Test& v)
+    {
+        return o << "(" << v.x << ")";
+    }
+
+
+    inline Test RandomUnitVectorOnXZPlane (void)
+    {
+        return RandomVectorInUnitRadiusSphere().setYtoZero().normalize();
+    }
+}
+
      +

      The interface used is:

      +
      +%module test
+%include "test.cpp"
+
      + +SWIG generates 3 files, the first one is a C wrap which we don't show, + the second is the plain CFFI wrapper which is as shown below: +
      +(cffi:defcfun ("_wrap_Test_x_set" Test_x_set) :void
+  (self :pointer)
+  (x :float))
+
+(cffi:defcfun ("_wrap_Test_x_get" Test_x_get) :float
+  (self :pointer))
+
+(cffi:defcfun ("_wrap_new_Test__SWIG_0" new_Test) :pointer)
+
+(cffi:defcfun ("_wrap_new_Test__SWIG_1" new_Test) :pointer
+  (X :float))
+
+(cffi:defcfun ("_wrap_Test___add__" Test___add__) :pointer
+  (self :pointer)
+  (v :pointer))
+
+(cffi:defcfun ("_wrap_Test_lengthSquared" Test_lengthSquared) :float
+  (self :pointer))
+
+(cffi:defcfun ("_wrap_Test_distance" Test_distance) :float
+  (a :pointer)
+  (b :pointer))
+
+(cffi:defcfun ("_wrap_Test_parallelComponent" Test_parallelComponent) :pointer
+  (self :pointer)
+  (unitBasis :pointer))
+
+(cffi:defcfun ("_wrap_Test_setYtoZero" Test_setYtoZero) :pointer
+  (self :pointer))
+
+(cffi:defcvar ("Test_zero" Test_zero)
+ :pointer)
+
+(cffi:defcfun ("_wrap_delete_Test" delete_Test) :void
+  (self :pointer))
+
+(cffi:defcfun ("_wrap___mul__" __mul__) :pointer
+  (s :float)
+  (v :pointer))
+
+(cffi:defcfun ("_wrap___lshift__" __lshift__) :pointer
+  (o :pointer)
+  (v :pointer))
+
+(cffi:defcfun ("_wrap_RandomUnitVectorOnXZPlane" RandomUnitVectorOnXZPlane) :pointer)
+
      + +The output is pretty good but it fails in disambiguating overloaded + functions such as the constructor, in this case. One way of + resolving this problem is to make the interface use the rename + directiv, but hopefully there are better solutions. + In addition SWIG also generates, a CLOS file + + +
      +(clos:defclass test()
+  ((ff :reader ff-pointer)))
+
+(clos:defmethod (cl:setf x) (arg0 (obj test))
+  (Test_x_set (ff-pointer obj) arg0))
+
+(clos:defmethod x ((obj test))
+  (Test_x_get (ff-pointer obj)))
+
+(cl:shadow "+")
+(clos:defmethod + ((obj test) (self test) (v test))
+  (Test___add__ (ff-pointer obj) (ff-pointer self) (ff-pointer v)))
+
+(clos:defmethod length-squared ((obj test) (self test))
+  (Test_lengthSquared (ff-pointer obj) (ff-pointer self)))
+
+(clos:defmethod parallel-component ((obj test) (self test) (unitBasis test))
+  (Test_parallelComponent (ff-pointer obj) (ff-pointer self) (ff-pointer unitBasis)))
+
+(clos:defmethod set-yto-zero ((obj test) (self test))
+  (Test_setYtoZero (ff-pointer obj) (ff-pointer self)))
+
      + +

      I agree that the CFFI C++ module needs lot more work. But I hope it + provides a starting point, on which you can base your work of + importing C++ libraries to Lisp. +

      +

      +If you have any questions, suggestions, patches, etc., related to CFFI + module feel free to contact us on the SWIG mailing list, and + also please add a "[CFFI]" tag in the subject line. + +

      22.2.4 Inserting user code into generated files

      + + +

      +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 #include "header.h" directive. This can be done +using the SWIG %insert(section) %{ ...code... %} directive: +

      + +
      +
      +%module example
+
+%{
+#include "header.h"
+%}
+
+%include "header.h"
+
+int fact(int n);
+
      +
      + +

      +Additional sections have been added for inserting into the +generated lisp interface file: +

      +
        +
      • lisphead - inserts before type declarations
        • +
      • swiglisp - inserts after type declarations according to + where it appears in the .i file
        • +
      +

      +Note that the block %{ ... %} is effectively a shortcut for +%insert("header") %{ ... %}. +

      + + +

      22.3 CLISP

      + + +

      +CLISP is a feature-loaded + implementation of common lisp which is portable across most of the + operating system environments and hardware. CLISP includes an + interpreter, a compiler, a debugger, CLOS, MOP, a foreign + language interface, i18n, regular expressions, a socket + interface, and more. An X11 interface is available through CLX, + Garnet and CLUE/CLIO. Command line editing is provided by + readline. CLISP runs Maxima, ACL2 and many other Common Lisp + packages. +

      +

      + To run the clisp module of SWIG requires very little effort, you + just need to execute: +

      +
      +swig -clisp -module module-name   file-name 
+
+
      + +

      + Because of the high level nature of the CLISP FFI, the bindings + generated by SWIG may not be absolutely correct, and you may need + to modify them. The good thing is that you don't need to complex + interface file for the CLISP module. The CLISP module tries to + produce code which is both human readable and easily modifyable. +

      +

      22.3.1 Additional Commandline Options

      + + +

      +The following table list the additional commandline options available for the CLISP module. They can also be seen by using: +

      + +
      +swig -clisp -help 
+
      +
      + + + + + + + + + + + + + + + +
      CLISP specific options
      -extern-allIf this option is given then clisp definitions for all the functions
      +and global variables will be created otherwise only definitions for
      + externed functions and variables are created. +
      -generate-typedefIf this option is given then def-c-type will be used to generate
      + shortcuts according to the typedefs in the input. +
      + +

      22.3.2 Details on CLISP bindings

      + + +

      +As mentioned earlier the CLISP bindings generated by SWIG may need + some modifications. The clisp module creates a lisp file with + the same name as the module name. This + lisp file contains a 'defpackage' declaration, with the + package name same as the module name. This package uses the + 'common-lisp' and 'ffi' packages. Also, package exports all + the functions, structures and variables for which an ffi + binding was generated.
      + After generating the defpackage statement, the clisp module also + sets the default language. + +

      +(defpackage :test
+    (:use :common-lisp :ffi)
+  (:export
+   :make-bar
+   :bar-x
+   :bar-y
+   :bar-a
+   :bar-b
+   :bar-z
+   :bar-n
+   :pointer_func
+   :func123
+   :make-cfunr
+   :lispsort_double
+   :test123))
+
+(in-package :test)
+
+(default-foreign-language :stdc)
+
      +

      +The ffi wrappers for functions and variables are generated as shown + below. When functions have arguments of type "double * array", + SWIG doesn't knows whether it is an 'out' argument or it is + an array which will be passed, so SWIG plays it safe by + declaring it as an '(array (ffi:c-ptr DOUBLE-FLOAT))'. For + arguments of type "int **z[100]" where SWIG has more + information, i.e., it knows that 'z' is an array of pointers to + pointers of integers, SWIG defines it to be '(z (ffi:c-ptr + (ffi:c-array (ffi:c-ptr (ffi:c-ptr ffi:int)) 100)))' +

      +
      +extern "C" {
+int pointer_func(void (*ClosureFun)( void* _fun, void* _data, void* _evt ), int y);
+
+int func123(div_t * x,int **z[100],int y[][1000][10]);
+
+void lispsort_double (int n, double * array);
+
+void test123(float x , double y);
+
+}
+
      +
      +(ffi:def-call-out pointer_func
+    (:name "pointer_func")
+  (:arguments (ClosureFun (ffi:c-function (:arguments (arg0 (ffi:c-pointer NIL))
+						      (arg1 (ffi:c-pointer NIL))
+						      (arg2 (ffi:c-pointer NIL)))
+					  (:return-type NIL)))
+	      (y ffi:int))
+  (:return-type ffi:int)
+  (:library +library-name+))
+
+(ffi:def-call-out func123
+    (:name "func123")
+  (:arguments (x (ffi:c-pointer div_t))
+	      (z (ffi:c-ptr (ffi:c-array (ffi:c-ptr (ffi:c-ptr ffi:int)) 100)))
+	      (y (ffi:c-ptr (ffi:c-ptr (ffi:c-array ffi:int (1000 10))))))
+  (:return-type ffi:int)
+  (:library +library-name+))
+
+
+(ffi:def-call-out lispsort_double
+    (:name "lispsort_double")
+  (:arguments (n ffi:int)
+	      (array (ffi:c-ptr DOUBLE-FLOAT)))
+  (:return-type NIL)
+  (:library +library-name+))
+
+(ffi:def-call-out test123
+    (:name "test")
+  (:arguments (x SINGLE-FLOAT)
+	      (y DOUBLE-FLOAT))
+  (:return-type NIL)
+  (:library +library-name+))
+
+
      + +

      +The module also handles strutcures and #define constants as shown + below. SWIG automatically adds the constructors and accessors + created for the struct to the list of symbols exported by the + package. +

      +
      +struct bar {
+    short x, y;
+    char a, b;
+    int *z[1000];
+    struct bar * n;
+};
+
+#define max 1000
+
      +
      +(ffi:def-c-struct bar
+    (x :type ffi:short)
+  (y :type ffi:short)
+  (a :type character)
+  (b :type character)
+  (z :type (ffi:c-array (ffi:c-ptr ffi:int) 1000))
+  (n :type (ffi:c-pointer bar)))
+
+(defconstant max 1000)
+
+
      + +

      22.4 UFFI

      + + + + diff --git a/Doc/Manual/Lua.html b/Doc/Manual/Lua.html new file mode 100644 index 0000000..e66c1c7 --- /dev/null +++ b/Doc/Manual/Lua.html @@ -0,0 +1,1598 @@ + + + +SWIG and Lua + + + + +

      23 SWIG and Lua

      + +
      + +
      + + + + +

      +Lua is an extension programming language designed to support general procedural programming with data description facilities. It also offers good support for object-oriented programming, functional programming, and data-driven programming. Lua is intended to be used as a powerful, light-weight configuration language for any program that needs one. Lua is implemented as a library, written in clean C (that is, in the common subset of ANSI C and C++). Its also a really tiny language, less than 6000 lines of code, which compiles to <100 kilobytes of binary code. It can be found at http://www.lua.org +

      +

      23.1 Preliminaries

      + + +

      +The current SWIG implementation is designed to work with Lua 5.0.x and Lua 5.1.x. It should work with later versions of Lua, but certainly not with Lua 4.0 due to substantial API changes. ((Currently SWIG generated code has only been tested on Windows with MingW, though given the nature of Lua, is should not have problems on other OS's)). It is possible to either static link or dynamic link a Lua module into the interpreter (normally Lua static links its libraries, as dynamic linking is not available on all platforms). +

      +

      23.2 Running SWIG

      + + +

      +Suppose that you defined a SWIG module such as the following: +

      +
      +%module example
+%{
+#include "example.h"
+%}
+int gcd(int x, int y);
+extern double Foo;
+
      +

      +To build a Lua module, run SWIG using the -lua option. +

      +
      +$ swig -lua example.i
+
      +

      +If building a C++ extension, add the -c++ option: +

      +
      +$ swig -c++ -lua example.i
+
      +

      +This creates a C/C++ source file example_wrap.c or example_wrap.cxx. The generated C 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. +

      +

      +The name of the wrapper file is derived from the name of the input file. For example, if the input file is example.i, the name of the wrapper file is example_wrap.c. To change this, you can use the -o option. The wrappered module will export one function "int luaopen_example(lua_State* L)" which must be called to register the module with the Lua interpreter. The name "luaopen_example" depends upon the name of the module. +

      +

      23.2.1 Compiling and Linking and Interpreter

      + + +

      +Normally Lua is embedded into another program and will be statically linked. An extremely simple stand-alone interpreter (min.c) is given below: +

      +
      +#include <stdio.h>
+#include "lua.h"
+#include "lualib.h"
+#include "lauxlib.h"
+
+extern int luaopen_example(lua_State* L); // declare the wrapped module
+
+int main(int argc,char* argv[])
+{
+ lua_State *L;
+ if (argc<2)
+ {
+  printf("%s: <filename.lua>\n",argv[0]);
+  return 0;
+ }
+ L=lua_open();
+ luaopen_base(L);	// load basic libs (eg. print)
+ luaopen_example(L);	// load the wrappered module
+ if (luaL_loadfile(L,argv[1])==0) // load and run the file
+  lua_pcall(L,0,0,0);
+ else
+  printf("unable to load %s\n",argv[1]);
+ lua_close(L);
+ return 0;
+}
+
      +

      +A much improved set of code can be found in the Lua distribution src/lua/lua.c. Include your module, just add the external declaration & add a #define LUA_EXTRALIBS {"example",luaopen_example}, at the relevant place. +

      +

      +The exact commands for compiling and linking vary from platform to platform. Here is a possible set of commands of doing this: +

      +
      +$ swig -lua example.i -o example_wrap.c
+$ gcc -I/usr/include/lua -c min.c -o min.o
+$ gcc -I/usr/include/lua -c example_wrap.c -o example_wrap.o
+$ gcc -c example.c -o example.o
+$ gcc -I/usr/include/lua -L/usr/lib/lua min.o example_wrap.o example.o -o my_lua
+
      + +

      23.2.2 Compiling a dynamic module

      + + +

      +Most, but not all platforms support the dynamic loading of modules (Windows & Linux do). Refer to the Lua manual to determine if your platform supports it. For compiling a dynamically loaded module the same wrapper can be used. The commands will be something like this: +

      +
      +$ swig -lua example.i -o example_wrap.c
+$ gcc -I/usr/include/lua -c example_wrap.c -o example_wrap.o
+$ gcc -c example.c -o example.o
+$ gcc -shared -I/usr/include/lua -L/usr/lib/lua example_wrap.o example.o -o example.so
+
      +

      +The wrappers produced by SWIG can be compiled and linked with Lua 5.1.x. The loading is extremely simple. +

      +
      +require("example")
+
      +

      +For those using Lua 5.0.x, you will also need an interpreter with the loadlib function (such as the default interpreter compiled with Lua). In order to dynamically load a module you must call the loadlib function with two parameters: the filename of the shared library, and the function exported by SWIG. Calling loadlib should return the function, which you then call to initialise the module +

      +
      +my_init=loadlib("example.so","luaopen_example") -- for Unix/Linux
+--my_init=loadlib("example.dll","luaopen_example") -- for Windows
+assert(my_init) -- name sure its not nil
+my_init()       -- call the init fn of the lib
+
      +

      +Or can be done in a single line of Lua code +

      +
      +assert(loadlib("example.so","luaopen_example"))()
+
      + + +

      +If the code didn't work, don't panic. The best thing to do is to copy the module and your interpreter into a single directory and then execute the interpreter and try to manually load the module (take care, all this code is case sensitive). +

      +
      +a,b,c=package.loadlib("example.so","luaopen_example") -- for Unix/Linux
+--a,b,c=package.loadlib("example.dll","luaopen_example") -- for Windows
+print(a,b,c)
+
      +

      +Note: for Lua 5.0:
      +The loadlib() function is in the global namespace, not in package. So its just loadlib(). +

      +

      +if 'a' is a function, this its all working fine, all you need to do is call it +

      +
      +  a()
+
      +

      +to load your library which will add a table 'example' with all the functions added. +

      +

      +If it doesn't work, look at the error messages, in particular mesage 'b'
      + The specified module could not be found.
      +Means that is cannot find the module, check your the location and spelling of the module.
      + The specified procedure could not be found.
      +Means that it loaded the module, but cannot find the named function. Again check the spelling, and if possible check to make sure the functions were exported correctly.
      + 'loadlib' not installed/supported
      +Is quite obvious (Go back and consult the Lua documents on how to enable loadlib for your platform). +

      + + + +

      23.2.3 Using your module

      + + +

      +Assuming all goes well, you will be able to this: +

      +
      +$ ./my_lua
+> print(example.gcd(4,6))
+2
+> print(example.Foo)
+3
+> example.Foo=4
+> print(example.Foo)
+4
+>
+
      + +

      23.3 A tour of basic C/C++ wrapping

      + + +

      +By default, SWIG tries to build a very natural Lua interface to your C/C++ code. This section briefly covers the essential aspects of this wrapping. +

      +

      23.3.1 Modules

      + + +

      +The SWIG module directive specifies the name of the Lua module. If you specify `module example', then everything is wrapped into a Lua table 'example' containing all the functions and variables. When choosing a module name, make sure you don't use the same name as a built-in Lua command or standard module name. +

      +

      23.3.2 Functions

      + + +

      + Global functions are wrapped as new Lua built-in functions. For example, +

      +
      +%module example
+int fact(int n);
      +

      +creates a built-in function example.fact(n) that works exactly like you think it does: +

      + +
      +> print example.fact(4)
+24
+>
+
      +

      +To avoid name collisions, SWIG create a Lua table which it keeps all the functions and global variables in. It is possible to copy the functions out of this and into the global environment with the following code. This can easily overwrite existing functions, so this must be used with care. +

      +
      +> for k,v in pairs(example) do _G[k]=v end
+> print(fact(4))
+24
+>
+
      +

      +It is also possible to rename the module with an assignment. +

      +
      +> e=example
+> print(e.fact(4))
+24
+> print(example.fact(4))
+24
+
      + +

      23.3.3 Global variables

      + + +

      + Global variables (which are linked to C code) are supported, and appear to be just another variable in Lua. However the actual mechanism is more complex. Given a global variable: +

      + +
      %module example
+extern double Foo;
+
      +

      +SWIG will effectively generate two functions example.Foo_set() and example.Foo_get(). It then adds a metatable to the table 'example' to call these functions at the correct time (when you attempt to set or get examples.Foo). Therefore if you were to attempt to assign the global to another variable, you will get a local copy within the interpreter, which is no longer linked to the C code. +

      + +
      +> print(example.Foo)
+3
+> c=example.Foo   -- c is a COPY of example.Foo, not the same thing
+> example.Foo=4
+> print(c)
+3
+> c=5 -- this will not effect the original example.Foo
+> print(example.Foo,c)
+4    5
+
      +

      +Its is therefore not possible to 'move' the global variable into the global namespace as it is with functions. It is however, possible to rename the module with an assignment, to make it more convenient. +

      +
      +> e=example
+> -- e and example are the same table
+> -- so e.Foo and example.Foo are the same thing
+> example.Foo=4
+> print(e.Foo)
+4
+
      +

      +If a variable is marked with the %immutable directive then any attempts to set this variable will cause an Lua error. Given a global variable: +

      + +
      %module example
+%immutable;
+extern double Foo;
+%mutable;
+
      +

      +SWIG will allow the the reading of Foo but when a set attempt is made, an error function will be called. +

      +
      +> print(e.Foo) -- reading works ok
+4
+> example.Foo=40 -- but writing does not
+This variable is immutable
+stack traceback:
+        [C]: ?
+        [C]: ?
+        stdin:1: in main chunk
+        [C]: ?
+
      +

      +For those people who would rather that SWIG silently ignore the setting of immutables (as previous versions of the Lua bindings did), adding a -DSWIGLUA_IGNORE_SET_IMMUTABLE compile option will remove this. +

      +

      +Unlike earlier versions of the binding, it is now possible to add new functions or variables to the module, just as if it were a normal table. This also allows the user to rename/remove existing functions and constants (but not linked variables, mutable or immutable). Therefore users are recommended to be careful when doing so. +

      +
      +> -- example.PI does not exist
+> print(example.PI)
+nil
+> example.PI=3.142 -- new value added
+> print(example.PI)
+3.142
+
      + +

      23.3.4 Constants and enums

      + + +

      +Because Lua doesn't really have the concept of constants, C/C++ constants are not really constant in Lua. They are actually just a copy of the value into the Lua interpreter. Therefore they can be changed just as any other value. For example given some constants: +

      +
      %module example
+%constant int ICONST=42;
+#define    SCONST      "Hello World"
+enum Days{SUNDAY,MONDAY,TUESDAY,WEDNESDAY,THURSDAY,FRIDAY,SATURDAY};
+
      +

      +This is 'effectively' converted into the following Lua code: +

      +
      +example.ICONST=42
+example.SCONST="Hello World"
+example.SUNDAY=0
+....
+
      +

      +Constants are not guaranteed to remain constant in Lua. The name of the constant could be accidentally reassigned to refer to some other object. Unfortunately, there is no easy way for SWIG to generate code that prevents this. You will just have to be careful. +

      +

      23.3.5 Pointers

      + + +

      +C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no problem working with incomplete type information. Given a wrapping of the <file.h> interface: +

      +
      %module example
+
+FILE *fopen(const char *filename, const char *mode);
+int fputs(const char *, FILE *);
+int fclose(FILE *);
+
      +

      +When wrapped, you will be able to use the functions in a natural way from Lua. For example: +

      +
      +> f=example.fopen("junk","w")
+> example.fputs("Hello World",f)
+> example.fclose(f)
+
      +

      +Unlike many scripting languages, Lua has had support for pointers to C/C++ object built in for a long time. They are called 'userdata'. Unlike many other SWIG versions which use some kind of encoded character string, all objects will be represented as a userdata. The SWIG-Lua bindings provides a special function swig_type(), which if given a userdata object will return the type of object pointed to as a string (assuming it was a SWIG wrappered object). +

      +
      +> print(f)
+userdata: 003FDA80
+> print(swig_type(f))
+FILE * -- its a FILE*
+
      +

      +Lua enforces the integrity of its userdata, so it is virtually impossible to corrupt the data. But as the user of the pointer, you are responsible for freeing it, or closing any resources associated with it (just as you would in a C program). This does not apply so strictly to classes & structs (see below). One final note: if a function returns a NULL pointer, this is not encoded as a userdata, but as a Lua nil. +

      +
      +> f=example.fopen("not there","r") -- this will return a NULL in C
+> print(f)
+nil
+
      + +

      23.3.6 Structures

      + + +

      + If you wrap a C structure, it is also mapped to a Lua userdata. By adding a metatable to the userdata, this provides a very natural interface. For example, +

      +
      struct Point{
+  int x,y;
+};
+
      +

      +is used as follows: +

      +
      +> p=example.new_Point()
+> p.x=3
+> p.y=5
+> print(p.x,p.y)
+3       5
+>
+
      +

      +Similar access is provided for unions and the data members of C++ classes.
      +C structures are created using a function new_Point(), but for C++ classes are created using just the name Point(). +

      +

      +If you print out the value of p in the above example, you will see something like this: +

      +
      +> print(p)
+userdata: 003FA320
+
      +

      +Like the pointer in the previous section, this is held as a userdata. However, additional features have been added to make this more usable. SWIG effectivly creates some accessor/mutator functions to get and set the data. These functions will be added to the userdata's metatable. This provides the natural access to the member variables that were shown above (see end of the document for full details). +

      +

      +const members of a structure are read-only. Data members can also be forced to be read-only using the immutable directive. As with other immutable's, setting attempts will be cause an error. For example: +

      +
      struct Foo {
+   ...
+   %immutable;
+   int x;        // Read-only members
+   char *name;
+   %mutable;
+   ...
+};
+
      +

      +The mechanism for managing char* members as well as array members is similar to other languages. It is somewhat cumbersome and should probably be better handled by defining of typemaps (described later). +

      +

      +When a member of a structure is itself a structure, it is handled as a pointer. For example, suppose you have two structures like this: +

      + +
      struct Foo {
+   int a;
+};
+
+struct Bar {
+   Foo f;
+};
+
      +

      +Now, suppose that you access the f attribute of Bar like this: +

      +
      +> b = Bar()
+> x = b.f
+
      +

      +In this case, x is a pointer that points to the Foo that is inside b. This is the same value as generated by this C code: +

      +
      +Bar b;
+Foo *x = &b->f;       // Points inside b
+
      +

      +Because the pointer points inside the structure, you can modify the contents and everything works just like you would expect. For example: +

      +
      +> b = Bar()
+> b.f.a = 3               -- Modify attribute of structure member
+> x = b.f
+> x.a = 3                 -- Modifies the same structure
+
      + +

      23.3.7 C++ classes

      + + +

      +C++ classes are wrapped by a Lua userdata as well. For example, if you have this class, +

      +
      class List {
+public:
+  List();
+  ~List();
+  int  search(char *item);
+  void insert(char *item);
+  void remove(char *item);
+  char *get(int n);
+  int  length;
+};
+
      +

      +you can use it in Lua like this: +

      +
      +> l = example.List()
+> l:insert("Ale")
+> l:insert("Stout")
+> l:insert("Lager")
+> print(l:get(1))
+Stout
+> print(l:length)
+3
+>
+
      +

      +(Note: for calling methods of a class, you use class:method(args), not class.method(args), its an easy mistake to make. However for data attributes it is class.attribute) +

      +

      +Class data members are accessed in the same manner as C structures. Static class members present a special problem for Lua, as Lua doesn't have support for such features. Therefore, SWIG generates wrappers that try to work around some of these issues. To illustrate, suppose you have a class like this: +

      +
      class Spam {
+public:
+   static void foo();
+   static int bar;
+
+};
+
      +

      +In Lua, the static members can be accessed as follows: +

      +
      +> example.Spam_foo()            -- calling Spam::foo()
+> a=example.Spam_bar            -- reading Spam::bar 
+> example.Spam_bar=b            -- writing to Spam::bar
+
      +

      +It is not (currently) possible to access static members of an instance: +

      +
      +> s=example.Spam()      -- s is a Spam instance
+> s.foo()                       -- Spam::foo() via an instance
+                                -- does NOT work
+
      + +

      23.3.8 C++ inheritance

      + + +

      +SWIG is fully aware of issues related to C++ inheritance. Therefore, if you have classes like this +

      +
      class Foo {
+...
+};
+
+class Bar : public Foo {
+...
+};
+
      +

      +And if you have functions like this +

      +
      void spam(Foo *f);
+
      +

      +then the function spam() accepts a Foo pointer or a pointer to any class derived from Foo. +

      +

      +It is safe to use multiple inheritance with SWIG. +

      +

      23.3.9 Pointers, references, values, and arrays

      + + +

      +In C++, there are many different ways a function might receive and manipulate objects. For example: +

      +
      void spam1(Foo *x);      // Pass by pointer
+void spam2(Foo &x);      // Pass by reference
+void spam3(Foo x);       // Pass by value
+void spam4(Foo x[]);     // Array of objects
+
      +

      +In SWIG, there is no detailed distinction like this--specifically, there are only "objects". There are no pointers, references, arrays, and so forth. Because of this, SWIG unifies all of these types together in the wrapper code. For instance, if you actually had the above functions, it is perfectly legal to do this: +

      +
      +> f = Foo()           -- Create a Foo
+> spam1(f)            -- Ok. Pointer
+> spam2(f)            -- Ok. Reference
+> spam3(f)            -- Ok. Value.
+> spam4(f)            -- Ok. Array (1 element)
+
      +

      +Similar behaviour occurs for return values. For example, if you had functions like this, +

      +
      Foo *spam5();
+Foo &spam6();
+Foo  spam7();
+
      +

      +then all three functions will return a pointer to some Foo object. Since the third function (spam7) returns a value, newly allocated memory is used to hold the result and a pointer is returned (Lua will release this memory when the return value is garbage collected). The other two are pointers which are assumed to be managed by the C code and so will not be garbage collected. +

      +

      23.3.10 C++ overloaded functions

      + + +

      +C++ overloaded functions, methods, and constructors are mostly supported by SWIG. For example, if you have two functions like this: +

      +
      void foo(int);
+void foo(char *c);
+
      +

      +You can use them in Lua in a straightforward manner: +

      +
      +> foo(3)           -- foo(int)
+> foo("Hello")     -- foo(char *c)
+
      +

      +However due to Lua's coercion mechanism is can sometimes do strange things. +

      +
      +> foo("3")           -- "3" can be coerced into an int, so it calls foo(int)!
+
      +

      +As this coercion mechanism is an integral part of Lua, there is no easy way to get around this other than renaming of functions (see below). +

      +

      +Similarly, if you have a class like this, +

      +
      class Foo {
+public:
+    Foo();
+    Foo(const Foo &);
+    ...
+};
+
      +

      +you can write Lua code like this: +

      +
      +> f = Foo()          -- Create a Foo
+> g = Foo(f)         -- Copy f
+
      +

      +Overloading support is not quite as flexible as in C++. Sometimes there are methods that SWIG can't disambiguate. For example: +

      +
      void spam(int);
+void spam(short);
+
      +

      +or +

      +
      VOID FOO(bAR *B);
+void foo(Bar &b);
+
      +

      +If declarations such as these appear, you will get a warning message like this: +

      +
      +example.i:12: Warning(509): Overloaded spam(short) is shadowed by spam(int)
+at example.i:11.
+
      +

      + To fix this, you either need to ignore or rename one of the methods. For example: +

      +
      %rename(spam_short) spam(short);
+...
+void spam(int);
+void spam(short);   // Accessed as spam_short
+
      +

      +or +

      +
      %ignore spam(short);
+...
+void spam(int);
+void spam(short);   // Ignored
+
      +

      +SWIG resolves overloaded functions and methods using a disambiguation scheme that ranks and sorts declarations according to a set of type-precedence rules. The order in which declarations appear in the input does not matter except in situations where ambiguity arises--in this case, the first declaration takes precedence. +

      +

      +Please refer to the "SWIG and C++" chapter for more information about overloading. +

      +

      +Dealing with the Lua coercion mechanism, the priority is roughly (integers, floats, strings, userdata). But it is better to rename the functions rather than rely upon the ordering. +

      +

      23.3.11 C++ operators

      + + +

      +Certain C++ overloaded operators can be handled automatically by SWIG. For example, consider a class like this: +

      +
      class Complex {
+private:
+  double rpart, ipart;
+public:
+  Complex(double r = 0, double i = 0) : rpart(r), ipart(i) { }
+  Complex(const Complex &c) : rpart(c.rpart), ipart(c.ipart) { }
+  Complex &operator=(const Complex &c);
+  Complex operator+(const Complex &c) const;
+  Complex operator-(const Complex &c) const;
+  Complex operator*(const Complex &c) const;
+  Complex operator-() const;
+
+  double re() const { return rpart; }
+  double im() const { return ipart; }
+};
+
      +

      +When wrapped, it works like you expect: +

      +
      +> c = Complex(3,4)
+> d = Complex(7,8)
+> e = c + d
+> e:re()
+10.0
+> e:im()
+12.0
+
      +

      +One restriction with operator overloading support is that SWIG is not able to fully handle operators that aren't defined as part of the class. For example, if you had code like this +

      +
      class Complex {
+...
+friend Complex operator+(double, const Complex &c);
+...
+};
+
      +

      +then SWIG doesn't know what to do with the friend function--in fact, it simply ignores it and issues a warning. You can still wrap the operator, but you may have to encapsulate it in a special function. For example: +

      +
      %rename(Complex_add_dc) operator+(double, const Complex &);
+...
+Complex operator+(double, const Complex &c);
+
      +

      +There are ways to make this operator appear as part of the class using the %extend directive. Keep reading. +

      +

      +Also, be aware that certain operators don't map cleanly to Lua, and some Lua operators don't map cleanly to C++ operators. For instance, overloaded assignment operators don't map to Lua semantics and will be ignored, and C++ doesn't support Lua's concatenation operator (..). +

      +

      +In order to keep maximum compatibility within the different languages in SWIG, the Lua bindings uses the same set of operator names as python. Although internally it renames the functions to something else (on order to work with Lua). +

      +The current list of operators which can be overloaded (and the alternative function names) are:

        +
      • __add__ operator+ +
      • __sub__ operator- +
      • __mul__ operator * +
      • __div__ operator/ +
      • __neg__ unary minus +
      • __call__ operator() (often used in functor classes) +
      • __pow__ the exponential fn (no C++ equivalent, Lua uses ^) +
      • __concat__ the concatenation operator (SWIG maps C++'s ~ to Lua's ..) +
      • __eq__ operator== +
      • __lt__ operator< +
      • __le__ operator<= +
      +

      +Note: in Lua, only the equals, less than, and less than equals operators are defined. The other operators (!=,>,>=) are achieved by using a logical not applied to the results of other operators. +

      +

      +The following operators cannot be overloaded (mainly because they are not supported in Lua)

        +
      • ++ and --
      • +=,-=,*= etc
      • % operator (you have to use math.mod)
      • assignment operator
      • all bitwise/logical operations
      +

      +SWIG also accepts the __str__() member function which converts an object to a string. This function should return a const char*, preferably to static memory. This will be used for the print() and tostring() functions in Lua. Assuming the complex class has a function +

      +
      const char* __str__()
+{
+        static char buffer[255];
+        sprintf(buffer,"Complex(%g,%g)",this->re(),this->im());
+        return buffer;
+}
+
      +

      +Then this will support the following code in Lua +

      +
      +> c = Complex(3,4)
+> d = Complex(7,8)
+> e = c + d
+> print(e)
+Complex(10,12)
+> s=tostring(e) -- s is the number in string form
+> print(s)
+Complex(10,12)
+
      +

      +It is also possible to overload the operator[], but currently this cannot be automatically performed. To overload the operator[] you need to provide two functions, __getitem__() and __setitem__() +

      +
      class Complex
+{
+        //....
+        double __getitem__(int i)const; // i is the index, returns the data
+        void __setitem__(int i,double d); // i is the index, d is the data
+};
+
      + +

      23.3.12 Class extension with %extend

      + + +

      + One of the more interesting features of SWIG is that it can extend structures and classes with new methods. In the previous section, the Complex class would have benefited greatly from an __str__() method as well as some repairs to the operator overloading. It can also be used to add additional functions to the class if they are needed. +

      +

      +Take the original Complex class +

      +
      class Complex {
+private:
+  double rpart, ipart;
+public:
+  Complex(double r = 0, double i = 0) : rpart(r), ipart(i) { }
+  Complex(const Complex &c) : rpart(c.rpart), ipart(c.ipart) { }
+  Complex &operator=(const Complex &c);
+  Complex operator+(const Complex &c) const;
+  Complex operator-(const Complex &c) const;
+  Complex operator*(const Complex &c) const;
+  Complex operator-() const;
+
+  double re() const { return rpart; }
+  double im() const { return ipart; }
+};
+
      +

      +Now we extend it with some new code +

      +
      %extend Complex {
+   const char *__str__() {
+       static char tmp[1024];
+       sprintf(tmp,"Complex(%g,%g)", $self->re(),$self->im());
+       return tmp;
+   }
+   bool operator==(const Complex& c)
+   {    return ($self->re()==c.re() && $self->im()==c.im();}
+};
+
      +

      +Now, in Lua +

      +
      +> c = Complex(3,4)
+> d = Complex(7,8)
+> e = c + d
+> print(e)      -- print uses __str__ to get the string form to print
+Complex(10,12)
+> print(e==Complex(10,12))      -- testing the == operator
+true
+> print(e!=Complex(12,12))  -- the != uses the == operator
+true
+
      +

      +Extend works with both C and C++ code, on classes and structs. It does not modify the underlying object in any way---the extensions only show up in the Lua interface. The only item to take note of is the code has to use the '$self' instead of 'this', and that you cannot access protected/private members of the code (as you are not officially part of the class). +

      +

      23.3.13 C++ templates

      + + +

      + C++ templates don't present a huge problem for SWIG. However, in order to create wrappers, you have to tell SWIG to create wrappers for a particular template instantiation. To do this, you use the template directive. For example: +

      +
      %module example
+%{
+#include "pair.h"
+%}
+
+template<class T1, class T2>
+struct pair {
+   typedef T1 first_type;
+   typedef T2 second_type;
+   T1 first;
+   T2 second;
+   pair();
+   pair(const T1&, const T2&);
+  ~pair();
+};
+
+%template(pairii) pair<int,int>;
+
      +

      +In Lua: +

      +
      +> p = example.pairii(3,4)
+> print(p.first,p.second)
+3    4
+
      +

      +Obviously, there is more to template wrapping than shown in this example. More details can be found in the SWIG and C++ chapter. Some more complicated examples will appear later. +

      +

      23.3.14 C++ Smart Pointers

      + + +

      + In certain C++ programs, it is common to use classes that have been wrapped by so-called "smart pointers." Generally, this involves the use of a template class that implements operator->() like this: +

      +
      template<class T> class SmartPtr {
+   ...
+   T *operator->();
+   ...
+}
+
      +

      +Then, if you have a class like this, +

      +
      class Foo {
+public:
+     int x;
+     int bar();
+};
+
      +

      +A smart pointer would be used in C++ as follows: +

      +
      SmartPtr<Foo> p = CreateFoo();   // Created somehow (not shown)
+...
+p->x = 3;                        // Foo::x
+int y = p->bar();                // Foo::bar
+
      +

      +To wrap this, simply tell SWIG about the SmartPtr class and the low-level Foo object. Make sure you instantiate SmartPtr using template if necessary. For example: +

      +
      %module example
+...
+%template(SmartPtrFoo) SmartPtr<Foo>;
+...
+
      +

      +Now, in Lua, everything should just "work": +

      +
      +> p = example.CreateFoo()          -- Create a smart-pointer somehow
+> p.x = 3                          -- Foo::x
+> print(p:bar())                   -- Foo::bar
+
      +

      +If you ever need to access the underlying pointer returned by operator->() itself, simply use the __deref__() method. For example: +

      +
      +> f = p:__deref__()     -- Returns underlying Foo *
+
      + +

      23.3.15 C++ Exceptions

      + + +

      +Lua does not natively support exceptions, but it has errors which are similar. When a Lua function terminates with an error +it returns one value back to the caller. SWIG automatically maps any basic type which is thrown into a Lua error. +Therefore for a function: +

      +
      +int message() throw(const char *) {
+  throw("I died.");
+  return 1;
+}
+
      +

      +SWIG will automatically convert this to a Lua error. +

      + +
      +> message()
+I died.
+stack traceback:
+        [C]: in function 'message'
+        stdin:1: in main chunk
+        [C]: ?
+>
+
      + +

      +If you want to catch an exception, you must use either pcall() or xpcall(), which are documented in the Lua manual. +Using xpcall will allow you to obtain additional debug information (such as a stacktrace). +

      + +
      +> function a() b() end -- function a() calls function b()
+> function b() message() end -- function b() calls C++ function message(), which throws 
+> ok,res=pcall(a)  -- call the function
+> print(ok,res)
+false   I died.
+> ok,res=xpcall(a,debug.traceback)  -- call the function
+> print(ok,res)
+false   I died.
+stack traceback:
+        [C]: in function 'message'
+        runme.lua:70: in function 'b'
+        runme.lua:67: in function <runme.lua:66>
+        [C]: in function 'xpcall'
+        runme.lua:95: in main chunk
+        [C]: ?
+
      + +

      +SWIG is able to throw numeric types, enums, chars, char*'s and std::string's without problem. It has also written typemaps for std::exception and its derived classes, which convert the exception into and error string.

      +

      +However its not so simple for to throw other types of objects. +Thrown objects are not valid outside the 'catch' block. Therefore they cannot be +returned to the interpreter. +The obvious ways to overcome this would be to either return a copy of the object, or so convert the object to a string and +return that. Though it seems obvious to perform the former, in some cases this is not possible, most notably when +SWIG has no information about the object, or the object is not copyable/creatable. +

      +

      +Therefore by default SWIG converts all thrown object into strings and returns them. So given a function: +

      + +
      +void throw_A() throw(A*) {
+  throw new A();
+}
+
      +

      +SWIG will just convert it (poorly) to a string and use that as its error. (Yes its not that useful, but it always works). +

      + +
      +> throw_A()
+object exception:A *
+stack traceback:
+        [C]: in function 'unknown'
+        stdin:1: in main chunk
+        [C]: ?
+>
+
      +

      +To get a more useful behaviour out of SWIG you must either: provide a way to convert your exceptions into strings, or +throw objects which can be copied. +

      +

      +If you have your own class which you want output as a string you will need to add a typemap something like this: +

      +
      +%typemap(throws) my_except
+%{ 
+  lua_pushstring(L,$1.what()); // assuming my_except::what() returns a const char* message
+  SWIG_fail; // trigger the error handler
+%}
+
      +

      +If you wish your exception to be returned to the interpreter, it must firstly be copyable. Then you must have and additional +%apply statement, to inform SWIG to return a copy of this object to the interpreter. For example: +

      +
      +%apply SWIGTYPE EXCEPTION_BY_VAL {Exc}; // tell SWIG to return Exc by value to interpreter
+
+class Exc {
+public:
+  Exc(int c, const char *m) {
+    code = c;
+    strncpy(msg,m,256);
+  }
+  int code;
+  char msg[256];
+};
+
+void throw_exc() throw(Exc) {
+  throw(Exc(42,"Hosed"));
+} 
+
      +

      +Then the following code can be used (note: we use pcall to catch the error so we can process the exception). +

      +
      +> ok,res=pcall(throw_exc)
+> print(ok)
+false
+> print(res)
+userdata: 0003D880
+> print(res.code,res.msg)
+42      Hosed
+>
+
      + +

      +Note: is is also possible (though tedious) to have a function throw several different kinds of exceptions. To process this +will require a pcall, followed by a set of if statements checking the type of the error. +

      +

      +All of this code assumes that your C++ code uses exception specification (which a lot doesn't). +If it doesn't consult the "Exception handling with %catches" section +and the "Exception handling with %exception" section, for more details on how to +add exception specification to functions or globally (respectively). +

      + + +

      23.4 Typemaps

      + + +

      This section explains what typemaps are and the usage of them. The default wrappering behaviour of SWIG is enough in most cases. However sometimes SWIG may need a little additional assistance to know which typemap to apply to provide the best wrappering. This section will be explaining how to use typemaps to best effect

      + +

      23.4.1 What is a typemap?

      + + +

      A typemap is nothing more than a code generation rule that is attached to a specific C datatype. For example, to convert integers from Lua to C, you might define a typemap like this:

      + +
      %module example
+
+%typemap(in) int {
+	$1 = (int) lua_tonumber(L,$input);
+	printf("Received an integer : %d\n",$1);
+}
+%inline %{
+extern int fact(int n);
+%}
+
      + +

      Note: you shouldn't use this typemap, as SWIG already has a typemap for this task. This is purely for example.

      + +

      Typemaps are always associated with some specific aspect of code generation. In this case, the "in" method refers to the conversion of input arguments to C/C++. The datatype int is the datatype to which the typemap will be applied. The supplied C code is used to convert values. In this code a number of special variable prefaced by a $ are used. The $1 variable is placeholder for a local variable of type int. The $input is the index on the Lua stack for the value to be used.

      + +

      When this example is compiled into a Lua module, it operates as follows:

      + +
      > require "example"
+> print(example.fact(6))
+Received an integer : 6
+720
+
      + +

      23.4.2 Using typemaps

      + + +

      There are many ready written typemaps built into SWIG for all common types (int, float, short, long, char*, enum and more), which SWIG uses automatically, with no effort required on your part.

      + +

      However for more complex functions which use input/output parameters or arrays, you will need to make use of <typemaps.i>, which contains typemaps for these situations. For example, consider these functions:

      + +
      void add(int x, int y, int *result) {
+   *result = x + y;
+}
+
+int sub(int *x1, int *y1) {
+   return *x1-*y1;
+}
+
+void swap(int *sx, int *sy) {
+   int t=*sx;
+   *sx=*sy;
+   *sy=t;
+}
+
      + +

      It is clear to the programmer, that 'result' is an output parameter, 'x1' and 'y1' are input parameters and 'sx' and 'sy' are input/output parameters. However is not apparent to SWIG, so SWIG must to informed about which kind they are, so it can wrapper accordingly.

      + +

      One means would be to rename the argument name to help SWIG, eg void add(int x, int y, int *OUTPUT), however it is easier to use the %apply to achieve the same result, as shown below.

      + +
      %include <typemaps.i>
+%apply int* OUTPUT {int *result}; // int *result is output
+%apply int* INPUT {int *x1, int *y1}; // int *x1 and int *y1 are input
+%apply int* INOUT {int *sx, int *sy}; // int *sx and int *sy are input and output
+
+void add(int x, int y, int *result);
+int sub(int *x1, int *y1);
+void swap(int *sx, int *sy);
+
      + +

      When wrapped, it gives the following results:

      + +
      > require "example"
+> print(example.add(1,2))
+3
+> print(demo.sub(1,2))
+-1
+> a,b=1,2
+> c,d=demo.swap(a,b)
+> print(a,b,c,d)
+1       2       2       1
+
      + +

      Notice, that 'result' is not required in the arguments to call the function, as it an output parameter only. For 'sx' and 'sy' they must be passed in (as they are input), but the original value is not modified (Lua does not have a pass by reference feature). The modified results are then returned as two return values. All INPUT/OUTPUT/INOUT arguments will behave in a similar manner.

      + +

      Note: C++ references must be handled exactly the same way. However SWIG will automatically wrap a const int& as an input parameter (since that it obviously input).

      + +

      23.4.3 Typemaps and arrays

      + + +

      Arrays present a challenge for SWIG, because like pointers SWIG does not know whether these are input or output values, nor +does SWIG have any indication of how large an array should be. However with the proper guidance SWIG can easily wrapper +arrays for convenient usage.

      + +

      Given the functions:

      +
      extern void sort_int(int* arr, int len);
+extern void sort_double(double* arr, int len);
+
      + +

      There are basically two ways that SWIG can deal with this. The first way, uses the <carrays.i> library +to create an array in C/C++ then this can be filled within Lua and passed into the function. It works, but its a bit tedious. +More details can be found in the carrays.i documention.

      + +

      The second and more intuitive way, would be to pass a Lua table directly into the function, and have SWIG automatically convert between Lua-table and C-array. Within the <typemaps.i> file there are typemaps ready written to perform this task. To use them is again a matter of using %appy in the correct manner.

      + +

      The wrapper file below, shows both the use of carrays as well as the use of the typemap to wrap arrays.

      + +
      // using the C-array
+%include <carrays.i>
+// this declares a batch of function for manipulating C integer arrays
+%array_functions(int,int)
+
+extern void sort_int(int* arr, int len); // the function to wrap
+
+// using typemaps
+%include <typemaps.i>
+%apply (double *INOUT,int) {(double* arr,int len)};
+
+extern void sort_double(double* arr, int len); // the function to wrap
+
      + +

      Once wrappered, the functions can both be called, though with different ease of use:

      + +
      require "example"
+ARRAY_SIZE=10
+
+-- passing a C array to the sort_int()
+arr=example.new_int(ARRAY_SIZE) -- create the array
+for i=0,ARRAY_SIZE-1 do -- index 0..9 (just like C)
+    example.int_setitem(arr,i,math.random(1000))
+end
+example.sort_int(arr,ARRAY_SIZE)  -- call the function
+example.delete_int(arr) -- must delete the allocated memory
+
+-- use a typemap to call with a Lua-table
+-- one item of note: the typemap creates a copy, rather than edit-in-place
+t={} -- a Lua table
+for i=1,ARRAY_SIZE do -- index 1..10 (Lua style)
+    t[i]=math.random(1000)/10
+end
+t=example.sort_double(t) -- replace t with the result
+
      + +

      Obviously the first version could be made less tedious by writing a Lua function to perform the conversion from a table +to a C-array. The %luacode directive is good for this. See SWIG\Examples\lua\arrays for an example of this.

      + +

      Warning: in C indexes start at ZERO, in Lua indexes start at ONE. SWIG expects C-arrays to be filled for 0..N-1 +and Lua tables to be 1..N, (the indexing follows the norm for the language). In the typemap when it converts the table to an array it quietly changes the indexing accordingly. Take note of this behaviour if you have a C function which returns indexes.

      + +

      Note: SWIG also can support arrays of pointers in a similar manner.

      + +

      23.4.4 Typemaps and pointer-pointer functions

      + + +

      Several C++ libraries use a pointer-pointer functions to create its objects. These functions require a pointer to a pointer which is then filled with the pointer to the new object. Microsoft's COM and DirectX as well as many other libraries have this kind of function. An example is given below:

      + +
      struct iMath;    // some structure
+int Create_Math(iMath** pptr); // its creator (assume it mallocs)
+
      + +

      Which would be used with the following C code:

      + +
      iMath* ptr;
+int ok;
+ok=Create_Math(&ptr);
+// do things with ptr
+//...
+free(ptr); // dispose of iMath
+
      + +

      SWIG has a ready written typemap to deal with such a kind of function in <typemaps.i>. It provides the correct wrappering as well as setting the flag to inform Lua that the object in question should be garbage collected. Therefore the code is simply:

      + +
      %include <typemaps.i>
+%apply SWIGTYPE** OUTPUT{iMath **pptr }; // tell SWIG its an output
+
+struct iMath;    // some structure
+int Create_Math(iMath** pptr); // its creator (assume it mallocs)
+
      + +

      The usage is as follows:

      + +
      ok,ptr=Create_Math() -- ptr is a iMath* which is returned with the int (ok)
+ptr=nil -- the iMath* will be GC'ed as normal
+
      + +

      23.5 Writing typemaps

      + + +

      This section describes how you can modify SWIG's default wrapping behavior for various C/C++ datatypes using the %typemap directive. This is an advanced topic that assumes familiarity with the Lua C API as well as the material in the "Typemaps" chapter.

      + +

      Before proceeding, it should be stressed that writing typemaps is rarely needed unless you want to change some aspect of the wrappering, or to achieve an effect which in not available with the default bindings.

      + +

      Before proceeding, you should read the previous section on using typemaps, as well as read the ready written typemaps found in luatypemaps.swg and typemaps.i. These are both well documented and fairly easy to read. You should not attempt to write your own typemaps until you have read and can understand both of these files (they may well also give you a idea to base your worn on).

      + +

      23.5.1 Typemaps you can write

      + + +

      There are many different types of typemap that can be written, the full list can be found in the "Typemaps" chapter. However the following are the most commonly used ones.

      + +
        +
      • in this is for input arguments to functions
        • +
      • out this is for return types from functions
        • +
      • argout this is for a function argument which is actually returning something
        • +
      • typecheck this is used to determine which overloaded function should be called +(the syntax for the typecheck is different from the typemap, see typemaps for details).
        • +
      + +

      23.5.2 SWIG's Lua-C API

      + + +

      This section explains the SWIG specific Lua-C API. It does not cover the main Lua-C api, as this is well documented and not worth covering.

      + +

      int SWIG_ConvertPtr(lua_State* L,int index,void** ptr,swig_type_info *type,int flags);

      + +
      +This is the standard function used for converting a Lua userdata to a void*. It takes the value at the given index in the Lua state and converts it to a userdata. It will then provide the neccesary type checks, confirming that the pointer is compatible with the type given in 'type'. Then finally setting '*ptr' to the pointer. +If flags is set to SWIG_POINTER_DISOWN, this is will clear any ownership flag set on the object.
      +The returns a value which can be checked with the macro SWIG_IsOK() +
      + +

      void SWIG_NewPointerObj(lua_State* L,void* ptr,swig_type_info *type,int own);

      + +
      +This is the opposite of SWIG_ConvertPtr, as it pushes a new userdata which wrappers the pointer 'ptr' of type 'type'. +The parameter 'own' specifies if the object is owned be Lua and if it is 1 then Lua will GC the object when the userdata is disposed of. +
      + +

      void* SWIG_MustGetPtr(lua_State* L,int index,swig_type_info *type,int flags,int argnum,const char* func_name);

      + +
      +This function is a version of SWIG_ConvertPtr(), except that it will either work, or it will trigger a lua_error() with a text error message. This function is rarely used, and may be deprecated in the future. +
      + +

      SWIG_fail

      + +
      +This macro, when called within the context of a SWIG wrappered function, will jump to the error handler code. This will call any cleanup code (freeing any temp variables) and then triggers a lua_error.
      +A common use for this code is:
      +if (!SWIG_IsOK(SWIG_ConvertPtr( .....)){
+ lua_pushstring(L,"something bad happened");
+ SWIG_fail;
+}
      + +

      SWIG_fail_arg(char* func_name,int argnum,char* type)

      + +
      +This macro, when called within the context of a SWIG wrappered function, will display the error message and jump to the error handler code. The error message is of the form +
      +"Error in func_name (arg argnum), expected 'type' got 'whatever the type was'"
+
      + +

      SWIG_fail_ptr(const char* fn_name,int argnum,swig_type_info* type);

      + +
      +Similar to SWIG_fail_arg, except that it will display the swig_type_info information instead.
      + +

      23.6 Customization of your Bindings

      + + +

      +This section covers adding of some small extra bits to your module to add the last finishing touches. +

      + + + +

      23.6.1 Writing your own custom wrappers

      + + +

      +Sometimes, it may be neccesary to add your own special functions, which bypass the normal SWIG wrappering method, and just use the native Lua API calls. These 'native' functions allow direct adding of your own code into the module. This is performed with the %native directive as follows: +

      +
      %native(my_func) int native_function(lua_State*L);  // registers native_function() with SWIG
+...
+%{
+int native_function(lua_State*L) // my native code
+{
+ ...
+}
+%}
+
      +

      +The %native directive in the above example, tells SWIG that there is a function int native_function(lua_State*L); which is to be added into the module under the name 'my_func'. SWIG will not add any wrappering for this function, beyond adding it into the function table. How you write your code is entirely up to you. +

      + +

      23.6.2 Adding additional Lua code

      + + +

      +As well as adding additional C/C++ code, its also possible to add your own Lua code to the module as well. +This code is executed once all other initialisation, including the %init code has been called. +

      +

      +The directive %luacode adds code into the module which is executed upon loading. Normally you would +use this to add your own functions to the module. Though you could easily perform other tasks. +

      +
      %module example;
+
+%luacode {
+  function example.greet() 
+    print "hello world" 
+  end
+
+  print "Module loaded ok"
+}
+...
+%}
+
      +

      +Notice that the code is not part of the module table. Therefore any references to the module must have the +module name added. +

      +

      +Should there be an error in the Lua code, this will not stop loading of the module. +The default behaviour of SWIG is to print a error message to stderr and then continue. +It is possible to change this behaviour by using a #define SWIG_DOSTRING_FAIL(STR) to +define a different behaviour should the code fail. +

      +

      +Good uses for this feature is adding of new code, or writing helper functions to simplify some of the code. +See Examples/lua/arrays for an example of this code. +

      + +

      23.7 Details on the Lua binding

      + + +

      + In the previous section, a high-level view of Lua wrapping was presented. Obviously a lot of stuff happens behind the scenes to make this happen. This section will explain some of the low-level details on how this is achieved. +

      +

      + If you just want to use SWIG and don't care how it works, then stop reading here. This is going into the guts of the code and how it works. Its mainly for people who need to know whats going on within the code. + +

      + +

      23.7.1 Binding global data into the module.

      + + +

      +Assuming that you had some global data that you wanted to share between C and Lua. How does SWIG do it? +

      +
      %module example;
+extern double Foo;
+
      +

      +SWIG will effectively generate the pair of functions +

      +
      void Foo_set(double);
+double Foo_get();
+
      +

      +At initialisation time, it will then add to the interpreter a table called 'example', which represents the module. It will then add all its functions to the module. (Note: older versions of SWIG actually added the Foo_set() and Foo_get() functions, current implementation does not add these functions any more.) But it also adds a metatable to this table, which has two functions (__index and __newindex) as well as two tables (.get and .set) The following Lua code will show these hidden features. +

      +
      +> print(example)
+table: 003F8F90
+> m=getmetatable(example)
+> table.foreach(m,print)
+.set    table: 003F9088
+.get    table: 003F9038
+__index function: 003F8FE0
+__newindex      function: 003F8FF8
+> g=m['.get']
+> table.foreach(g,print)
+Foo     function: 003FAFD8
+>
+
      +

      +The .get and .set tables are lookups connecting the variable name 'Foo' to the accessor/mutator functions (Foo_set,Foo_get) +

      +

      +The Lua equivalent of the code for the __index and __newindex looks a bit like this +

      +
      +function __index(mod,name)
+        local g=getmetatable(mod)['.get'] -- gets the table
+        if not g then return nil end
+        local f=g[name] -- looks for the function
+        -- calls it & returns the value
+        if type(f)=="function" then return f() end
+        return nil
+end
+
+function __newindex(mod,name,value)
+        local s=getmetatable(mod)['.set'] -- gets the table
+        if not s then return end
+        local f=s[name] -- looks for the function
+        -- calls it to set the value
+        if type(f)=="function" then f(value)
+        else rawset(mod,name,value) end
+end
+
      +

      +That way when you call 'a=example.Foo', the interpreter looks at the table 'example' sees that there is no field 'Foo' and calls __index. This will in turn check in '.get' table and find the existence of 'Foo' and then return the value of the C function call 'Foo_get()'. Similarly for the code 'example.Foo=10', the interpreter will check the table, then call the __newindex which will then check the '.set' table and call the C function 'Foo_set(10)'. +

      +

      23.7.2 Userdata and Metatables

      + + +

      +As mentioned earlier, classes and structures, are all held as pointer, using the Lua 'userdata' structure. This structure is actually a pointer to a C structure 'swig_lua_userdata', which contains the pointer to the data, a pointer to the swig_type_info (an internal SWIG struct) and a flag which marks if the object is to be disposed of when the interpreter no longer needs it. The actual accessing of the object is done via the metatable attached to this userdata. +

      +

      +The metatable is a Lua 5.0 feature (which is also why SWIG cannot wrap Lua 4.0). Its a table which holds a list of functions, operators and attributes. This is what gives the userdata the feeling that it is a real object and not just a hunk of memory. +

      +

      +Given a class +

      +
      %module excpp;
+
+class Point
+{
+public:
+ int x,y;
+ Point(){x=y=0;}
+ ~Point(){}
+ virtual void Print(){printf("Point @%p (%d,%d)\n",this,x,y);}
+};
+
      +

      +SWIG will create a module excpp, with all the various function inside. However to allow the intuitive use of the userdata is also creates up a set of metatables. As seen in the above section on global variables, use of the metatables allows for wrappers to be used intuitively. To save effort, the code creates one metatable per class and stores it inside Lua's registry. Then when an new object is instantiated, the metatable is found in the registry and the userdata associated to the metatable. Currently derived classes make a complete copy of the base classes table and then add on their own additional function. +

      +

      +Some of the internals can be seen by looking at a classes metatable. +

      +
      +> p=excpp.Point()
+> print(p)
+userdata: 003FDB28
+> m=getmetatable(p)
+> table.foreach(m,print)
+.type   Point
+__gc    function: 003FB6C8
+__newindex      function: 003FB6B0
+__index function: 003FB698
+.get    table: 003FB4D8
+.set    table: 003FB500
+.fn     table: 003FB528
+
      +

      +The '.type' attribute is the name of the class. The '.get' and '.set' tables work in a similar manner to the modules, the main difference is the '.fn' table which also holds all the member functions. (The '__gc' function is the classes destructor function) +

      +

      +The Lua equivalent of the code for enabling functions looks a little like this +

      +
      +function __index(obj,name)
+        local m=getmetatable(obj) -- gets the metatable
+        if not m then return nil end
+        local g=m['.get'] -- gets the attribute table
+        if not g then return nil end
+        local f=g[name] -- looks for the get_attribute function
+        -- calls it & returns the value
+        if type(f)=="function" then return f() end
+        -- ok, so it not an attribute, maybe its a function
+        local fn=m['.fn'] -- gets the function table
+        if not fn then return nil end
+        local f=fn[name] -- looks for the function
+        -- if found the fn then return the function
+        -- so the interpreter can call it
+        if type(f)=="function" then return f end
+        return nil
+end
+
      +

      +So when 'p:Print()' is called, the __index looks on the object metatable for a 'Print' attribute, then looks for a 'Print' function. When it finds the function, it returns the function, and then interpreter can call 'Point_Print(p)' +

      +

      +In theory, you can play with this usertable & add new features, but remember that it is a shared table between all instances of one class, and you could very easily corrupt the functions in all the instances. +

      +

      +Note: Both the opaque structures (like the FILE*) and normal wrappered classes/structs use the same 'swig_lua_userdata' structure. Though the opaque structures has do not have a metatable attached, or any information on how to dispose of them when the interpreter has finished with them. +

      +

      +Note: Operator overloads are basically done in the same way, by adding functions such as '__add' & '__call' to the classes metatable. The current implementation is a bit rough as it will add any member function beginning with '__' into the metatable too, assuming its an operator overload. +

      +

      23.7.3 Memory management

      + + +

      +Lua is very helpful with the memory management. The 'swig_lua_userdata' is fully managed by the interpreter itself. This means that neither the C code nor the Lua code can damage it. Once a piece of userdata has no references to it, it is not instantly collected, but will be collected when Lua deems is necessary. (You can force collection by calling the Lua function collectgarbage()). Once the userdata is about to be free'ed, the interpreter will check the userdata for a metatable and for a function '__gc'. If this exists this is called. For all complete types (ie normal wrappered classes & structs) this should exist. The '__gc' function will check the 'swig_lua_userdata' to check for the 'own' field and if this is true (which is will be for all owned data's) it will then call the destructor on the pointer. +

      +

      +It is currently not recommended to edit this field or add some user code, to change the behaviour. Though for those who wish to try, here is where to look. +

      +

      +It is also currently not possible to change the ownership flag on the data (unlike most other scripting languages, Lua does not permit access to the data from within the interpreter) +

      + + diff --git a/Doc/Manual/Makefile b/Doc/Manual/Makefile new file mode 100644 index 0000000..4c90779 --- /dev/null +++ b/Doc/Manual/Makefile @@ -0,0 +1,70 @@ +# Makefile for generating the SWIG documentation +# +# Note that the htmldoc package needs to be installed, but requires patching (using the +# margin-left.patch file from this directory) in order to correctly generate the pdf docs. +# The .html files are first processed and updated with chapter numbering and anchor names +# are added to the HTML headings using the python scripts. The htmldoc program is then +# used to generate the PDF document and single page HTML version of the documentation. +# HTML TIDY (package also known as tidy) is also required and is used as an aid to HTML +# validation. +# +# Additional html validation can be done using the validate target. +# + +# Note the # and " are escaped +HTMLDOC_OPTIONS = "--book --toclevels 4 --no-numbered --toctitle \"Table of Contents\" --title --titleimage swig16.png --linkcolor \#0000ff --linkstyle underline --size Universal --left 0.50in --right 0.50in --top 0.50in --bottom 0.50in --header .t. --footer h.1 --nup 1 --tocheader .t. --tocfooter ..i --portrait --color --no-pscommands --no-xrxcomments --compression=1 --jpeg=0 --fontsize 10.0 --fontspacing 1.2 --headingfont Helvetica --bodyfont Times --headfootsize 10.0 --headfootfont Helvetica --charset iso-8859-1 --links --no-embedfonts --pagemode outline --pagelayout single --firstpage c1 --pageeffect none --pageduration 10 --effectduration 1.0 --no-encryption --permissions all --owner-password \"\" --user-password \"\" --browserwidth 680" + +.PHONY: maketoc check generate all clean validate test + +all: maketoc check generate + +maketoc: CCache.html + python maketoc.py + +CCache.html: ../../CCache/ccache.yo + yodl2html -o CCache.html ../../CCache/ccache.yo + +# Use htmltidy to warn about some HTML errors. Note that it is not used to clean/tidy the HTML, +# it is just used as a primitive HTML checker. +# CCache.html is generated by yodl2html and has a few insignificant problems, so we don't put it through tidy +check: + tidy -errors --gnu-emacs yes -quiet index.html + tidy -errors --gnu-emacs yes -quiet Sections.html + all=`sed '/^#/d' chapters | grep -v CCache.html`; for a in $$all; do tidy -errors --gnu-emacs yes -quiet $$a; done; + +generate: swightml.book swigpdf.book + htmldoc --batch swightml.book || true + htmldoc --batch swigpdf.book || true + python fixstyle.py SWIGDocumentation.html + +swigpdf.book: + echo "#HTMLDOC 1.8.24" > swigpdf.book + echo -t pdf13 -f SWIGDocumentation.pdf $(HTMLDOC_OPTIONS) --stylesheet style.css >> swigpdf.book + echo "Sections.html" >> swigpdf.book + cat chapters >> swigpdf.book + +swightml.book: + echo "#HTMLDOC 1.8.24" > swightml.book + echo -t html -f SWIGDocumentation.html $(HTMLDOC_OPTIONS) >> swightml.book + echo "Sections.html" >> swightml.book + cat chapters >> swightml.book + +clean: clean-baks + rm -f swightml.book + rm -f swigpdf.book + rm -f CCache.html + rm -f SWIGDocumentation.html + rm -f SWIGDocumentation.pdf + +clean-baks: + rm -f *.bak + +test: + grep "href=\".*\.html\"" index.html + grep "href=\".*\.html\"" Sections.html + all=`sed '/^#/d' chapters`; for a in $$all; do grep -l "href=\".*\.html\"" $$a; done; + +# Validating using the WDG offline validator - http://www.htmlhelp.com/tools/validator/offline/ +validate: + all=`sed '/^#/d' chapters`; for a in $$all; do validate --emacs $$a; done; + diff --git a/Doc/Manual/Modula3.html b/Doc/Manual/Modula3.html new file mode 100644 index 0000000..c4e4852 --- /dev/null +++ b/Doc/Manual/Modula3.html @@ -0,0 +1,1067 @@ + + + +SWIG and Modula-3 + + + +

      24 SWIG and Modula-3

      + +
      + +
      + + + + +

      +This chapter describes SWIG's support of +Modula-3. +You should be familiar with the +basics +of SWIG, +especially +typemaps. +

      + +

      24.1 Overview

      + + +

      +The Modula-3 support is 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! +The Modula-3 generator was already useful for interfacing +to the libraries +

      + +
        +
      1. + +PLPlot + +
        2. +
      2. + +FFTW + . +
        3. +
      + + +

      +I took some more time to explain +why I think it's right what I'm doing. +So the introduction got a bit longer than it should ... ;-) +

      + + +

      24.1.1 Why not scripting ?

      + + +

      +SWIG started as wrapper from the fast compiled languages C and C++ +to high level scripting languages like Python. +Although scripting languages are designed +to make programming life easier +by hiding machine internals from the programmer +there are several aspects of today's scripting languages +that are unfavourable in my opinion. +

      + +

      +Besides C, C++, Cluster (a Modula derivate for Amiga computers) +I evaluated several scripting like languages in the past: +Different dialects of BASIC, +Perl, ARexx (a variant of Rexx for Amiga computers), +shell scripts. +I found them too inconsistent, +too weak in distinguishing types, +too weak in encapsulating pieces of code. +Eventually I have started several projects in Python +because of the fine syntax. +But when projects became larger +I lost the track. +I got convinced that one can not have +maintainable code in a language +that is not statically typed. +In fact the main advantages of scripting languages +e.g. matching regular expressions, +complex built-in datatypes like lists, dictionaries, +are not advantages of the language itself +but can be provided by function libraries. +

      + +

      24.1.2 Why Modula-3 ?

      + + +

      +Modula-3 is a compiler language +in the tradition of Niklaus Wirth's Modula 2, +which is in turn a successor of the popular Pascal. +I have chosen Modula-3 +because of its +logical syntax, +strong modularization, +the type system which is very detailed +for machine types compared to other languages. +Of course it supports all of the modern games +like exceptions, objects, garbage collection, threads. +While C++ programmers must +control three languages, +namely the preprocessor, C and ++, +Modula-3 is made in one go +and the language definition is really compact. +

      + +

      +On the one hand Modula-3 can be safe +(but probably less efficient) in normal modules +while providing much static and dynamic safety. +On the other hand you can write efficient +but less safe code in the style of C +within UNSAFE modules. +

      + +

      +Unfortunately Modula's safety and strength +requires more writing than scripting languages do. +Today if I want to safe characters +I prefer Haskell (similar to OCAML) - +it's statically typed, too. +

      + + +

      24.1.3 Why C / C++ ?

      + + +

      +Although it is no problem to write Modula-3 programs +that performs as fast as C +most libraries are not written in Modula-3 but in C. +Fortunately the binary interface of most function libraries +can be addressed by Modula-3. +Even more fortunately even non-C libraries may provide C header files. +This is where SWIG becomes helpful. +

      + +

      24.1.4 Why SWIG ?

      + + +

      +The C headers and the possibility to interface to C libraries +still leaves the work for you +to write Modula-3 interfaces to them. +To make things comfortable you will also need +wrappers that convert between high-level features of Modula-3 +(garbage collecting, exceptions) +and the low level of the C libraries. +

      + +

      +SWIG converts C headers to Modula-3 interfaces for you. +You could call the C functions without loss +of efficiency but it won't be joy +because you could not pass TEXTs +or open arrays and +you would have to process error return codes +rather then exceptions. +But using some typemaps SWIG will also generate +wrappers that bring the whole Modula-3 comfort to you. +If the library API is ill designed +writing appropriate typemaps can be still 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. +

      + +

      + +But you have still a problem: +C library interfaces are often ill. +They lack for certain information +because C compilers wouldn't care about. +You should integrate detailed type information +by adding typedefs and consts +and you should persuade the C library programmer +to add this information to his interface. +Only this way other language users can benefit from your work +and only this way you can easily update your interfaces +when a new library version is released. + +You will realise that writing good SWIG interfaces +is very costly and it will only amortise +when considering evolving libraries. +

      + + +

      +Without SWIG you would probably never consider +to call C++ libraries from Modula-3. +But with SWIG this is worth a consideration. +SWIG can write C wrappers to C++ functions and object methods +that may throw exceptions. +In fact it breaks down C++ libraries to C interfaces +which can be in turn called from Modula-3. +To make it complete you can hide the C interface +with Modula-3 classes and exceptions. +

      + +

      +Although SWIG does the best it can do +it can only serve as a one-way strategy. +That means you can use C++ libraries +with Modula-3 (even with call back functions), +but it's certainly not possible to smoothly +integrate Modula-3 code into a C / C++ project. +

      + + +

      24.2 Conception

      + + +

      24.2.1 Interfaces to C libraries

      + + +

      +Modula-3 has an 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. +

      + + + + + + + + + + + + + + + + + + + +
      C library support integrated in Modula-3
      Pragma <* EXTERNAL *>Precedes a declaration of a PROCEDURE that is implemented +in an external library instead of a Modula-3 module.
      Pragma <* CALLBACK *>Precedes a declaration of a PROCEDURE that should be called +by external library code.
      Module CtypesContains Modula-3 types that match some basic C types.
      Module M3toCContains routines that convert between Modula-3's TEXT type +and C's char * type.
      + +

      +In each run of SWIG the Modula-3 part +generates several files: +

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Module name schemeIdentifier for %insertDescription
      ModuleRaw.i3m3rawintfDeclaration of types that are equivalent to those of the C library, + EXTERNAL procedures as interface to the C library functions
      ModuleRaw.m3m3rawimplAlmost empty.
      Module.i3m3wrapintfDeclaration of comfortable wrappers to the C library functions.
      Module.m3m3wrapimplImplementation 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 WeakRefs + and raises exceptions.
      m3makefilem3makefileAdd 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 m3makefile in each run, + because SWIG must be started for each Modula-3 module it creates. + Thus the m3makefile is overwritten each time. :-( +
      + +

      +Here's a scheme of how the function calls to Modula-3 wrappers +are redirected to C library functions: +

      + + + + + + + + + + + + + + + + + +
      + Modula-3 wrapper
      + Module.i3
      + generated by Modula-3 part of SWIG +
      + + |
      + v +
      + Modula-3 interface to C
      + ModuleRaw.i3
      + generated by Modula-3 part of SWIG +       		--> + C library +
      + + +

      +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 Database, +it is good Modula-3 style to set up one Module with the name Database +where the database type is declared with the name T +and where all functions are declared that operates on it. +

      + +

      +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 (%ignore) +and the principal type must be renamed (%typemap). +

      + + +

      24.2.2 Interfaces to C++ libraries

      + + +

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

      + +

      +Here's a scheme of how the function calls to Modula-3 wrappers +a redirected to C library functions: +

      + + + + + + + + + + + + + + + + + +
      + Modula-3 wrapper
      + Module.i3
      + generated by Modula-3 part of SWIG +       		C++ library
      + + |
      + v +       		+ ^
      + | +
      + Modula-3 interface to C
      + ModuleRaw.i3
      + generated by Modula-3 part of SWIG +       		--> + C interface to C++
      + module_wrap.cxx
      + generated by the SWIG core +
      + +

      +Wrapping C++ libraries arises additional problems: +

      +
        +
      • +Is it sensible to wrap C++ classes with Modula-3 classes? +
        • +
      • +How to find the wrapping Modula-3 class +for a class pointer that is returned by a C++ routine? +
        • +
      • +How to deal with multiple inheritance +which was neglected for Modula-3 for good reasons? +
        • +
      • +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 +Java and +Python. +
        • +
      • +How to manage storage with the garbage collector of Modula-3? +Support for + +%newobject and %typemap(newfree) +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. +
        • +
      • +How to turn C++ exceptions into Modula-3 exceptions? +There's also no support for + +%exception, yet. +
        • +
      + +

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

      + +

      24.3 Preliminaries

      + + +

      24.3.1 Compilers

      + + +

      +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 library file +modula3.swg +may do so. +For testing examples I use Critical Mass cm3. +

      + + +

      24.3.2 Additional Commandline Options

      + + +

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

      + + + + + + + + + + + + + + + + + + + + + +
      Modula-3 specific optionsDescription
      -generateconst <file> +Disable generation of interfaces and wrappers. +Instead write code for computing numeric values of constants +to the specified file. +
      +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 (1 << FLAG_MAXIMIZEWINDOW) +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. +
      +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 double. +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. +
      -generaterename <file> +Disable generation of interfaces and wrappers. +Instead generate suggestions for %rename. +
      +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 %rename directive. +This switch outputs a list of such directives +with a name suggestion generated by a simple heuristic. +
      -generatetypemap <file> +Disable generation of interfaces and wrappers. +Instead generate templates for some basic typemaps. +
      + +

      24.4 Modula-3 typemaps

      + + +

      24.4.1 Inputs and outputs

      + + +

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

      + +

      +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 typemap library +modula3.swg +. +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. +

      + +

      +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 ModuleRaw.i3 or the Module.i3, 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. +

      + +

      +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: +

      +
        +
      • Generate PROCEDURE signature.
        • +
      • Declare local variables.
        • +
      • Convert input values from Modula-3 to C.
        • +
      • Check for input value integrity.
        • +
      • Call the C function.
        • +
      • Check returned values, e.g. error codes.
        • +
      • Convert and write back values into Modula-3 records.
        • +
      • Free temporary storage.
        • +
      • Return values.
        • +
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      TypemapExampleDescription
      m3wrapargvar$1: INTEGER := $1_name; + Declaration of some variables needed for temporary results. +
      m3wrapargconst$1 = "$1_name"; + Declaration of some constant, maybe for debug purposes. +
      m3wrapargrawORD($1_name) + The expression that should be passed as argument to the raw Modula-3 interface function. +
      m3wrapargdirout + Referential arguments can be used for input, output, update. + ??? +
      m3wrapinmodeREADONLY + One of Modula-3 parameter modes + VALUE (or empty), + VAR, + READONLY +
      m3wrapinname + New name of the input argument. +
      m3wrapintype + Modula-3 type of the input argument. +
      m3wrapindefault + Default value of the input argument +
      m3wrapinconv$1 := M3toC.SharedTtoS($1_name); + Statement for converting the Modula-3 input value to C compliant value. +
      m3wrapincheckIF Text.Length($1_name) > 10 THEN RAISE E("str too long"); END; + Check the integrity of the input value. +
      m3wrapoutname + Name of the RECORD field to be used for returning multiple values. + This applies to referential output arguments that shall be turned + into return values. +
      m3wrapouttype + Type of the value that is returned instead of a referential output argument. +
      m3wrapoutconv +
      m3wrapoutcheck +
      m3wrapretraw +
      m3wrapretname +
      m3wraprettype +
      m3wrapretvar +
      m3wrapretconv +
      m3wrapretcheck +
      m3wrapfreeargM3toC.FreeSharedS(str,arg1); + Free resources that were temporarily used in the wrapper. + Since this step should never be skipped, + SWIG will put it in the FINALLY branch + of a TRY .. FINALLY structure. +
      + + +

      24.4.2 Subranges, Enumerations, Sets

      + + +

      +Subranges, enumerations, and sets are machine oriented types +that make Modula very strong and expressive compared +with the type systems of many other languages. +

      + +
        +
      • +Subranges are used for statically restricted choices of integers. +
        • +
      • +Enumerations are used for named choices. +
        • +
      • +Sets are commonly used for flag (option) sets. +
        • +
      + +

      +Using them extensively makes Modula code very safe and readable. +

      + +

      +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 +(#define, const int, enum) +is somewhere used for defining something +that must be handled completely different in Modula-3 +(INTEGER, enumeration, SET). +

      + +

      +I played around with several %features and %pragmas +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. +

      + + +

      24.4.3 Objects

      + + +

      +Declarations of C++ classes are mapped to OBJECT 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. +

      + + +

      24.4.4 Imports

      + + +

      +Pieces of Modula-3 code provided by typemaps +may contain identifiers from foreign modules. +If the typemap m3wrapinconv for blah * +contains code using the function M3toC.SharedTtoS +you may declare %typemap("m3wrapinconv:import") blah * %{M3toC%}. +Then the module M3toC is imported +if the m3wrapinconv typemap for blah * +is used at least once. +Use %typemap("m3wrapinconv:import") blah * %{MyConversions AS M3toC%} +if you need module renaming. +Unqualified import is not supported. +

      + +

      +It is cumbersome to add this typemap to each piece of Modula-3 code. +It is especially useful when writing general typemaps +for the typemap library +modula3.swg +. +For a monolithic module you might be better off +if you add the imports directly: +

      + +
      +
      +%insert(m3rawintf) %{
+IMPORT M3toC;
+%}
+
      + + +

      24.4.5 Exceptions

      + + +

      +Modula-3 provides another possibility +of an output of a function: exceptions. +

      + +

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

      + +

      +The RAISES clause is controlled +by typemaps with the throws extension. +If the typemap m3wrapinconv for blah * +contains code that may raise the exceptions OSError.E +you should declare +%typemap("m3wrapinconv:throws") blah * %{OSError.E%}. +

      + +

      24.4.6 Example

      + + +

      +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: +

      + +
      +         (* %relabel  m3wrapinmode m3wrapinname m3wrapintype  m3wrapindefault *)
+  PROCEDURE Name     (READONLY       str       :    TEXT    :=      ""       )
+              (* m3wrapoutcheck:throws *)
+     : NameResult RAISES {E} =
+    CONST
+      arg1name = "str";                  (* m3wrapargconst *)
+    VAR
+      arg0   : C.char_star;              (* m3wrapretvar *)
+      arg1   : C.char_star;              (* m3wrapargvar *)
+      arg2   : C.int;
+      result : RECORD
+           (*m3wrapretname  m3wraprettype*)
+                 unixPath : TEXT;
+           (*m3wrapoutname  m3wrapouttype*)
+                 checksum : CARDINAL;
+               END;
+    BEGIN
+      TRY
+        arg1 := M3toC.SharedTtoS(str);   (* m3wrapinconv *)
+        IF Text.Length(arg1) > 10 THEN   (* m3wrapincheck *)
+          RAISE E("str too long");
+        END;
+ (* m3wrapretraw           m3wrapargraw *)
+        arg0 := MessyToUnix  (arg1,   arg2);
+        result.unixPath := M3toC.CopyStoT(arg0);  (* m3wrapretconv *)
+        result.checksum := arg2;         (* m3wrapoutconv *)
+        IF result.checksum = 0 THEN      (* m3wrapoutcheck *)
+          RAISE E("invalid checksum");
+        END;
+      FINALLY
+        M3toC.FreeSharedS(str,arg1);     (* m3wrapfreearg *)
+      END;
+    END Name;
+
      + + +

      24.5 More hints to the generator

      + + +

      24.5.1 Features

      + + + + + + + + + + + + + + + + + + +
      FeatureExampleDescription
      multiretval%m3multiretval get_box; or + %feature("modula3:multiretval") get_box;Let the denoted function return a RECORD + rather than a plain value. + This RECORD 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 must have the multiretval feature activated, + but it is explicitly requested from the user to prevent mistakes.
      constnumeric%constnumeric(12) twelve; or + %feature("constnumeric","12") twelve;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 + -generateconst option. + In future it may be generalized to other kind of values + such as strings. +
      + +

      24.5.2 Pragmas

      + + + + + + + + + + + + + + + + + + +
      PragmaExampleDescription
      unsafe%pragma(modula3) unsafe="true";Mark the raw interface modules as UNSAFE. + This will be necessary in many cases.
      library%pragma(modula3) library="m3fftw";Specifies the library name for the wrapper library to be created. + It should be distinct from the name of the library to be wrapped.
      + +

      24.6 Remarks

      + + +
        +
      • +The Modula-3 part of SWIG doesn't try to generate nicely formatted code. +Use m3pp to postprocess the Modula files, +it does a very good job here. +
        • +
      + + + diff --git a/Doc/Manual/Modules.html b/Doc/Manual/Modules.html new file mode 100644 index 0000000..1b628f8 --- /dev/null +++ b/Doc/Manual/Modules.html @@ -0,0 +1,348 @@ + + + +Working with Modules + + + + +

      15 Working with Modules

      + +
      + +
      + + + + +

      15.1 Modules Introduction

      + + +

      +Each invocation of SWIG requires a module name to be specified. +The module name is used to name the resulting target language extension module. +Exactly what this means and and what the name is used for +depends on the target language, for example the name can define +a target language namespace or merely be a useful name for naming files or helper classes. +Essentially, a module comprises target language wrappers for a chosen collection of global variables/functions, structs/classes and other C/C++ types. +

      + +

      +The module name can be supplied in one of two ways. +The first is to specify it with the special %module +directive. This directive must appear at the beginning of the interface file. +The general form of this directive is: +

      + +
      +%module(option1="value1",option2="value2",...) modulename
+
      + +

      +where the modulename is mandatory and the options add one or more optional additional features. +Typically no options are specified, for example: +

      + +
      +%module mymodule
+
      + +

      +The second way to specify the module name is with the -module command line option, for example -module mymodule. +If the module name is supplied on the command line, it overrides the name specified by the +%module directive. +

      + +

      +When first working with SWIG, users commonly start by creating a +single module. That is, you might define a single SWIG interface that +wraps some set of C/C++ code. You then compile all of the generated +wrapper code together and use it. For large applications, however, +this approach is problematic---the size of the generated wrapper code +can be rather large. Moreover, it is probably easier to manage the +target language interface when it is broken up into smaller pieces. +

      + +

      +This chapter describes the problem of using SWIG in programs +where you want to create a collection of modules. +Each module in the collection is created via separate invocations of SWIG. +

      + +

      15.2 Basics

      + + +

      +The basic usage case with multiple modules is when modules do not have +cross-references (ie. when wrapping multiple independent C APIs). In that case, +swig input files should just work out of the box - you simply create multiple +wrapper .cxx files, link them into your application, and insert/load each in the +scripting language runtime as you would do for the single module case. +

      + +

      +A bit more complex is the case in which modules need to share information. +For example, when one module extends the class of another by deriving from +it: +

      + +
      +// File: base.h
+class base {
+public:
+  int foo();
+};
+
      +  + +
      +// File: base_module.i
+%module base_module
+
+%{
+#include "base.h"
+%}
+%include "base.h"
+
      +  + +
      +// File: derived_module.i
+%module derived_module
+
+%import "base_module.i"
+
+%inline %{
+class derived : public base {
+public:
+  int bar();
+};
+%}
+
      + +

      To create the wrapper properly, module derived_module needs to know about the +base class and that its interface is covered in another module. The +line %import "base_module.i" lets SWIG know exactly that. Oftentimes +the .h file is passed to %import instead of the .i, +which unfortunately doesn't work for all language modules. For example, Python requires the +name of module that the base class exists in so that the proxy classes can fully inherit the +base class's methods. Typically you will get a warning when the module name is missing, eg: +

      + +
      +derived_module.i:8: Warning(401): Base class 'base' ignored - unknown module name for base. Either import 
+the appropriate module interface file or specify the name of the module in the %import directive.
+
      + +

      +It is sometimes desirable to import the header file rather than the interface file and overcome +the above warning. +For example in the case of the imported interface being quite large, it may be desirable to +simplify matters and just import a small header file of dependent types. +This can be done by specifying the optional module attribute in the %import directive. +The derived_module.i file shown above could be replaced with the following: + +

      +// File: derived_module.i
+%module derived_module
+
+%import(module="base_module") "base.h"
+
+%inline %{
+class derived : public base {
+public:
+  int bar();
+};
+
      + +

      +Note that "base_module" is the module name and is the same as that specified in %module +in base_module.i as well as the %import in derived_module.i. +

      + +

      +Another issue +to beware of is that multiple dependent wrappers should not be linked/loaded +in parallel from multiple threads as SWIG provides no locking - for more on that +issue, read on. +

      + +

      15.3 The SWIG runtime code

      + + +

      +Many of SWIG's target languages generate a set of functions commonly known as +the "SWIG runtime." These functions are primarily related to the runtime type +system which checks pointer types and performs other tasks such as proper +casting of pointer values in C++. As a general rule, the statically typed target +languages, such as Java, use the language's built in static type checking and +have no need for a SWIG runtime. All the dynamically typed / interpreted +languages rely on the SWIG runtime. +

      + +

      +The runtime functions are private to each SWIG-generated module. That is, the +runtime functions are declared with "static" linkage and are visible only to the +wrapper functions defined in that module. The only problem with this approach is +that when more than one SWIG module is used in the same application, those +modules often need to share type information. This is especially true for C++ +programs where SWIG must collect and share information about inheritance +relationships that cross module boundaries. +

      + +

      +To solve the problem of sharing information across modules, a pointer to the +type information is stored in a global variable in the target language +namespace. During module initialization, type information is loaded into the +global data structure of type information from all modules. +

      + +

      +There are a few trade offs with this approach. This type information is global +across all SWIG modules loaded, and can cause type conflicts between modules +that were not designed to work together. To solve this approach, the SWIG +runtime code uses a define SWIG_TYPE_TABLE to provide a unique type table. This +behavior can be enabled when compiling the generated _wrap.cxx or _wrap.c file +by adding -DSWIG_TYPE_TABLE=myprojectname to the command line argument. +

      + +

      +Then, only modules compiled with SWIG_TYPE_TABLE set to myprojectname will share +type information. So if your project has three modules, all three should be +compiled with -DSWIG_TYPE_TABLE=myprojectname, and then these three modules will +share type information. But any other project's types will not interfere or +clash with the types in your module. +

      + +

      +Another issue relating to the global type table is thread safety. If two modules +try and load at the same time, the type information can become corrupt. SWIG +currently does not provide any locking, and if you use threads, you must make +sure that modules are loaded serially. Be careful if you use threads and the +automatic module loading that some scripting languages provide. One solution is +to load all modules before spawning any threads, or use SWIG_TYPE_TABLE to +separate type tables so they do not clash with each other. +

      + +

      +Lastly, SWIG uses a #define SWIG_RUNTIME_VERSION, located in Lib/swigrun.swg and +near the top of every generated module. This number gets incremented when the +data structures change, so that SWIG modules generated with different versions +can peacefully coexist. So the type structures are separated by the +(SWIG_TYPE_TABLE, SWIG_RUNTIME_VERSION) pair, where by default SWIG_TYPE_TABLE +is empty. Only modules compiled with the same pair will share type information. +

      + +

      15.4 External access to the runtime

      + + +

      As described in The run-time type checker, +the functions SWIG_TypeQuery, SWIG_NewPointerObj, and others sometimes need +to be called. Calling these functions from a typemap is supported, since the typemap code +is embedded into the _wrap.c file, which has those declarations available. If you need +to call the SWIG run-time functions from another C file, there is one header you need +to include. To generate the header that needs to be included, run the following command: + +

      +$ swig -python -external-runtime <filename>
+
      + +

      The filename argument is optional and if it is not passed, then the default filename will +be something like swigpyrun.h, depending on the language. This header file should +be treated like any of the other _wrap.c output files, and should be regenerated when the +_wrap files are. After including this header, your code will be able to call SWIG_TypeQuery, +SWIG_NewPointerObj, SWIG_ConvertPtr and others. The exact argument parameters +for these functions might differ between language modules; please check the language module chapters +for more information.

      + +

      Inside this header the functions are declared static and are included inline into the file, +and thus the file does not need to be linked against any SWIG libraries or code (you might still +need to link against the language libraries like libpython-2.3). Data is shared between this +file and the _wrap.c files through a global variable in the scripting language. It is also +possible to copy this header file along with the generated wrapper files into your own package, +so that you can distribute a package that can be compiled without SWIG installed (this works +because the header file is self-contained, and does not need to link with anything).

      + +

      +This header will also use the -DSWIG_TYPE_TABLE described above, so when +compiling any code which includes the generated header file should define the +SWIG_TYPE_TABLE to be the same as the module whose types you are trying to +access. +

      + +

      15.5 A word of caution about static libraries

      + + +

      +When working with multiple SWIG modules, you should take care not to use static +libraries. For example, if you have a static library libfoo.a and you link a collection +of SWIG modules with that library, each module will get its own private copy of the library code inserted +into it. This is very often NOT what you want and it can lead to unexpected or bizarre program +behavior. When working with dynamically loadable modules, you should try to work exclusively with shared libraries. +

      + +

      15.6 References

      + + +

      +Due to the complexity of working with shared libraries and multiple modules, it might be a good idea to consult +an outside reference. John Levine's "Linkers and Loaders" is highly recommended. +

      + +

      15.7 Reducing the wrapper file size

      + + +

      +Using multiple modules with the %import directive is the most common approach to modularising large projects. +In this way a number of different wrapper files can be generated, thereby avoiding the generation of a single large wrapper file. +There are a couple of alternative solutions for reducing the size of a wrapper file through the use of command line options and features. +

      + +

      +-fcompact
      +This command line option will compact the size of the wrapper file without changing the code generated into the wrapper file. +It simply removes blank lines and joins lines of code together. +This is useful for compilers that have a maximum file size that can be handled. +

      + +

      +-fvirtual
      +This command line option will remove the generation of superfluous virtual method wrappers. +Consider the following inheritance hierarchy: +

      + +
      +
      +struct Base {
+  virtual void method();
+  ...
+};
+
+struct Derived : Base {
+  virtual void method();
+  ...
+};
+
      +
      + +

      +Normally wrappers are generated for both methods, whereas this command line option will suppress the generation of a wrapper for Derived::method. +Normal polymorphic behaviour remains as Derived::method will still be called should you have +a Derived instance and call the wrapper for Base::method. +

      + +

      +%feature("compactdefaultargs")
      +This feature can reduce the number of wrapper methods when wrapping methods with default arguments. The section on default arguments discusses the feature and its limitations. +

      + + + diff --git a/Doc/Manual/Mzscheme.html b/Doc/Manual/Mzscheme.html new file mode 100644 index 0000000..9413bb0 --- /dev/null +++ b/Doc/Manual/Mzscheme.html @@ -0,0 +1,71 @@ + + + + +SWIG and MzScheme + + + + + +

      25 SWIG and MzScheme

      + +
      + +
      + + + + +

      +This section contains information on SWIG's support of MzScheme. + +

      25.1 Creating native MzScheme structures

      + + +

      +Example interface file: +

      + +
      +
      +/* define a macro for the struct creation */
+%define handle_ptr(TYPE,NAME)
+%typemap(argout) TYPE *NAME{
+    Scheme_Object *o = SWIG_NewStructFromPtr($1, $*1_mangle);
+    SWIG_APPEND_VALUE(o);
+}
+
+%typemap(in,numinputs=0) TYPE *NAME (TYPE temp) {
+    $1 = &temp;
+}
+%enddef
+
+/* setup the typemaps for the pointer to an output parameter cntrs */
+handle_ptr(struct diag_cntrs, cntrs);
+
      +
      + +

      +Then in scheme, you can use regular struct access procedures like +

      + +
      +
      +	; suppose a function created a struct foo as 
+	; (define foo (make-diag-cntrs (#x1 #x2 #x3) (make-inspector))
+	; Then you can do
+	(format "0x~x" (diag-cntrs-field1 foo))
+	(format "0x~x" (diag-cntrs-field2 foo))
+	;etc...
+
      +
      + +

      +That's pretty much it. It works with nested structs as well. +

      + + + diff --git a/Doc/Manual/Ocaml.html b/Doc/Manual/Ocaml.html new file mode 100644 index 0000000..b658311 --- /dev/null +++ b/Doc/Manual/Ocaml.html @@ -0,0 +1,991 @@ + + + + SWIG and Ocaml + + + + +

      26 SWIG and Ocaml

      + +
      + +
      + + + + +

      + This chapter describes SWIG's +support of Ocaml. Ocaml is a relatively recent addition to the ML family, +and is a recent addition to SWIG. It's the second compiled, typed +language to be added. Ocaml has widely acknowledged benefits for engineers, +mostly derived from a sophisticated type system, compile-time checking +which eliminates several classes of common programming errors, and good +native performance. While all of this is wonderful, there are well-written +C and C++ libraries that Ocaml users will want to take advantage of as +part of their arsenal (such as SSL and gdbm), as well as their own mature +C and C++ code. SWIG allows this code to be used in a natural, type-safe +way with Ocaml, by providing the necessary, but repetitive glue code +which creates and uses Ocaml values to communicate with C and C++ code. + In addition, SWIG also produces the needed Ocaml source that binds +variants, functions, classes, etc. +

      + +

      +If you're not familiar with the Objective Caml language, you can visit +The Ocaml Website. +

      + +

      26.1 Preliminaries

      + + +

      + SWIG 1.3 works with Ocaml 3.04 and above. Given the choice, + you should use the latest stable release. The SWIG Ocaml module has +been tested on Linux (x86,PPC,Sparc) and Cygwin on Windows. The +best way to determine whether your system will work is to compile the +examples and test-suite which come with SWIG. You can do this by running +make check from the SWIG root directory after installing SWIG. + The Ocaml module has been tested using the system's dynamic linking (the +usual -lxxx against libxxx.so, as well as with Gerd Stolpmann's +Dl package +. The ocaml_dynamic and ocaml_dynamic_cpp targets in the +file Examples/Makefile illustrate how to compile and link SWIG modules that +will be loaded dynamically. This has only been tested on Linux so far. +

      + +

      26.1.1 Running SWIG

      + + +

      + The basics of getting a SWIG Ocaml module up and running + can be seen from one of SWIG's example Makefiles, but is also described + here. To build an Ocaml module, run SWIG using the -ocaml +option. +

      + +
      + 
      +%swig -ocaml example.i
+
      +
      + +

      This will produce 3 files. The file example_wrap.c contains +all of the C code needed to build an Ocaml module. To build the module, +you will compile the file example_wrap.c with ocamlc or +ocamlopt to create the needed .o file. You will need to compile +the resulting .ml and .mli files as well, and do the final link with -custom +(not needed for native link).

      + +

      26.1.2 Compiling the code

      + + +

      +The O'Caml SWIG module now requires you to compile a module (Swig) +separately. In addition to aggregating common SWIG functionality, the Swig +module contains the data structure that represents C/C++ values. This allows +easier data sharing between modules if two or more are combined, because +the type of each SWIG'ed module's c_obj is derived from Swig.c_obj_t. This +also allows SWIG to acquire new conversions painlessly, as well as giving +the user more freedom with respect to custom typing. + + Use ocamlc or ocamlopt to compile your + SWIG interface like: +

      + +
      + 
      +% swig -ocaml -co swig.mli ; swig -ocaml co swig.ml
+% ocamlc -c swig.mli ; ocamlc -c swig.ml
+% ocamlc -c -ccopt "-I/usr/include/foo" example_wrap.c
+% ocamlc -c example.mli
+% ocamlc -c example.ml
+
      +
      + +

      ocamlc is aware of .c files and knows how to handle them. Unfortunately, + it does not know about .cxx, .cc, or .cpp files, so when SWIG is invoked + in C++ mode, you must:

      + +
      + 
      +% cp example_wrap.cxx example_wrap.cxx.c
      % ocamlc -c ... -ccopt -xc++ example_wrap.cxx.c
      % ...
      
+
      +
      + +

      26.1.3 The camlp4 module

      + + +

      +The camlp4 module (swigp4.ml -> swigp4.cmo) contains a simple rewriter which +makes C++ code blend more seamlessly with objective caml code. It's use is +optional, but encouraged. The source file is included in the Lib/ocaml +directory of the SWIG source distribution. You can checkout this file with +"swig -ocaml -co swigp4.ml". You should compile the file with +"ocamlc -I `camlp4 -where` -pp 'camlp4o pa_extend.cmo q_MLast.cmo' -c swigp4.ml" +

      + +

      +The basic principle of the module is to recognize certain non-caml expressions +and convert them for use with C++ code as interfaced by SWIG. The camlp4 +module is written to work with generated SWIG interfaces, and probably isn't +great to use with anything else. +

      + +

      +Here are the main rewriting rules: +

      + + + + + + + + + + + + + + +
      InputRewritten to
      f'( ... ) as in
      atoi'("0") or
      _exit'(0)      		f(C_list [ ... ]) as in
      atoi (C_list [ C_string "0" ]) or
      _exit (C_list [ C_int 0 ])
      object -> method ( ... )(invoke object) "method" (C_list [ ... ])
      +object 'binop argument as in
      +a '+= b      		 +(invoke object) "+=" argument as in
      +(invoke a) "+=" b
      Note that because camlp4 always recognizes << +and >>, they are replaced by lsl and lsr in operator names. +
      +'unop object as in
      +'! a +      		 +(invoke a) "!" C_void
      +Smart pointer access like this
      +object '-> method ( args )
      +      		 +(invoke (invoke object "->" C_void)) +
      +Invoke syntax
      +object . '( ... ) +      		 +(invoke object) "()" (C_list [ ... ]) +
      +Array syntax
      +object '[ 10 ] +      		 +(invoke object) "[]" (C_int 10) +
      +Assignment syntax
      +let a = '10 and b = '"foo" and c = '1.0 and d = 'true +      		 +let a = C_int 10 and b = C_string "foo" and c = C_double 1.0 and d = C_bool true +
      +Cast syntax
      +let a = _atoi '("2") as int
      +let b = (getenv "PATH") to string
      +This works for int, string, float, bool +      		 +let a = get_int (_atoi (C_string "2"))
      +let b = C_string (getenv "PATH") +
      + +

      26.1.4 Using your module

      + + +

      +You can test-drive your module by building a +toplevel ocaml interpreter. Consult the ocaml manual for details. +

      + +

      +When linking any ocaml bytecode with your module, use the -custom + option to build your functions into the primitive list. This + option is not needed when you build native code. +

      + +

      26.1.5 Compilation problems and compiling with C++

      + + +

      +As mentioned above, .cxx files need special +handling to be compiled with ocamlc. Other than that, C code +that uses class as a non-keyword, and C code that is too +liberal with pointer types may not compile under the C++ compiler. +Most code meant to be compiled as C++ will not have problems. +

      + +

      26.2 The low-level Ocaml/C interface

      + + +

      +In order to provide access to overloaded functions, and +provide sensible outputs from them, all C entities are represented as +members of the c_obj type: +

      + +

      +In the code as seen by the typemap +writer, there is a value, swig_result, that always contains the +current return data. It is a list, and must be appended with the +caml_list_append function, or with functions and macros provided by +objective caml.
      +

      + +
      +type c_obj =
+    C_void
+  | C_bool of bool
+  | C_char of char
+  | C_uchar of char
+  | C_short of int
+  | C_ushort of int
+  | C_int of int
+  | C_uint of int32
+  | C_int32 of int32
+  | C_int64 of int64
+  | C_float of float
+  | C_double of float
+  | C_ptr of int64 * int64
+  | C_array of c_obj array
+  | C_list of c_obj list
+  | C_obj of (string -> c_obj -> c_obj)
+  | C_string of string
+  | C_enum of c_enum_t
+
      + +

      + A few functions exist which generate and return these: +

      + +
        +
      • caml_ptr_val receives a c_obj and returns a void *.  This + should be used for all pointer purposes.
        • +
      • caml_long_val receives a c_obj and returns a long.  This + should be used for most integral purposes.
        +
        • +
      • caml_val_ptr receives a void * and returns a c_obj.
        • +
      • caml_val_bool receives a C int and returns a c_obj representing + it's bool value.
        • +
      • caml_val_(u)?(char|short|int|long|float|double) receives an +appropriate C value and returns a c_obj representing it.
        • +
      • caml_val_string receives a char * and returns a string value.
        • +
      • caml_val_string_len receives a char * and a length and returns + a string value.
        • +
      • caml_val_obj receives a void * and an object type and returns + a C_obj, which contains a closure giving method access.
        • + +
      + +

      +Because of this style, a typemap can return any kind of value it +wants from a function.  This enables out typemaps and inout typemaps +to work well.  The one thing to remember about outputting values +is that you must append them to the return list with swig_result = caml_list_append(swig_result,v). +

      + +

      + This function will return a new list that has your element + appended. Upon return to caml space, the fnhelper function + beautifies the result. A list containing a single item degrades to + only that item (i.e. [ C_int 3 ] -> C_int 3), and a list + containing more than one item is wrapped in C_list (i.e. [ C_char + 'a' ; C_char 'b' -> C_list [ C_char 'a' ; C_char b + ]).  This is in order to make return values easier to handle + when functions have only one return value, such as constructors, + and operators.  In addition, string, pointer, and object + values are interchangeable with respect to caml_ptr_val, so you can + allocate memory as caml strings and still use the resulting + pointers for C purposes, even using them to construct simple objects + on. Note, though, that foreign C++ code does not respect the garbage + collector, although the SWIG interface does.

      + +

      + The wild card type that you can use in lots of different ways is + C_obj. It allows you to wrap any type of thing you like as an + object using the same mechanism that the ocaml module + does.  When evaluated in caml_ptr_val, the returned value is + the result of a call to the object's "&" operator, taken as a pointer. +

      +

      + You should only construct values using objective caml, or using the + functions caml_val_* functions provided as static functions to a SWIG + ocaml module, as well as the caml_list_* functions. These functions + provide everything a typemap needs to produce values. In addition, + value items pass through directly, but you must make your own type + signature for a function that uses value in this way. +

      + +

      26.2.1 The generated module

      + + +

      +The SWIG %module directive specifies the name of the Ocaml +module to be generated. If you specified `%module example', +then your Ocaml code will be accessible in the module Example. The +module name is always capitalized as is the ocaml convention. Note +that you must not use any Ocaml keyword to name your module. Remember +that the keywords are not the same as the C++ ones. +

      + +

      +You can introduce extra code into the output wherever you like with SWIG. +These are the places you can introduce code: + + + + + + + +
      "header"This code is inserted near the beginning of the +C wrapper file, before any function definitions.
      "wrapper"This code is inserted in the function definition +section.
      "runtime"This code is inserted near the end of the C wrapper +file.
      "mli"This code is inserted into the caml interface file. +Special signatures should be inserted here. +
      "ml"This code is inserted in the caml code defining the +interface to your C code. Special caml code, as well as any initialization +which should run when the module is loaded may be inserted here. +
      "classtemplate"The "classtemplate" place is special because +it describes the output SWIG will generate for class definitions. +
      + +

      26.2.2 Enums

      + + +

      +SWIG will wrap enumerations as polymorphic variants in the output +Ocaml code, as above in C_enum.  In order to support all +C++-style uses of enums, the function int_to_enum and enum_to_int are +provided for ocaml code to produce and consume these values as +integers.  Other than that, correct uses of enums will not have +a problem.  Since enum labels may overlap between enums, the +enum_to_int and int_to_enum functions take an enum type label as an +argument. Example: +

      + +
      +%module enum_test
+%{
+enum c_enum_type { a = 1, b, c = 4, d = 8 };
+%}
+enum c_enum_type { a = 1, b, c = 4, d = 8 };
+
      + +

      +The output mli contains: +

      + +
      +type c_enum_type = [
+  `unknown
+| `c_enum_type
+]
+type c_enum_tag = [
+  `int of int
+| `a
+| `b
+| `c
+| `d
+]
+val int_to_enum c_enum_type -> int -> c_obj
+val enum_to_int c_enum_type -> c_obj -> c_obj
+
      +
      + +

      + So it's possible to do this: +

      + +
      + 
      +bash-2.05a$ ocamlmktop -custom enum_test_wrap.o enum_test.cmo -o enum_test_top
+bash-2.05a$ ./enum_test_top 
+        Objective Caml version 3.04
+
+# open Enum_test ;;
+# let x = C_enum `a ;;
+val x : Enum_test.c_obj = C_enum `a
+# enum_to_int `c_enum_type x ;;
+- : Enum_test.c_obj = C_int 1
+# int_to_enum `c_enum_type 4 ;;
+- : Enum_test.c_obj = C_enum `c
+
      +
      + +

      26.2.2.1 Enum typing in Ocaml

      + + +

      +The ocaml SWIG module now has support for loading and using multiple SWIG +modules at the same time. This enhances modularity, but presents problems +when used with a language which assumes that each module's types are complete +at compile time. In order to achieve total soundness enum types are now +isolated per-module. The type issue matters when values are shared between +functions imported from different modules. You must convert values to master +values using the swig_val function before sharing them with another module. +

      + +

      26.2.3 Arrays

      + + +

      26.2.3.1 Simple types of bounded arrays

      + + +

      +SWIG has support for array types, but you generally will need to provide +a typemap to handle them. You can currently roll your own, or expand +some of the macros provided (but not included by default) with the SWIG +distribution. +

      + +

      +By including "carray.i", you will get access to some macros that help you +create typemaps for array types fairly easily. +

      + +

      +%make_simple_array_typemap is the easiest way to get access to +arrays of simple types with known bounds in your code, but this only works +for arrays whose bounds are completely specified. +

      + +

      26.2.3.2 Complex and unbounded arrays

      + + +

      +Unfortunately, unbounded arrays and pointers can't be handled in a +completely general way by SWIG, because the end-condition of such an +array can't be predicted. In some cases, it will be by consent +(e.g. an array of four or more chars), sometimes by explicit length +(char *buffer, int len), and sometimes by sentinel value (0,-1,etc.). +SWIG can't predict which of these methods will be used in the array, +so you have to specify it for yourself in the form of a typemap. +

      + +

      26.2.3.3 Using an object

      + + +

      +It's possible to use C++ to your advantage by creating a simple object that +provides access to your array. This may be more desirable in some cases, +since the object can provide bounds checking, etc., that prevents crashes. +

      + +

      +Consider writing an object when the ending condition of your array is complex, +such as using a required sentinel, etc. +

      + +

      26.2.3.4 Example typemap for a function taking float * and int

      + + +

      +This is a simple example in typemap for an array of float, where the +length of the array is specified as an extra parameter. Other such typemaps +will work similarly. In the example, the function printfloats is called with +a float array, and specified length. The actual length reported in the len +argument is the length of the array passed from ocaml, making passing an array +into this type of function convenient. +

      + + + + + +
      tarray.i
      +%module tarray
+%{
+#include <stdio.h>
+
+void printfloats( float *tab, int len ) {
+	int i;
+
+	for( i = 0; i < len; i++ ) {
+		printf( "%f ", tab[i] );
+	}
+
+	printf( "\n" );  
+}
+%}
+
+%typemap(in) (float *tab, int len) {
+    int i;
+    /* $*1_type */
+    $2 = caml_array_len($input);
+    $1 = ($*1_type *)malloc( $2 * sizeof( float ) );
+    for( i = 0; i < $2; i++ ) {
+        $1[i] = caml_double_val(caml_array_nth($input,i));
+    }
+}
+
+void printfloats( float *tab, int len );
+
      Sample Run
      +# open Tarray ;;
+# _printfloats (C_array [| C_double 1.0 ; C_double 3.0 ; C_double 5.6666 |]) ;;
+1.000000 3.000000 5.666600
+- : Tarray.c_obj = C_void
+
      + + +

      26.2.4 C++ Classes

      + + +

      +C++ classes, along with structs and unions are represented by C_obj +(string -> c_obj -> c_obj) wrapped closures.  These objects +contain a method list, and a type, which allow them to be used like +C++ objects. When passed into typemaps that use pointers, they +degrade to pointers through their "&" method.  Every method +an object has is represented as a string in the object's method table, +and each method table exists in memory only once.  In addition +to any other operators an object might have, certain builtin ones are +provided by SWIG: (all of these take no arguments (C_void)) +

      + + + + + + + + + + +
      "~"Delete this object
      "&"Return an ordinary C_ptr value representing this +object's address
      "sizeof"If enabled with ("sizeof"="1") on the module node, +return the object's size in char.
      ":methods"Returns a list of strings containing the names of +the methods this object contains
      ":classof"Returns the name of the class this object belongs +to.
      ":parents"Returns a list of all direct parent classes which +have been wrapped by SWIG.
      "::[parent-class]"Returns a view of the object as the +indicated parent class. This is mainly used internally by the SWIG module, +but may be useful to client programs.
      "[member-variable]"Each member variable is wrapped as a +method with an optional parameter. +Called with one argument, the member variable is set to the value of the +argument. With zero arguments, the value is returned. +
      + +

      +Note that this string belongs to the wrapper object, and not +the underlying pointer, so using create_[x]_from_ptr alters the +returned value for the same object. +

      + +

      26.2.4.1 STL vector and string Example

      + + +

      +Standard typemaps are now provided for STL vector and string. More are in +the works. STL strings are passed just like normal strings, and returned +as strings. STL string references don't mutate the original string, (which +might be surprising), because Ocaml strings are mutable but have fixed +length. Instead, use multiple returns, as in the argout_ref example. +

      + + + + + +
      example.i
      +%module example
+%{
+#include "example.h"
+%}
+
+%include <stl.i>
+
+namespace std {
+        %template(StringVector) std::vector < string >;
+};
+
+%include "example.h"
+
      This example is in Examples/ocaml/stl +
      + +

      +Since there's a makefile in that directory, the example is easy to build. +

      + +

      +Here's a sample transcript of an interactive session using a string vector +after making a toplevel (make toplevel). This example uses the camlp4 +module. +

      + +
      +bash-2.05a$ ./example_top 
+        Objective Caml version 3.06
+
+        Camlp4 Parsing version 3.06
+
+# open Swig ;;
+# open Example ;;
+# let x = new_StringVector '() ;;
+val x : Example.c_obj = C_obj <fun>
+# x -> ":methods" () ;;
+- : Example.c_obj =
+C_list
+ [C_string "nop"; C_string "size"; C_string "empty"; C_string "clear";
+  C_string "push_back"; C_string "[]"; C_string "="; C_string "set";
+  C_string "~"; C_string "&"; C_string ":parents"; C_string ":classof";
+  C_string ":methods"]
+# x -> push_back ("foo") ;;
+- : Example.c_obj = C_void
+# x -> push_back ("bar") ;;
+- : Example.c_obj = C_void
+# x -> push_back ("baz") ;;
+- : Example.c_obj = C_void
+# x '[1] ;;
+- : Example.c_obj = C_string "bar"
+# x -> set (1,"spam") ;;
+- : Example.c_obj = C_void
+# x '[1] ;;
+- : Example.c_obj = C_string "spam"
+# for i = 0 to (x -> size() as int) - 1 do 
+    print_endline ((x '[i to int]) as string) 
+  done ;;
+foo
+bar
+baz
+- : unit = ()
+# 
+
      + +

      26.2.4.2 C++ Class Example

      + + +

      +Here's a simple example using Trolltech's Qt Library: +

      + + + +
      qt.i
      +%module qt
+%{
+#include <qapplication.h>
+#include <qpushbutton.h>
+%}
+class QApplication {
+public:
+        QApplication( int argc, char **argv );
+        void setMainWidget( QWidget *widget );
+        void exec();
+};
+
+class QPushButton {
+public:
+        QPushButton( char *str, QWidget *w );
+        void resize( int x, int y );
+        void show();
+};
+
      + +

      26.2.4.3 Compiling the example

      + + +
      +bash-2.05a$ QTPATH=/your/qt/path
+bash-2.05a$ for file in swig.mli swig.ml swigp4.ml ; do swig -ocaml -co $file ; done
+bash-2.05a$ ocamlc -c swig.mli ; ocamlc -c swig.ml
+bash-2.05a$ ocamlc -I `camlp4 -where` -pp "camlp4o pa_extend.cmo q_MLast.cmo" -c swigp4.ml
+bash-2.05a$ swig -ocaml -c++ -I$QTPATH/include  qt.i
+bash-2.05a$ mv qt_wrap.cxx qt_wrap.c
+bash-2.05a$ ocamlc -c -ccopt -xc++ -ccopt -g -g -ccopt -I$QTPATH/include qt_wrap.c 
+bash-2.05a$ ocamlc -c qt.mli
+bash-2.05a$ ocamlc -c qt.ml
+bash-2.05a$ ocamlmktop -custom swig.cmo -I `camlp4 -where` \
+  camlp4o.cma swigp4.cmo qt_wrap.o qt.cmo -o qt_top -cclib \
+  -L$QTPATH/lib -cclib -lqt
+
      + +

      26.2.4.4 Sample Session

      + + +
      +bash-2.05a$ ./qt_top 
+        Objective Caml version 3.06
+
+        Camlp4 Parsing version 3.06
+
+# open Swig ;;
+# open Qt ;;
+# let a = new_QApplication '(0,0) ;;
+val a : Qt.c_obj = C_obj <fun>
+# let hello = new_QPushButton '("hi",0) ;;
+val hello : Qt.c_obj = C_obj <fun>
+# hello -> resize (100,30) ;;
+- : Qt.c_obj = C_void
+# hello -> show () ;;
+- : Qt.c_obj = C_void
+# a -> exec () ;;
+
      + +

      +Assuming you have a working installation of QT, you will see a window +containing the string "hi" in a button. +

      + +

      26.2.5 Director Classes

      + + +

      26.2.5.1 Director Introduction

      + + +

      +Director classes are classes which allow Ocaml code to override the public +methods of a C++ object. This facility allows the user to use C++ libraries +that require a derived class to provide application specific functionality in +the context of an application or utility framework. +

      + +

      +You can turn on director classes by using an optional module argument like +this: +

      + +
      +%module(directors="1")
+
+...
+
+// Turn on the director class for a specific class like this:
+%feature("director")
+class foo {
+  ...
+};
+
      + +

      26.2.5.2 Overriding Methods in Ocaml

      + + +

      +Because the Ocaml language module treats C++ method calls as calls to a +certain function, all you need to do is to define the function that will +handle the method calls in terms of the public methods of the object, and +any other relevant information. The function new_derived_object +uses a stub class to call your methods in place of the ones provided by the +underlying implementation. The object you receive is the underlying object, +so you are free to call any methods you want from within your derived method. +Note that calls to the underlying object do not invoke Ocaml code. You need +to handle that yourself. +

      + +

      +new_derived_object receives your function, the function that creates +the underlying object, and any constructor arguments, and provides an +object that you can use in any usual way. When C++ code calls one of the +object's methods, the object invokes the Ocaml function as if it had been +invoked from Ocaml, allowing any method definitions to override the C++ ones. +

      + +

      +In this example, I'll examine the objective caml code involved in providing +an overloaded class. This example is contained in Examples/ocaml/shapes. +

      + +

      26.2.5.3 Director Usage Example

      + + + + + +
      example_prog.ml
      +
      +open Swig
+open Example
+
+...
+
+let triangle_class pts ob meth args =
+  match meth with
+      "cover" ->
+        (match args with
+             C_list [ x_arg ; y_arg ] ->
+	     let xa = x_arg as float
+	     and ya = y_arg as float in
+	       (point_in_triangle pts xa ya) to bool
+           | _ -> raise (Failure "cover needs two double arguments."))
+    | _ -> (invoke ob) meth args ;;
+
+let triangle =
+  new_derived_object 
+    new_shape
+    (triangle_class ((0.0,0.0),(0.5,1.0),(1.0,0.0)))
+    '() ;;
+
+let _ = _draw_shape_coverage '(triangle, C_int 60, C_int 20) ;;
+
      + +

      +This is the meat of what you need to do. The actual "class" definition +containing the overloaded method is defined in the function triangle_class. +This is a lot like the class definitions emitted by SWIG, if you look at +example.ml, which is generated when SWIG consumes example.i. Basically, +you are given the arguments as a c_obj and the method name as a string, and +you must intercept the method you are interested in and provide whatever +return value you need. Bear in mind that the underlying C++ code needs the +right return type, or an exception will be thrown. This exception will +generally be Failure, or NotObject. You must call other ocaml methods that +you rely on yourself. Due to the way directors are implemented, method +calls on your object from with ocaml code will always invoke C++ methods +even if they are overridden in ocaml. +

      + +

      +In the example, the draw_shape_coverage function plots the indicated number +of points as either covered (x) or uncovered ( ) between +0 and 1 on the X and Y axes. Your shape implementation can provide any +coverage map it likes, as long as it responds to the "cover" method call +with a boolean return (the underlying method returns bool). This might allow +a tricky shape implementation, such as a boolean combination, to be expressed +in a more effortless style in ocaml, while leaving the "engine" part of the +program in C++. +

      + +

      26.2.5.4 Creating director objects

      + + +

      +The definition of the actual object triangle can be described this way: +

      + +
      +let triangle =
+  new_derived_object 
+    new_shape
+    (triangle_class ((0.0,0.0),(0.5,1.0),(1.0,0.0)))
+    '()
+
      + +

      +The first argument to new_derived_object, new_shape is the method +which returns a shape instance. This function will be invoked with the +third argument will be appended to the argument list [ C_void ]. In the +example, the actual argument list is sent as (C_list [ C_void ; C_void ]). +The augmented constructor for a director class needs the first argument +to determine whether it is being constructed as a derived object, or as +an object of the indicated type only (in this case shape). The +Second argument is a closure that will be added to the final C_obj. +

      + +

      +The actual object passed to the self parameter of the director object will +be a C_director_core, containing a c_obj option ref and a c_obj. The +c_obj provided is the same object that will be returned from new_derived +object, that is, the object exposing the overridden methods. The other part +is an option ref that will have its value extracted before becoming the +ob parameter of your class closure. This ref will contain +None if the C++ object underlying is ever destroyed, and will +consequently trigger an exception when any method is called on the object +after that point (the actual raise is from an inner function used by +new_derived_object, and throws NotObject). This prevents a deleted C++ +object from causing a core dump, as long as the object is destroyed +properly. +

      + +

      26.2.5.5 Typemaps for directors, directorin, directorout, directorargout

      + + +

      +Special typemaps exist for use with directors, the directorin, directorout, directorargout +are used in place of in, out, argout typemaps, except that their +direction is reversed. They provide for you to provide argout values, as +well as a function return value in the same way you provide function arguments, +and to receive arguments the same way you normally receive function returns. +

      + +

      26.2.5.6 directorin typemap

      + + +

      +The directorin typemap is used when you will receive arguments from a call +made by C++ code to you, therefore, values will be translated from C++ to +ocaml. You must provide some valid C_obj value. This is the value your ocaml +code receives when you are called. In general, a simple directorin typemap +can use the same body as a simple out typemap. +

      + +

      26.2.5.7 directorout typemap

      + + +

      +The directorout typemap is used when you will send an argument from your +code back to the C++ caller. That is; directorout specifies a function return +conversion. You can usually use the same body as an in typemap +for the same type, except when there are special requirements for object +ownership, etc. +

      + +

      26.2.5.8 directorargout typemap

      + + +

      +C++ allows function arguments which are by pointer (*) and by reference (&) +to receive a value from the called function, as well as sending one there. +Sometimes, this is the main purpose of the argument given. directorargout +typemaps allow your caml code to emulate this by specifying additional return +values to be put into the output parameters. The SWIG ocaml module is a bit +loose in order to make code easier to write. In this case, your return to +the caller must be a list containing the normal function return first, followed +by any argout values in order. These argout values will be taken from the +list and assigned to the values to be returned to C++ through directorargout typemaps. +In the event that you don't specify all of the necessary values, integral +values will read zero, and struct or object returns have undefined results. +

      + +

      26.2.6 Exceptions

      + + +

      +Catching exceptions is now supported using SWIG's %exception feature. A simple +but not too useful example is provided by the throw_exception testcase in +Examples/test-suite. You can provide your own exceptions, too. +

      + + + diff --git a/Doc/Manual/Octave.html b/Doc/Manual/Octave.html new file mode 100644 index 0000000..7409d78 --- /dev/null +++ b/Doc/Manual/Octave.html @@ -0,0 +1,836 @@ + + + +SWIG and Octave + + + + + + +

      27 SWIG and Octave

      + +
      + +
      + + + + +

      + Octave is a high-level language intended for numerical programming that is mostly compatible with MATLAB. +More information can be found at www.octave.org. +

      + +

      + This chapter is intended to give an introduction to using the module. You should also read the SWIG documentation that is not specific to Octave. +Also, there are a dozen or so examples in the Examples/octave directory, and hundreds in the test suite (Examples/test-suite and Examples/test-suite/octave). +

      + +

      27.1 Preliminaries

      + + +

      +The current SWIG implemention is based on Octave 2.9.12. Support for other versions (in particular the recent 3.0) has not been tested, nor has support for any OS other than Linux. +

      + +

      27.2 Running SWIG

      + + +

      +Let's start with a very simple SWIG interface file: +

      + +
      %module example
+%{
+#include "example.h"
+%}
+int gcd(int x, int y);
+extern double Foo;
      + +

      +To build an Octave module, run SWIG using the -octave option. The -c++ option is required (for now) as Octave itself is written in C++ and thus the wrapper code must also be. +

      + +
      $ swig -octave -c++ example.i
      + +

      +This creates a C/C++ source file example_wrap.cxx. The generated C++ source file contains the low-level wrappers that need to be compiled and linked with the rest of your C/C++ application (in this case, the gcd implementation) to create an extension module. +

      + +

      +The swig command line has a number of options you can use, like to redirect it's output. Use swig --help to learn about these. +

      + +

      27.2.1 Compiling a dynamic module

      + + +

      +Octave modules are DLLs/shared objects having the ".oct" suffix. +Building an oct file is usually done with the mkoctfile command (either within Octave itself, or from the shell). For example, +

      + +
      +$ swig -octave -c++ example.i -o example_wrap.cxx
+$ mkoctfile example_wrap.cxx example.c
+
      + +

      + where example.c is the file containing the gcd() implementation. +

      + +

      + mkoctfile can also be used to extract the build parameters required to invoke the compiler and linker yourself. See the Octave manual and mkoctfile man page. +

      + +

      + mkoctfile will produce example.oct, which contains the compiled extension module. Loading it into Octave is then a matter of invoking +

      + + 
      octave:1> example
      + +

      27.2.2 Using your module

      + + +

      +Assuming all goes well, you will be able to do this: +
      +

      + + 
      $ octave -q
+octave:1> example
+octave:2> example.gcd(4,6)
+ans =  2
+octave:3> example.cvar.Foo
+ans =  3
+octave:4> example.cvar.Foo=4;
+octave:5> example.cvar.Foo
+ans =  4
      + +

      27.3 A tour of basic C/C++ wrapping

      + + +

      27.3.1 Modules

      + + +

      +The SWIG module directive specifies the name of the Octave module. If you specify `module example', then in Octave everything in the module will be accessible under "example", as in the above example. When choosing a module name, make sure you don't use the same name as a built-in Octave command or standard module name. +

      + +

      +When Octave is asked to invoke example, it will try to find the .m or .oct file that defines the function "example". It will thusly find example.oct, that upon loading will register all of the module's symbols. +

      + +

      +Giving this function a parameter "global" will cause it to load all symbols into the global namespace in addition to the example namespace. For example: +

      + + 
      $ octave -q
+octave:1> example("global")
+octave:2> gcd(4,6)
+ans =  2
+octave:3> cvar.Foo
+ans =  3
+octave:4> cvar.Foo=4;
+octave:5> cvar.Foo
+ans =  4 
+
      +

      + It is also possible to rename the module namespace with an assignment, as in:
      + 

      octave:1> example;
+octave:2> c=example;
+octave:3> c.gcd(10,4)
+ans =  2
      + +

      +All global variables are put into the cvar namespace object. This is accessible either as my_module.cvar, or just cvar (if the module is imported into the global namespace). +

      +

      +One can also rename it by simple assignment, e.g., +

      +
      +octave:1> some_vars = cvar;
+
      + +

      27.3.2 Functions

      + + +

      +Global functions are wrapped as new Octave built-in functions. For example, +

      + + 
      %module example
+int fact(int n);
      + +

      + creates a built-in function example.fact(n) that works exactly like you think it does: +

      + + 
      octave:1> example.fact(4)
+24
      + +

      27.3.3 Global variables

      + + +

      + Global variables are a little special in Octave. Given a global variable: +

      + + 
      %module example
+extern double Foo;
+
      + +

      + To expose variables, SWIG actually generates two functions, to get and set the value. In this case, Foo_set and Foo_set would be generated. SWIG then automatically calls these functions when you get and set the variable-- in the former case creating a local copy in the interpreter of the C variables, and in the latter case copying an interpreter variables onto the C variable. +

      + + 
      octave:1> example;
+octave:2> c=example.cvar.Foo
+c =  3
+octave:3> example.cvar.Foo=4;
+octave:4> c
+c =  3
+octave:5> example.cvar.Foo
+ans =  4
      + +

      +If a variable is marked with the %immutable directive then any attempts to set this variable will cause an Octave error. Given a global variable: +

      + + 
      %module example
+%immutable;
+extern double Foo;
+%mutable;
+
      + +

      + SWIG will allow the the reading of Foo but when a set attempt is made, an error function will be called. +

      + + 
      octave:1> example
+octave:2> example.Foo=4
+error: attempt to set immutable member variable
+error: assignment failed, or no method for `swig_type = scalar'
+error: evaluating assignment expression near line 2, column 12
      + +

      + It is possible to add new functions or variables to the module. This also allows the user to rename/remove existing functions and constants (but not linked variables, mutable or immutable). Therefore users are recommended to be careful when doing so. +

      + + 
      octave:1> example;
+octave:2> example.PI=3.142;
+octave:3> example.PI
+ans =  3.1420
      + +

      27.3.4 Constants and enums

      + + +

      + Because Octave doesn't really have the concept of constants, C/C++ constants are not really constant in Octave. They are actually just a copy of the value into the Octave interpreter. Therefore they can be changed just as any other value. For example given some constants: +

      + + 
      %module example
+%constant int ICONST=42;
+#define    SCONST      "Hello World"
+enum Days{SUNDAY,MONDAY,TUESDAY,WEDNESDAY,THURSDAY,FRIDAY,SATURDAY};
+
      + +

      + This is 'effectively' converted into the following Octave code: +

      + + 
      example.ICONST=42
+example.SCONST="Hello World"
+example.SUNDAY=0
+....
      + +

      27.3.5 Pointers

      + + +

      + C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no problem working with incomplete type information. Given a wrapping of the <file.h> interface: + C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no problem working with incomplete type information. Given a wrapping of the <file.h> interface: +

      + +
      %module example
+FILE *fopen(const char *filename, const char *mode);
+int fputs(const char *, FILE *);
+int fclose(FILE *);
+
      + +

      +When wrapped, you will be able to use the functions in a natural way from Octave. For example: +

      + +
      +octave:1> example;
+octave:2> f=example.fopen("w","junk");
+octave:3> example.fputs("Hello world",f);
+octave:4> example.fclose(f);
+
      + +

      + Simply printing the value of a wrapped C++ type will print it's typename. E.g., +

      + + 
      octave:1> example;
+octave:2> f=example.fopen("junk","w");
+octave:3> f
+f =
+
+{
+  _p_FILE, ptr = 0x9b0cd00
+}
      + +

      + As the user of the pointer, you are responsible for freeing it, or closing any resources associated with it (just as you would in a C program). This does not apply so strictly to classes and structs (see below). +

      + + 
      octave:1> example;
+octave:2> f=example.fopen("not there","r");
+error: value on right hand side of assignment is undefined
+error: evaluating assignment expression near line 2, column 2
      + +

      27.3.6 Structures and C++ classes

      + + +

      + SWIG wraps C structures and C++ classes by using a special Octave type called a swig_ref. A swig_ref contains a reference to one or more instances of C/C++ objects, or just the type information for an object. +For each wrapped structure and class, a swig_ref will be exposed that has the name of the type. When invoked as a function, it creates a new object of its type and returns a swig_ref that points to that instance. This provides a very natural interface. For example, +

      + + 
      struct Point{
+  int x,y;
+};
+
      + +

      + is used as follows: +

      + +
      + 
      octave:1> example;
+octave:2> p=example.Point();
+octave:3> p.x=3;
+octave:4> p.y=5;
+octave:5> p.x, p.y
+ans =  3
+ans =  5 
+
      +

      +In C++, invoking the type object in this way calls the object's constructor. +swig_ref objects can also be acquired by having a wrapped function return a pointer, reference, or value of a non-primitive type. +

      +

      +The swig_ref type handles indexing operations such that usage maps closely to what you would have in C/C++. +Structure members are accessed as in the above example, by calling set and get methods for C++ variables. + +Methods also work as expected. For example, code wrapped in the following way +

      + + 
      class Point{
+public:
+  int x,y;
+  Point(int _x,int _y) : x(_x),y(_y) {}
+  double distance(const Point& rhs) {
+    return sqrt(pow(x-rhs.x,2)+pow(y-rhs.y,2));
+  }
+  void set(int _x,int _y) {
+    x=_x; y=_y;
+  }
+};
+
      +

      +can be used from Octave like this +

      +
      + 
      octave:1> example;
+octave:2> p1=example.Point(3,5);
+octave:3> p2=example.Point(1,2);
+octave:4> p1.distance(p2)
+ans =  3.6056
+
      +

      +By using the swig_this() and swig_type() functions, one can discover the pointers to and types of the underlying C/C++ object. +

      + +
      + 
      +octave:5> swig_this(p1)
+ans = 162504808
+octave:6> swig_type(p1)
+ans = Point
+
      +

      +Note that swig_ref is a reference-counted pointer to a C/C++ object/type, and as such has pass-by-reference semantics. For example if one has a allocated a single object but has two swig_ref's pointing to it, modifying the object through either of them will change the single allocated object. +This differs from the usual pass-by-value (copy-on-write) semantics that Octave maintains for built-in types. For example, in the following snippet, modifying b does not modify a, +

      + +
      + 
      +octave:7> a=struct('x',4)
+a =
+{
+  x =  4
+}
+
+octave:8> b=a
+b =
+{
+  x =  4
+}
+
+octave:9> b.y=4
+b =
+{
+  x =  4
+  y =  4
+}
+
+octave:10> a
+a =
+{
+  x =  4
+}
+
      +

      +However, when dealing with wrapped objects, one gets the behavior +

      + +
      + 
      +octave:2> a=Point(3,5)
+a =
+
+{
+  Point, ptr = 0x9afbbb0
+}
+
+octave:3> b=a
+b =
+
+{
+  Point, ptr = 0x9afbbb0
+}
+
+octave:4> b.set(2,1);
+octave:5> b.x, b.y
+ans =  2
+ans =  1
+octave:6> a.x, a.y
+ans =  2
+ans =  1
+
      + +

      +Depending on the ownership setting of a swig_ref, it may call C++ destructors when its reference count goes to zero. See the section on memory management below for details. +

      + +

      27.3.7 C++ inheritance

      + + +

      +Single and multiple inheritance are fully supported. The swig_ref type carries type information along with any C++ object pointer it holds. +This information contains the full class hierarchy. When an indexing operation (such as a method invocation) occurs, +the tree is walked to find a match in the current class as well as any of its bases. The lookup is then cached in the swig_ref. +

      + +

      27.3.8 C++ overloaded functions

      + + +

      +Overloaded functions are supported, and handled as in other modules. That is, +each overload is wrapped separately (under internal names), and a dispatch function is also emitted under the external/visible name. +The dispatch function selects which overload to call (if any) based on the passed arguments. +typecheck typemaps are used to analyze each argument, as well as assign precedence. See the chapter on typemaps for details. +

      + +

      27.3.9 C++ operators

      + + +

      +C++ operator overloading is supported, in a way similar to other modules. +The swig_ref type supports all unary and binary operators between itself and all other types that exist in the system at module load time. When an operator is used (where one of the operands is a swig_ref), the runtime routes the call to either a member function of the given object, or to a global function whose named is derived from the types of the operands (either both or just the lhs or rhs). +

      +

      +For example, if a and b are SWIG variables in Octave, a+b becomes a.__add(b). The wrapper is then free to implement __add to do whatever it wants. A wrapper may define the __add function manually, %rename some other function to it, or %rename a C++ operator to it. +

      +

      +By default the C++ operators are renamed to their corresponding Octave operators. So without doing any work, the following interface +

      +
      +%inline {
+struct A {
+  int value;
+  A(int _value) : value(_value) {}
+  A operator+ (const A& x) {
+    return A(value+x.value);
+  }
+};
+}
+
      +

      +is usable from Octave like this: +

      +
      +a=A(2), b=A(3), c=a+b
+assert(c.value==5);
+
      +

      +Octave operators are mapped in the following way: +

      +
      +__brace      a{args}
+__brace_asgn a{args} = rhs
+__paren      a(args)
+__paren_asgn a(args) = rhs
+__str        generates string rep
+__not        !a
+__uplus      +a
+__uminus     -a
+__transpose  a.'
+__hermitian  a'
+__incr       a++
+__decr       a--
+__add        a + b
+__sub        a - b
+__mul        a * b
+__div        a / b
+__pow        a ^ b
+__ldiv       a \ b
+__lshift     a << b
+__rshift     a >> b
+__lt         a < b
+__le         a <= b
+__eq         a == b
+__ge         a >= b
+__gt         a > b
+__ne         a != b
+__el_mul     a .* b
+__el_div     a ./ b
+__el_pow     a .^ b
+__el_ldiv    a .\ b
+__el_and     a & b
+__el_or      a | b
+
      +

      +On the C++ side, the default mappings are as follows: +

      +
      +%rename(__add)       *::operator+;
+%rename(__add)       *::operator+();
+%rename(__add)       *::operator+() const;
+%rename(__sub)       *::operator-;
+%rename(__uminus)    *::operator-();
+%rename(__uminus)    *::operator-() const;
+%rename(__mul)       *::operator*;
+%rename(__div)       *::operator/;
+%rename(__mod)       *::operator%;
+%rename(__lshift)    *::operator<<;
+%rename(__rshift)    *::operator>>;
+%rename(__el_and)    *::operator&&;
+%rename(__el_or)     *::operator||;
+%rename(__xor)       *::operator^;
+%rename(__invert)    *::operator~;
+%rename(__lt)        *::operator<;
+%rename(__le)        *::operator<=;
+%rename(__gt)        *::operator>;
+%rename(__ge)        *::operator>=;
+%rename(__eq)        *::operator==;
+%rename(__ne)        *::operator!=;
+%rename(__not)       *::operator!;
+%rename(__incr)      *::operator++;
+%rename(__decr)      *::operator--;
+%rename(__paren)     *::operator();
+%rename(__brace)     *::operator[];
+
      + +

      27.3.10 Class extension with %extend

      + + +

      +The %extend directive works the same as in other modules. +

      +

      +You can use it to define special behavior, like for example defining Octave operators not mapped to C++ operators, or defining certain Octave mechanisms such as how an object prints. For example, the octave_value::{is_string,string_value,print} functions are routed to a special method __str that can be defined inside an %extend. +

      +
      +%extend A {
+string __str() {
+  stringstream sout;
+  sout<<$self->value;
+  return sout.str();
+}
+}
+
      +

      +Then in Octave one gets, +

      +
      +octave:1> a=A(4);
+octave:2> a
+a = 4
+octave:3> printf("%s\n",a);
+4
+octave:4> a.__str()
+4
+
      +

      27.3.11 C++ templates

      + + +

      +C++ class and function templates are fully supported as in other modules, in that the %template directive may used to create explicit instantiations of templated types. +For example, function templates can be instantiated as follows: +

      + +
      %module example
+%inline {
+ template<class __scalar>
+   __scalar mul(__scalar a,__scalar b) {
+   return a*b;
+ }
+}
+%include <std_complex.i>
+%template(mul) mul<std::complex<double> >
+%template(mul) mul<double>
+
      +

      +and then used from Octave +

      + +
      +octave:1> mul(4,3)
+ans =  12
+octave:2> mul(4.2,3.6)
+ans =  15.120
+octave:3> mul(3+4i,10+2i)
+ans =  22 + 46i
+
      + +

      +Similarly, class templates can be instantiated as in the following example, +

      + +
      %module example
+%include <std_complex.i>
+%include <std_string.i>
+%inline {
+  #include <sstream>
+  template<class __scalar> class sum {
+    __scalar s;
+  public:
+    sum(__scalar _s=0) : s(_s) {}
+    sum& add(__scalar _s) {
+      s+=_s;
+      return *this;
+    }
+    std::string __str() const {
+      std::stringstream sout;
+      sout<<s;
+      return sout.str();
+    }
+  };
+}
+%template(sum_complex) sum<std::complex<double> >;
+%template(sum_double) sum<double>;
+
      + +

      +and then used from Octave +

      + +
      +octave:2> a=sum_complex(2+3i);
+octave:3> a.add(2)
+ans =
+
+(4,3)
+octave:4> a.add(3+i)
+ans =
+
+(7,4)
+
      + + +

      27.3.12 C++ Smart Pointers

      + + +

      +C++ smart pointers are fully supported as in other modules. +

      + +

      27.3.13 Directors (calling Octave from C++ code)

      + + +

      +There is full support for SWIG Directors, which permits Octave code to subclass C++ classes, and implement their virtual methods. +

      +

      +Octave has no direct support for object oriented programming, however the swig_ref type provides some of this support. You can manufacture a swig_ref using the subclass function (provided by the SWIG/Octave runtime). +

      +

      +For example, +

      +
      +octave:1> a=subclass();
+octave:2> a.my_var = 4;
+octave:3> a.my_method = @(self) printf("my_var = ",self.my_var);
+octave:4> a.my_method();
+my_var = 4
+
      +

      +subclass() can also be used to subclass one or more C++ types. Suppose you have an interface defined by +

      +
      +%inline {
+class A {
+public:
+  virtual my_method() {
+    printf("c-side routine called\n");
+  }
+};
+void call_your_method(A& a) {
+  a.my_method();
+}
+}
+
      +

      +Then from Octave you can say: +

      +
      +octave:1> B=@() subclass(A(),@my_method);
+octave:2> function my_method(self)
+octave:3>   printf("octave-side routine called\n");
+octave:4> end
+octave:5> call_your_method(B());
+octave-side routine called
+
      +

      +or more concisely, +

      +
      +octave:1> B=@() subclass(A(),'my_method',@(self) printf("octave-side routine called\n"));
+octave:2> call_your_method(B());
+octave-side routine called
+
      +

      +Note that you have to enable directors via the %feature directive (see other modules for this). +

      +

      +subclass() will accept any number of C++ bases or other subclass()'ed objects, (string,octave_value) pairs, and function_handles. In the first case, these are taken as base classes; in the second case, as named members (either variables or functions, depending on whether the given value is a function handle); in the third case, as member functions whose name is taken from the given function handle. E.g., +

      +
      +octave:1> B=@(some_var=2) subclass(A(),'some_var',some_var,@some_func,'another_func',@(self) do_stuff())
+
      +

      +You can also assign non-C++ member variables and functions after construct time. There is no support for non-C++ static members. +

      +

      +There is limited support for explicitly referencing C++ bases. So, in the example above, we could have +

      +
      +octave:1> B=@() subclass(A(),@my_method);
+octave:2> function my_method(self)
+octave:3>   self.A.my_method();
+octave:4>   printf("octave-side routine called\n");
+octave:5> end
+octave:6> call_your_method(B());
+c-side routine called
+octave-side routine called
+
      + +

      27.3.14 Threads

      + + +

      +The use of threads in wrapped Director code is not supported; i.e., an Octave-side implementation of a C++ class must be called from the Octave interpreter's thread. Anything fancier (apartment/queue model, whatever) is left to the user. Without anything fancier, this amounts to the limitation that Octave must drive the module... like, for example, an optimization package that calls Octave to evaluate an objective function. +

      + +

      27.3.15 Memory management

      + + +

      +As noted above, swig_ref represents a reference counted pointer to a C/C++-side object. It also contains a flag indicating whether Octave or the C/C++ code owns the object. If Octave owns it, any destructors will be called when the reference count reaches zero. If the C/C++ side owns the object, then destructors will not be called when the reference count goes to zero. +

      +

      +For example, +

      +%inline {
+class A {
+public:
+  A() { printf("A constructing\n"); }
+  ~A() { printf("A destructing\n"); }
+};
+}
+
      +

      +Would produce this behavior in Octave: +

      +
      +octave:1> a=A();
+A constructing
+octave:2> b=a;
+octave:3> clear a;
+octave:4> b=4;
+A destructing
+
      +

      +The %newobject directive may be used to control this behavior for pointers returned from functions. +

      +In the case where one wishes for the C++ side to own an object that was created in Octave (especially a Director object), one can use the __disown() method to invert this logic. Then letting the Octave reference count go to zero will not destroy the object, but destroying the object will invalidate the Octave-side object if it still exists (and call destructors of other C++ bases in the case of multiple inheritance/subclass()'ing). +

      + +

      27.3.16 STL support

      + + +

      +This is some skeleton support for various STL containers. +

      + +

      27.3.17 Matrix typemaps

      + + +

      +Octave provides a rich set of classes for dealing with matrices. Currently there are no built-in typemaps to deal with those. However, these are relatively straight forward for users to add themselves (see the docs on typemaps). Without much work (a single typemap decl-- say, 5 lines of code in the interface file), it would be possible to have a function +

      +
      +double my_det(const double* mat,int m,int n);
+
      +

      +that is accessed from Octave as, +

      +
      +octave:1> my_det(rand(4));
+ans = -0.18388
+
      + +
      + + diff --git a/Doc/Manual/Perl5.html b/Doc/Manual/Perl5.html new file mode 100644 index 0000000..8f74bd1 --- /dev/null +++ b/Doc/Manual/Perl5.html @@ -0,0 +1,3001 @@ + + + +SWIG and Perl5 + + + + +

      28 SWIG and Perl5

      + +
      + +
      + + + + +

      +Caution: This chapter is under repair! +

      + +

      +This chapter describes SWIG's support of Perl5. Although the Perl5 +module is one of the earliest SWIG modules, it has continued to evolve +and has been improved greatly with the help of SWIG users. For the +best results, it is recommended that SWIG be used with Perl5.003 or +later. Earlier versions are problematic and SWIG generated extensions +may not compile or run correctly. +

      + +

      28.1 Overview

      + + +

      +To build Perl extension modules, SWIG uses a layered approach. At +the lowest level, simple procedural wrappers are generated for +functions, classes, methods, and other declarations in the input file. +Then, for structures and classes, an optional collection of Perl +proxy classes can be generated in order to provide a more natural object oriented Perl +interface. These proxy classes simply build upon the low-level interface. +

      + +

      +In describing the Perl interface, this chapter begins by covering the +essentials. First, the problem of configuration, compiling, +and installing Perl modules is discussed. Next, the low-level +procedural interface is presented. Finally, proxy classes are +described. Advanced customization features, typemaps, and other +options are found near the end of the chapter. +

      + +

      28.2 Preliminaries

      + + +

      +To build a Perl5 module, run Swig using the -perl option as +follows : +

      + +
      +swig -perl example.i
+
+
      + +

      +This produces two files. The first file, example_wrap.c +contains all of the C code needed to build a Perl5 module. The second +file, example.pm contains supporting Perl code needed to +properly load the module. +

      + +

      +To build the module, you will need to compile the file +example_wrap.c and link it with the rest of your program. +

      + +

      28.2.1 Getting the right header files

      + + +

      +In order to compile, SWIG extensions need the following Perl5 header files :

      + +
      +#include "Extern.h"
+#include "perl.h"
+#include "XSUB.h"
+
      + +

      +These are typically located in a directory like this

      + +
      +/usr/lib/perl5/5.00503/i386-linux/CORE
+
      + +

      +The SWIG configuration script automatically tries to locate this directory so +that it can compile examples. However, if you need to find out where the directory is +loaded, an easy way to find out is to run Perl itself. +

      + +
      +
      +% perl -e 'use Config; print $Config{archlib};'
+/usr/lib/perl5/5.00503/i386-linux
+
      +
      + +

      28.2.2 Compiling a dynamic module

      + + +

      +The preferred approach to building an extension module is to compile it into +a shared object file or DLL. To do this, you will need to compile your program +using commands like this (shown for Linux): +

      + +
      +$ swig -perl example.i
+% gcc example.c
+% gcc -c example_wrap.c -I/usr/lib/perl5/5.00503/i386-linux/CORE -Dbool=char
+% gcc -shared example.o example_wrap.o -o example.so
+
      + +

      +The exact compiler options vary from platform to platform. +SWIG tries to guess the right options when it is installed. Therefore, +you may want to start with one of the examples in the SWIG/Examples/perl5 +directory. If that doesn't work, you will need to read the man-pages for +your compiler and linker to get the right set of options. You might also +check the SWIG Wiki for +additional information. +

      + +

      +When linking the module, the name of the shared object file must match the module name used in +the SWIG interface file. If you used `%module example', then +the target should be named `example.so', +`example.sl', or the appropriate dynamic module name on your system. +

      + +

      28.2.3 Building a dynamic module with MakeMaker

      + + +

      +It is also possible to use Perl to build dynamically loadable modules +for you using the MakeMaker utility. To do this, write a Perl +script such as the following :

      + +
      +# File : Makefile.PL
+use ExtUtils::MakeMaker;
+WriteMakefile(
+	`NAME'    => `example',                  # Name of package
+	`LIBS'    => [`-lm'],                    # Name of custom libraries
+	`OBJECT'  => `example.o example_wrap.o'  # Object files
+);
+
+
      + +

      +Now, to build a module, simply follow these steps :

      + +
      +% perl Makefile.PL
+% make
+% make install
+
      + +

      +If you are planning to distribute a SWIG-generated module, this is +the preferred approach to compilation. More information about MakeMaker can be +found in "Programming Perl, 2nd ed." by Larry Wall, Tom Christiansen, +and Randal Schwartz.

      + +

      28.2.4 Building a static version of Perl

      + + +

      +If you machine does not support dynamic loading or if you've tried to +use it without success, you can build a new version of the Perl +interpreter with your SWIG extensions added to it. To build a static +extension, you first need to invoke SWIG as follows :

      + +
      +% swig -perl -static example.i
+
      + +

      +By default SWIG includes code for dynamic loading, but the +-static option takes it out.

      + +

      +Next, you will need to supply a main() function that +initializes your extension and starts the Perl interpreter. While, +this may sound daunting, SWIG can do this for you automatically as +follows :

      + +
      +%module example
+
+%inline %{
+extern double My_variable;
+extern int fact(int);
+%}
+
+// Include code for rebuilding Perl
+%include <perlmain.i>
+
      + +

      +The same thing can be accomplished by running SWIG as follows :

      + +
      +% swig -perl -static -lperlmain.i example.i
+
      + +

      +The perlmain.i file inserts Perl's main() function +into the wrapper code and automatically initializes the SWIG generated +module. If you just want to make a quick a dirty module, this may be +the easiest way. By default, the perlmain.i code does not +initialize any other Perl extensions. If you need to use other +packages, you will need to modify it appropriately. You can do this by +just copying perlmain.i out of the SWIG library, placing it +in your own directory, and modifying it to suit your purposes.

      + +

      +To build your new Perl executable, follow the exact same procedure as +for a dynamic module, but change the link line to something like this: +

      + +
      +% gcc example.o example_wrap.o -L/usr/lib/perl5/5.00503/i386-linux/CORE \
+	-lperl -lsocket -lnsl -lm -o myperl
+
      + +

      +This will produce a new version of Perl called myperl. It +should be functionality identical to Perl with your C/C++ extension +added to it. Depending on your machine, you may need to link with +additional libraries such as -lsocket, -lnsl, -ldl, etc. +

      + +

      28.2.5 Using the module

      + + +

      +To use the module, simply use the Perl use statement. If +all goes well, you will be able to do this: +

      + +
      +$ perl
+use example;
+print example::fact(4),"\n";
+24
+
      + +

      +A common error received by first-time users is the following: +

      + +
      +
      +use example;
+Can't locate example.pm in @INC (@INC contains: /usr/lib/perl5/5.00503/i386-lin
+ux /usr/lib/perl5/5.00503 /usr/lib/perl5/site_perl/5.005/i386-linux /usr/lib/pe
+rl5/site_perl/5.005 .) at - line 1.
+BEGIN failed--compilation aborted at - line 1.
+
      +
      + +

      +This error is almost caused when the name of the shared object file you created doesn't match the module name +you specified with the %module directive. +

      + +

      +A somewhat related, but slightly different error is this: +

      + +
      +
      +use example;
+Can't find 'boot_example' symbol in ./example.so
+ at - line 1
+BEGIN failed--compilation aborted at - line 1.
+
      +
      + +

      +This error is generated because Perl can't locate the module bootstrap function in the +SWIG extension module. This could be caused by a mismatch between the module name and the shared library name. +However, another possible cause is forgetting to link the SWIG-generated wrapper code with the rest +of your application when you linked the extension module. +

      + +

      +Another common error is the following: +

      + +
      +
      +use example;
+Can't load './example.so' for module example: ./example.so: 
+undefined symbol: Foo at /usr/lib/perl5/5.00503/i386-linux/DynaLoader.pm line 169.
+
+ at - line 1
+BEGIN failed--compilation aborted at - line 1.
+
      +
      + +

      +This error usually indicates that you forgot to include some object +files or libraries in the linking of the shared library file. Make +sure you compile both the SWIG wrapper file and your original program +into a shared library file. Make sure you pass all of the required libraries +to the linker. +

      + +

      +Sometimes unresolved symbols occur because a wrapper has been created +for a function that doesn't actually exist in a library. This usually +occurs when a header file includes a declaration for a function that +was never actually implemented or it was removed from a library +without updating the header file. To fix this, you can either edit +the SWIG input file to remove the offending declaration or you can use +the %ignore directive to ignore the declaration. Better yet, +update the header file so that it doesn't have an undefined declaration. +

      + +

      +Finally, suppose that your extension module is linked with another library like this: +

      + +
      +
      +$ gcc -shared example.o example_wrap.o -L/home/beazley/projects/lib -lfoo \
+      -o example.so
+
      +
      + +

      +If the foo library is compiled as a shared library, you might get the following +error when you try to use your module: +

      + +
      +
      +use example;
+Can't load './example.so' for module example: libfoo.so: cannot open shared object file: 
+No such file or directory at /usr/lib/perl5/5.00503/i386-linux/DynaLoader.pm line 169.
+
+ at - line 1
+BEGIN failed--compilation aborted at - line 1.
+>>>                 
+
      +
      + +

      +This error is generated because the dynamic linker can't locate the +libfoo.so library. When shared libraries are loaded, the +system normally only checks a few standard locations such as +/usr/lib and /usr/local/lib. To get the loader to look in other +locations, there are several things you can do. First, you can recompile your extension +module with extra path information. For example, on Linux you can do this: +

      + +
      +
      +$ gcc -shared example.o example_wrap.o -L/home/beazley/projects/lib -lfoo \
+      -Xlinker -rpath /home/beazley/projects/lib \
+      -o example.so
+
      +
      + +

      +Alternatively, you can set the LD_LIBRARY_PATH environment +variable to include the directory with your shared libraries. If +setting LD_LIBRARY_PATH, be aware that setting this variable +can introduce a noticeable performance impact on all other +applications that you run. To set it only for Perl, you might want +to do this instead: +

      + +
      +
      +$ env LD_LIBRARY_PATH=/home/beazley/projects/lib perl
+
      +
      + +

      +Finally, you can use a command such as ldconfig (Linux) or +crle (Solaris) to add additional search paths to the default +system configuration (this requires root access and you will need to +read the man pages). +

      + +

      28.2.6 Compilation problems and compiling with C++

      + + +

      +Compilation of C++ extensions has traditionally been a tricky problem. +Since the Perl interpreter is written in C, you need to take steps to +make sure C++ is properly initialized and that modules are compiled +correctly. +

      + +

      +On most machines, C++ extension modules should be linked using the C++ +compiler. For example: +

      + +
      +% swig -c++ -perl example.i
+% g++ -c example.cxx
+% g++ -c example_wrap.cxx -I/usr/lib/perl5/5.00503/i386-linux/CORE
+% g++ -shared example.o example_wrap.o -o example.so
+
      + +

      +In addition to this, you may need to include additional library +files to make it work. For example, if you are using the Sun C++ compiler on +Solaris, you often need to add an extra library -lCrun like this: +

      + +
      +% swig -c++ -perl example.i
+% g++ -c example.cxx
+% g++ -c example_wrap.cxx -I/usr/lib/perl5/5.00503/i386-linux/CORE
+% g++ -shared example.o example_wrap.o -o example.so -lCrun
+
      + +

      +Of course, the names of the extra libraries are completely non-portable---you will +probably need to do some experimentation. +

      + +

      +Another possible compile problem comes from recent versions of Perl (5.8.0) and the GNU tools. +If you see errors having to do with _crypt_struct, that means _GNU_SOURCE is not defined and +it needs to be. So you should compile the wrapper like: +

      + +
      +% g++ -c example_wrap.cxx -I/usr/lib/perl/5.8.0/CORE -D_GNU_SOURCE
+
      + +

      +-D_GNU_SOURCE is also included in the Perl ccflags, which can be found by running +

      + +
      +% perl -e 'use Config; print $Config{ccflags};'
+
      + +

      +So you could also compile the wrapper like +

      + +
      +% g++ -c example_wrap.cxx -I/usr/lib/perl/5.8.0/CORE \
+`perl -e 'use Config; print $Config{ccflags}'`
+
      + +

      +Sometimes people have suggested that it is necessary to relink the +Perl interpreter using the C++ compiler to make C++ extension modules work. +In the experience of this author, this has never actually appeared to be +necessary on most platforms. Relinking the interpreter with C++ really only includes the +special run-time libraries described above---as long as you link your extension +modules with these libraries, it should not be necessary to rebuild Perl. +

      + +

      +If you aren't entirely sure about the linking of a C++ extension, you +might look at an existing C++ program. On many Unix machines, the +ldd command will list library dependencies. This should give +you some clues about what you might have to include when you link your +extension module. For example, notice the first line of output here: +

      + +
      +
      +$ ldd swig
+        libstdc++-libc6.1-1.so.2 => /usr/lib/libstdc++-libc6.1-1.so.2 (0x40019000)
+        libm.so.6 => /lib/libm.so.6 (0x4005b000)
+        libc.so.6 => /lib/libc.so.6 (0x40077000)
+        /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
+$
+
      +
      + +

      +If linking wasn't enough of a problem, another major complication of C++ is that it does not +define any sort of standard for binary linking of libraries. This +means that C++ code compiled by different compilers will not link +together properly as libraries nor is the memory layout of classes and +data structures implemented in any kind of portable manner. In a +monolithic C++ program, this problem may be unnoticed. However, in Perl, it +is possible for different extension modules to be compiled with +different C++ compilers. As long as these modules are self-contained, +this probably won't matter. However, if these modules start sharing data, +you will need to take steps to avoid segmentation faults and other +erratic program behavior. Also, be aware that certain C++ features, especially RTTI, +can behave strangely when working with multiple modules. +

      + +

      +It should be noted that you may get a lot of error messages +about the `bool' datatype when compiling a C++ Perl module. If +you experience this problem, you can try the following :

      + +
        +
      • Use -DHAS_BOOL when compiling the SWIG wrapper code +
      • Or use -Dbool=char when compiling. +
      + +

      +Finally, recent versions of Perl (5.8.0) have namespace conflict problems. Perl defines a bunch +of short macros to make the Perl API function names shorter. For example, in +/usr/lib/perl/5.8.0/CORE/embed.h there is a line: +

      + +
      +#define do_open Perl_do_open
+
      + +

      +The problem is, in the <iostream> header from GNU libstdc++v3 there is a private +function named do_open. If <iostream> is included after the perl headers, then +the Perl macro causes the iostream do_open to be renamed, which causes compile errors. +Hopefully in the future Perl will support a PERL_NO_SHORT_NAMES flag, but for now the +only solution is to undef the macros that conflict. Lib/perl5/noembed.h in the SWIG +source has a list of macros that are known to conflict with either standard headers or +other headers. But if you get macro type conflicts from other macros not included +in Lib/perl5/noembed.h while compiling the wrapper, you will +have to find the macro that conflicts and add an #undef into the .i file. Please report +any conflicting macros you find to swig-user mailing list. +

      + +

      28.2.7 Compiling for 64-bit platforms

      + + +

      +On platforms that support 64-bit applications (Solaris, Irix, etc.), +special care is required when building extension modules. On these +machines, 64-bit applications are compiled and linked using a different +set of compiler/linker options. In addition, it is not generally possible to mix +32-bit and 64-bit code together in the same application. +

      + +

      +To utilize 64-bits, the Perl executable will need to be recompiled +as a 64-bit application. In addition, all libraries, wrapper code, +and every other part of your application will need to be compiled for +64-bits. If you plan to use other third-party extension modules, they +will also have to be recompiled as 64-bit extensions. +

      + +

      +If you are wrapping commercial software for which you have no source +code, you will be forced to use the same linking standard as used by +that software. This may prevent the use of 64-bit extensions. It may +also introduce problems on platforms that support more than one +linking standard (e.g., -o32 and -n32 on Irix). +

      + +

      28.3 Building Perl Extensions under Windows

      + + +

      +Building a SWIG extension to Perl under Windows is roughly +similar to the process used with Unix. Normally, you will want to +produce a DLL that can be loaded into the Perl interpreter. This +section assumes you are using SWIG with Microsoft Visual C++ +although the procedure may be similar with other compilers. +

      + +

      28.3.1 Running SWIG from Developer Studio

      + + +

      +If you are developing your application within Microsoft developer +studio, SWIG can be invoked as a custom build option. The process +roughly requires these steps :

      + +
        +
      • Open up a new workspace and use the AppWizard to select a DLL +project. + +
      • Add both the SWIG interface file (the .i file), any supporting C +files, and the name of the wrapper file that will be created by SWIG +(ie. example_wrap.c). Note : If using C++, choose a +different suffix for the wrapper file such as +example_wrap.cxx. Don't worry if the wrapper file doesn't +exist yet--Developer studio will keep a reference to it around. + +
      • Select the SWIG interface file and go to the settings menu. Under +settings, select the "Custom Build" option. + +
      • Enter "SWIG" in the description field. + +
      • Enter "swig -perl5 -o $(ProjDir)\$(InputName)_wrap.cxx +$(InputPath)" in the "Build command(s) field" + +
      • Enter "$(ProjDir)\$(InputName)_wrap.cxx" in the "Output +files(s) field". + +
      • Next, select the settings for the entire project and go to +"C++:Preprocessor". Add the include directories for your Perl 5 +installation under "Additional include directories". + +
      • Define the symbols WIN32 and MSWIN32 under preprocessor options. +If using the ActiveWare port, also define the symbol PERL_OBJECT. +Note that all extensions to the ActiveWare port must be compiled with +the C++ compiler since Perl has been encapsulated in a C++ class. + +
      • Finally, select the settings for the entire project and go to +"Link Options". Add the Perl library file to your link libraries. +For example "perl.lib". Also, set the name of the output file to +match the name of your Perl module (ie. example.dll). + +
      • Build your project. +
      + +

      +Now, assuming you made it this far, SWIG will be automatically invoked when +you build your project. Any changes made to the interface file will +result in SWIG being automatically invoked to produce a new version of +the wrapper file. To run your new Perl extension, simply run Perl and +use the use command as normal. For example : +

      + +
      +DOS > perl
+use example;
+$a = example::fact(4);
+print "$a\n";
+
+
      + +

      28.3.2 Using other compilers

      + + +

      +SWIG is known to work with Cygwin and may work with other compilers on Windows. +For general hints and suggestions refer to the Windows chapter. +

      + +

      28.4 The low-level interface

      + + +

      +At its core, the Perl module uses a simple low-level interface +to C function, variables, constants, and classes. This low-level interface +can be used to control your application. However, it is also used to +construct more user-friendly proxy classes as described in the next section. +

      + +

      28.4.1 Functions

      + + +

      +C functions are converted into new Perl built-in commands (or +subroutines). For example: +

      + +
      +%module example
+int fact(int a);
+...
+
      + +

      +Now, in Perl: +

      + +
      +use example;
+$a = &example::fact(2);
+
      + +

      28.4.2 Global variables

      + + +

      +Global variables are handled using Perl's magic +variable mechanism. SWIG generates a pair of functions +that intercept read/write operations and attaches them to a Perl variable with +the same name as the C global variable. Thus, an interface like this

      + +
      +%module example;
+...
+double Spam;
+...
+
      + +

      +is accessed as follows :

      + +
      +use example;
+print $example::Spam,"\n";
+$example::Spam = $example::Spam + 4
+# ... etc ...
+
+
      + +

      +If a variable is declared as const, it is wrapped as a +read-only variable. Attempts to modify its value will result in an +error. +

      + +

      +To make ordinary variables read-only, you can also use the %immutable directive. For example: +

      + +
      +
      +%{
+extern char *path;
+%}
+%immutable;
+extern char *path;
+%mutable;
+
      +
      + +

      +The %immutable directive stays in effect until it is explicitly disabled or cleared using +%mutable. +See the Creating read-only variables section for further details. +

      + +

      +It is also possible to tag a specific variable as read-only like this: +

      + +
      +
      +%{
+extern char *path;
+%}
+%immutable path; 
+...
+...
+extern char *path;       // Declared later in the input
+
      +
      + +

      28.4.3 Constants

      + + +

      +By default, constants are wrapped as read-only Perl variables. For example: +

      + +
      +
      +%module example
+
+#define FOO 42
+
      +
      + +

      +In Perl: +

      + +
      +
      +use example;
+print $example::FOO,"\n";    # OK
+$example::FOO = 2;           # Error
+
      +
      + +

      +Alternatively, if you use swig's -const option, constants are wrapped +such that the leading $ isn't required (by using a constant subroutine), which +usually gives a more natural Perl interface, for example: +

      + +
      +
      +use example;
+print example::FOO,"\n";
+
      +
      + +

      28.4.4 Pointers

      + + +

      +SWIG represents pointers as blessed references. A blessed reference +is the same as a Perl reference except that it has additional +information attached to it indicating what kind of reference it +is. That is, if you have a C declaration like this :

      + +
      +Matrix *new_Matrix(int n, int m);
+
      + +

      +The module returns a value generated as follows: +

      + +
      +$ptr = new_Matrix(int n, int m);     # Save pointer return result
+bless $ptr, "p_Matrix";              # Bless it as a pointer to Matrix
+
      + +

      +SWIG uses the "blessing" to check the datatype of various pointers. +In the event of a mismatch, an error or warning message is +generated.

      + +

      +To check to see if a value is the NULL pointer, use the +defined() command :

      + +
      +if (defined($ptr)) {
+	print "Not a NULL pointer.";
+} else {
+	print "Is a NULL pointer.";
+}
+
+
      + +

      +To create a NULL pointer, you should pass the undef value to +a function. +

      + +

      +The "value" of a Perl reference is not the same as the underlying C +pointer that SWIG wrapper functions return. Suppose that $a +and $b are two references that point to the same C object. +In general, $a and $b will be different--since they +are different references. Thus, it is a mistake to check the equality +of $a and $b to check the equality of two C +pointers. The correct method to check equality of C pointers is to +dereference them as follows : +

      + +
      +if ($$a == $$b) {
+	print "a and b point to the same thing in C";
+} else {
+	print "a and b point to different objects.";
+}
+
+
      + +

      +As much as you might be inclined to modify a pointer value directly +from Perl, don't. Manipulating pointer values is architecture dependent and +could cause your program to crash. Similarly, don't try to manually cast +a pointer to a new type by reblessing a pointer. This +may not work like you expect and it is particularly dangerous when +casting C++ objects. If you need to cast a pointer or +change its value, consider writing some helper functions instead. For +example: +

      + +
      +
      +%inline %{
+/* C-style cast */
+Bar *FooToBar(Foo *f) {
+   return (Bar *) f;
+}
+
+/* C++-style cast */
+Foo *BarToFoo(Bar *b) {
+   return dynamic_cast<Foo*>(b);
+}
+
+Foo *IncrFoo(Foo *f, int i) {
+    return f+i;
+}
+%}
+
      +
      + +

      +Also, if working with C++, you should always try +to use the new C++ style casts. For example, in the above code, the +C-style cast may return a bogus result whereas as the C++-style cast will return +NULL if the conversion can't be performed. +

      + +

      +Compatibility Note: In earlier versions, SWIG tried to preserve the same pointer naming conventions +as XS and xsubpp. Given the advancement of the SWIG typesystem and the growing differences between +SWIG and XS, this is no longer supported. +

      + +

      28.4.5 Structures

      + + +

      +Access to the contents of a structure are provided through a set of low-level +accessor functions as described in the "SWIG Basics" chapter. For example, +

      + +
      +struct Vector {
+	double x,y,z;
+};
+
      + +

      +gets mapped into the following collection of accessor functions: +

      + +
      +struct Vector *new_Vector();
+void           delete_Vector(Vector *v);
+double         Vector_x_get(Vector *obj)
+void           Vector_x_set(Vector *obj, double x)
+double         Vector_y_get(Vector *obj)
+void           Vector_y_set(Vector *obj, double y)
+double         Vector_z_get(Vector *obj)
+void           Vector_z_set(Vector *obj, double z)
+
+
      + +

      +These functions are then used to access structure data from Perl as follows: +

      + +
      +$v = example::new_Vector();
+print example::Vector_x_get($v),"\n";    # Get x component
+example::Vector_x_set($v,7.8);          # Change x component
+
      + +

      +Similar access is provided for unions and the data members of C++ classes. +

      + +

      +const members of a structure are read-only. Data members +can also be forced to be read-only using the %immutable directive. For example: +

      + +
      +
      +struct Foo {
+   ...
+   %immutable;
+   int x;        /* Read-only members */
+   char *name;
+   %mutable;
+   ...
+};
+
      +
      + +

      +When char * members of a structure are wrapped, the contents are assumed to be +dynamically allocated using malloc or new (depending on whether or not +SWIG is run with the -c++ option). When the structure member is set, the old contents will be +released and a new value created. If this is not the behavior you want, you will have to use +a typemap (described later). +

      + +

      +Array members are normally wrapped as read-only. For example, +

      + +
      +
      +struct Foo {
+   int  x[50];
+};
+
      +
      + +

      +produces a single accessor function like this: +

      + +
      +
      +int *Foo_x_get(Foo *self) {
+    return self->x;
+};
+
      +
      + +

      +If you want to set an array member, you will need to supply a "memberin" typemap +described later in this chapter. As a special case, SWIG does generate +code to set array members of type char (allowing you to store a Python +string in the structure). +

      + +

      +When structure members are wrapped, they are handled as pointers. For example, +

      + +
      +
      +struct Foo {
+   ...
+};
+
+struct Bar {
+   Foo f;
+};
+
      +
      + +

      +generates accessor functions such as this: +

      + +
      +
      +Foo *Bar_f_get(Bar *b) {
+    return &b->f;
+}
+
+void Bar_f_set(Bar *b, Foo *val) {
+    b->f = *val;
+}
+
      +
      + + +

      28.4.6 C++ classes

      + + +

      +C++ classes are wrapped by building a set of low level accessor functions. +Consider the following class : +

      + +
      +class List {
+public:
+  List();
+  ~List();
+  int  search(char *item);
+  void insert(char *item);
+  void remove(char *item);
+  char *get(int n);
+  int  length;
+static void print(List *l);
+};
+
      + +

      +When wrapped by SWIG, the following functions are created : +

      + +
      +List    *new_List();
+void     delete_List(List *l);
+int      List_search(List *l, char *item);
+void     List_insert(List *l, char *item);
+void     List_remove(List *l, char *item);
+char    *List_get(List *l, int n);
+int      List_length_get(List *l);
+void     List_length_set(List *l, int n);
+void     List_print(List *l);
+
+
      + +

      +In Perl, these functions are used in a straightforward manner: +

      + +
      +use example;
+$l = example::new_List();
+example::List_insert($l,"Ale");
+example::List_insert($l,"Stout");
+example::List_insert($l,"Lager")
+example::List_print($l)
+Lager
+Stout
+Ale
+print example::List_length_get($l),"\n";
+3
+
      + +

      +At this low level, C++ objects are really just typed pointers. Member +functions are accessed by calling a C-like wrapper with an instance pointer +as the first argument. Although this interface is fairly primitive, it +provides direct access to C++ objects. A higher level interface using Perl proxy classes +can be built using these low-level accessors. This is described shortly. +

      + +

      28.4.7 C++ classes and type-checking

      + + +

      +The SWIG type-checker is fully aware of C++ inheritance. Therefore, if you have +classes like this +

      + +
      +
      +class Foo {
+...
+};
+
+class Bar : public Foo {
+...
+};
+
      +
      + +

      +and a function +

      + +
      +
      +void spam(Foo *f);
+
      +
      + +

      +then the function spam() accepts Foo * or a pointer to any class derived from Foo. +If necessary, the type-checker also adjusts the value of the pointer (as is necessary when +multiple inheritance is used). +

      + +

      28.4.8 C++ overloaded functions

      + + +

      +If you have a C++ program with overloaded functions or methods, you will need to disambiguate +those methods using %rename. For example: +

      + +
      +
      +/* Forward renaming declarations */
+%rename(foo_i) foo(int); 
+%rename(foo_d) foo(double);
+...
+void foo(int);           // Becomes 'foo_i'
+void foo(char *c);       // Stays 'foo' (not renamed)
+
+class Spam {
+public:
+   void foo(int);      // Becomes 'foo_i'
+   void foo(double);   // Becomes 'foo_d'
+   ...
+};
+
      +
      + +

      +Now, in Perl, the methods are accessed as follows: +

      + +
      +
      +use example;
+example::foo_i(3);
+$s = example::new_Spam();
+example::Spam_foo_i($s,3);
+example::Spam_foo_d($s,3.14);
+
      +
      + +

      +Please refer to the "SWIG Basics" chapter for more information. +

      + +

      28.4.9 Operators

      + + +

      +As of version 1.3.27 SWIG automatically renames the most common C++ operators, and maps them into the perl module with the proper 'use overload ...' so you don't need to do any work. +

      + +

      +The following C++ operators are currently supported by the Perl module: +

      + +
        +
      • operator++
        • +
      • operator--
        • +
      • operator+
        • +
      • operator-
        • +
      • operator*
        • +
      • operator/
        • +
      • operator==
        • +
      • operator!=
        • +
      • operator%
        • +
      • operator>
        • +
      • operator<
        • +
      • operator and
        • +
      • operator or
        • +
      + +

      28.4.10 Modules and packages

      + + +

      +When you create a SWIG extension, everything gets placed into +a single Perl module. The name of the module is determined by the +%module directive. To use the module, do the following : +

      + +
      +% perl5
+use example;                      # load the example module
+print example::fact(4),"\n"       # Call a function in it
+24
+
      + +

      +Usually, a module consists of a collection of code that is contained +within a single file. A package, on the other hand, is the Perl +equivalent of a namespace. A package is a lot like a module, except +that it is independent of files. Any number of files may be part of +the same package--or a package may be broken up into a collection of +modules if you prefer to think about it in this way. +

      + +

      +SWIG installs its functions into a package with the same name as +the module.

      + +

      +Incompatible Change: previous versions of SWIG enabled you to +change the name of the package by using the -package option, this +feature has been removed in order to properly support modules that +used nested namespaces, e.g. Foo::Bar::Baz. To give your module a +nested namespace simply provide the fully qualified name in your +%module directive:

      + +
      +%module "Foo::Bar::Baz"
+
      + +

      +NOTE: the double quotes are necessary. +

      + +

      + Using the package option of the %module directive allows + you to specify what Perl namespace that the module will be living in when + installed. This is useful in the situation where a module maintainer + wants to split a large module into smaller pieces to make maintenance + easier, but doesn't want to have that affect the module name used by + applications. So for example, if I wanted to split XML::Xerces + into XML::Xerces::SAX, etc. , but I wanted all the applications + to be able to access the classes using the XML::Xerces namespace + I could use: + +

      + +
      +
      +%module(package="XML::Xerces") "XML::Xerces::SAX
+
      +
      + +

      + And now all the applications could use the class + XML::Xerces::SAXParser. Without the package directive + splitting the module would force applications to use the class + XML::Xerces::SAX::SAXParser. This could break compatibility for + existing applications that are already using the class under the name + XML::Xerces::SAXParser. +

      + + + +

      28.5 Input and output parameters

      + + +

      +A common problem in some C programs is handling parameters passed as simple pointers. For +example: +

      + +
      +
      +void add(int x, int y, int *result) {
+   *result = x + y;
+}
+
      +
      + +

      +or perhaps +

      + +
      +
      +int sub(int *x, int *y) {
+   return *x+*y;
+}
+
      +
      + +

      +The easiest way to handle these situations is to use the typemaps.i file. For example: +

      + +
      +
      +%module example
+%include "typemaps.i"
+
+void add(int, int, int *OUTPUT);
+int  sub(int *INPUT, int *INPUT);
+
      +
      + +

      +In Perl, this allows you to pass simple values. For example: +

      + +
      +
      +$a = example::add(3,4);
+print "$a\n";
+7
+$b = example::sub(7,4);
+print "$b\n";
+3
+
      +
      + +

      +Notice how the INPUT parameters allow integer values to be passed instead of pointers +and how the OUTPUT parameter creates a return result. +

      + +

      +If you don't want to use the names INPUT or OUTPUT, use the %apply +directive. For example: +

      + +
      +
      +%module example
+%include "typemaps.i"
+
+%apply int *OUTPUT { int *result };
+%apply int *INPUT  { int *x, int *y};
+
+void add(int x, int y, int *result);
+int  sub(int *x, int *y);
+
      +
      + +

      +If a function mutates one of its parameters like this, +

      + +
      +
      +void negate(int *x) {
+   *x = -(*x);
+}
+
      +
      + +

      +you can use INOUT like this: +

      + +
      +
      +%include "typemaps.i"
+...
+void negate(int *INOUT);
+
      +
      + +

      +In Perl, a mutated parameter shows up as a return value. For example: +

      + +
      +
      +$a = example::negate(3);
+print "$a\n";
+-3
+
      +
      + +

      +The most common use of these special typemap rules is to handle functions that +return more than one value. For example, sometimes a function returns a result +as well as a special error code: +

      + +
      +
      +/* send message, return number of bytes sent, along with success code */
+int send_message(char *text, int len, int *success);
+
      +
      + +

      +To wrap such a function, simply use the OUTPUT rule above. For example: +

      + +
      +
      +%module example
+%include "typemaps.i"
+%apply int *OUTPUT { int *success };
+...
+int send_message(char *text, int *success);
+
      +
      + +

      +When used in Perl, the function will return multiple values. +

      + +
      +
      +($bytes, $success) = example::send_message("Hello World");
+
      +
      + +

      +Another common use of multiple return values are in query functions. For example: +

      + +
      +
      +void get_dimensions(Matrix *m, int *rows, int *columns);
+
      +
      + +

      +To wrap this, you might use the following: +

      + +
      +
      +%module example
+%include "typemaps.i"
+%apply int *OUTPUT { int *rows, int *columns };
+...
+void get_dimensions(Matrix *m, int *rows, *columns);
+
      +
      + +

      +Now, in Perl: +

      + +
      +
      +($r,$c) = example::get_dimensions($m);
+
      +
      + +

      +In certain cases, it is possible to treat Perl references as C pointers. To do this, use the REFERENCE typemap. For +example: +

      + +
      +
      +%module example
+%include "typemaps.i"
+
+void add(int x, int y, int *REFERENCE);
+
      +
      + +

      +In Perl: +

      + +
      +
      +use example;
+$c = 0.0;
+example::add(3,4,\$c);
+print "$c\n";
+7
+
      +
      + +

      +Note: The REFERENCE feature is only currently supported for numeric types (integers and floating point). +

      + +

      28.6 Exception handling

      + + +

      +The SWIG %exception directive can be used to create a +user-definable exception handler for converting exceptions in your +C/C++ program into Perl exceptions. The chapter on customization features +contains more details, but suppose you have a C++ class like the +following : +

      + +
      +class RangeError {};   // Used for an exception
+
+class DoubleArray {
+  private:
+    int n;
+    double *ptr;
+  public:
+    // Create a new array of fixed size
+    DoubleArray(int size) {
+      ptr = new double[size];
+      n = size;
+    }
+    // Destroy an array
+    ~DoubleArray() {
+       delete ptr;
+    }
+    // Return the length of the array
+    int   length() {
+      return n;
+    }
+
+    // Get an item from the array and perform bounds checking.
+    double getitem(int i) {
+      if ((i >= 0) && (i < n))
+        return ptr[i];
+      else
+        throw RangeError();
+    }
+
+    // Set an item in the array and perform bounds checking.
+    void setitem(int i, double val) {
+      if ((i >= 0) && (i < n))
+        ptr[i] = val;
+      else {
+        throw RangeError();
+      }
+    }
+  };
+
      + +

      +Since several methods in this class can throw an exception +for an out-of-bounds access, you might want to catch +this in the Perl extension by writing the following in an +interface file: +

      + +
      +%exception {
+  try {
+    $action
+  }
+  catch (RangeError) {
+    croak("Array index out-of-bounds");
+  }
+}
+
+class DoubleArray {
+...
+};
+
      + +

      +The exception handling code is inserted directly into generated wrapper +functions. The $action variable is replaced with the C/C++ +code being executed by the wrapper. When an exception handler +is defined, errors can be caught and used to gracefully generate a Perl error +instead of forcing the entire program to terminate with an uncaught error. +

      + +

      +As shown, the exception handling code will be added to every wrapper function. +Since this is somewhat inefficient. You might consider refining the +exception handler to only apply to specific methods like this: +

      + +
      +
      +%exception getitem {
+  try {
+    $action
+  }
+  catch (RangeError) {
+    croak("Array index out-of-bounds");
+  }
+}
+
+%exception setitem {
+  try {
+    $action
+  }
+  catch (RangeError) {
+    croak("Array index out-of-bounds");
+  }
+}
+
      +
      + +

      +In this case, the exception handler is only attached to methods and functions +named getitem and setitem. +

      + +

      +If you had a lot of different methods, you can avoid extra typing by using a macro. +For example: +

      + +
      +
      +%define RANGE_ERROR
+{
+  try {
+    $action
+  }
+  catch (RangeError) {
+    croak("Array index out-of-bounds");
+  }
+}
+%enddef
+
+%exception getitem RANGE_ERROR;
+%exception setitem RANGE_ERROR;
+
      +
      + +

      +Since SWIG's exception handling is user-definable, you are not limited to C++ exception handling. +See the chapter on "Customization features" for more examples. +

      + +

      +Compatibility note: In SWIG1.1, exceptions were defined using the older %except directive: +

      + +
      +
      +%except(python) {
+  try {
+    $function
+  }
+  catch (RangeError) {
+    croak("Array index out-of-bounds");
+  }
+}
+
      +
      + +

      +This is still supported, but it is deprecated. The newer %exception directive provides the same +functionality, but it has additional capabilities that make it more powerful. +

      + +

      28.7 Remapping datatypes with typemaps

      + + +

      +This section describes how you can modify SWIG's default wrapping behavior +for various C/C++ datatypes using the %typemap directive. This +is an advanced topic that assumes familiarity with the Perl C API as well +as the material in the "Typemaps" chapter. +

      + +

      +Before proceeding, it should be stressed that typemaps are not a required +part of using SWIG---the default wrapping behavior is enough in most cases. +Typemaps are only used if you want to change some aspect of the primitive +C-Perl interface. +

      + +

      28.7.1 A simple typemap example

      + + +

      +A typemap is nothing more than a code generation rule that is attached to +a specific C datatype. For example, to convert integers from Perl to C, +you might define a typemap like this: +

      + +
      +%module example
+
+%typemap(in) int {
+	$1 = (int) SvIV($input);
+	printf("Received an integer : %d\n", $1);
+}
+...
+%inline %{
+extern int fact(int n);
+%}
+
+
      + +

      +Typemaps are always associated with some specific aspect of code generation. +In this case, the "in" method refers to the conversion of input arguments +to C/C++. The datatype int is the datatype to which the typemap +will be applied. The supplied C code is used to convert values. In this +code a number of special variable prefaced by a $ are used. The +$1 variable is placeholder for a local variable of type int. +The $input variable is the input object (usually a SV *). +

      + +

      +When this example is used in Perl5, it will operate as follows : +

      + +
      +use example;
+$n = example::fact(6);
+print "$n\n";
+...
+
+Output :
+Received an integer : 6
+720
+
      + +

      +The application of a typemap to specific datatypes and argument names involves +more than simple text-matching--typemaps are fully integrated into the +SWIG type-system. When you define a typemap for int, that typemap +applies to int and qualified variations such as const int. In addition, +the typemap system follows typedef declarations. For example: +

      + +
      +
      +%typemap(in) int n {
+	$1 = (int) SvIV($input);
+	printf("n = %d\n",$1);
+}
+%inline %{
+typedef int Integer;
+extern int fact(Integer n);    // Above typemap is applied
+%}
+
      +
      + +

      +It should be noted that the matching of typedef only occurs in one direction. If you +defined a typemap for Integer, it is not applied to arguments of +type int. +

      + +

      +Typemaps can also be defined for groups of consecutive arguments. For example: +

      + +
      +
      +%typemap(in) (char *str, unsigned len) {
+    $1 = SvPV($input,$2);
+};
+
+int count(char c, char *str, unsigned len);
+
      +
      + +

      +When a multi-argument typemap is defined, the arguments are always handled as a single +Perl object. This allows the function to be used like this (notice how the length +parameter is omitted): +

      + +
      +
      +example::count("e","Hello World");
+1
+>>>
+
      +
      + + +

      28.7.2 Perl5 typemaps

      + + +

      +The previous section illustrated an "in" typemap for converting Perl objects to C. +A variety of different typemap methods are defined by the Perl module. For example, +to convert a C integer back into a Perl object, you might define an "out" typemap +like this: +

      + + +
      +
      +%typemap(out) int {
+    $result = sv_newmortal();
+    set_setiv($result, (IV) $1);
+    argvi++;
+}
+
      +
      + +

      +The following typemap methods are available: +

      + +

      +%typemap(in) +

      + +
      +Converts Perl5 object to input function arguments. +
      + +

      +%typemap(out) +

      + +
      +Converts function return value to a Perl5 value. +
      + +

      +%typemap(varin) +

      + +
      +Converts a Perl5 object to a global variable. +
      + +

      +%typemap(varout) +

      + +
      +Converts a global variable to a Perl5 object. +
      + +

      +%typemap(freearg) +

      + +
      +Cleans up a function argument after a function call +
      + +

      +%typemap(argout) +

      + +
      +Output argument handling +
      + +

      +%typemap(ret) +

      + +
      +Clean up return value from a function. +
      + +

      +%typemap(memberin) +

      + +
      +Setting of C++ member data (all languages). +
      + +

      +%typemap(memberout) +

      + +
      +Return of C++ member data (all languages). +
      + +

      +%typemap(check) +

      + +
      +Check value of input parameter. +
      + +

      28.7.3 Typemap variables

      + + +

      +Within typemap code, a number of special variables prefaced with a $ may appear. +A full list of variables can be found in the "Typemaps" chapter. +This is a list of the most common variables: +

      + +

      +$1 +

      + +
      +A C local variable corresponding to the actual type specified in the +%typemap directive. For input values, this is a C local variable +that's supposed to hold an argument value. For output values, this is +the raw result that's supposed to be returned to Perl. +
      + +

      +$input +

      + +
      +A Perl object holding the value of an argument of variable value. +
      + +

      +$result +

      + +
      +A Perl object that holds the result to be returned to Perl. +
      + +

      +$1_name +

      + +
      +The parameter name that was matched. +
      + +

      +$1_type +

      + +
      +The actual C datatype matched by the typemap. +
      + +

      +$1_ltype +

      + +
      +An assignable version of the datatype matched by the typemap (a type that can appear on the left-hand-side of +a C assignment operation). This type is stripped of qualifiers and may be an altered version of $1_type. +All arguments and local variables in wrapper functions are declared using this type so that their values can be +properly assigned. +
      + +

      +$symname +

      + +
      +The Perl name of the wrapper function being created. +
      + +

      28.7.4 Useful functions

      + + +

      +When writing typemaps, it is necessary to work directly with Perl5 +objects. This, unfortunately, can be a daunting task. Consult the +"perlguts" man-page for all of the really ugly details. A short +summary of commonly used functions is provided here for reference. It +should be stressed that SWIG can be used quite effectively without +knowing any of these details--especially now that there are typemap +libraries that can already been written. +

      + +

      +Perl Integer Functions +

      + +
      +
      +int   SvIV(SV *);
+void  sv_setiv(SV *sv, IV value);
+SV   *newSViv(IV value);
+int   SvIOK(SV *);
+
      +
      + +

      +Perl Floating Point Functions +

      + +
      +
      +double SvNV(SV *);
+void   sv_setnv(SV *, double value);
+SV    *newSVnv(double value);
+int    SvNOK(SV *);
+
      +
      + +

      +Perl String Functions +

      + +
      +
      +char     *SvPV(SV *, STRLEN len);
+void      sv_setpv(SV *, char *val);
+void      sv_setpvn(SV *, char *val, STRLEN len);
+SV       *newSVpv(char *value, STRLEN len);
+int       SvPOK(SV *);
+void      sv_catpv(SV *, char *);
+void      sv_catpvn(SV *, char *, STRLEN);
+
      +
      + +

      +Perl References +

      + +
      +
      +void      sv_setref_pv(SV *, char *, void *ptr);
+int       sv_isobject(SV *);
+SV       *SvRV(SV *);
+int       sv_isa(SV *, char *0;
+
      +
      + + +

      28.8 Typemap Examples

      + + +

      +This section includes a few examples of typemaps. For more examples, you +might look at the files "perl5.swg" and "typemaps.i" in +the SWIG library. +

      + +

      28.8.1 Converting a Perl5 array to a char **

      + + +

      +A common problem in many C programs is the processing of command line +arguments, which are usually passed in an array of NULL terminated +strings. The following SWIG interface file allows a Perl5 array +reference to be used as a char ** datatype. +

      + +
      +%module argv
+
+// This tells SWIG to treat char ** as a special case
+%typemap(in) char ** {
+	AV *tempav;
+	I32 len;
+	int i;
+	SV  **tv;
+	if (!SvROK($input))
+	    croak("Argument $argnum is not a reference.");
+        if (SvTYPE(SvRV($input)) != SVt_PVAV)
+	    croak("Argument $argnum is not an array.");
+        tempav = (AV*)SvRV($input);
+	len = av_len(tempav);
+	$1 = (char **) malloc((len+2)*sizeof(char *));
+	for (i = 0; i <= len; i++) {
+	    tv = av_fetch(tempav, i, 0);	
+	    $1[i] = (char *) SvPV(*tv,PL_na);
+        }
+	$1[i] = NULL;
+};
+
+// This cleans up the char ** array after the function call
+%typemap(freearg) char ** {
+	free($1);
+}
+
+// Creates a new Perl array and places a NULL-terminated char ** into it
+%typemap(out) char ** {
+	AV *myav;
+	SV **svs;
+	int i = 0,len = 0;
+	/* Figure out how many elements we have */
+	while ($1[len])
+	   len++;
+	svs = (SV **) malloc(len*sizeof(SV *));
+	for (i = 0; i < len ; i++) {
+	    svs[i] = sv_newmortal();
+	    sv_setpv((SV*)svs[i],$1[i]);
+	};
+	myav =	av_make(len,svs);
+	free(svs);
+        $result = newRV_noinc((SV*)myav);
+        sv_2mortal($result);
+        argvi++;
+}
+
+// Now a few test functions
+%inline %{
+int print_args(char **argv) {
+    int i = 0;
+    while (argv[i]) {
+         printf("argv[%d] = %s\n", i,argv[i]);
+         i++;
+    }
+    return i;
+}
+
+// Returns a char ** list 
+char **get_args() {
+    static char *values[] = { "Dave", "Mike", "Susan", "John", "Michelle", 0};
+    return &values[0];
+}
+%}
+
+
      + +

      +When this module is compiled, the wrapped C functions can be used in a +Perl script as follows : +

      + +
      +use argv;
+@a = ("Dave", "Mike", "John", "Mary");           # Create an array of strings
+argv::print_args(\@a);                           # Pass it to our C function
+$b = argv::get_args();                           # Get array of strings from C
+print @$b,"\n";                                  # Print it out
+
      + + +

      28.8.2 Return values

      + + +

      +Return values are placed on the argument stack of each wrapper +function. The current value of the argument stack pointer is +contained in a variable argvi. Whenever a new output value +is added, it is critical that this value be incremented. For multiple +output values, the final value of argvi should be the total +number of output values. +

      + +

      +The total number of return values should not exceed the number of +input values unless you explicitly extend the argument stack. This +can be done using the EXTEND() macro as in : +

      + +
      +%typemap(argout) int *OUTPUT {
+	if (argvi >= items) {            
+		EXTEND(sp,1);              /* Extend the stack by 1 object */
+	}
+	$result = sv_newmortal();
+	sv_setiv($target,(IV) *($1));
+	argvi++;
+}
+
      + +

      28.8.3 Returning values from arguments

      + + +

      +Sometimes it is desirable for a function to return a value in one of +its arguments. This example describes the implementation of the OUTPUT typemap. +

      + +
      +%module return
+
+// This tells SWIG to treat an double * argument with name 'OutDouble' as
+// an output value.  
+
+%typemap(argout) double *OUTPUT {
+	$result = sv_newmortal();
+	sv_setnv($result, *$input);
+	argvi++;                     /* Increment return count -- important! */
+}
+
+// We don't care what the input value is. Ignore, but set to a temporary variable
+
+%typemap(in,numinputs=0) double *OUTPUT(double junk) {
+	$1 = &junk;
+}
+
+// Now a function to test it
+%{
+/* Returns the first two input arguments */
+int multout(double a, double b, double *out1, double *out2) {
+	*out1 = a;
+	*out2 = b;
+	return 0;
+};
+%}
+
+// If we name both parameters OutDouble both will be output
+
+int multout(double a, double b, double *OUTPUT, double *OUTPUT);
+...
+
      + +

      +When this function is called, the output arguments are appended to the stack used +to return results. This shows up an array in Perl. +For example : +

      + +
      +@r = multout(7,13);
+print "multout(7,13) = @r\n";
+($x,$y) = multout(7,13);
+
      + +

      28.8.4 Accessing array structure members

      + + +

      +Consider the following data structure : +

      + +
      +#define SIZE  8
+typedef struct {
+    int   values[SIZE];
+    ...
+} Foo;
+
+
      + +

      +By default, SWIG doesn't know how to the handle the values structure +member it's an array, not a pointer. In this case, SWIG makes the array member +read-only. Reading will simply return a pointer to the first item in the array. +To make the member writable, a "memberin" typemap can be used. +

      + +
      +%typemap(memberin) int [SIZE] {
+    int i;
+    for (i = 0; i < SIZE; i++) {
+        $1[i] = $input[i];
+    }
+}
+
+
      + +

      +Whenever a int [SIZE] member is encountered in a structure +or class, this typemap provides a safe mechanism for setting its +value. +

      + +

      +As in the previous example, the typemap can be generalized for any dimension. +For example: +

      + +
      +%typemap(memberin) int [ANY] {
+   int i;
+   for (i = 0; i < $1_dim0; i++) {
+      $1[i] = $input[i];
+   }
+}
+
      + +

      +When setting structure members, the input object is always assumed to +be a C array of values that have already been converted from the +target language. Because of this, the memberin typemap is +almost always combined with the use of an "in" typemap. For example, +the "in" typemap in the previous section would be used to convert an +int[] array to C whereas the "memberin" typemap would be used +to copy the converted array into a C data structure. +

      + +

      28.8.5 Turning Perl references into C pointers

      + + +

      +A frequent confusion on the SWIG mailing list is errors caused by the +mixing of Perl references and C pointers. For example, suppose you +have a C function that modifies its arguments like this : +

      + +
      +void add(double a, double b, double *c) {
+	*c = a + b;
+}
+
      + +

      +A common misinterpretation of this function is the following Perl script : +

      + +
      +# Perl script
+$a = 3.5;
+$b = 7.5;
+$c = 0.0;          # Output value
+add($a,$b,\$c);    # Place result in c (Except that it doesn't work)
+
      + +

      +To make this work with a reference, you can use a typemap such as this: +

      + +
      +%typemap(in) double * (double dvalue) {
+  SV* tempsv;
+  if (!SvROK($input)) {
+    croak("expected a reference\n");
+  }
+  tempsv = SvRV($input);
+  if ((!SvNOK(tempsv)) && (!SvIOK(tempsv))) {
+    croak("expected a double reference\n");
+  }
+  dvalue = SvNV(tempsv);
+  $1 = &dvalue;
+}
+
+%typemap(argout) double * {
+  SV *tempsv;
+  tempsv = SvRV($input);
+  sv_setnv(tempsv, *$1);
+}
+
      + +

      +Now, if you place this before the add function, you can do this : +

      + +
      +$a = 3.5;
+$b = 7.5;
+$c = 0.0;
+add($a,$b,\$c);            # Now it works!
+print "$c\n";
+
+
      + +

      28.8.6 Pointer handling

      + + +

      +Occasionally, it might be necessary to convert pointer values that have +been stored using the SWIG typed-pointer representation. To convert a pointer from Perl to C, the following +function is used: +

      + +

      + +int SWIG_ConvertPtr(SV *obj, void **ptr, swig_type_info *ty, int flags) + +

      + +
      +Converts a Perl object obj to a C pointer. The result of the conversion is placed +into the pointer located at ptr. ty is a SWIG type descriptor structure. +flags is used to handle error checking and other aspects of conversion. flags is +currently undefined and reserved for future expansion. Returns 0 on success and -1 on error. +
      + +

      + +void *SWIG_MakePtr(SV *obj, void *ptr, swig_type_info *ty, int flags) +

      + +
      +Creates a new Perl pointer object. obj is a Perl SV that has been initialized to hold the result, +ptr is the pointer to convert, ty is the SWIG type descriptor structure that +describes the type, and flags is a flag that controls properties of the conversion. flags is currently undefined +and reserved. +
      + +

      +Both of these functions require the use of a special SWIG +type-descriptor structure. This structure contains information about +the mangled name of the datatype, type-equivalence information, as +well as information about converting pointer values under C++ +inheritance. For a type of Foo *, the type descriptor structure +is usually accessed as follows: +

      + +
      +
      +Foo *f;
+if (SWIG_ConvertPtr($input, (void **) &f, SWIGTYPE_p_Foo, 0) == -1) return NULL;
+
+SV *sv = sv_newmortal();
+SWIG_MakePtr(sv, f, SWIGTYPE_p_Foo, 0);
+
      +
      + +

      +In a typemap, the type descriptor should always be accessed using the special typemap +variable $1_descriptor. For example: +

      + +
      +
      +%typemap(in) Foo * {
+   if ((SWIG_ConvertPtr($input,(void **) &$1, $1_descriptor,0)) == -1) return NULL;
+}
+
      +
      + +

      +If necessary, the descriptor for any type can be obtained using the $descriptor() macro in a typemap. +For example: +

      + +
      +
      +%typemap(in) Foo * {
+   if ((SWIG_ConvertPtr($input,(void **) &$1, $descriptor(Foo *), 0)) == -1) return NULL;
+}
+
      +
      + +

      28.9 Proxy classes

      + + +

      +Out of date. Needs update. +

      + +

      +Using the low-level procedural interface, SWIG can also construct a +high-level object oriented interface to C structures and C++ classes. +This is done by constructing a Perl proxy class (also known as a shadow class) +that provides an OO wrapper +to the underlying code. This section describes the implementation +details of the proxy interface. +

      + +

      28.9.1 Preliminaries

      + + +

      +Proxy classes, are generated by default. If you want to turn them off, use the -noproxy command line option. +For example: +

      + +
      +
      +$ swig -c++ -perl -noproxy example.i
+
      +
      + +

      +When proxy classes are used, SWIG moves all of the low-level procedural wrappers to +another package name. By default, this package is named 'modulec' where 'module' is the name of the module +you provided with the %module directive. Then, in place of the original module, +SWIG creates a collection of high-level Perl wrappers. In your scripts, you will use these +high level wrappers. The wrappers, in turn, interact with the low-level procedural module. +

      + +

      28.9.2 Structure and class wrappers

      + + +

      +Suppose you have the following SWIG interface file : +

      + +
      +%module example
+struct Vector {
+	Vector(double x, double y, double z);
+	~Vector();
+	double x,y,z;
+};
+
+
      + +

      +When wrapped, SWIG creates the following set of low-level accessor +functions as described in previous sections. +

      + +
      +Vector *new_Vector(double x, double y, double z);
+void    delete_Vector(Vector *v);
+double  Vector_x_get(Vector *v);
+double  Vector_x_set(Vector *v, double value);
+double  Vector_y_get(Vector *v);
+double  Vector_y_set(Vector *v, double value);
+double  Vector_z_get(Vector *v);
+double  Vector_z_set(Vector *v, double value);
+
+
      + +

      +However, when proxy classes are enabled, these accessor functions are +wrapped inside a Perl class like this: +

      + +
      +package example::Vector;
+@ISA = qw( example );
+%OWNER = ();
+%BLESSEDMEMBERS = ();
+
+sub new () {
+    my $self = shift;
+    my @args = @_;
+    $self = vectorc::new_Vector(@args);
+    return undef if (!defined($self));
+    bless $self, "example::Vector";
+    $OWNER{$self} = 1;
+    my %retval;
+    tie %retval, "example::Vector", $self;
+    return bless \%retval,"Vector";
+}
+
+sub DESTROY {
+    return unless $_[0]->isa('HASH');
+    my $self = tied(%{$_[0]});
+    delete $ITERATORS{$self};
+    if (exists $OWNER{$self}) {
+	 examplec::delete_Vector($self));
+	 delete $OWNER{$self};
+}
+
+sub FETCH {
+    my ($self,$field) = @_;
+    my $member_func = "vectorc::Vector_${field}_get";
+    my $val = &$member_func($self);
+    if (exists $BLESSEDMEMBERS{$field}) {
+        return undef if (!defined($val));
+        my %retval;
+        tie %retval,$BLESSEDMEMBERS{$field},$val;
+        return bless \%retval, $BLESSEDMEMBERS{$field};
+    }
+    return $val;
+}
+
+sub STORE {
+    my ($self,$field,$newval) = @_;
+    my $member_func = "vectorc::Vector_${field}_set";
+    if (exists $BLESSEDMEMBERS{$field}) {
+        &$member_func($self,tied(%{$newval}));
+    } else {
+        &$member_func($self,$newval);
+    }
+}
+
      + +

      +Each structure or class is mapped into a Perl package of the same +name. The C++ constructors and destructors are mapped into +constructors and destructors for the package and are always named +"new" and "DESTROY". The constructor always returns a tied hash +table. This hash table is used to access the member variables of a +structure in addition to being able to invoke member functions. The +%OWNER and %BLESSEDMEMBERS hash tables are used +internally and described shortly. +

      + +

      +To use our new proxy class we can simply do the following: +

      + +
      +# Perl code using Vector class
+$v = new Vector(2,3,4);
+$w = Vector->new(-1,-2,-3);
+
+# Assignment of a single member
+$v->{x} = 7.5;
+
+# Assignment of all members
+%$v = ( x=>3,
+	 y=>9,
+	 z=>-2);
+
+# Reading members
+$x = $v->{x};
+
+# Destruction
+$v->DESTROY();
+
+
      + +

      28.9.3 Object Ownership

      + + +

      +In order for proxy classes to work properly, it is necessary for Perl +to manage some mechanism of object ownership. Here's the crux of the +problem---suppose you had a function like this : +

      + +
      +Vector *Vector_get(Vector *v, int index) {
+	return &v[i];
+}
+
      + +

      +This function takes a Vector pointer and returns a pointer to another +Vector. Such a function might be used to manage arrays or lists of +vectors (in C). Now contrast this function with the constructor for a +Vector object : +

      + +
      +Vector *new_Vector(double x, double y, double z) {
+	Vector *v;
+	v = new Vector(x,y,z);        // Call C++ constructor
+	return v;
+}
+
      + +

      +Both functions return a Vector, but the constructor is returning a +brand-new Vector while the other function is returning a Vector that +was already created (hopefully). In Perl, both vectors will be +indistinguishable---clearly a problem considering that we would +probably like the newly created Vector to be destroyed when we are +done with it. +

      + +

      +To manage these problems, each class contains two methods that access +an internal hash table called %OWNER. This hash keeps a list +of all of the objects that Perl knows that it has created. This +happens in two cases: (1) when the constructor has been called, and +(2) when a function implicitly creates a new object (as is done when +SWIG needs to return a complex datatype by value). When the +destructor is invoked, the Perl proxy class module checks the +%OWNER hash to see if Perl created the object. If so, the +C/C++ destructor is invoked. If not, we simply destroy the Perl +object and leave the underlying C object alone (under the assumption +that someone else must have created it). +

      + +

      +This scheme works remarkably well in practice but it isn't foolproof. +In fact, it will fail if you create a new C object in Perl, pass it on +to a C function that remembers the object, and then destroy the +corresponding Perl object (this situation turns out to come up +frequently when constructing objects like linked lists and trees). +When C takes possession of an object, you can change Perl's ownership +by simply deleting the object from the %OWNER hash. This is +done using the DISOWN method. +

      + +
      +# Perl code to change ownership of an object
+$v = new Vector(x,y,z);
+$v->DISOWN();     
+
      + +

      +To acquire ownership of an object, the ACQUIRE method can be used. +

      + +
      +# Given Perl ownership of a file
+$u = Vector_get($v);
+$u->ACQUIRE();
+
+
      + +

      +As always, a little care is in order. SWIG does not provide reference +counting, garbage collection, or advanced features one might find in +sophisticated languages. +

      + +

      28.9.4 Nested Objects

      + + +

      +Suppose that we have a new object that looks like this : +

      + +
      +struct Particle {
+	Vector r;
+	Vector v;
+	Vector f;
+	int	type;
+}
+
+
      + +

      +In this case, the members of the structure are complex objects that +have already been encapsulated in a Perl proxy class. To handle +these correctly, we use the %BLESSEDMEMBERS hash which would +look like this (along with some supporting code) : +

      + +
      +package Particle;
+...
+%BLESSEDMEMBERS = (
+	r => `Vector',
+	v => `Vector',
+	f => `Vector',
+);
+
+
      + +

      +When fetching members from the structure, %BLESSEDMEMBERS is +checked. If the requested field is present, we create a tied-hash +table and return it. If not, we just return the corresponding member +unmodified. +

      + +

      +This implementation allows us to operate on nested structures as follows : +

      + +
      +# Perl access of nested structure
+$p = new Particle();
+$p->{f}->{x} = 0.0;
+%${$p->{v}} = ( x=>0, y=>0, z=>0);         
+
      + +

      28.9.5 Proxy Functions

      + + +

      +When functions take arguments involving a complex object, it is +sometimes necessary to write a proxy function. For example : +

      + +
      +double dot_product(Vector *v1, Vector *v2);
+
      + +

      +Since Vector is an object already wrapped into a proxy class, we need +to modify this function to accept arguments that are given in the form +of tied hash tables. This is done by creating a Perl function like +this : +

      + +
      +sub dot_product {
+    my @args = @_;
+    $args[0] = tied(%{$args[0]});         # Get the real pointer values
+    $args[1] = tied(%{$args[1]});
+    my $result = vectorc::dot_product(@args);
+    return $result;
+}
+
      + +

      +This function replaces the original function, but operates in an +identical manner. +

      + +

      28.9.6 Inheritance

      + + +

      +Simple C++ inheritance is handled using the Perl @ISA array +in each class package. For example, if you have the following +interface file : +

      + +
      +// shapes.i
+// SWIG interface file for shapes class
+%module shapes
+%{
+#include "shapes.h"
+%}
+
+class Shape {
+public:
+	virtual double area() = 0;
+	virtual double perimeter() = 0;
+	void    set_location(double x, double y);
+};
+class Circle : public Shape {
+public:
+	Circle(double radius);
+	~Circle();
+	double area();
+	double perimeter();
+};
+class Square : public Shape {
+public:
+	Square(double size);
+	~Square();
+	double area();
+	double perimeter();
+}
+
+
      + +

      +The resulting, Perl wrapper class will create the following code : +

      + +
      +Package Shape;
+@ISA = (shapes);
+...
+Package Circle;
+@ISA = (shapes Shape);
+...
+Package Square;
+@ISA = (shapes Shape);
+
+
      + +

      +The @ISA array determines where to look for methods of a +particular class. In this case, both the Circle and +Square classes inherit functions from Shape so we'll +want to look in the Shape base class for them. All classes +also inherit from the top-level module shapes. This is +because certain common operations needed to implement proxy classes +are implemented only once and reused in the wrapper code for various +classes and structures. +

      + +

      +Since SWIG proxy classes are implemented in Perl, it is easy to +subclass from any SWIG generated class. To do this, simply put the +name of a SWIG class in the @ISA array for your new +class. However, be forewarned that this is not a trivial problem. In +particular, inheritance of data members is extremely tricky (and I'm +not even sure if it really works). +

      + +

      28.9.7 Modifying the proxy methods

      + + +

      +It is possible to override the SWIG generated proxy/shadow methods, using %feature("shadow"). +It works like all the other %feature directives. +Here is a simple example showing how to add some Perl debug code to the constructor: +

      + +
      +/* Let's make the constructor of the class Square more verbose */
+%feature("shadow") Square(double w)
+%{
+  sub new {
+    my $pkg = shift;
+    my $self = examplec::new_Square(@_);
+    print STDERR "Constructed an @{[ref($self)]}\n";
+    bless $self, $pkg if defined($self);
+  }
+%}
+
+class Square {
+public:
+  Square(double w);
+  ...
+};
+
      + +

      28.10 Adding additional Perl code

      + + +

      +If writing support code in C isn't enough, it is also possible to write code in +Perl. This code gets inserted in to the .pm file created by SWIG. One +use of Perl code might be to supply a high-level interface to certain functions. +For example: +

      + +
      +
      +void set_transform(Image *im, double x[4][4]);
+
+...
+/* Rewrite the high level interface to set_transform */
+%perlcode %{
+sub set_transform
+{
+  my ($im, $x) = @_;
+  my $a = new_mat44();
+  for (my $i = 0; $i < 4, $i++)
+  {
+    for (my $j = 0; $j < 4, $j++)
+    {
+      mat44_set($a, $i, $j, $x->[i][j])
+      }
+  }
+  example.set_transform($im, $a);
+  free_mat44($a);
+}
+%}
+
      +
      + +

      +In this example, set_transform() provides a high-level Perl interface built on top of +low-level helper functions. For example, this code now seems to work: +

      + +
      +
      +my $a =
+  [[1,0,0,0],
+   [0,1,0,0],
+   [0,0,1,0],
+   [0,0,0,1]];
+set_transform($im, $a);
+
      +
      + + + + + diff --git a/Doc/Manual/Php.html b/Doc/Manual/Php.html new file mode 100644 index 0000000..de745e1 --- /dev/null +++ b/Doc/Manual/Php.html @@ -0,0 +1,1252 @@ + + + + +SWIG and PHP + + + + +

      29 SWIG and PHP

      + +
      + +
      + + + + +

      +SWIG supports generating wrappers for PHP5. Support for PHP4 has been removed +as of SWIG 1.3.37. The PHP developers are no longer making new PHP4 releases, +and won't even be patching critical security issues after 2008-08-08, so it +doesn't make much sense for SWIG to continue to support PHP4 at this point. +If you need to continue to use PHP4, stick with SWIG 1.3.36. +

      + +

      +In this chapter, we discuss SWIG's support of PHP. The PHP module +was extensively rewritten in release 1.3.26, and support for generating +OO wrappers for PHP5 was added in 1.3.30. The PHP module works fairly +well, but currently does not implement all the +features available in some of the other languages. +

      + +

      +In order to use this module, you will need to have a copy of the PHP5 +include files to compile the SWIG generated files. If you installed +PHP from a binary package, you may need to install a "php-dev" or "php-devel" +package for these to be installed. You can find out where these files are +by running php-config --includes. To use the built PHP module you +will need either the php binary or the Apache php module. If you want to build +your extension into php directly, you will need the complete PHP source tree +available. +

      + +

      29.1 Generating PHP Extensions

      + + +

      +To build a PHP extension, run swig using the -php option as +follows: +

      + +
      +swig -php example.i
+
      + +

      +This will produce 3 files example_wrap.c, php_example.h and +example.php. The first file, example_wrap.c contains all of +the C code needed to build a PHP extension. The second file, +php_example.h contains the header information needed if +you wish to statically link the extension into the php interpreter. +The third file, +example.php 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 PHP5 class wrappers. +

      + +

      +Swig can generate PHP extensions from C++ libraries as well when +given the -c++ option. The support for C++ is discussed in +more detail in section 27.2.6. +

      + +

      +The usual (and recommended) way is to build the extension as a separate +dynamically loaded module (which is supported by all modern operating +systems). You can then specify that this be loaded +automatically in php.ini or load it explicitly for any script which +needs it. +

      + +

      +It is also possible to rebuild PHP from source so that your module is +statically linked into the php executable/library. This is a lot more +work, and also requires a full rebuild of PHP to update your module, +and it doesn't play nicely with package system. We don't recommend +this approach, or provide explicit support for it. +

      + +

      29.1.1 Building a loadable extension

      + + +

      +To build your module as a dynamically loadable extension, use compilation +commands like these (if you aren't using GCC, the commands will be different, +and there may be some variation between platforms - these commands should at +least work for Linux though): +

      + +
      +	gcc `php-config --includes` -fpic -c example_wrap.c
+	gcc -shared example_wrap.o -o example.so
+
      + +

      29.1.2 Using PHP Extensions

      + + +

      +To test the extension from a PHP script, you need to load it first. You +can load it for every script by adding this line the [PHP] section of +php.ini: +

      + +
      +	extension=/path/to/modulename.so
+
      + +

      +Alternatively, you can load it explicitly only for scripts which need it +by adding this line: +

      + +
      +	dl("/path/to/modulename.so");	// Load the module
+
      + +

      +to the start of each PHP file. SWIG also generates a php module, which +attempts to do the dl() call for you: +

      + +
      +	include("example.php");
+
      + +

      29.2 Basic PHP interface

      + + +

      +It is important to understand that PHP uses a single global namespace +into which all symbols from extension modules are loaded. It is quite +possible for names of symbols in one extension module to clash with +other symbols unless care is taken to %rename them. +

      + +

      29.2.1 Constants

      + + +

      +These work in much the same way as in C/C++, constants can be defined +by using either the normal C pre-processor declarations, or the +%constant SWIG directive. These will then be available from +your PHP script as a PHP constant, (i.e. no dollar sign is needed to +access them.) For example, with a swig interface file like this, +

      + +
      +%module example
+
+#define PI 3.14159
+
+%constant int E  = 2.71828
+
      +
      + +

      +you can access the constants in your php script like this, +

      + +
      +include("example.php");
+
+echo "PI = " . PI . "\n";
+
+echo "E = " . E . "\n";
+
+
      +
      + +

      +There are two peculiarities with using constants in PHP. The first is that +if you try to use an undeclared constant, it will evaluate to a string +set to the constant's name. For example, +

      + +
      +%module example
+
+#define EASY_TO_MISPELL	0
+
      +
      + +

      +accessed incorrectly in PHP, +

      + +
      +
      +include("example.php");
+
+if(EASY_TO_MISPEL) {
+	....
+} else {
+	....
+}
+
+
      +
      + +

      +will issue a warning about the undeclared constant, but will then +evaluate it and turn it into a string ('EASY_TO_MISPEL'), which +evaluates to true, rather than the value of the constant which would +be false. This is a feature! +

      + +

      +The second 'feature' is that although constants are case sensitive (by +default), you cannot declare a constant twice with alternative +cases. E.g., +

      + +
      +
      +%module example
+
+#define TEST	Hello
+#define Test	World
+
      +
      + +

      +accessed from PHP, +

      + +
      +
      +include("example.php");
+
+echo TEST, Test;
+
      +
      + +

      +will output "Hello Test" rather than "Hello World". This is because +internally, all constants are stored in a hash table by their lower +case name, so 'TEST' and 'Test' will map to the same hash element +('Test'). But, because we declared them case sensitive, the Zend +engine will test if the case matches with the case the constant was +declared with first. +

      + +

      +So, in the example above, the TEST constant was declared first, and +will be stored under the hash element 'test'. The 'Test' constant will +also map to the same hash element 'test', but will not overwrite +it. When called from the script, the TEST constant will again be +mapped to the hash element 'test' so the constant will be +retrieved. The case will then be checked, and will match up, so the +value ('Hello') will be returned. When 'Test' is evaluated, it will +also map to the same hash element 'test'. The same constant will be +retrieved, this time though the case check will fail as 'Test' != +'TEST'. So PHP will assume that Test is a undeclared constant, and as +explained above, will return it as a string set to the constant name +('Test'). Hence the script above will print 'Hello Test'. If they were +declared non-case sensitive, the output would be 'Hello Hello', as +both point to the same value, without the case test taking place. ( +Apologies, this paragraph needs rewriting to make some sense. ) +

      + +

      29.2.2 Global Variables

      + + +

      +Because PHP does not provide a mechanism to intercept access and +assignment of global variables, global variables are supported through +the use of automatically generated accessor functions. +

      + +
      +%module example;
+
+%inline %{
+  double seki = 2;
+  void print_seki() {
+    zend_printf("seki is now %f\n",seki);
+  }
+%}
+
      + +

      +is accessed as follows: +

      + +
      +include("example.php");
+print seki_get();
+seki_set( seki_get() * 2);	# The C variable is now 4.
+print seki_get();
+
      + +

      +SWIG supports global variables of all C datatypes including pointers +and complex objects. Additional types can be supported by using the +varinit typemap. +

      + +

      +SWIG honors the %immutable modifier by not generating code +for the _set method. This provides read-only access to the +variable from the php script. Attempting to access the _set +method will result in a php fatal error because the function is +undefined. +

      + +

      +At this time SWIG does not support custom accessor methods. +

      + +

      29.2.3 Functions

      + + +

      +C functions are converted into PHP functions. Default/optional arguments are +also allowed. An interface file like this : +

      + +
      +%module example
+int foo(int a);
+double bar(double, double b = 3.0);
+...
+
      + +

      +Will be accessed in PHP like this : +

      + +
      +include("example.php");
+$a = foo(2);
+$b = bar(3.5, -1.5);
+$c = bar(3.5);		# Use default argument for 2nd parameter
+
+
      + + + + +

      29.2.4 Overloading

      + + +

      +Although PHP does not support overloading functions natively, swig +will generate dispatch functions which will use %typecheck +typemaps to allow overloading. This dispatch function's operation and +precedence is described in Wrapping +Overloaded Functions and Methods. +

      + + + +

      29.2.5 Pointers and References

      + + +

      +Pointers to C/C++ objects are represented +as PHP resources, rather like MySQL connection handles. +

      + +

      +There are multiple ways to wrap pointers to simple types. Given the +following C method: +

      + +
      +  void add( int *in1, int *in2, int *result);
+
      + +

      +One can include cpointer.i to generate PHP wrappers to int +*. +

      + +
      +%module example
+%include "cpointer.i"
+%pointer_functions(int,intp)
+
+void add( int *in1, int *in2, int *result);
+
      + +

      +This will result in the following usage in PHP: +

      + +
      +<?php
+
+include("example.php");
+
+$in1=copy_intp(3);
+$in2=copy_intp(5);
+$result=new_intp();
+
+add( $in1, $in2, $result );
+
+echo "The sum " . intp_value($in1) . " + " . intp_value($in2) . " = " . intp_value( $result) . "\n";
+?>
+
      + +

      +An alternative would be to use the include typemaps.i which +defines named typemaps for INPUT, OUTPUT and INOUT variables. One +needs to either %apply the appropriate typemap or adjust the +parameter names as appropriate. +

      + +
      +%module example
+%include "typemaps.i"
+
+void add( int *INPUT, int *INPUT, int *OUTPUT);
+
+
      + +

      +This will result in the following usage in PHP: +

      + +
      +<?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";
+?>
+
      + +

      +Because PHP has a native concept of reference, it may seem more natural +to the PHP developer to use references to pass pointers. To enable +this, one needs to include phppointers.i which defines the +named typemap REFERENCE. +

      + +
      +%module example
+%include "phppointers.i"
+
+void add( int *REF, int *REF, int *REF);
+
+
      + +

      +This will result in the following usage in PHP: +

      + +
      +<?php
+
+include("example.php");
+
+$in1 = 3;
+$in2 = 5;
+$result = 0;
+add(&$in1,&$in2,&$result);
+
+echo "The sum $in1 + $in2 = $result\n";
+?>
+
      + +

      +It is important to note that a php variable which is NULL when passed +by reference would end up passing a NULL pointer into the function. +In PHP, an unassigned variable (i.e. where the first reference to the +variable is not an assignment) is +NULL. In the above example, if any of the three variables had not +been assigned, a NULL pointer would have been passed into +add. Depending on the implementation of the function, this +may or may not be a good thing. +

      + +

      +We chose to allow passing NULL pointers into functions because that is +sometimes required in C libraries. A NULL pointer can be created in +PHP in a number of ways: by using unset on an existing +variable, or assigning NULL to a variable. +

      + +

      29.2.6 Structures and C++ classes

      + + +

      +SWIG defaults to wrapping C++ structs and classes with PHP classes +unless "-noproxy" is specified. For PHP5, a PHP wrapper +class is generated which calls a set of flat functions wrapping the C++ class. +

      + +

      +This interface file +

      + +
      +%module vector
+
+class Vector {
+public:
+	double x,y,z;
+	Vector();
+	~Vector();
+	double magnitude();
+};
+
+struct Complex {
+ double re, im;
+};
+
      + +

      +Would be used in the following way from PHP5: +

      + +
      +<?php
+  require "vector.php";
+
+  $v = new Vector();
+  $v->x = 3;
+  $v->y = 4;
+  $v->z = 5;
+
+  echo "Magnitude of ($v->x,$v->y,$v->z) = " . $v->magnitude() . "\n";
+
+  $v = NULL;   # destructor called.
+
+  $c = new Complex();
+
+  $c->re = 0;
+  $c->im = 0;
+
+  # $c destructor called when $c goes out of scope.
+?>
+
      + +

      +Member variables and methods are accessed using the -> operator. +

      + +

      29.2.6.1 Using -noproxy

      + + +

      +The -noproxy option flattens the object structure and +generates collections of named functions (these are the functions +which the PHP5 class wrappers call). The above example results +in the following PHP functions: +

      + +
      +new_Vector();
+Vector_x_set($obj,$d);
+Vector_x_get($obj);
+Vector_y_set($obj,$d);
+Vector_y_get($obj);
+Vector_z_set($obj,$d);
+Vector_z_get($obj);
+Vector_magnitude($obj);
+new_Complex();
+Complex_re_set($obj,$d);
+Complex_re_get($obj);
+Complex_im_set($obj,$d);
+Complex_im_get($obj);
+
      + +

      29.2.6.2 Constructors and Destructors

      + + +

      +The constructor is called when new Object() (or +new_Object() if using -noproxy) is used to create an +instance of the object. If multiple constructors are defined for an +object, function overloading will be used to determine which +constructor to execute. +

      + +

      +Because PHP uses reference counting to manage resources, simple +assignment of one variable to another such as: +

      + +
      +$ref = $v;
+
      + +

      +causes the symbol $ref to refer to the same underlying object +as $v. This does not result in a call to the C++ copy +constructor or copy assignment operator. +

      + +

      +One can force execution of the copy constructor by using: +

      +
      +$o_copy = new Object($o);
+
      + +

      +Destructors are automatically called when all variables referencing +the instance are reassigned or go out of scope. The destructor is not +available to be called manually. To force a destructor to be called +the programmer can either reassign the variable or call +unset($v) +

      + +

      29.2.6.3 Static Member Variables

      + + +

      +Static member variables in C++ are not wrapped as such in PHP +as it does not appear to be possible to intercept accesses to such variables. +Therefore, static member variables are +wrapped using a class function with the same name, which +returns the current value of the class variable. For example +

      + +
      +%module example
+
+class Ko {
+	static int threats;
+};
+
+
      + +

      +would be accessed in PHP as, +

      + +
      +include("example.php");
+
+echo "There has now been " . Ko::threats() . " threats\n";
+
+
      + +

      +To set the static member variable, pass the value as the argument to the class +function, e.g. +

      + +
      +
+Ko::threats(10);
+
+echo "There has now been " . Ko::threats() . " threats\n";
+
+
      +

      29.2.6.4 Static Member Functions

      + + +

      +Static member functions are supported in PHP using the +class::function() syntax. For example +

      + +
      +%module example
+class Ko {
+  static void threats();
+};
+
      + +would be executed in PHP as, +
      +include("example.php");
+Ko::threats();
+
      + + +

      29.2.7 PHP Pragmas, Startup and Shutdown code

      + + +

      +To place PHP code in the generated "example.php" file one can use the +code pragma. The code is inserted after loading the shared +object. +

      + +
      +%module example
+%pragma(php) code="
+# This code is inserted into example.php
+echo \"example.php execution\\n\";
+"
+
      + +

      +Results in the following in "example.php" +

      + +
      +# This code is inserted into example.php
+echo "example.php execution\n";
+
      + +

      +The include pragma is a short cut to add include statements to +the example.php file. +

      + +
      +%module example
+%pragma(php) code="
+include \"include.php\";
+"
+%pragma(php) include="include.php"   // equivalent.
+
      + +

      +The phpinfo pragma inserts code in the +PHP_MINFO_FUNCTION which is called from PHP's +phpinfo() function. +

      + +
      +%module example;
+%pragma(php) phpinfo="
+  zend_printf("An example of PHP support through SWIG\n");
+  php_info_print_table_start();
+  php_info_print_table_header(2, \"Directive\", \"Value\");
+  php_info_print_table_row(2, \"Example support\", \"enabled\");
+  php_info_print_table_end();
+"
+
      + +

      +To insert code into the PHP_MINIT_FUNCTION, one can use +either %init or %minit. +

      + +
      +%module example;
+%init {
+  zend_printf("Inserted into PHP_MINIT_FUNCTION\n");
+}
+%minit {
+  zend_printf("Inserted into PHP_MINIT_FUNCTION\n");
+}
+
      + +

      +To insert code into the PHP_MSHUTDOWN_FUNCTION, one can use +either %init or %minit. +

      + +
      +%module example;
+%mshutdown {
+  zend_printf("Inserted into PHP_MSHUTDOWN_FUNCTION\n");
+}
+
      + +

      +The %rinit and %rshutdown statements insert code +into the request init and shutdown code respectively. +

      + +

      29.3 Cross language polymorphism

      + + +

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

      + +

      +This arrangement is asymmetric in the sense that no corresponding +mechanism exists to pass method calls down the inheritance chain from +C++ to PHP. In particular, if a C++ class has been extended in PHP +(by extending the proxy class), these extensions will not be visible +from C++ code. Virtual method calls from C++ are thus not able access +the lowest implementation in the inheritance chain. +

      + +

      +Changes have been made to SWIG 1.3.18 to address this problem and make +the relationship between C++ classes and proxy classes more symmetric. +To achieve this goal, new classes called directors are introduced at the +bottom of the C++ inheritance chain. Support for generating PHP classes +has been added in SWIG 1.3.40. The job of the directors is to route +method calls correctly, either to C++ implementations higher in the +inheritance chain or to PHP implementations lower in the inheritance +chain. The upshot is that C++ classes can be extended in PHP and from +C++ these extensions look exactly like native C++ classes. Neither C++ +code nor PHP code needs to know where a particular method is +implemented: the combination of proxy classes, director classes, and C +wrapper functions takes care of all the cross-language method routing +transparently. +

      + +

      29.3.1 Enabling directors

      + + +

      +The director feature is disabled by default. To use directors you +must make two changes to the interface file. First, add the "directors" +option to the %module directive, like this: +

      + +
      +
      +%module(directors="1") modulename
+
      +
      + +

      +Without this option no director code will be generated. Second, you +must use the %feature("director") directive to tell SWIG which classes +and methods should get directors. The %feature directive can be applied +globally, to specific classes, and to specific methods, like this: +

      + +
      +
      +// generate directors for all classes that have virtual methods
+%feature("director");         
+
+// generate directors for all virtual methods in class Foo
+%feature("director") Foo;      
+
+// generate a director for just Foo::bar()
+%feature("director") Foo::bar; 
+
      +
      + +

      +You can use the %feature("nodirector") directive to turn off +directors for specific classes or methods. So for example, +

      + +
      +
      +%feature("director") Foo;
+%feature("nodirector") Foo::bar;
+
      +
      + +

      +will generate directors for all virtual methods of class Foo except +bar(). +

      + +

      +Directors can also be generated implicitly through inheritance. +In the following, class Bar will get a director class that handles +the methods one() and two() (but not three()): +

      + +
      +
      +%feature("director") Foo;
+class Foo {
+public:
+    Foo(int foo);
+    virtual void one();
+    virtual void two();
+};
+
+class Bar: public Foo {
+public:
+    virtual void three();
+};
+
      +
      + +

      +then at the PHP side you can define +

      + +
      +
      +require("mymodule.php");
+
+class MyFoo extends Foo {
+  function one() {
+     print "one from php\n";
+  }
+}
+
      +
      + + +

      29.3.2 Director classes

      + + + + + +

      +For each class that has directors enabled, SWIG generates a new class +that derives from both the class in question and a special +Swig::Director 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. +

      + +

      +For simplicity let's ignore the Swig::Director class and refer to the +original C++ class as the director's base class. By default, a director +class extends all virtual methods in the inheritance chain of its base +class (see the preceding section for how to modify this behavior). +Thus all virtual method calls, whether they originate in C++ or in +PHP via proxy classes, eventually end up in at the implementation in the +director class. The job of the director methods is to route these method +calls to the appropriate place in the inheritance chain. By "appropriate +place" we mean the method that would have been called if the C++ base +class and its extensions in PHP were seamlessly integrated. That +seamless integration is exactly what the director classes provide, +transparently skipping over all the messy extension API glue that binds +the two languages together. +

      + +

      +In reality, the "appropriate place" is one of only two possibilities: +C++ or PHP. Once this decision is made, the rest is fairly easy. If the +correct implementation is in C++, then the lowest implementation of the +method in the C++ inheritance chain is called explicitly. If the correct +implementation is in PHP, the Zend API is used to call the method of the +underlying PHP object (after which the usual virtual method resolution +in PHP automatically finds the right implementation). +

      + +

      +Now how does the director decide which language should handle the method call? +The basic rule is to handle the method in PHP, unless there's a good +reason not to. The reason for this is simple: PHP has the most +"extended" implementation of the method. This assertion is guaranteed, +since at a minimum the PHP proxy class implements the method. If the +method in question has been extended by a class derived from the proxy +class, that extended implementation will execute exactly as it should. +If not, the proxy class will route the method call into a C wrapper +function, expecting that the method will be resolved in C++. The wrapper +will call the virtual method of the C++ instance, and since the director +extends this the call will end up right back in the director method. Now +comes the "good reason not to" part. If the director method were to blindly +call the PHP method again, it would get stuck in an infinite loop. We avoid this +situation by adding special code to the C wrapper function that tells +the director method to not do this. The C wrapper function compares the +called and the declaring class name of the given method. If these are +not the same, then the C wrapper function tells the director to resolve +the method by calling up the C++ inheritance chain, preventing an +infinite loop. +

      + +

      +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 ->_cPtr. This is exactly what happens without directors +and is true even if directors are enabled for the particular class in +question. When a class derived 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 +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++ +so there is no need for the extra overhead involved with routing the +calls through PHP. +

      + +

      29.3.3 Ownership and object destruction

      + + +

      +Memory management issues are slightly more complicated with directors +than for proxy classes alone. PHP instances hold a pointer to the +associated C++ director object, and the director in turn holds a pointer +back to the PHP object. By default, proxy classes own their C++ director +object and take care of deleting it when they are garbage collected. +

      + +

      +This relationship can be reversed by calling the special +->thisown property of the proxy class. After setting this +property to 0, the director class no longer destroys the PHP +object. Assuming no outstanding references to the PHP object remain, +the PHP object will be destroyed at the same time. This is a good thing, +since directors and proxies refer to each other and so must be created +and destroyed together. Destroying one without destroying the other will +likely cause your program to segfault. +

      + +

      +Here is an example: +

      + +
      +
      +class Foo {
+public:
+    ...
+};
+class FooContainer {
+public:
+    void addFoo(Foo *);
+    ...
+};
+
      +
      + +
      + +
      +
      +$c = new FooContainer();
+$a = new Foo();
+$a->thisown = 0;
+$c->addFoo($a);
+
      +
      + +

      +In this example, we are assuming that FooContainer will take care of +deleting all the Foo pointers it contains at some point. +

      + +

      29.3.4 Exception unrolling

      + + +

      +With directors routing method calls to PHP, and proxies routing them +to C++, the handling of exceptions is an important concern. By default, the +directors ignore exceptions that occur during method calls that are +resolved in PHP. To handle such exceptions correctly, it is necessary +to temporarily translate them into C++ exceptions. This can be done with +the %feature("director:except") directive. The following code should +suffice in most cases: +

      + +
      +
      +%feature("director:except") {
+    if ($error == FAILURE) {
+        throw Swig::DirectorMethodException();
+    }
+}
+
      +
      + +

      +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. +Currently no information about the PHP error is stored in the +Swig::DirectorMethodException object, but this will likely change in the +future. +

      + +

      +It may be the case that a method call originates in PHP, travels up to +C++ through a proxy class, and then back into PHP via a director method. +If an exception occurs in PHP at this point, it would be nice for that +exception to find its way back to the original caller. This can be done +by combining a normal %exception directive with the +director:except handler shown above. Here is an example of a +suitable exception handler: +

      + +
      +
      +%exception {
+    try { $action }
+    catch (Swig::DirectorException &e) { SWIG_fail; }
+}
+
      +
      + +

      +The class Swig::DirectorException used in this example is actually a +base class of Swig::DirectorMethodException, so it will trap this +exception. Because the PHP error state is still set when +Swig::DirectorMethodException is thrown, PHP will register the exception +as soon as the C wrapper function returns. +

      + +

      29.3.5 Overhead and code bloat

      + + +

      +Enabling directors for a class will generate a new director method for +every virtual method in the class' inheritance chain. This alone can +generate a lot of code bloat for large hierarchies. Method arguments +that require complex conversions to and from target language types can +result in large director methods. For this reason it is recommended that +you selectively enable directors only for specific classes that are +likely to be extended in PHP and used in C++. +

      + +

      +Compared to classes that do not use directors, the call routing in the +director methods does add some overhead. In particular, at least one +dynamic cast and one extra function call occurs per method call from +PHP. Relative to the speed of PHP execution this is probably completely +negligible. For worst case routing, a method call that ultimately +resolves in C++ may take one extra detour through PHP in order to ensure +that the method does not have an extended PHP implementation. This could +result in a noticeable overhead in some cases. +

      + +

      +Although directors make it natural to mix native C++ objects with PHP +objects (as director objects) via a common base class pointer, one +should be aware of the obvious fact that method calls to PHP objects +will be much slower than calls to C++ objects. This situation can be +optimized by selectively enabling director methods (using the %feature +directive) for only those methods that are likely to be extended in PHP. +

      + +

      29.3.6 Typemaps

      + + +

      +Typemaps for input and output of most of the basic types from director +classes have been written. These are roughly the reverse of the usual +input and output typemaps used by the wrapper code. The typemap +operation names are 'directorin', 'directorout', and 'directorargout'. +The director code does not currently use any of the other kinds of +typemaps. It is not clear at this point which kinds are appropriate and +need to be supported. +

      + + +

      29.3.7 Miscellaneous

      + + +

      Director typemaps for STL classes are mostly in place, and hence you +should be able to use std::string, etc., as you would any other type. +

      + + + diff --git a/Doc/Manual/Pike.html b/Doc/Manual/Pike.html new file mode 100644 index 0000000..a47d078 --- /dev/null +++ b/Doc/Manual/Pike.html @@ -0,0 +1,245 @@ + + + +SWIG and Pike + + + + +

      30 SWIG and Pike

      + +
      + +
      + + + + +

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

      + +

      +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 "SWIG Basics" +chapter.
      +

      + +

      30.1 Preliminaries

      + + +

      30.1.1 Running SWIG

      + + +

      +Suppose that you defined a SWIG module such as the following: +

      + +
      + 
      %module example

      %{
      #include "example.h"
      %}

      int fact(int n);
      +
      + +

      +To build a C extension module for Pike, run SWIG using the -pike option : +

      + +
      + 
      $ swig -pike example.i
      +
      + +

      +If you're building a C++ extension, be sure to add the -c++ option: +

      + +
      + 
      $ swig -c++ -pike example.i
      +
      + +

      +This creates a single source file named example_wrap.c (or example_wrap.cxx, if you +ran SWIG with the -c++ 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. +

      + +

      +The name of the wrapper file is derived from the name of the input +file. For example, if the input file is example.i, the name +of the wrapper file is example_wrap.c. To change this, you +can use the -o option: +

      + +
      + 
      $ swig -pike -o pseudonym.c example.i
      +
      +

      30.1.2 Getting the right header files

      + + +

      +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 +

      + +
      + 
      /usr/local/pike/7.4.10/include/pike
      +
      + +

      +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 global.h, program.h +and so on. +

      + +

      30.1.3 Using your module

      + + +

      +To use your module, simply use Pike's import statement: +

      + +
      +$ pike
+Pike v7.4 release 10 running Hilfe v3.5 (Incremental Pike Frontend)
+> import example;
+> fact(4);
+(1) Result: 24
+
      + +

      30.2 Basic C/C++ Mapping

      + + +

      30.2.1 Modules

      + + +

      +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 %module directive doesn't really have any +significance. +

      + +

      30.2.2 Functions

      + + +

      +Global functions are wrapped as new Pike built-in functions. For +example, +

      + +
      +%module example
+
+int fact(int n);
+
      + +

      +creates a new built-in function example.fact(n) that works +exactly as you'd expect it to: +

      + +
      +> import example;
+> fact(4);
+(1) Result: 24
+
      + +

      30.2.3 Global variables

      + + +

      +Global variables are currently wrapped as a pair of of functions, one to get +the current value of the variable and another to set it. For example, the +declaration +

      + +
      +%module example
+
+double Foo;
+
      + +

      +will result in two functions, Foo_get() and Foo_set(): +

      + +
      +> import example;
+> Foo_get();
+(1) Result: 3.000000
+> Foo_set(3.14159);
+(2) Result: 0
+> Foo_get();
+(3) Result: 3.141590
+
      + +

      30.2.4 Constants and enumerated types

      + + +

      +Enumerated types in C/C++ declarations are wrapped as Pike constants, +not as Pike enums. +

      + +

      30.2.5 Constructors and Destructors

      + + +

      +Constructors are wrapped as create() methods, and destructors are +wrapped as destroy() methods, for Pike classes. +

      + +

      30.2.6 Static Members

      + + +

      +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: +

      + +
      +class Shape
+{
+public:
+    static void print();
+    static int nshapes;
+};
+
      + +

      +SWIG will generate a Shape_print() method that invokes the static +Shape::print() member function, as well as a pair of methods, +Shape_nshapes_get() and Shape_nshapes_set(), to get and set +the value of Shape::nshapes. +

      + + + diff --git a/Doc/Manual/Preface.html b/Doc/Manual/Preface.html new file mode 100644 index 0000000..630657a --- /dev/null +++ b/Doc/Manual/Preface.html @@ -0,0 +1,251 @@ + + + +Preface + + + + +

      1 Preface

      + +
      + +
      + + + + +

      1.1 Introduction

      + + +

      +SWIG (Simplified Wrapper and Interface Generator) is a software development tool for building scripting language +interfaces to C and C++ programs. Originally developed in 1995, SWIG was +first used by scientists in the Theoretical Physics Division at Los Alamos National Laboratory for +building user interfaces to simulation codes running on the Connection +Machine 5 supercomputer. In this environment, scientists needed to +work with huge amounts of simulation data, complex hardware, and a +constantly changing code base. The use of a scripting language +interface provided a simple yet highly flexible foundation for solving these +types of problems. SWIG simplifies development by largely automating +the task of scripting language integration--allowing developers and users +to focus on more important problems. +

      + +

      +Although SWIG was originally developed for scientific applications, it +has since evolved into a general purpose tool that is used in a wide +variety of applications--in fact almost anything where C/C++ programming +is involved. + +

      1.2 Special Introduction for Version 1.3

      + + +

      +Since SWIG was released in 1996, its user base and applicability has +continued to grow. Although its rate of development has varied, an +active development effort has continued to make improvements to the +system. Today, nearly a dozen developers are working to create +SWIG-2.0---a system that aims to provide wrapping support for nearly +all of the ANSI C++ standard and approximately ten target languages +including Guile, Java, Mzscheme, Ocaml, Perl, Pike, PHP, Python, Ruby, +and Tcl. +

      + +

      1.3 SWIG Versions

      + + +

      +For several years, the most stable version of SWIG has been release +1.1p5. Starting with version 1.3, a new version numbering scheme has +been adopted. Odd version numbers (1.3, 1.5, etc.) represent +development versions of SWIG. Even version numbers (1.4, 1.6, etc.) +represent stable releases. Currently, developers are working to +create a stable SWIG-2.0 release. Don't let the development status +of SWIG-1.3 scare you---it is much more stable (and capable) than SWIG-1.1p5. +

      + +

      1.4 SWIG resources

      + + +

      +The official location of SWIG related material is +

      + +
      +http://www.swig.org
+
      + +

      +This site contains the latest version of the software, users guide, +and information regarding bugs, installation problems, and +implementation tricks. + +

      +You can also subscribe to the swig-user mailing list by visiting the page +

      + +
      +http://www.swig.org/mail.html
+
      + +

      +The mailing list often discusses some of the more technical aspects of +SWIG along with information about beta releases and future work. +

      + +

      +SVN access to the latest version of SWIG is also available. More information +about this can be obtained at: +

      + +
      +http://www.swig.org/svn.html
+
      + + +

      1.5 Prerequisites

      + + +

      +This manual assumes that you know how to write C/C++ programs and that you +have at least heard of scripting languages such as +Tcl, Python, and Perl. A detailed knowledge of these scripting +languages is not required although some familiarity won't +hurt. No prior experience with building C extensions to these +languages is required---after all, this is what SWIG does automatically. +However, you should be reasonably familiar with the use of +compilers, linkers, and makefiles since making +scripting language extensions is somewhat more complicated than +writing a normal C program. +

      + +

      +Recent SWIG releases have become significantly more capable in +their C++ handling--especially support for advanced features like +namespaces, overloaded operators, and templates. Whenever possible, +this manual tries to cover the technicalities of this interface. +However, this isn't meant to be a tutorial on C++ programming. For many +of the gory details, you will almost certainly want to consult a good C++ reference. If you don't program +in C++, you may just want to skip those parts of the manual. + +

      1.6 Organization of this manual

      + + +

      +The first few chapters of this manual describe SWIG in general and +provide an overview of its capabilities. The remaining chapters are +devoted to specific SWIG language modules and are self +contained. Thus, if you are using SWIG to build Python interfaces, you +can probably skip to that chapter and find almost everything you need +to know. Caveat: we are currently working on a documentation rewrite and many +of the older language module chapters are still somewhat out of date. +

      + +

      1.7 How to avoid reading the manual

      + + +

      +If you hate reading manuals, glance at the "Introduction" which +contains a few simple examples. These +examples contain about 95% of everything you need to know to use +SWIG. After that, simply use the language-specific chapters as a reference. +The SWIG distribution also comes with a large directory of +examples that illustrate different topics. +

      + +

      1.8 Backwards Compatibility

      + + +

      +If you are a previous user of SWIG, don't expect recent versions of +SWIG to provide backwards compatibility. In fact, backwards +compatibility issues may arise even between successive 1.3.x releases. +Although these incompatibilities are regrettable, SWIG-1.3 is an active +development project. The primary goal of this effort is to make SWIG +better---a process that would simply be impossible if the developers +are constantly bogged down with backwards compatibility issues. +

      + +

      +On a positive note, a few incompatibilities are a small price to pay +for the large number of new features that have been +added---namespaces, templates, smart pointers, overloaded methods, +operators, and more. +

      + + +

      +If you need to work with different versions of SWIG and backwards +compatibility is an issue, you can use the SWIG_VERSION preprocessor +symbol which holds the version of SWIG being executed. +SWIG_VERSION is a hexadecimal integer such as 0x010311 (corresponding to SWIG-1.3.11). +This can be used in an interface file to define different typemaps, take +advantage of different features etc: +

      + +
      +#if SWIG_VERSION >= 0x010311
+/* Use some fancy new feature */
+#endif
+
      + +

      +Note: The version symbol is not defined in the generated SWIG +wrapper file. The SWIG preprocessor has defined SWIG_VERSION since SWIG-1.3.11. +

      + +

      1.9 Credits

      + + +

      +SWIG is an unfunded project that would not be possible without the +contributions of many people. Most recent SWIG development has been +supported by Matthias Köppe, William Fulton, Lyle Johnson, +Richard Palmer, Thien-Thi Nguyen, Jason Stewart, Loic Dachary, Masaki +Fukushima, Luigi Ballabio, Sam Liddicott, Art Yerkes, Marcelo Matus, +Harco de Hilster, John Lenz, and Surendra Singhi. +

      + +

      +Historically, the following people contributed to early versions of SWIG. +Peter Lomdahl, Brad Holian, Shujia Zhou, Niels Jensen, and Tim Germann +at Los Alamos National Laboratory were the first users. Patrick +Tullmann at the University of Utah suggested the idea of automatic +documentation generation. John Schmidt and Kurtis Bleeker at the +University of Utah tested out the early versions. Chris Johnson +supported SWIG's developed at the University of Utah. John Buckman, +Larry Virden, and Tom Schwaller provided valuable input on the first +releases and improving the portability of SWIG. David Fletcher and +Gary Holt have provided a great deal of input on improving SWIG's +Perl5 implementation. Kevin Butler contributed the first Windows NT +port. + +

      1.10 Bug reports

      + + +

      +Although every attempt has been made to make SWIG bug-free, we are also trying +to make feature improvements that may introduce bugs. +To report a bug, either send mail to the SWIG developer +list at the swig-devel mailing list or report a bug +at the SWIG bug tracker. In your report, be as specific as +possible, including (if applicable), error messages, tracebacks (if a +core dump occurred), corresponding portions of the SWIG interface file +used, and any important pieces of the SWIG generated wrapper code. We +can only fix bugs if we know about them. +

      + + + diff --git a/Doc/Manual/Preprocessor.html b/Doc/Manual/Preprocessor.html new file mode 100644 index 0000000..5afa592 --- /dev/null +++ b/Doc/Manual/Preprocessor.html @@ -0,0 +1,491 @@ + + + +SWIG Preprocessor + + + + +

      7 Preprocessing

      + +
      + +
      + + + + +

      +SWIG includes its own enhanced version of the C preprocessor. The preprocessor +supports the standard preprocessor directives and macro expansion rules. +However, a number of modifications and enhancements have been made. This +chapter describes some of these modifications. +

      + +

      7.1 File inclusion

      + + +

      +To include another file into a SWIG interface, use the %include directive +like this: +

      + +
      +
      +%include "pointer.i"
+
      +
      + +

      +Unlike, #include, %include includes each file once (and will not +reload the file on subsequent %include declarations). Therefore, it +is not necessary to use include-guards in SWIG interfaces. +

      + +

      +By default, the #include is ignored unless you run SWIG with the +-includeall option. The reason for ignoring traditional includes +is that you often don't want SWIG to try and wrap everything included +in standard header system headers and auxiliary files. + +

      7.2 File imports

      + + +

      +SWIG provides another file inclusion directive with the %import directive. +For example: +

      + +
      +
      +%import "foo.i"
+
      +
      + +

      +The purpose of %import is to collect certain information from another +SWIG interface file or a header file without actually generating any wrapper code. +Such information generally includes type declarations (e.g., typedef) as well as +C++ classes that might be used as base-classes for class declarations in the interface. +The use of %import is also important when SWIG is used to generate +extensions as a collection of related modules. This is an advanced topic and is described +in later in the Working with Modules chapter. +

      + +

      +The -importall directive tells SWIG to follow all #include statements +as imports. This might be useful if you want to extract type definitions from system +header files without generating any wrappers. + +

      7.3 Conditional Compilation

      + + +

      +SWIG fully supports the use of #if, #ifdef, +#ifndef, #else, #endif to conditionally +include parts of an interface. The following symbols are predefined +by SWIG when it is parsing the interface: +

      + +
      +SWIG                            Always defined when SWIG is processing a file
+SWIGIMPORTED                    Defined when SWIG is importing a file with %import
+SWIGMAC                         Defined when running SWIG on the Macintosh
+SWIGWIN                         Defined when running SWIG under Windows
+SWIG_VERSION                    Hexadecimal number containing SWIG version,
+                                such as 0x010311 (corresponding to SWIG-1.3.11).
+
+SWIGALLEGROCL                   Defined when using Allegro CL
+SWIGCFFI                        Defined when using CFFI
+SWIGCHICKEN                     Defined when using CHICKEN
+SWIGCLISP                       Defined when using CLISP
+SWIGCSHARP                      Defined when using C#
+SWIGGUILE                       Defined when using Guile
+SWIGJAVA                        Defined when using Java
+SWIGLUA                         Defined when using Lua
+SWIGMODULA3                     Defined when using Modula-3
+SWIGMZSCHEME                    Defined when using Mzscheme        
+SWIGOCAML                       Defined when using Ocaml
+SWIGOCTAVE                      Defined when using Octave
+SWIGPERL                        Defined when using Perl
+SWIGPHP                         Defined when using PHP
+SWIGPIKE                        Defined when using Pike
+SWIGPYTHON                      Defined when using Python
+SWIGR                           Defined when using R
+SWIGRUBY                        Defined when using Ruby
+SWIGSEXP                        Defined when using S-expressions
+SWIGTCL                         Defined when using Tcl
+SWIGXML                         Defined when using XML
+
      + +

      +In addition, SWIG defines the following set of standard C/C++ macros: +

      + +
      +
      +__LINE__                        Current line number
+__FILE__                        Current file name
+__STDC__                        Defined to indicate ANSI C
+__cplusplus                     Defined when -c++ option used
+
      +
      + +

      +Interface files can look at these symbols as necessary to change the +way in which an interface is generated or to mix SWIG directives with +C code. These symbols are also defined within the C code generated by +SWIG (except for the symbol `SWIG' which is only defined +within the SWIG compiler). +

      + +

      7.4 Macro Expansion

      + + +

      +Traditional preprocessor macros can be used in SWIG interfaces. Be aware that the #define statement +is also used to try and detect constants. Therefore, if you have something like this in your file, +

      + +
      +
      +#ifndef _FOO_H 1
+#define _FOO_H 1
+...
+#endif
+
      +
      + +

      +you may get some extra constants such as _FOO_H showing up in the scripting interface. +

      + +

      +More complex macros can be defined in the standard way. For example: +

      + +
      +
      +#define EXTERN extern
+#ifdef __STDC__
+#define _ANSI(args)   (args)
+#else
+#define _ANSI(args) ()
+#endif
+
      +
      + +

      +The following operators can appear in macro definitions: +

      + +
        +
      • #x
        +Converts macro argument x to a string surrounded by double quotes ("x"). +
        • + +
      • x ## y
        +Concatenates x and y together to form xy. +
        • + +
      • `x`
        +If x is a string surrounded by double quotes, do nothing. Otherwise, turn into a string +like #x. This is a non-standard SWIG extension. +
        • +
      + +

      7.5 SWIG Macros

      + + +

      +SWIG provides an enhanced macro capability with the %define and %enddef directives. +For example: +

      + +
      +
      +%define ARRAYHELPER(type,name)
+%inline %{
+type *new_ ## name (int nitems) {
+   return (type *) malloc(sizeof(type)*nitems);
+}
+void delete_ ## name(type *t) {
+   free(t);
+}
+type name ## _get(type *t, int index) {
+   return t[index];
+}
+void name ## _set(type *t, int index, type val) {
+   t[index] = val;
+}
+%}
+%enddef
+
+ARRAYHELPER(int, IntArray)
+ARRAYHELPER(double, DoubleArray)
+
      +
      + +

      +The primary purpose of %define is to define large macros of code. Unlike normal C preprocessor +macros, it is not necessary to terminate each line with a continuation character (\)--the macro definition +extends to the first occurrence of %enddef. Furthermore, when such macros are expanded, +they are reparsed through the C preprocessor. Thus, SWIG macros can contain all other preprocessor +directives except for nested %define statements. +

      + +

      +The SWIG macro capability is a very quick and easy way to generate large amounts of code. In fact, +many of SWIG's advanced features and libraries are built using this mechanism (such as C++ template +support). +

      + +

      7.6 C99 and GNU Extensions

      + + +

      +SWIG-1.3.12 and newer releases support variadic preprocessor macros. For example: +

      + +
      +
      +#define DEBUGF(fmt,...)   fprintf(stderr,fmt,__VA_ARGS__)
+
      +
      + +

      +When used, any extra arguments to ... are placed into the +special variable __VA_ARGS__. This also works with special SWIG +macros defined using %define. +

      + +

      +SWIG allows a variable number of arguments to be empty. However, this often results +in an extra comma (,) and syntax error in the resulting expansion. For example: +

      + +
      +
      +DEBUGF("hello");   --> fprintf(stderr,"hello",);
+
      +
      + +

      +To get rid of the extra comma, use ## like this: +

      + +
      +
      +#define DEBUGF(fmt,...)   fprintf(stderr,fmt, ##__VA_ARGS__)
+
      +
      + +

      +SWIG also supports GNU-style variadic macros. For example: +

      + +
      +
      +#define DEBUGF(fmt, args...)  fprintf(stdout,fmt,args)
+
      +
      + +

      +Comment: It's not entirely clear how variadic macros might be useful to +interface building. However, they are used internally to implement a number of +SWIG directives and are provided to make SWIG more compatible with C99 code. +

      + +

      7.7 Preprocessing and %{ ... %} & " ... " delimiters

      + + +

      +The SWIG preprocessor does not process any text enclosed in a code block %{ ... %}. Therefore, +if you write code like this, +

      + +
      +
      +%{
+#ifdef NEED_BLAH
+int blah() {
+   ...
+}
+#endif
+%}
+
      +
      + +

      +the contents of the %{ ... %} block are copied without +modification to the output (including all preprocessor directives). +

      + +

      7.8 Preprocessing and { ... } delimiters

      + + +

      +SWIG always runs the preprocessor on text appearing inside { ... }. However, +sometimes it is desirable to make a preprocessor directive pass through to the output +file. For example: +

      + +
      +
      +%extend Foo {
+   void bar() {
+      #ifdef DEBUG
+       printf("I'm in bar\n");
+      #endif
+   }
+}
+
      +
      + +

      +By default, SWIG will interpret the #ifdef DEBUG statement. However, if you really wanted that code +to actually go into the wrapper file, prefix the preprocessor directives with % like this: +

      + +
      +
      +%extend Foo {
+   void bar() {
+      %#ifdef DEBUG
+       printf("I'm in bar\n");
+      %#endif
+   }
+}
+
      +
      + +

      +SWIG will strip the extra % and leave the preprocessor directive in the code. +

      + +

      7.9 Preprocessor and Typemaps

      + + +

      +Typemaps support a special attribute called noblock where the { ... } delimiters can be used, +but the delimiters are not actually generated into the code. +The effect is then similar to using "" or %{ %} delimiters but the code is run through the preprocessor. For example: +

      + +
      +
      +#define SWIG_macro(CAST) (CAST)$input
+%typemap(in) Int {$1= SWIG_macro(int);}
+
      +
      + +

      +might generate +

      + +
      +
      +  {
+    arg1=(int)jarg1;
+  }
+
      +
      + +

      +whereas +

      + +
      +
      +#define SWIG_macro(CAST) (CAST)$input
+%typemap(in,noblock=1) Int {$1= SWIG_macro(int);}
+
      +
      + +

      +might generate +

      + +
      +
      +  arg1=(int)jarg1;
+
      +
      + +

      +and +

      + +
      +
      +#define SWIG_macro(CAST) (CAST)$input
+%typemap(in) Int %{$1=SWIG_macro(int);%}
+
      +
      + +

      +would generate +

      + +
      +
      +  arg1=SWIG_macro(int);
+
      +
      + + +

      7.10 Viewing preprocessor output

      + + +

      +Like many compilers, SWIG supports a -E command line option to display the output from the preprocessor. +When the -E switch is used, SWIG will not generate any wrappers. +Instead the results after the preprocessor has run are displayed. +This might be useful as an aid to debugging and viewing the results of macro expansions. +

      + +

      7.11 The #error and #warning directives

      + + +

      +SWIG supports the commonly used #warning and #error preprocessor directives. +The #warning directive will cause SWIG to issue a warning then continue processing. +The #error directive will cause SWIG to exit with a fatal error. +Example usage: +

      + +
      +
      +#error "This is a fatal error message"
+#warning "This is a warning message"
+
      +
      + +

      +The #error behaviour can be made to work like #warning if the -cpperraswarn +commandline option is used. Alternatively, the #pragma directive can be used to the same effect, for example: +

      + +
      +
      +  /* Modified behaviour: #error does not cause SWIG to exit with error */
+  #pragma SWIG cpperraswarn=1
+  /* Normal behaviour: #error does cause SWIG to exit with error */
+  #pragma SWIG cpperraswarn=0
+
      +
      + + + diff --git a/Doc/Manual/Python.html b/Doc/Manual/Python.html new file mode 100644 index 0000000..8b359bd --- /dev/null +++ b/Doc/Manual/Python.html @@ -0,0 +1,5213 @@ + + + +SWIG and Python + + + + +

      31 SWIG and Python

      + +
      + +
      + + + + +

      +Caution: This chapter is under repair! +

      + +

      +This chapter describes SWIG's support of Python. SWIG is compatible +with most recent Python versions including Python 3.0 and Python 2.6, +as well as older versions dating back to Python 2.0. For the best results, +consider using Python 2.3 or newer. +

      + +

      +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 "SWIG +Basics" chapter. +

      + +

      31.1 Overview

      + + +

      +To build Python extension modules, SWIG uses a layered approach in which +parts of the extension module are defined in C and other parts are +defined in Python. The C layer contains low-level wrappers whereas Python code +is used to define high-level features. +

      + +

      +This layered approach recognizes the fact that certain aspects of +extension building are better accomplished in each language (instead +of trying to do everything in C or C++). Furthermore, by generating code in both +languages, you get a lot more flexibility since you can enhance the extension +module with support code in either language. +

      + +

      +In describing the Python interface, this chapter starts by covering the +basics of configuration, compiling, and installing Python modules. +Next, the Python interface to common C and C++ programming features is +described. Advanced customization features such as typemaps are then +described followed by a discussion of low-level implementation +details. +

      + +

      31.2 Preliminaries

      + + +

      31.2.1 Running SWIG

      + + +

      +Suppose that you defined a SWIG module such as the following: +

      + +
      +
      +/* File: example.i */
+%module example
+
+%{
+#define SWIG_FILE_WITH_INIT
+#include "example.h"
+%}
+
+int fact(int n);
+
      +
      + +

      +The #define SWIG_FILE_WITH_INIT line inserts a macro that specifies that the +resulting C file should be built as a python extension, inserting the module +init code. This .i file wraps the following simple C file: +

      + +
      +
      +/* File: example.c */
+
+#include "example.h"
+
+int fact(int n) {
+    if (n < 0){ /* This should probably return an error, but this is simpler */
+        return 0;
+    }
+    if (n == 0) {
+        return 1;
+    }
+    else {
+        /* testing for overflow would be a good idea here */
+        return n * fact(n-1);
+    }
+}
+
+
      +
      + +

      +With the header file: +

      + +
      +
      +/* File: example.h */
+
+int fact(int n);
+
      +
      + +

      +To build a Python module, run SWIG using the -python option: +

      + +
      +$ swig -python example.i
+
      + +

      +If building a C++ extension, add the -c++ option: +

      + +
      +$ swig -c++ -python example.i
+
      + +

      +This creates two different files; a C/C++ source file example_wrap.c or +example_wrap.cxx and a Python source file example.py. The generated C +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. The Python source file +contains high-level support code. This is the file that you will import to use the module. +

      + +

      +The name of the wrapper file is derived from the name of the input file. For example, if the +input file is example.i, the name of the wrapper file is example_wrap.c. +To change this, you can use the -o option. The name of the Python file is derived +from the module name specified with %module. If the module name is example, +then a file example.py is created. +

      + +

      +The following sections have further practical examples and details on +how you might go about compiling and using the generated files. +

      + +

      31.2.2 Using distutils

      + + +

      +The preferred approach to building an extension module for python is to compile it with +distutils, which comes with all recent versions of python +(Distutils Docs). +

      + +

      +Distutils takes care of making sure that your extension is built with all the correct +flags, headers, etc. for the version of Python it is run with. Distutils will compile your +extension into a shared object file or DLL (.so on Linux, .pyd on +Windows, etc). In addition, distutils can handle installing your package into +site-packages, if that is desired. A configuration file (conventionally called: setup.py) +describes the extension (and related python modules). The distutils will +then generate all the right compiler directives to build it for you. +

      + +

      +Here is a sample setup.py file for the above example: +

      + +
      +
      +#!/usr/bin/env python
+
+"""
+setup.py file for SWIG example
+"""
+
+from distutils.core import setup, Extension
+
+
+example_module = Extension('_example',
+                           sources=['example_wrap.c', 'example.c'],
+                           )
+
+setup (name = 'example',
+       version = '0.1',
+       author      = "SWIG Docs",
+       description = """Simple swig example from docs""",
+       ext_modules = [example_module],
+       py_modules = ["example"],
+       )
+
      +
      + +

      +In this example, the line: example_module = Extension(....) creates an Extension +module object, defining the name as _example, and using the source code files: +example_wrap.c, generated by swig, and example.c, your original c +source. The swig (and other python extension modules) tradition is for the compiled +extension to have the name of the python portion, prefixed by an underscore. If the name +of your python module is "example.py", then the name of the corresponding object file +will be"_example.so" +

      + +

      +The setup call then sets up distutils to build your package, defining +some meta data, and passing in your extension module object. +Once this is saved as setup.py, you can build your extension with these commands: +

      + +
      +$ swig -python example.i
+$ python setup.py build_ext --inplace
+
      + +

      +And a .so, or .pyd or... will be created for you. It will build a version that matches the +python that you run the command with. Taking apart the command line: +

      + +
        +
      • python -- the version of python you want to build for +
      • setup.py -- the name of your setup script (it can be called anything, but + setup.py is the tradition) +
      • build_ext -- telling distutils to build extensions +
      • --inplace -- this tells distutils to put the extension lib in the current dir. + Otherwise, it will put it inside a build hierarchy, and you'd have to move it to use it. +
      + +

      +The distutils have many other features, consult the python distutils docs for details. +

      + +

      +This same approach works on all platforms if the appropriate compiler is installed. (it +can even build extensions to the standard Windows Python using MingGW) +

      + +

      31.2.3 Hand compiling a dynamic module

      + + +

      +While the preferred approach to building an extension module is to use the distutils, some +people like to integrate building extensions with a larger build system, and thus may wish +to compile their modules without the distutils. To do this, you need to compile your +program using commands like this (shown for Linux): +

      + +
      +$ swig -python example.i
+$ gcc -O2 -fPIC -c example.c
+$ gcc -O2 -fPIC -c example_wrap.c -I/usr/local/include/python2.5
+$ gcc -shared example.o example_wrap.o -o _example.so
+
      + +

      +The exact commands for doing this vary from platform to platform. +However, SWIG tries to guess the right options when it is installed. Therefore, +you may want to start with one of the examples in the SWIG/Examples/python +directory. If that doesn't work, you will need to read the man-pages for +your compiler and linker to get the right set of options. You might also +check the SWIG Wiki for +additional information. +

      + +

      +When linking the module, the name of the output file has to match the name +of the module prefixed by an underscore. If the name of your module is "example", then the +name of the corresponding object file should be +"_example.so" or "_examplemodule.so". +The name of the module is specified using the %module directive or the + -module command line option. +

      + +

      +Compatibility Note: In SWIG-1.3.13 and earlier releases, module +names did not include the leading underscore. This is because modules +were normally created as C-only extensions without the extra Python +support file (instead, creating Python code was supported as an optional +feature). This has been changed in SWIG-1.3.14 and is consistent with +other Python extension modules. For example, the socket +module actually consists of two files; socket.py and +_socket.so. Many other built-in Python modules follow a similar convention. +

      + + +

      31.2.4 Static linking

      + + +

      +An alternative approach to dynamic linking is to rebuild the Python +interpreter with your extension module added to it. In the past, +this approach was sometimes necessary due to limitations in dynamic loading +support on certain machines. However, the situation has improved greatly +over the last few years and you should not consider this approach +unless there is really no other option. +

      + +

      +The usual procedure for adding a new module to Python involves finding +the Python source, adding an entry to the Modules/Setup file, +and rebuilding the interpreter using the Python Makefile. However, +newer Python versions have changed the build process. You may need to edit +the 'setup.py' file in the Python distribution instead. +

      + +

      +In earlier versions of SWIG, the embed.i library file could be used to +rebuild the interpreter. For example: +

      + +
      +%module example
+
+%inline %{
+extern int fact(int);
+extern int mod(int, int);
+extern double My_variable;
+%}
+
+%include "embed.i"       // Include code for a static version of Python
+
+
      + +

      +The embed.i library file includes supporting code that +contains everything needed to rebuild Python. To rebuild the interpreter, +you simply do something like this: +

      + +
      +$ swig -python example.i
+$ gcc example.c example_wrap.c \
+        -Xlinker -export-dynamic \
+        -DHAVE_CONFIG_H -I/usr/local/include/python2.1 \
+	-I/usr/local/lib/python2.1/config \
+	-L/usr/local/lib/python2.1/config -lpython2.1 -lm -ldl \
+	-o mypython
+
+
      +

      +You will need to supply the same libraries that were used to build Python the first +time. This may include system libraries such as -lsocket, -lnsl, +and -lpthread. Assuming this actually works, the new version of Python +should be identical to the default version except that your extension module will be +a built-in part of the interpreter. +

      + +

      +Comment: In practice, you should probably try to avoid static +linking if possible. Some programmers may be inclined +to use static linking in the interest of getting better performance. +However, the performance gained by static linking tends to be rather +minimal in most situations (and quite frankly not worth the extra +hassle in the opinion of this author). +

      + +

      +Compatibility note: The embed.i library file is +deprecated and has not been maintained for several years. Even though it +appears to "work" with Python 2.1, no future support is guaranteed. +If using static linking, you might want to rely on a different approach +(perhaps using distutils). +

      + +

      31.2.5 Using your module

      + + +

      +To use your module, simply use the Python import statement. If +all goes well, you will be able to this: +

      + +
      +$ python
+>>> import example
+>>> example.fact(4)
+24
+>>>
+
      + +

      +A common error received by first-time users is the following: +

      + +
      +
      +>>> import example
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+  File "example.py", line 2, in ?
+    import _example
+ImportError: No module named _example
+
      +
      + +

      +If you get this message, it means that you either forgot to compile the wrapper +code into an extension module or you didn't give the extension module the right +name. Make sure that you compiled the wrappers into a module called _example.so. And +don't forget the leading underscore (_). +

      + +

      +Another possible error is the following: +

      + +
      +
      +>>> import example
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+ImportError: dynamic module does not define init function (init_example)
+>>>                                                               
+
      +
      + +

      +This error is almost always caused when a bad name is given to the shared object file. +For example, if you created a file example.so instead of _example.so you would +get this error. Alternatively, this error could arise if the name of the module is +inconsistent with the module name supplied with the %module directive. +Double-check the interface to make sure the module name and the shared object +filename match. Another possible cause of this error is forgetting to link the SWIG-generated +wrapper code with the rest of your application when creating the extension module. +

      + +

      +Another common error is something similar to the following: +

      + +
      +
      +Traceback (most recent call last):
+  File "example.py", line 3, in ?
+    import example
+ImportError: ./_example.so: undefined symbol: fact
+
      +
      + +

      +This error usually indicates that you forgot to include some object +files or libraries in the linking of the shared library file. Make +sure you compile both the SWIG wrapper file and your original program +into a shared library file. Make sure you pass all of the required libraries +to the linker. +

      + +

      +Sometimes unresolved symbols occur because a wrapper has been created +for a function that doesn't actually exist in a library. This usually +occurs when a header file includes a declaration for a function that +was never actually implemented or it was removed from a library +without updating the header file. To fix this, you can either edit +the SWIG input file to remove the offending declaration or you can use +the %ignore directive to ignore the declaration. +

      + +

      +Finally, suppose that your extension module is linked with another library like this: +

      + +
      +
      +$ gcc -shared example.o example_wrap.o -L/home/beazley/projects/lib -lfoo \
+      -o _example.so
+
      +
      + +

      +If the foo library is compiled as a shared library, you might encounter the following +problem when you try to use your module: +

      + +
      +
      +>>> import example
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+ImportError: libfoo.so: cannot open shared object file: No such file or directory
+>>>                 
+
      +
      + +

      +This error is generated because the dynamic linker can't locate the +libfoo.so library. When shared libraries are loaded, the +system normally only checks a few standard locations such as +/usr/lib and /usr/local/lib. To fix this problem, +there are several things you can do. First, you can recompile your extension +module with extra path information. For example, on Linux you can do this: +

      + +
      +
      +$ gcc -shared example.o example_wrap.o -L/home/beazley/projects/lib -lfoo \
+      -Xlinker -rpath /home/beazley/projects/lib  \
+      -o _example.so
+
      +
      + +

      +Alternatively, you can set the LD_LIBRARY_PATH environment variable to +include the directory with your shared libraries. +If setting LD_LIBRARY_PATH, be aware that setting this variable can introduce +a noticeable performance impact on all other applications that you run. +To set it only for Python, you might want to do this instead: +

      + +
      +
      +$ env LD_LIBRARY_PATH=/home/beazley/projects/lib python
+
      +
      + +

      +Finally, you can use a command such as ldconfig (Linux) or +crle (Solaris) to add additional search paths to the default +system configuration (this requires root access and you will need to +read the man pages). +

      + +

      31.2.6 Compilation of C++ extensions

      + + +

      +Compilation of C++ extensions has traditionally been a tricky problem. +Since the Python interpreter is written in C, you need to take steps to +make sure C++ is properly initialized and that modules are compiled +correctly. This should be a non-issue if you're using distutils, as +it takes care of all that for you. The following is included for +historical reasons, and in case you need to compile on your own. +

      + +

      +On most machines, C++ extension modules should be linked using the C++ +compiler. For example: +

      + +
      +$ swig -c++ -python example.i
+$ g++ -O2 -fPIC -c example.cxx
+$ g++ -O2 -fPIC -c example_wrap.cxx -I/usr/local/include/python2.5
+$ g++ -shared example.o example_wrap.o -o _example.so
+
      + +

      +The -fPIC option tells GCC to generate position-independent code (PIC) +which is required for most architectures (it's not vital on x86, but +still a good idea as it allows code pages from the library to be shared between +processes). Other compilers may need a different option specified instead of +-fPIC. +

      + +

      +In addition to this, you may need to include additional library +files to make it work. For example, if you are using the Sun C++ compiler on +Solaris, you often need to add an extra library -lCrun like this: +

      + +
      +$ swig -c++ -python example.i
+$ CC -c example.cxx
+$ CC -c example_wrap.cxx -I/usr/local/include/python2.5
+$ CC -G example.o example_wrap.o -L/opt/SUNWspro/lib -o _example.so -lCrun
+
      + +

      +Of course, the extra libraries to use are completely non-portable---you will +probably need to do some experimentation. +

      + +

      +Sometimes people have suggested that it is necessary to relink the +Python interpreter using the C++ compiler to make C++ extension modules work. +In the experience of this author, this has never actually appeared to be +necessary. Relinking the interpreter with C++ really only includes the +special run-time libraries described above---as long as you link your extension +modules with these libraries, it should not be necessary to rebuild Python. +

      + +

      +If you aren't entirely sure about the linking of a C++ extension, you +might look at an existing C++ program. On many Unix machines, the +ldd command will list library dependencies. This should give +you some clues about what you might have to include when you link your +extension module. For example: +

      + +
      +
      +$ ldd swig
+        libstdc++-libc6.1-1.so.2 => /usr/lib/libstdc++-libc6.1-1.so.2 (0x40019000)
+        libm.so.6 => /lib/libm.so.6 (0x4005b000)
+        libc.so.6 => /lib/libc.so.6 (0x40077000)
+        /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
+
      +
      + +

      +As a final complication, a major weakness of C++ is that it does not +define any sort of standard for binary linking of libraries. This +means that C++ code compiled by different compilers will not link +together properly as libraries nor is the memory layout of classes and +data structures implemented in any kind of portable manner. In a +monolithic C++ program, this problem may be unnoticed. However, in Python, it +is possible for different extension modules to be compiled with +different C++ compilers. As long as these modules are self-contained, +this probably won't matter. However, if these modules start sharing data, +you will need to take steps to avoid segmentation faults and other +erratic program behavior. If working with lots of software components, you +might want to investigate using a more formal standard such as COM. +

      + +

      31.2.7 Compiling for 64-bit platforms

      + + +

      +On platforms that support 64-bit applications (Solaris, Irix, etc.), +special care is required when building extension modules. On these +machines, 64-bit applications are compiled and linked using a different +set of compiler/linker options. In addition, it is not generally possible to mix +32-bit and 64-bit code together in the same application. +

      + +

      +To utilize 64-bits, the Python executable will need to be recompiled +as a 64-bit application. In addition, all libraries, wrapper code, +and every other part of your application will need to be compiled for +64-bits. If you plan to use other third-party extension modules, they +will also have to be recompiled as 64-bit extensions. +

      + +

      +If you are wrapping commercial software for which you have no source +code, you will be forced to use the same linking standard as used by +that software. This may prevent the use of 64-bit extensions. It may +also introduce problems on platforms that support more than one +linking standard (e.g., -o32 and -n32 on Irix). +

      + +

      On the Linux x86_64 platform (Opteron or EM64T), besides of the +required compiler option -fPIC discussed above, you will need to be +careful about the libraries you link with or the library path you +use. In general, a Linux distribution will have two set of libraries, +one for native x86_64 programs (under /usr/lib64), and another for 32 +bits compatibility (under /usr/lib). Also, the compiler options -m32 +and -m64 allow you to choose the desired binary format for your python +extension. +

      + +

      31.2.8 Building Python Extensions under Windows

      + + +

      +Building a SWIG extension to Python under Windows is roughly similar to +the process used with Unix. Using the distutils, it is essentially +identical. If you have the same version of the MS compiler that Python +was built with (the python2.4 and python2.5 distributed by python.org +are built with Visual Studio 2003), the standard python setup.py +build should just work. +

      + +

      +As of python2.5, the distutils support building extensions with MingGW out +of the box. Following the instruction here: +Building +Python extensions for Windows with only free tools should get you started. +

      + +

      +If you need to build it on your own, the following notes are provided: +

      + +

      +You will need to create a DLL that can be loaded into the interpreter. +This section briefly describes the use of SWIG with Microsoft Visual +C++. As a starting point, many of SWIG's examples include project +files. You might want to take a quick look at these in addition to +reading this section. +

      + +

      +In Developer Studio, SWIG should be invoked as a custom build option. +This is usually done as follows: +

      + +
        +
      • Open up a new workspace and use the AppWizard to select a DLL +project. + +
      • Add both the SWIG interface file (the .i file), any supporting C +files, and the name of the wrapper file that will be created by SWIG +(ie. example_wrap.c). Note : If using C++, choose a +different suffix for the wrapper file such as +example_wrap.cxx. Don't worry if the wrapper file doesn't +exist yet--Developer Studio keeps a reference to it. + +
      • Select the SWIG interface file and go to the settings menu. Under +settings, select the "Custom Build" option. + +
      • Enter "SWIG" in the description field. + +
      • Enter "swig -python -o $(ProjDir)\$(InputName)_wrap.c $(InputPath)" in the "Build command(s) field" + +
      • Enter "$(ProjDir)\$(InputName)_wrap.c" in the "Output files(s) field". + +
      • Next, select the settings for the entire project and go to +"C++:Preprocessor". Add the include directories for your Python +installation under "Additional include directories". + +
      • Define the symbol __WIN32__ under preprocessor options. + +
      • Finally, select the settings for the entire project and go to +"Link Options". Add the Python library file to your link libraries. +For example "python21.lib". Also, set the name of the output file to +match the name of your Python module, ie. _example.pyd - Note that _example.dll also worked with Python-2.4 and earlier. + +
      • Build your project. +
      + +

      +If all went well, SWIG will be automatically invoked whenever +you build your project. Any changes made to the interface file will +result in SWIG being automatically executed to produce a new version of +the wrapper file. +

      + +

      +To run your new Python extension, simply run Python +and use the import command as normal. For example : +

      + +
      +$ python
+>>> import example
+>>> print example.fact(4)
+24
+>>>
+
      + +

      +If you get an ImportError exception when importing the module, you may +have forgotten to include additional library files when you built your module. +If you get an access violation or some kind of general protection fault +immediately upon import, you have a more serious problem. This +is often caused by linking your extension module against the wrong +set of Win32 debug or thread libraries. You will have to fiddle around with +the build options of project to try and track this down. +

      + +

      +Some users have reported success in building extension modules using Cygwin +and other compilers. However, the problem of building usable DLLs with these +compilers tends to be rather problematic. For the latest information, +you may want to consult the +SWIG Wiki. +

      + + +

      31.3 A tour of basic C/C++ wrapping

      + + +

      +By default, SWIG tries to build a very natural Python interface +to your C/C++ code. Functions are wrapped as functions, classes are wrapped as classes, and so forth. +This section briefly covers the essential aspects of this wrapping. +

      + +

      31.3.1 Modules

      + + +

      +The SWIG %module directive specifies the name of the Python +module. If you specify `%module example', then everything is +wrapped into a Python 'example' module. Underneath the covers, +this module consists of a Python source file example.py and a low-level +extension module _example.so. When choosing a +module name, make sure you don't use the same name as a built-in +Python command or standard module name. +

      + +

      31.3.2 Functions

      + + +

      +Global functions are wrapped as new Python built-in functions. For example, +

      + +
      +%module example
+int fact(int n);
+
      + +

      +creates a built-in function example.fact(n) that works exactly +like you think it does: +

      + +
      +>>> import example
+>>> print example.fact(4)
+24
+>>>
+
      + +

      31.3.3 Global variables

      + + +

      +C/C++ global variables are fully supported by SWIG. However, the underlying +mechanism is somewhat different than you might expect due to the way that +Python assignment works. When you type the following in Python +

      + +
      +a = 3.4
+
      + +

      +"a" becomes a name for an object containing the value 3.4. If you later type +

      + +
      +b = a
+
      + +

      +then "a" and "b" are both names for the object containing the value +3.4. Thus, there is only one object containing 3.4 and "a" +and "b" are both names that refer to it. This is quite +different than C where a variable name refers to a memory location in which +a value is stored (and assignment copies data into that location). +Because of this, there is no direct way to map variable +assignment in C to variable assignment in Python. +

      + +

      +To provide access to C global variables, SWIG creates a special +object called `cvar' that is added to each SWIG generated +module. Global variables are then accessed as attributes of this object. +For example, consider this interface +

      + +
      +// SWIG interface file with global variables
+%module example
+...
+%inline %{
+extern int My_variable;
+extern double density;
+%}
+...
+
      +

      +Now look at the Python interface: +

      + +
      +>>> import example
+>>> # Print out value of a C global variable
+>>> print example.cvar.My_variable
+4
+>>> # Set the value of a C global variable
+>>> example.cvar.density = 0.8442
+>>> # Use in a math operation
+>>> example.cvar.density = example.cvar.density*1.10
+
      + +

      +If you make an error in variable assignment, you will receive an +error message. For example: +

      + +
      +>>> example.cvar.density = "Hello"
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+TypeError: C variable 'density (double )'
+>>> 
+
      + +

      +If a variable is declared as const, it is wrapped as a +read-only variable. Attempts to modify its value will result in an +error. +

      + +

      +To make ordinary variables read-only, you can use the %immutable directive. For example: +

      + +
      +
      +%{
+extern char *path;
+%}
+%immutable;
+extern char *path;
+%mutable;
+
      +
      + +

      +The %immutable directive stays in effect until it is explicitly disabled or cleared using +%mutable. +See the Creating read-only variables section for further details. +

      + +

      +If you just want to make a specific variable immutable, supply a declaration name. For example: +

      + +
      +
      +%{
+extern char *path;
+%}
+%immutable path;
+...
+extern char *path;      // Read-only (due to %immutable)
+
      +
      + +

      +If you would like to access variables using a name other than "cvar", it can be +changed using the -globals option : +

      + +
      +$ swig -python -globals myvar example.i
+
      + +

      +Some care is in order when importing multiple SWIG modules. +If you use the "from <file> import *" style of +importing, you will get a name clash on the variable `cvar' +and you will only be able to access global variables from the last +module loaded. To prevent this, you might consider renaming +cvar or making it private to the module by giving it a name +that starts with a leading underscore. SWIG does not create cvar +if there are no global variables in a module. +

      + +

      31.3.4 Constants and enums

      + + +

      +C/C++ constants are installed as Python objects containing the +appropriate value. To create a constant, use #define, enum, or the +%constant directive. For example: +

      + +
      +
      +#define PI 3.14159
+#define VERSION "1.0"
+
+enum Beverage { ALE, LAGER, STOUT, PILSNER };
+
+%constant int FOO = 42;
+%constant const char *path = "/usr/local";
+
      +
      + +

      +For enums, make sure that the definition of the enumeration actually appears in a header +file or in the wrapper file somehow---if you just stick an enum in a SWIG interface without +also telling the C compiler about it, the wrapper code won't compile. +

      + +

      +Note: declarations declared as const are wrapped as read-only variables and +will be accessed using the cvar object described in the previous section. They +are not wrapped as constants. For further discussion about this, see the SWIG Basics chapter. +

      + +

      +Constants are not guaranteed to remain constant in Python---the name +of the constant could be accidentally reassigned to refer to some +other object. Unfortunately, there is no easy way for SWIG to +generate code that prevents this. You will just have to be careful. +

      + +

      31.3.5 Pointers

      + + +

      +C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no +problem working with incomplete type information. Here is a rather +simple interface: +

      + +
      +
      +%module example
+
+FILE *fopen(const char *filename, const char *mode);
+int fputs(const char *, FILE *);
+int fclose(FILE *);
+
      +
      + +

      +When wrapped, you will be able to use the functions in a natural way from Python. For example: +

      + +
      +
      +>>> import example
+>>> f = example.fopen("junk","w")
+>>> example.fputs("Hello World\n", f)
+>>> example.fclose(f)
+
      +
      + +

      +If this makes you uneasy, rest assured that there is no +deep magic involved. Underneath the covers, pointers to C/C++ objects are +simply represented as opaque values using an especial python container object: +

      + +
      +>>> print f
+<Swig Object at _08a71808_p_FILE>
+
      + +

      +This pointer value can be freely passed around to different C functions that +expect to receive an object of type FILE *. The only thing you can't do is +dereference the pointer from Python. Of course, that isn't much of a concern in this example. +

      + +

      +In older versions of Swig (1.3.22 or older), pointers were represented +using a plain string object. If you have an old package that still +requires that representation, or you just feel nostalgic, you can +always retrieve it by casting the pointer object to a string: +

      + +
      +>>> print str(f)
+_c0671108_p_FILE
+
      + +

      +Also, if you need to pass the raw pointer value to some external +python library, you can do it by casting the pointer object to an +integer: +

      + +
      +>>> print int(f)
+135833352
+
      + +

      +However, the inverse operation is not possible, i.e., you can't build +a Swig pointer object from a raw integer value. +

      + +

      +Note also that the '0' or NULL pointer is always represented by +None, no matter what type swig is addressing. In the +previous example, you can call: +

      + +
      +
      +>>> example.fclose(None)
+
      +
      + +

      +and that will be equivalent to the following, but not really useful, C +code: +

      + +
      +
      +FILE *f = NULL;
+fclose(f);
+
      +
      + +

      +As much as you might be inclined to modify a pointer value directly +from Python, don't. The hexadecimal encoding is not necessarily the +same as the logical memory address of the underlying object. Instead +it is the raw byte encoding of the pointer value. The encoding will +vary depending on the native byte-ordering of the platform (i.e., +big-endian vs. little-endian). Similarly, don't try to manually cast +a pointer to a new type by simply replacing the type-string. This may +not work like you expect, it is particularly dangerous when casting +C++ objects. If you need to cast a pointer or change its value, +consider writing some helper functions instead. For example: +

      + +
      +
      +%inline %{
+/* C-style cast */
+Bar *FooToBar(Foo *f) {
+   return (Bar *) f;
+}
+
+/* C++-style cast */
+Foo *BarToFoo(Bar *b) {
+   return dynamic_cast<Foo*>(b);
+}
+
+Foo *IncrFoo(Foo *f, int i) {
+    return f+i;
+}
+%}
+
      +
      + +

      +Also, if working with C++, you should always try +to use the new C++ style casts. For example, in the above code, the +C-style cast may return a bogus result whereas as the C++-style cast will return +None if the conversion can't be performed. +

      + +

      31.3.6 Structures

      + + +

      +If you wrap a C structure, it is wrapped by a Python class. This provides +a very natural interface. For example, +

      + +
      +struct Vector {
+	double x,y,z;
+};
+
+
      + +

      +is used as follows: +

      + +
      +>>> v = example.Vector()
+>>> v.x = 3.5
+>>> v.y = 7.2
+>>> print v.x, v.y, v.z
+7.8 -4.5 0.0
+>>> 
+
      + +

      +Similar access is provided for unions and the data members of C++ classes. +

      + +

      +If you print out the value of v in the above example, you will see +something like this: +

      + +
      +
      +>>> print v
+<C Vector instance at _18e31408_p_Vector>
+
      +
      + +

      +This object is actually a Python instance that has been wrapped around a pointer to the low-level +C structure. This instance doesn't actually do anything--it just serves as a proxy. +The pointer to the C object can be found in the the .this +attribute. For example: +

      + +
      +
      +>>> print v.this
+_18e31408_p_Vector
+>>>
+
      +
      + +

      +Further details about the Python proxy class are covered a little later. +

      + +

      +const members of a structure are read-only. Data members +can also be forced to be read-only using the %immutable directive. For example: +

      + +
      +
      +struct Foo {
+   ...
+   %immutable;
+   int x;        /* Read-only members */
+   char *name;
+   %mutable;
+   ...
+};
+
      +
      + +

      +When char * members of a structure are wrapped, the contents are assumed to be +dynamically allocated using malloc or new (depending on whether or not +SWIG is run with the -c++ option). When the structure member is set, the old contents will be +released and a new value created. If this is not the behavior you want, you will have to use +a typemap (described later). +

      + +

      +If a structure contains arrays, access to those arrays is managed through pointers. For +example, consider this: +

      + +
      +
      +struct Bar {
+    int  x[16];
+};
+
      +
      + +

      +If accessed in Python, you will see behavior like this: +

      + +
      +
      +>>> b = example.Bar()
+>>> print b.x
+_801861a4_p_int
+>>> 
+
      +
      + +

      +This pointer can be passed around to functions that expect to receive +an int * (just like C). You can also set the value of an array member using +another pointer. For example: +

      + +
      +
      +>>> c = example.Bar()
+>>> c.x = b.x             # Copy contents of b.x to c.x
+
      +
      + +

      +For array assignment, SWIG copies the entire contents of the array starting with the data pointed +to by b.x. In this example, 16 integers would be copied. Like C, SWIG makes +no assumptions about bounds checking---if you pass a bad pointer, you may get a segmentation +fault or access violation. +

      + +

      +When a member of a structure is itself a structure, it is handled as a +pointer. For example, suppose you have two structures like this: +

      + +
      +
      +struct Foo {
+   int a;
+};
+
+struct Bar {
+   Foo f;
+};
+
      +
      + +

      +Now, suppose that you access the f attribute of Bar like this: +

      + +
      +
      +>>> b = Bar()
+>>> x = b.f
+
      +
      + +

      +In this case, x is a pointer that points to the Foo that is inside b. +This is the same value as generated by this C code: +

      + +
      +
      +Bar b;
+Foo *x = &b->f;       /* Points inside b */
+
      +
      + +

      +Because the pointer points inside the structure, you can modify the contents and +everything works just like you would expect. For example: +

      + +
      +
      +>>> b = Bar()
+>>> b.f.a = 3               # Modify attribute of structure member
+>>> x = b.f                   
+>>> x.a = 3                 # Modifies the same structure
+
      +
      + +

      31.3.7 C++ classes

      + + +

      +C++ classes are wrapped by Python classes as well. For example, if you have this class, +

      + +
      +class List {
+public:
+  List();
+  ~List();
+  int  search(char *item);
+  void insert(char *item);
+  void remove(char *item);
+  char *get(int n);
+  int  length;
+};
+
      + +

      +you can use it in Python like this: +

      + +
      +>>> l = example.List()
+>>> l.insert("Ale")
+>>> l.insert("Stout")
+>>> l.insert("Lager")
+>>> l.get(1)
+'Stout'
+>>> print l.length
+3
+>>>
+
      + +

      +Class data members are accessed in the same manner as C structures. +

      + +

      +Static class members present a special problem for Python. Prior to Python-2.2, +Python classes had no support for static methods and no version of Python +supports static member variables in a manner that SWIG can utilize. Therefore, +SWIG generates wrappers that try to work around some of these issues. To illustrate, +suppose you have a class like this: +

      + +
      +
      +class Spam {
+public:
+   static void foo();
+   static int bar;
+
+};
+
      +
      + +

      +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
+
      +
      + +

      +The first two methods of access are supported in all versions of Python. The +last technique is only available in Python-2.2 and later versions. +

      + +

      +Static member variables are currently accessed as global variables. This means, +they are accessed through cvar like this: +

      + +
      +
      +>>> print example.cvar.Spam_bar
+7
+
      +
      + +

      31.3.8 C++ inheritance

      + + +

      +SWIG is fully aware of issues related to C++ inheritance. Therefore, if you have +classes like this +

      + +
      +
      +class Foo {
+...
+};
+
+class Bar : public Foo {
+...
+};
+
      +
      + +

      +those classes are wrapped into a hierarchy of Python classes that reflect the same inheritance +structure. All of the usual Python utility functions work normally: +

      + +
      +
      +>>> b = Bar()
+>>> instance(b,Foo)
+1
+>>> issubclass(Bar,Foo)
+1
+>>> issubclass(Foo,Bar)
+0
+
      +
      + +

      +Furthermore, if you have functions like this +

      + +
      +
      +void spam(Foo *f);
+
      +
      + +

      +then the function spam() accepts Foo * or a pointer to any class derived from Foo. +

      + +

      +It is safe to use multiple inheritance with SWIG. +

      + +

      31.3.9 Pointers, references, values, and arrays

      + + +

      +In C++, there are many different ways a function might receive +and manipulate objects. For example: +

      + +
      +
      +void spam1(Foo *x);      // Pass by pointer
+void spam2(Foo &x);      // Pass by reference
+void spam3(const Foo &x);// Pass by const reference
+void spam4(Foo x);       // Pass by value
+void spam5(Foo x[]);     // Array of objects
+
      +
      + +

      +In Python, there is no detailed distinction like this--specifically, +there are only "objects". There are no pointers, references, arrays, +and so forth. Because of this, SWIG unifies all of these types +together in the wrapper code. For instance, if you actually had the +above functions, it is perfectly legal to do this: +

      + +
      +
      +>>> f = Foo()           # Create a Foo
+>>> spam1(f)            # Ok. Pointer
+>>> spam2(f)            # Ok. Reference
+>>> spam3(f)            # Ok. Const reference
+>>> spam4(f)            # Ok. Value.
+>>> spam5(f)            # Ok. Array (1 element)
+
      +
      + +

      +Similar behavior occurs for return values. For example, if you had +functions like this, +

      + +
      +
      +Foo *spam6();
+Foo &spam7();
+Foo  spam8();
+const Foo &spam9();
+
      +
      + +

      +then all three functions will return a pointer to some Foo object. +Since the third function (spam8) returns a value, newly allocated memory is used +to hold the result and a pointer is returned (Python will release this memory +when the return value is garbage collected). The fourth case (spam9) +which returns a const reference, in most of the cases will be +treated as a returning value, and it will follow the same +allocation/deallocation process. +

      + +

      31.3.10 C++ overloaded functions

      + + +

      +C++ overloaded functions, methods, and constructors are mostly supported by SWIG. For example, +if you have two functions like this: +

      + +
      +
      +void foo(int);
+void foo(char *c);
+
      +
      + +

      +You can use them in Python in a straightforward manner: +

      + +
      +
      +>>> foo(3)           # foo(int)
+>>> foo("Hello")     # foo(char *c)
+
      +
      + +

      +Similarly, if you have a class like this, +

      + +
      +
      +class Foo {
+public:
+    Foo();
+    Foo(const Foo &);
+    ...
+};
+
      +
      + +

      +you can write Python code like this: +

      + +
      +
      +>>> f = Foo()          # Create a Foo
+>>> g = Foo(f)         # Copy f
+
      +
      + +

      +Overloading support is not quite as flexible as in C++. Sometimes there are methods that SWIG +can't disambiguate. For example: +

      + +
      +
      +void spam(int);
+void spam(short);
+
      +
      + +

      +or +

      + +
      +
      +void foo(Bar *b);
+void foo(Bar &b);
+
      +
      + +

      +If declarations such as these appear, you will get a warning message like this: +

      + +
      +
      +example.i:12: Warning(509): Overloaded spam(short) is shadowed by spam(int)
+at example.i:11.
+
      +
      + +

      +To fix this, you either need to ignore or rename one of the methods. For example: +

      + +
      +
      +%rename(spam_short) spam(short);
+...
+void spam(int);    
+void spam(short);   // Accessed as spam_short
+
      +
      + +

      +or +

      + +
      +
      +%ignore spam(short);
+...
+void spam(int);    
+void spam(short);   // Ignored
+
      +
      + +

      +SWIG resolves overloaded functions and methods using a disambiguation scheme that ranks and sorts +declarations according to a set of type-precedence rules. The order in which declarations appear +in the input does not matter except in situations where ambiguity arises--in this case, the +first declaration takes precedence. +

      + +

      +Please refer to the "SWIG and C++" chapter for more information about overloading. +

      + +

      31.3.11 C++ operators

      + + +

      +Certain C++ overloaded operators can be handled automatically by SWIG. For example, +consider a class like this: +

      + +
      +
      +class Complex {
+private:
+  double rpart, ipart;
+public:
+  Complex(double r = 0, double i = 0) : rpart(r), ipart(i) { }
+  Complex(const Complex &c) : rpart(c.rpart), ipart(c.ipart) { }
+  Complex &operator=(const Complex &c);
+
+  Complex operator+=(const Complex &c) const;
+  Complex operator+(const Complex &c) const;
+  Complex operator-(const Complex &c) const;
+  Complex operator*(const Complex &c) const;
+  Complex operator-() const;
+  
+  double re() const { return rpart; }
+  double im() const { return ipart; }
+};
+
      +
      + +

      +When wrapped, it works like you expect: +

      + +
      +
      +>>> c = Complex(3,4)
+>>> d = Complex(7,8)
+>>> e = c + d
+>>> e.re()
+10.0
+>>> e.im()
+12.0
+>>> c += d
+>>> c.re()
+10.0
+>>> c.im()
+12.0
+
+
      +
      + +

      +One restriction with operator overloading support is that SWIG is not +able to fully handle operators that aren't defined as part of the class. +For example, if you had code like this +

      + +
      +
      +class Complex {
+...
+friend Complex operator+(double, const Complex &c);
+...
+};
+
      +
      + +

      +then SWIG ignores it and issues a warning. You can still wrap the operator, +but you may have to encapsulate it in a special function. For example: +

      + +
      +
      +%rename(Complex_add_dc) operator+(double, const Complex &);
+
      +
      + +

      +There are ways to make this operator appear as part of the class using the %extend directive. +Keep reading. +

      + +

      +Also, be aware that certain operators don't map cleanly to Python. For instance, +overloaded assignment operators don't map to Python semantics and will be ignored. +

      + +

      31.3.12 C++ namespaces

      + + +

      +SWIG is aware of C++ namespaces, but namespace names do not appear in +the module nor do namespaces result in a module that is broken up into +submodules or packages. For example, if you have a file like this, +

      + +
      +
      +%module example
+
+namespace foo {
+   int fact(int n);
+   struct Vector {
+       double x,y,z;
+   };
+};
+
      +
      + +

      +it works in Python as follows: +

      + +
      +
      +>>> import example
+>>> example.fact(3)
+6
+>>> v = example.Vector()
+>>> v.x = 3.4
+>>> print v.y
+0.0
+>>>
+
      +
      + +

      +If your program has more than one namespace, name conflicts (if any) can be resolved using %rename +For example: +

      + +
      +
      +%rename(Bar_spam) Bar::spam;
+
+namespace Foo {
+    int spam();
+}
+
+namespace Bar {
+    int spam();
+}
+
      +
      + +

      +If you have more than one namespace and your want to keep their +symbols separate, consider wrapping them as separate SWIG modules. +For example, make the module name the same as the namespace and create +extension modules for each namespace separately. If your program +utilizes thousands of small deeply nested namespaces each with +identical symbol names, well, then you get what you deserve. +

      + +

      31.3.13 C++ templates

      + + +

      +C++ templates don't present a huge problem for SWIG. However, in order +to create wrappers, you have to tell SWIG to create wrappers for a particular +template instantiation. To do this, you use the %template directive. +For example: +

      + +
      +
      +%module example
+%{
+#include "pair.h"
+%}
+
+template<class T1, class T2>
+struct pair {
+   typedef T1 first_type;
+   typedef T2 second_type;
+   T1 first;
+   T2 second;
+   pair();
+   pair(const T1&, const T2&);
+  ~pair();
+};
+
+%template(pairii) pair<int,int>;
+
      +
      + +

      +In Python: +

      + +
      +
      +>>> import example
+>>> p = example.pairii(3,4)
+>>> p.first
+3
+>>> p.second
+4
+
      +
      + +

      +Obviously, there is more to template wrapping than shown in this example. +More details can be found in the SWIG and C++ chapter. +Some more complicated +examples will appear later. +

      + +

      31.3.14 C++ Smart Pointers

      + + +

      +In certain C++ programs, it is common to use classes that have been wrapped by +so-called "smart pointers." Generally, this involves the use of a template class +that implements operator->() like this: +

      + +
      +
      +template<class T> class SmartPtr {
+   ...
+   T *operator->();
+   ...
+}
+
      +
      + +

      +Then, if you have a class like this, +

      + +
      +
      +class Foo {
+public:
+     int x;
+     int bar();
+};
+
      +
      + +

      +A smart pointer would be used in C++ as follows: +

      + +
      +
      +SmartPtr<Foo> p = CreateFoo();   // Created somehow (not shown)
+...
+p->x = 3;                        // Foo::x
+int y = p->bar();                // Foo::bar
+
      +
      + +

      +To wrap this in Python, simply tell SWIG about the SmartPtr class and the low-level +Foo object. Make sure you instantiate SmartPtr using %template if necessary. +For example: +

      + +
      +
      +%module example
+...
+%template(SmartPtrFoo) SmartPtr<Foo>;
+...
+
      +
      + +

      +Now, in Python, everything should just "work": +

      + +
      +
      +>>> p = example.CreateFoo()          # Create a smart-pointer somehow
+>>> p.x = 3                          # Foo::x
+>>> p.bar()                          # Foo::bar
+
      +
      + +

      +If you ever need to access the underlying pointer returned by operator->() itself, +simply use the __deref__() method. For example: +

      + +
      +
      +>>> f = p.__deref__()     # Returns underlying Foo *
+
      +
      + + +

      31.3.15 C++ Reference Counted Objects (ref/unref)

      + + +

      +Another usual idiom in C++ is the use of reference counted +objects. Consider for example: + +

      +
      +class RCObj  {
+  // implement the ref counting mechanism
+  int add_ref();
+  int del_ref();
+  int ref_count();
+
+public:
+  virtual ~RCObj() = 0;
+
+  int ref() const {
+    return add_ref();
+  }
+
+  int unref() const   {
+    if (ref_count() == 0 || del_ref() == 0 ) {
+	delete this;
+	return 0;
+      } 
+    return ref_count();
+  }
+};
+
+
+class A : RCObj {
+public:
+  A();
+  int foo();
+};
+
+
+class B {
+  A *_a;
+
+public:
+  B(A *a) : _a(a) { 
+    a->ref(); 
+  }
+
+  ~B() { 
+    a->unref(); 
+  }
+};
+
+int main() {
+  A *a  = new A();
+  a->ref();           // 'a' is ref here
+
+  B *b1 = new B(a);   // 'a' is ref here
+  if (1 + 1 == 2) {
+    B *b2 = new B(a); // 'a' is ref here
+    delete b2;        // 'a' is unref, but not deleted   
+  }
+
+  delete b1;          // 'a' is unref, but not deleted   
+  a->unref();         // 'a' is unref and deleted
+}
+
      +
      + +

      +In the example above, the 'A' class instance 'a' is a reference counted +object, which can't be deleted arbitrarily since it is shared between +the objects 'b1' and 'b2'. 'A' is derived from an Reference Counted +Object 'RCObj', which implements the ref/unref idiom. +

      + +

      +To tell SWIG that 'RCObj' and all its derived classes are reference +counted objects, you use the "ref" and "unref" features, or +%ref and %unref directives (since 1.3.28). For example: +

      + + +
      +
      +%module example
+...
+
+%feature("ref")   RCObj "$this->ref();"
+%feature("unref") RCObj "$this->unref();"
+
+%include "rcobj.h"
+%include "A.h"
+...
+
      +
      + +or, using the directive form: + + +
      +
      +%module example
+...
+
+%ref   RCObj "$this->ref();"
+%unref RCObj "$this->unref();"
+
+%include "rcobj.h"
+%include "A.h"
+...
+
      +
      + + + +

      +where the code passed to the "ref" and "unref" features will be +executed as needed whenever a new object is passed to python, or when +python tries to release the shadow object instance, respectively. +

      + +

      +In the python side, the use of a reference counted object is not +different than any other regular instance: +

      + +
      +
      +def create_A():
+  a = A()         # SWIG ref 'a' (new object is passed to python)
+  b1 = B(a)       # C++  ref 'a'
+  if 1 + 1 == 2:
+     b2 = B(a)    # C++ ref 'a'
+  return a        # 'b1' and 'b2' are released, C++ unref 'a' twice
+
+a = create_A()   
+exit              # 'a' is released, SWIG unref 'a'
+
      +
      + +

      +Note that the user doesn't explicitly need to call 'a->ref()' nor 'a->unref()' +(as neither 'delete a'). Instead, SWIG take cares of executing the "ref" +and "unref" codes as needed. If the user doesn't specify the +"ref/unref" features, SWIG will produce a code equivalent to define +them as: +

      + +
      +
      +%feature("ref")   ""
+%feature("unref") "delete $this;"
+
      +
      + +

      +In other words, SWIG will not do anything special when a new object +is passed to python, and it will always 'delete' the object when +python releases the proxy instance. +

      + + +

      31.4 Further details on the Python class interface

      + + +

      +In the previous section, a high-level view of Python wrapping was +presented. A key component of this wrapping is that structures and +classes are wrapped by Python proxy classes. This provides a very +natural Python interface and allows SWIG to support a number of +advanced features such as operator overloading. However, a number +of low-level details were omitted. This section provides a brief overview +of how the proxy classes work. +

      + +

      31.4.1 Proxy classes

      + + +

      +In the "SWIG basics" and "SWIG and C++" chapters, +details of low-level structure and class wrapping are described. To summarize those chapters, if you +have a class like this +

      + +
      +
      +class Foo {
+public:
+     int x;
+     int spam(int);
+     ...
+
      +
      + +

      +then SWIG transforms it into a set of low-level procedural wrappers. For example: +

      + +
      +
      +Foo *new_Foo() {
+    return new Foo();
+}
+void delete_Foo(Foo *f) {
+    delete f;
+}
+int Foo_x_get(Foo *f) {
+    return f->x;
+}
+void Foo_x_set(Foo *f, int value) {
+    f->x = value;
+}
+int Foo_spam(Foo *f, int arg1) {
+    return f->spam(arg1);
+}
+
      +
      + +

      +These wrappers can be found in the low-level extension module (e.g., _example). +

      + +

      +Using these wrappers, SWIG generates a high-level Python proxy class (also known as a shadow class) like this (shown +for Python 2.2): +

      + +
      +
      +import _example
+
+class Foo(object):
+     def __init__(self):
+         self.this = _example.new_Foo()
+         self.thisown = 1
+     def __del__(self):
+         if self.thisown:
+               _example.delete_Foo(self.this)
+     def spam(self,arg1):
+         return _example.Foo_spam(self.this,arg1)
+     x = property(_example.Foo_x_get, _example.Foo_x_set)
+
      +
      + +

      +This class merely holds a pointer to the underlying C++ object (.this) and dispatches methods and +member variable access to that object using the low-level accessor functions. From a user's point of +view, it makes the class work normally: +

      + +
      +
      +>>> f = example.Foo()
+>>> f.x = 3
+>>> y = f.spam(5)
+
      +
      + +

      +The fact that the class has been wrapped by a real Python class offers certain advantages. For instance, +you can attach new Python methods to the class and you can even inherit from it (something not supported +by Python built-in types until Python 2.2). +

      + +

      31.4.2 Memory management

      + + +

      +Associated with proxy object, is an ownership flag .thisown The value of this +flag determines who is responsible for deleting the underlying C++ object. If set to 1, +the Python interpreter will destroy the C++ object when the proxy class is +garbage collected. If set to 0 (or if the attribute is missing), then the destruction +of the proxy class has no effect on the C++ object. +

      + +

      +When an object is created by a constructor or returned by value, Python automatically takes +ownership of the result. For example: +

      + +
      +
      +class Foo {
+public:
+    Foo();
+    Foo bar();
+};
+
      +
      + +

      +In Python: +

      + +
      +
      +>>> f = Foo()
+>>> f.thisown
+1
+>>> g = f.bar()
+>>> g.thisown
+1
+
      +
      + +

      +On the other hand, when pointers are returned to Python, there is often no way to know where +they came from. Therefore, the ownership is set to zero. For example: +

      + +
      +
      +class Foo {
+public:
+    ...
+    Foo *spam();
+    ...
+};
+
      +
      + +
      + +
      +
      +>>> f = Foo()
+>>> s = f.spam()
+>>> print s.thisown
+0
+>>>
+
      +
      + +

      +This behavior is especially important for classes that act as +containers. For example, if a method returns a pointer to an object +that is contained inside another object, you definitely don't want +Python to assume ownership and destroy it! +

      + +

      +A good way to indicate that ownership should be set for a returned pointer +is to use the %newobject directive. +

      + +

      +Related to containers, ownership issues can arise whenever an object is assigned to a member +or global variable. For example, consider this interface: +

      + +
      +
      +%module example
+
+struct Foo {
+    int  value;
+    Foo  *next;
+};
+
+Foo *head = 0;
+
      +
      + +

      +When wrapped in Python, careful observation will reveal that ownership changes whenever an object +is assigned to a global variable. For example: +

      + +
      +
      +>>> f = example.Foo()
+>>> f.thisown
+1
+>>> example.cvar.head = f           
+>>> f.thisown
+0
+>>>
+
      +
      + +

      +In this case, C is now holding a reference to the object---you probably don't want Python to destroy it. +Similarly, this occurs for members. For example: +

      + +
      +
      +>>> f = example.Foo()
+>>> g = example.Foo()
+>>> f.thisown
+1
+>>> g.thisown
+1
+>>> f.next = g
+>>> g.thisown
+0
+>>>
+
      +
      + +

      +For the most part, memory management issues remain hidden. However, +there are occasionally situations where you might have to manually +change the ownership of an object. For instance, consider code like this: +

      + +
      +
      +class Node {
+   Object *value;
+public:
+   void set_value(Object *v) { value = v; }
+   ...
+};
+
      +
      + +

      +Now, consider the following Python code: +

      + +
      +
      +>>> v = Object()           # Create an object
+>>> n = Node()             # Create a node
+>>> n.set_value(v)         # Set value
+>>> v.thisown
+1
+>>> del v
+
      +
      + +

      +In this case, the object n is holding a reference to +v internally. However, SWIG has no way to know that this +has occurred. Therefore, Python still thinks that it has ownership of the +object. Should the proxy object be destroyed, then the C++ destructor +will be invoked and n will be holding a stale-pointer. If +you're lucky, you will only get a segmentation fault. +

      + +

      +To work around this, it is always possible to flip the ownership flag. For example, +

      + +
      +
      +>>> v.thisown = 0
+
      +
      + +

      +It is also possible to deal with situations like this using +typemaps--an advanced topic discussed later. +

      + +

      31.4.3 Python 2.2 and classic classes

      + + +

      +SWIG makes every attempt to preserve backwards compatibility with +older versions of Python to the extent that it is possible. However, +in Python-2.2, an entirely new type of class system was introduced. +This new-style class system offers many enhancements including static +member functions, properties (managed attributes), and class methods. +Details about all of these changes can be found on www.python.org and is not repeated here. +

      + +

      +To address differences between Python versions, SWIG currently emits +dual-mode proxy class wrappers. In Python-2.2 and newer releases, +these wrappers encapsulate C++ objects in new-style classes that take +advantage of new features (static methods and properties). However, +if these very same wrappers are imported into an older version of Python, +old-style classes are used instead. +

      + +

      +This dual-nature of the wrapper code means that you can create extension +modules with SWIG and those modules will work with all versions of Python +ranging from Python-1.4 to the very latest release. Moreover, the wrappers take +advantage of Python-2.2 features when available. +

      + +

      +For the most part, the interface presented to users is the same regardless +of what version of Python is used. The only incompatibility lies in the handling +of static member functions. In Python-2.2, they can be accessed via the +class itself. In Python-2.1 and earlier, they have to be accessed as a global +function or through an instance (see the earlier section). +

      + +

      31.5 Cross language polymorphism

      + + +

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

      + +

      +This arrangement is asymmetric in the sense that no corresponding +mechanism exists to pass method calls down the inheritance chain from +C++ to Python. In particular, if a C++ class has been extended in Python +(by extending the proxy class), these extensions will not be visible +from C++ code. Virtual method calls from C++ are thus not able access +the lowest implementation in the inheritance chain. +

      + +

      +Changes have been made to SWIG 1.3.18 to address this problem and +make the relationship between C++ classes and proxy classes more +symmetric. To achieve this goal, new classes called directors are +introduced at the bottom of the C++ inheritance chain. The job of the +directors is to route method calls correctly, either to C++ +implementations higher in the inheritance chain or to Python +implementations lower in the inheritance chain. The upshot is that C++ +classes can be extended in Python and from C++ these extensions look +exactly like native C++ classes. Neither C++ code nor Python code needs +to know where a particular method is implemented: the combination of +proxy classes, director classes, and C wrapper functions takes care of +all the cross-language method routing transparently. +

      + +

      31.5.1 Enabling directors

      + + +

      +The director feature is disabled by default. To use directors you +must make two changes to the interface file. First, add the "directors" +option to the %module directive, like this: +

      + +
      +
      +%module(directors="1") modulename
+
      +
      + +

      +Without this option no director code will be generated. Second, you +must use the %feature("director") directive to tell SWIG which classes +and methods should get directors. The %feature directive can be applied +globally, to specific classes, and to specific methods, like this: +

      + +
      +
      +// generate directors for all classes that have virtual methods
+%feature("director");         
+
+// generate directors for all virtual methods in class Foo
+%feature("director") Foo;      
+
+// generate a director for just Foo::bar()
+%feature("director") Foo::bar; 
+
      +
      + +

      +You can use the %feature("nodirector") directive to turn off +directors for specific classes or methods. So for example, +

      + +
      +
      +%feature("director") Foo;
+%feature("nodirector") Foo::bar;
+
      +
      + +

      +will generate directors for all virtual methods of class Foo except +bar(). +

      + +

      +Directors can also be generated implicitly through inheritance. +In the following, class Bar will get a director class that handles +the methods one() and two() (but not three()): +

      + +
      +
      +%feature("director") Foo;
+class Foo {
+public:
+    Foo(int foo);
+    virtual void one();
+    virtual void two();
+};
+
+class Bar: public Foo {
+public:
+    virtual void three();
+};
+
      +
      + +

      +then at the python side you can define +

      + +
      +
      +import mymodule
+
+class MyFoo(mymodule.Foo):
+  def __init__(self, foo):
+     mymodule.Foo(self, foo)  
+
+  def one(self):
+     print "one from python"
+
      +
      + + +

      31.5.2 Director classes

      + + + + + +

      +For each class that has directors enabled, SWIG generates a new class +that derives from both the class in question and a special +Swig::Director class. These new classes, referred to as director +classes, can be loosely thought of as the C++ equivalent of the Python +proxy classes. The director classes store a pointer to their underlying +Python object and handle various issues related to object ownership. +Indeed, this is quite similar to the "this" and "thisown" members of the +Python proxy classes. +

      + +

      +For simplicity let's ignore the Swig::Director class and refer to the +original C++ class as the director's base class. By default, a director +class extends all virtual methods in the inheritance chain of its base +class (see the preceding section for how to modify this behavior). +Thus all virtual method calls, whether they originate in C++ or in +Python via proxy classes, eventually end up in at the implementation in +the director class. The job of the director methods is to route these +method calls to the appropriate place in the inheritance chain. By +"appropriate place" we mean the method that would have been called if +the C++ base class and its extensions in Python were seamlessly +integrated. That seamless integration is exactly what the director +classes provide, transparently skipping over all the messy extension API +glue that binds the two languages together. +

      + +

      +In reality, the "appropriate place" is one of only two possibilities: +C++ or Python. Once this decision is made, the rest is fairly easy. If +the correct implementation is in C++, then the lowest implementation of +the method in the C++ inheritance chain is called explicitly. If the +correct implementation is in Python, the Python API is used to call the +method of the underlying Python object (after which the usual virtual +method resolution in Python automatically finds the right +implementation). +

      + +

      +Now how does the director decide which language should handle the method call? +The basic rule is to handle the method in Python, unless there's a good +reason not to. The reason for this is simple: Python has the most +"extended" implementation of the method. This assertion is guaranteed, +since at a minimum the Python proxy class implements the method. If the +method in question has been extended by a class derived from the proxy +class, that extended implementation will execute exactly as it should. +If not, the proxy class will route the method call into a C wrapper +function, expecting that the method will be resolved in C++. The wrapper +will call the virtual method of the C++ instance, and since the director +extends this the call will end up right back in the director method. Now +comes the "good reason not to" part. If the director method were to blindly +call the Python method again, it would get stuck in an infinite loop. We avoid this +situation by adding special code to the C wrapper function that tells +the director method to not do this. The C wrapper function compares the +pointer to the Python object that called the wrapper function to the +pointer stored by the director. If these are the same, then the C +wrapper function tells the director to resolve the method by calling up +the C++ inheritance chain, preventing an infinite loop. +

      + +

      +One more point needs to be made about the relationship between director +classes and proxy classes. When a proxy class instance is created in +Python, SWIG creates an instance of the original C++ class and assigns +it to .this. This is exactly what happens without directors and +is true even if directors are enabled for the particular class in +question. When a class derived 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 +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++ +so there is no need for the extra overhead involved with routing the +calls through Python. +

      + +

      31.5.3 Ownership and object destruction

      + + +

      +Memory management issues are slightly more complicated with directors +than for proxy classes alone. Python instances hold a pointer to the +associated C++ director object, and the director in turn holds a pointer +back to the Python object. By default, proxy classes own their C++ +director object and take care of deleting it when they are garbage +collected. +

      + +

      +This relationship can be reversed by calling the special +__disown__() method of the proxy class. After calling this +method, the .thisown flag is set to zero, and the director +class increments the reference count of the Python object. When the +director class is deleted it decrements the reference count. Assuming no +outstanding references to the Python object remain, the Python object +will be destroyed at the same time. This is a good thing, since +directors and proxies refer to each other and so must be created and +destroyed together. Destroying one without destroying the other will +likely cause your program to segfault. +

      + +

      +To help ensure that no references to the Python object remain after +calling __disown__(), this method returns a weak reference to +the Python object. Weak references are only available in Python versions +2.1 and higher, so for older versions you must explicitly delete all +references. Here is an example: +

      + +
      +
      +class Foo {
+public:
+    ...
+};
+class FooContainer {
+public:
+    void addFoo(Foo *);
+    ...
+};
+
      +
      + +
      + +
      +
      +>>> c = FooContainer()
+>>> a = Foo().__disown()__
+>>> c.addFoo(a)
+>>> b = Foo()
+>>> b = b.__disown()__
+>>> c.addFoo(b)
+>>> c.addFoo(Foo().__disown()__)
+
      +
      + +

      +In this example, we are assuming that FooContainer will take care of +deleting all the Foo pointers it contains at some point. Note that no hard +references to the Foo objects remain in Python. +

      + +

      31.5.4 Exception unrolling

      + + +

      +With directors routing method calls to Python, and proxies routing them +to C++, the handling of exceptions is an important concern. By default, the +directors ignore exceptions that occur during method calls that are +resolved in Python. To handle such exceptions correctly, it is necessary +to temporarily translate them into C++ exceptions. This can be done with +the %feature("director:except") directive. The following code should +suffice in most cases: +

      + +
      +
      +%feature("director:except") {
+    if ($error != NULL) {
+        throw Swig::DirectorMethodException();
+    }
+}
+
      +
      + +

      +This code will check the Python error state after each method call from +a director into Python, and throw a C++ exception if an error occurred. +This exception can be caught in C++ to implement an error handler. +Currently no information about the Python error is stored in the +Swig::DirectorMethodException object, but this will likely change in +the future. +

      + +

      +It may be the case that a method call originates in Python, travels up +to C++ through a proxy class, and then back into Python via a director +method. If an exception occurs in Python at this point, it would be nice +for that exception to find its way back to the original caller. This can +be done by combining a normal %exception directive with the +director:except handler shown above. Here is an example of a +suitable exception handler: +

      + +
      +
      +%exception {
+    try { $action }
+    catch (Swig::DirectorException &e) { SWIG_fail; }
+}
+
      +
      + +

      +The class Swig::DirectorException used in this example is actually a +base class of Swig::DirectorMethodException, so it will trap this +exception. Because the Python error state is still set when +Swig::DirectorMethodException is thrown, Python will register the +exception as soon as the C wrapper function returns. +

      + +

      31.5.5 Overhead and code bloat

      + + +

      +Enabling directors for a class will generate a new director method for +every virtual method in the class' inheritance chain. This alone can +generate a lot of code bloat for large hierarchies. Method arguments +that require complex conversions to and from target language types can +result in large director methods. For this reason it is recommended that +you selectively enable directors only for specific classes that are +likely to be extended in Python and used in C++. +

      + +

      +Compared to classes that do not use directors, the call routing in the +director methods does add some overhead. In particular, at least one +dynamic cast and one extra function call occurs per method call from +Python. Relative to the speed of Python execution this is probably +completely negligible. For worst case routing, a method call that +ultimately resolves in C++ may take one extra detour through Python in +order to ensure that the method does not have an extended Python +implementation. This could result in a noticeable overhead in some cases. +

      + +

      +Although directors make it natural to mix native C++ objects with Python +objects (as director objects) via a common base class pointer, one +should be aware of the obvious fact that method calls to Python objects +will be much slower than calls to C++ objects. This situation can be +optimized by selectively enabling director methods (using the %feature +directive) for only those methods that are likely to be extended in +Python. +

      + +

      31.5.6 Typemaps

      + + +

      +Typemaps for input and output of most of the basic types from director +classes have been written. These are roughly the reverse of the usual +input and output typemaps used by the wrapper code. The typemap +operation names are 'directorin', 'directorout', and 'directorargout'. +The director code does not currently use any of the other kinds of typemaps. +It is not clear at this point which kinds are appropriate and +need to be supported. +

      + + +

      31.5.7 Miscellaneous

      + + +

      +Director typemaps for STL classes are in place, and hence you should +be able to use std::vector, std::string, etc., as you would any other type. +

      + +

      +Note: The director typemaps for return types based in const +references, such as + +

      +
      +class Foo {
+…
+    virtual const int& bar();
+…
+};
+
      +
      + +

      +will work only for simple call scenarios. Usually the resulting code +is neither thread or reentrant safe. Hence, the user is advised to +avoid returning const references in director methods. For example, +the user could modify the method interface to use lvalue return +types, wherever possible, for example +

      + +
      +
      +class Foo {
+…
+    virtual int bar();
+…
+};
+
      +
      + +

      +If that is not possible, the user should avoid enabling the +director feature for reentrant, recursive or threaded member +methods that return const references. +

      + + +

      31.6 Common customization features

      + + +

      +The last section presented the absolute basics of C/C++ wrapping. If +you do nothing but feed SWIG a header file, you will get an interface +that mimics the behavior described. However, sometimes this isn't +enough to produce a nice module. Certain types of functionality might +be missing or the interface to certain functions might be awkward. +This section describes some common SWIG features that are used to +improve your the interface to an extension module. +

      + +

      31.6.1 C/C++ helper functions

      + + +

      +Sometimes when you create a module, it is missing certain bits of functionality. For +example, if you had a function like this +

      + +
      +
      +void set_transform(Image *im, double m[4][4]);
+
      +
      + +

      +it would be accessible from Python, but there may be no easy way to call it. +For example, you might get errors like this: +

      + +
      +
      +>>> a = [
+...   [1,0,0,0],
+...   [0,1,0,0],
+...   [0,0,1,0],
+...   [0,0,0,1]]
+>>> set_transform(im,a)
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+TypeError: Type error. Expected _p_a_4__double
+
      +
      + +

      +The problem here is that there is no easy way to construct and manipulate a suitable +double [4][4] value to use. To fix this, you can write some extra C helper +functions. Just use the %inline directive. For example: +

      + +
      +
      +%inline %{
+/* Note: double[4][4] is equivalent to a pointer to an array double (*)[4] */
+double (*new_mat44())[4] {
+   return (double (*)[4]) malloc(16*sizeof(double));
+}
+void free_mat44(double (*x)[4]) {
+   free(x);
+}
+void mat44_set(double x[4][4], int i, int j, double v) {
+   x[i][j] = v;
+}
+double mat44_get(double x[4][4], int i, int j) {
+   return x[i][j];
+}
+%}
+
      +
      + +

      +From Python, you could then write code like this: +

      + +
      +
      +>>> a = new_mat44()
+>>> mat44_set(a,0,0,1.0)
+>>> mat44_set(a,1,1,1.0)
+>>> mat44_set(a,2,2,1.0)
+...
+>>> set_transform(im,a)
+>>>
+
      +
      + +

      +Admittedly, this is not the most elegant looking approach. However, it works and it wasn't too +hard to implement. It is possible to clean this up using Python code, typemaps, and other +customization features as covered in later sections. +

      + +

      31.6.2 Adding additional Python code

      + + +

      +If writing support code in C isn't enough, it is also possible to write code in +Python. This code gets inserted in to the .py file created by SWIG. One +use of Python code might be to supply a high-level interface to certain functions. +For example: +

      + +
      +
      +void set_transform(Image *im, double x[4][4]);
+
+...
+/* Rewrite the high level interface to set_transform */
+%pythoncode %{
+def set_transform(im,x):
+   a = new_mat44()
+   for i in range(4):
+       for j in range(4):
+           mat44_set(a,i,j,x[i][j])
+   _example.set_transform(im,a)
+   free_mat44(a)
+%}
+
      +
      + +

      +In this example, set_transform() provides a high-level Python interface built on top of +low-level helper functions. For example, this code now seems to work: +

      + +
      +
      +>>> a = [
+...   [1,0,0,0],
+...   [0,1,0,0],
+...   [0,0,1,0],
+...   [0,0,0,1]]
+>>> set_transform(im,a)
+>>>
+
      +
      + +

      +Admittedly, this whole scheme for wrapping the two-dimension array +argument is rather ad-hoc. Besides, shouldn't a Python list or a +Numeric Python array just work normally? We'll get to those examples +soon enough. For now, think of this example as an illustration of +what can be done without having to rely on any of the more advanced +customization features. +

      + +

      Sometimes you may want to replace or modify the wrapper function +that SWIG creates in the proxy .py file. The Python module +in SWIG provides some features that enable you do do this. First, to +entirely replace a proxy function you can use +%feature("shadow"). For example:

      + +
      +
      +%module example
+
+// Rewrite bar() python code
+
+%feature("shadow") Foo::bar(int) %{
+def bar(*args):
+    #do something before
+    $action
+    #do something after
+%}
+    
+class Foo {
+public:
+    int bar(int x);
+}
+
      +
      + +

      where $action will be replaced by the call to +the C/C++ proper method. +

      + +

      +Often the proxy function created by SWIG is fine, but you simply want +to add code to it without touching the rest of the generated function +body. For these cases SWIG provides the pythonprepend and +pythonappend features which do exactly as their names suggest. The +pythonprepend feature will insert its value at the beginning of the +proxy function, and pythonappend will insert code at the end of the +proxy, just before the return statement. +

      + + +
      +
      +%module example
+
+// Add python code to bar() 
+
+%feature("pythonprepend") Foo::bar(int) %{
+   #do something before C++ call
+%}
+
+%feature("pythonappend") Foo::bar(int) %{
+   #do something after C++ call
+%}
+
+    
+class Foo {
+public:
+    int bar(int x);
+}
+
      +
      + +

      +Notes: Usually the pythonappend and pythonprepend +features are safer to use than the shadow feature. Also, from +SWIG version 1.3.28 you can use the directive forms +%pythonappend and %pythonprepend as follows:

      + + +
      +
      +%module example
+
+// Add python code to bar() 
+
+%pythonprepend Foo::bar(int) %{
+   #do something before C++ call
+%}
+
+%pythonappend Foo::bar(int) %{
+   #do something after C++ call
+%}
+
+    
+class Foo {
+public:
+    int bar(int x);
+}
+
      +
      + + + + +

      31.6.3 Class extension with %extend

      + + +

      +One of the more interesting features of SWIG is that it can extend +structures and classes with new methods--at least in the Python interface. +Here is a simple example: +

      + +
      +
      +%module example
+%{
+#include "someheader.h"
+%}
+
+struct Vector {
+   double x,y,z;
+};
+
+%extend Vector {
+   char *__str__() {
+       static char tmp[1024];
+       sprintf(tmp,"Vector(%g,%g,%g)", $self->x,$self->y,$self->z);
+       return tmp;
+   }
+   Vector(double x, double y, double z) {
+       Vector *v = (Vector *) malloc(sizeof(Vector));
+       v->x = x;
+       v->y = y;
+       v->z = z;
+       return v;
+   }
+};
+
      +
      + +

      +Now, in Python +

      + +
      +
      +>>> v = example.Vector(2,3,4)
+>>> print v
+Vector(2,3,4)
+>>>
+
      +
      + +

      +%extend can be used for many more tasks than this. +For example, if you wanted to overload a Python operator, you might do this: +

      + +
      +
      +%extend Vector {
+    Vector __add__(Vector *other) {
+         Vector v;
+         v.x = $self->x + other->x;
+         v.y = $self->y + other->y;
+         v.z = $self->z + other->z;
+         return v;
+    }
+};
+
      +
      + +

      +Use it like this: +

      + +
      +
      +>>> import example
+>>> v = example.Vector(2,3,4)
+>>> w = example.Vector(10,11,12)
+>>> print v+w
+Vector(12,14,16)
+>>> 
+
      +
      + +

      +%extend works with both C and C++ code. It does not modify the underlying object +in any way---the extensions only show up in the Python interface. +

      + +

      31.6.4 Exception handling with %exception

      + + +

      +If a C or C++ function throws an error, you may want to convert that error into a Python +exception. To do this, you can use the %exception directive. %exception +simply lets you rewrite part of the generated wrapper code to include an error check. +

      + +

      +In C, a function often indicates an error by returning a status code (a negative number +or a NULL pointer perhaps). Here is a simple example of how you might handle that: +

      + +
      +
      +%exception malloc {
+  $action
+  if (!result) {
+     PyErr_SetString(PyExc_MemoryError,"Not enough memory");
+     return NULL;
+  }
+}
+void *malloc(size_t nbytes);
+
      +
      + +

      +In Python, +

      + +
      +
      +>>> a = example.malloc(2000000000)
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+MemoryError: Not enough memory
+>>>
+
      +
      + +

      +If a library provides some kind of general error handling framework, you can also use +that. For example: +

      + +
      +
      +%exception {
+   $action
+   if (err_occurred()) {
+      PyErr_SetString(PyExc_RuntimeError, err_message());
+      return NULL;
+   }
+}
+
      +
      + +

      +No declaration name is given to %exception, it is applied to all wrapper functions. +

      + +

      +C++ exceptions are also easy to handle. For example, you can write code like this: +

      + +
      +
      +%exception getitem {
+   try {
+      $action
+   } catch (std::out_of_range &e) {
+      PyErr_SetString(PyExc_IndexError, const_cast<char*>(e.what()));
+      return NULL;
+   }
+}
+
+class Base {
+public:
+     Foo *getitem(int index);      // Exception handled added
+     ...
+};
+
      +
      + +

      +When raising a Python exception from C, use the PyErr_SetString() +function as shown above. The following exception types can be used as the first argument. +

      + +
      +
      +PyExc_ArithmeticError
+PyExc_AssertionError
+PyExc_AttributeError
+PyExc_EnvironmentError
+PyExc_EOFError
+PyExc_Exception
+PyExc_FloatingPointError
+PyExc_ImportError
+PyExc_IndexError
+PyExc_IOError
+PyExc_KeyError
+PyExc_KeyboardInterrupt
+PyExc_LookupError
+PyExc_MemoryError
+PyExc_NameError
+PyExc_NotImplementedError
+PyExc_OSError
+PyExc_OverflowError
+PyExc_RuntimeError
+PyExc_StandardError
+PyExc_SyntaxError
+PyExc_SystemError
+PyExc_TypeError
+PyExc_UnicodeError
+PyExc_ValueError
+PyExc_ZeroDivisionError
+
      +
      + +

      +The language-independent exception.i library file can also be used +to raise exceptions. See the SWIG Library chapter. +

      + +

      31.7 Tips and techniques

      + + +

      +Although SWIG is largely automatic, there are certain types of wrapping problems that +require additional user input. Examples include dealing with output parameters, +strings, binary data, and arrays. This chapter discusses the common techniques for +solving these problems. +

      + +

      31.7.1 Input and output parameters

      + + +

      +A common problem in some C programs is handling parameters passed as simple pointers. For +example: +

      + +
      +
      +void add(int x, int y, int *result) {
+   *result = x + y;
+}
+
      +
      + +

      +or perhaps +

      + +
      +
      +int sub(int *x, int *y) {
+   return *x-*y;
+}
+
      +
      + +

      +The easiest way to handle these situations is to use the typemaps.i file. For example: +

      + +
      +
      +%module example
+%include "typemaps.i"
+
+void add(int, int, int *OUTPUT);
+int  sub(int *INPUT, int *INPUT);
+
      +
      + +

      +In Python, this allows you to pass simple values. For example: +

      + +
      +
      +>>> a = add(3,4)
+>>> print a
+7
+>>> b = sub(7,4)
+>>> print b
+3
+>>>
+
      +
      + +

      +Notice how the INPUT parameters allow integer values to be passed instead of pointers +and how the OUTPUT parameter creates a return result. +

      + +

      +If you don't want to use the names INPUT or OUTPUT, use the %apply +directive. For example: +

      + +
      +
      +%module example
+%include "typemaps.i"
+
+%apply int *OUTPUT { int *result };
+%apply int *INPUT  { int *x, int *y};
+
+void add(int x, int y, int *result);
+int  sub(int *x, int *y);
+
      +
      + +

      +If a function mutates one of its parameters like this, +

      + +
      +
      +void negate(int *x) {
+   *x = -(*x);
+}
+
      +
      + +

      +you can use INOUT like this: +

      + +
      +
      +%include "typemaps.i"
+...
+void negate(int *INOUT);
+
      +
      + +

      +In Python, a mutated parameter shows up as a return value. For example: +

      + +
      +
      +>>> a = negate(3)
+>>> print a
+-3
+>>>
+
      +
      + +

      +Note: Since most primitive Python objects are immutable, it is not possible to +perform in-place modification of a Python object passed as a parameter. +

      + +

      +The most common use of these special typemap rules is to handle functions that +return more than one value. For example, sometimes a function returns a result +as well as a special error code: +

      + +
      +
      +/* send message, return number of bytes sent, along with success code */
+int send_message(char *text, int len, int *success);
+
      +
      + +

      +To wrap such a function, simply use the OUTPUT rule above. For example: +

      + +
      +
      +%module example
+%include "typemaps.i"
+%apply int *OUTPUT { int *success };
+...
+int send_message(char *text, int *success);
+
      +
      + +

      +When used in Python, the function will return multiple values. +

      + +
      +
      +bytes, success = send_message("Hello World")
+if not success:
+    print "Whoa!"
+else:
+    print "Sent", bytes
+
      +
      + +

      +Another common use of multiple return values are in query functions. For example: +

      + +
      +
      +void get_dimensions(Matrix *m, int *rows, int *columns);
+
      +
      + +

      +To wrap this, you might use the following: +

      + +
      +
      +%module example
+%include "typemaps.i"
+%apply int *OUTPUT { int *rows, int *columns };
+...
+void get_dimensions(Matrix *m, int *rows, *columns);
+
      +
      + +

      +Now, in Python: +

      + +
      +
      +>>> r,c = get_dimensions(m)
+
      +
      + +

      +Be aware that the primary purpose of the typemaps.i file is to support primitive datatypes. +Writing a function like this +

      + +
      +
      +void foo(Bar *OUTPUT);
+
      +
      + +

      +may not have the intended effect since typemaps.i does not define an OUTPUT rule for Bar. +

      + +

      31.7.2 Simple pointers

      + + +

      +If you must work with simple pointers such as int * or double * and you don't want to use +typemaps.i, consider using the cpointer.i library file. For example: +

      + +
      +
      +%module example
+%include "cpointer.i"
+
+%inline %{
+extern void add(int x, int y, int *result);
+%}
+
+%pointer_functions(int, intp);
+
      +
      + +

      +The %pointer_functions(type,name) macro generates five helper functions that can be used to create, +destroy, copy, assign, and dereference a pointer. In this case, the functions are as follows: +

      + +
      +
      +int  *new_intp();
+int  *copy_intp(int *x);
+void  delete_intp(int *x);
+void  intp_assign(int *x, int value);
+int   intp_value(int *x);
+
      +
      + +

      +In Python, you would use the functions like this: +

      + +
      +
      +>>> result = new_intp()
+>>> print result
+_108fea8_p_int
+>>> add(3,4,result)
+>>> print intp_value(result)
+7
+>>>
+
      +
      + +

      +If you replace %pointer_functions() by %pointer_class(type,name), the interface is more class-like. +

      + +
      +
      +>>> result = intp()
+>>> add(3,4,result)
+>>> print result.value()
+7
+
      +
      + +

      +See the SWIG Library chapter for further details. +

      + +

      31.7.3 Unbounded C Arrays

      + + +

      +Sometimes a C function expects an array to be passed as a pointer. For example, +

      + +
      +
      +int sumitems(int *first, int nitems) {
+    int i, sum = 0;
+    for (i = 0; i < nitems; i++) {
+        sum += first[i];
+    }
+    return sum;
+}
+
      +
      + +

      +To wrap this into Python, you need to pass an array pointer as the first argument. +A simple way to do this is to use the carrays.i library file. For example: +

      + +
      +
      +%include "carrays.i"
+%array_class(int, intArray);
+
      +
      + +

      +The %array_class(type, name) macro creates wrappers for an unbounded array object that +can be passed around as a simple pointer like int * or double *. +For instance, you will be able to do this in Python: +

      + +
      +
      +>>> a = intArray(10000000)         # Array of 10-million integers
+>>> for i in xrange(10000):        # Set some values
+...     a[i] = i
+>>> sumitems(a,10000)
+49995000
+>>>
+
      +
      + +

      +The array "object" created by %array_class() does not +encapsulate pointers inside a special array object. In fact, there is +no bounds checking or safety of any kind (just like in C). Because of +this, the arrays created by this library are extremely low-level +indeed. You can't iterate over them nor can you even query their +length. In fact, any valid memory address can be accessed if you want +(negative indices, indices beyond the end of the array, etc.). +Needless to say, this approach is not going to suit all applications. +On the other hand, this low-level approach is extremely efficient and +well suited for applications in which you need to create buffers, +package binary data, etc. +

      + +

      31.7.4 String handling

      + + +

      +If a C function has an argument of char *, then a Python string +can be passed as input. For example: +

      + +
      +
      +// C
+void foo(char *s);
+
      +
      + +
      +
      +# Python
+>>> foo("Hello")
+
      +
      + +

      +When a Python string is passed as a parameter, the C function receives a pointer to the raw +data contained in the string. Since Python strings are immutable, it is illegal +for your program to change the value. In fact, doing so will probably crash the Python +interpreter. +

      + +

      +If your program modifies the input parameter or uses it to return data, consider +using the cstring.i library file described in the SWIG Library chapter. +

      + +

      +When functions return a char *, it is assumed to be a NULL-terminated string. +Data is copied into a new Python string and returned. +

      + +

      +If your program needs to work with binary data, you can use a typemap +to expand a Python string into a pointer/length argument pair. As luck would have it, +just such a typemap is already defined. Just do this: +

      + +
      +
      +%apply (char *STRING, int LENGTH) { (char *data, int size) };
+...
+int parity(char *data, int size, int initial);
+
      +
      + +

      +Now in Python: +

      + +
      +
      +>>> parity("e\x09ffss\x00\x00\x01\nx", 0)
+
      +
      + +

      +If you need to return binary data, you might use the +cstring.i library file. The cdata.i library can +also be used to extra binary data from arbitrary pointers. +

      + +

      31.7.5 Arrays

      + + +

      31.7.6 String arrays

      + + +

      31.7.7 STL wrappers

      + + +

      31.8 Typemaps

      + + +

      +This section describes how you can modify SWIG's default wrapping behavior +for various C/C++ datatypes using the %typemap directive. This +is an advanced topic that assumes familiarity with the Python C API as well +as the material in the "Typemaps" chapter. +

      + +

      +Before proceeding, it should be stressed that typemaps are not a required +part of using SWIG---the default wrapping behavior is enough in most cases. +Typemaps are only used if you want to change some aspect of the primitive +C-Python interface or if you want to elevate your guru status. +

      + +

      31.8.1 What is a typemap?

      + + +

      +A typemap is nothing more than a code generation rule that is attached to +a specific C datatype. For example, to convert integers from Python to C, +you might define a typemap like this: +

      + +
      +%module example
+
+%typemap(in) int {
+	$1 = (int) PyLong_AsLong($input);
+	printf("Received an integer : %d\n",$1);
+}
+%inline %{
+extern int fact(int n);
+%}
+
      + +

      +Typemaps are always associated with some specific aspect of code generation. +In this case, the "in" method refers to the conversion of input arguments +to C/C++. The datatype int is the datatype to which the typemap +will be applied. The supplied C code is used to convert values. In this +code a number of special variable prefaced by a $ are used. The +$1 variable is placeholder for a local variable of type int. +The $input variable is the input object of type PyObject *. +

      + +

      +When this example is compiled into a Python module, it operates as follows: +

      + +
      +>>> from example import *
+>>> fact(6)
+Received an integer : 6
+720
+
      + +

      +In this example, the typemap is applied to all occurrences of the int datatype. +You can refine this by supplying an optional parameter name. For example: +

      + +
      +%module example
+
+%typemap(in) int nonnegative {
+	$1 = (int) PyLong_AsLong($input);
+        if ($1 < 0) {
+           PyErr_SetString(PyExc_ValueError,"Expected a nonnegative value.");
+           return NULL;
+        }
+}
+%inline %{
+extern int fact(int nonnegative);
+%}
+
      + +

      +In this case, the typemap code is only attached to arguments that exactly match int nonnegative. +

      + +

      +The application of a typemap to specific datatypes and argument names involves +more than simple text-matching--typemaps are fully integrated into the +SWIG C++ type-system. When you define a typemap for int, that typemap +applies to int and qualified variations such as const int. In addition, +the typemap system follows typedef declarations. For example: +

      + +
      +
      +%typemap(in) int n {
+	$1 = (int) PyLong_AsLong($input);
+	printf("n = %d\n",$1);
+}
+%inline %{
+typedef int Integer;
+extern int fact(Integer n);    // Above typemap is applied
+%}
+
      +
      + +

      +Typemaps can also be defined for groups of consecutive arguments. For example: +

      + +
      +
      +%typemap(in) (char *str, int len) {
+    $1 = PyString_AsString($input);
+    $2 = PyString_Size($input);
+};
+
+int count(char c, char *str, int len);
+
      +
      + +

      +When a multi-argument typemap is defined, the arguments are always handled as a single +Python object. This allows the function to be used like this (notice how the length +parameter is omitted): +

      + +
      +
      +>>> example.count('e','Hello World')
+1
+>>>
+
      +
      + +

      31.8.2 Python typemaps

      + + +

      +The previous section illustrated an "in" typemap for converting Python objects to C. +A variety of different typemap methods are defined by the Python module. For example, +to convert a C integer back into a Python object, you might define an "out" typemap +like this: +

      + +
      +
      +%typemap(out) int {
+    $result = PyInt_FromLong((long) $1);
+}
+
      +
      + +

      +A detailed list of available methods can be found in the "Typemaps" chapter. +

      + +

      +However, the best source of typemap information (and examples) is +probably the Python module itself. In fact, all of SWIG's default +type handling is defined by typemaps. You can view these typemaps by +looking at the files in the SWIG library. Just take into account that +in the latest versions of swig (1.3.22+), the library files are not +very pristine clear for the casual reader, as they used to be. The +extensive use of macros and other ugly techniques in the latest +version produce a very powerful and consistent python typemap library, +but at the cost of simplicity and pedagogic value. +

      + +

      +To learn how to write a simple or your first typemap, you better take +a look at the SWIG library version 1.3.20 or so. +

      + + +

      31.8.3 Typemap variables

      + + +

      +Within typemap code, a number of special variables prefaced with a $ may appear. +A full list of variables can be found in the "Typemaps" chapter. +This is a list of the most common variables: +

      + +

      +$1 +

      + +
      +A C local variable corresponding to the actual type specified in the +%typemap directive. For input values, this is a C local variable +that's supposed to hold an argument value. For output values, this is +the raw result that's supposed to be returned to Python. +
      + +

      +$input +

      + +
      + A PyObject * holding a raw Python object with an argument or variable value. +
      + +

      +$result +

      + +
      +A PyObject * that holds the result to be returned to Python. +
      + +

      +$1_name +

      + +
      +The parameter name that was matched. +
      + +

      +$1_type +

      + +
      +The actual C datatype matched by the typemap. +
      + +

      +$1_ltype +

      + +
      +An assignable version of the datatype matched by the typemap (a type that can appear on the left-hand-side of +a C assignment operation). This type is stripped of qualifiers and may be an altered version of $1_type. +All arguments and local variables in wrapper functions are declared using this type so that their values can be +properly assigned. +
      + +

      +$symname +

      + +
      +The Python name of the wrapper function being created. +
      + +

      31.8.4 Useful Python Functions

      + + +

      +When you write a typemap, you usually have to work directly with Python objects. +The following functions may prove to be useful. +

      + +

      +Python Integer Functions +

      + +
      +
      +PyObject *PyInt_FromLong(long l);
+long      PyInt_AsLong(PyObject *);
+int       PyInt_Check(PyObject *);
+
      +
      + +

      +Python Floating Point Functions +

      + +
      +
      +PyObject *PyFloat_FromDouble(double);
+double    PyFloat_AsDouble(PyObject *);
+int       PyFloat_Check(PyObject *);
+
      +
      + +

      +Python String Functions +

      + +
      +
      +PyObject *PyString_FromString(char *);
+PyObject *PyString_FromStringAndSize(char *, lint len);
+int       PyString_Size(PyObject *);
+char     *PyString_AsString(PyObject *);
+int       PyString_Check(PyObject *);
+
      +
      + +

      +Python List Functions +

      + +
      +
      +PyObject *PyList_New(int size);
+int       PyList_Size(PyObject *list);
+PyObject *PyList_GetItem(PyObject *list, int i);
+int       PyList_SetItem(PyObject *list, int i, PyObject *item);
+int       PyList_Insert(PyObject *list, int i, PyObject *item);
+int       PyList_Append(PyObject *list, PyObject *item);
+PyObject *PyList_GetSlice(PyObject *list, int i, int j);
+int       PyList_SetSlice(PyObject *list, int i, int , PyObject *list2);
+int       PyList_Sort(PyObject *list);
+int       PyList_Reverse(PyObject *list);
+PyObject *PyList_AsTuple(PyObject *list);
+int       PyList_Check(PyObject *);
+
      +
      + +

      +Python Tuple Functions +

      + +
      +
      +PyObject *PyTuple_New(int size);
+int       PyTuple_Size(PyObject *);
+PyObject *PyTuple_GetItem(PyObject *, int i);
+int       PyTuple_SetItem(PyObject *, int i, PyObject *item);
+PyObject *PyTuple_GetSlice(PyObject *t, int i, int j);
+int       PyTuple_Check(PyObject *);
+
      +
      + +

      +Python Dictionary Functions +

      + +
      +
      +PyObject *PyDict_New();
+int       PyDict_Check(PyObject *);
+int       PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val);
+int       PyDict_SetItemString(PyObject *p, const char *key, PyObject *val);
+int       PyDict_DelItem(PyObject *p, PyObject *key);
+int       PyDict_DelItemString(PyObject *p, char *key);
+PyObject* PyDict_Keys(PyObject *p);
+PyObject* PyDict_Values(PyObject *p);
+PyObject* PyDict_GetItem(PyObject *p, PyObject *key);
+PyObject* PyDict_GetItemString(PyObject *p, const char *key);
+int       PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue);
+Py_ssize_t PyDict_Size(PyObject *p);
+int       PyDict_Update(PyObject *a, PyObject *b);
+int       PyDict_Merge(PyObject *a, PyObject *b, int override);
+PyObject* PyDict_Items(PyObject *p);
+
      +
      + +

      +Python File Conversion Functions +

      + +
      +
      +PyObject *PyFile_FromFile(FILE *f);
+FILE     *PyFile_AsFile(PyObject *);
+int       PyFile_Check(PyObject *);
+
      +
      + +

      +Abstract Object Interface +

      + +
      +
      +write me
+
      +
      + +

      31.9 Typemap Examples

      + + +

      +This section includes a few examples of typemaps. For more examples, you +might look at the files "python.swg" and "typemaps.i" in +the SWIG library. +

      + +

      31.9.1 Converting Python list to a char **

      + + +

      +A common problem in many C programs is the processing of command line +arguments, which are usually passed in an array of NULL terminated +strings. The following SWIG interface file allows a Python list +object to be used as a char ** object. +

      + +
      +%module argv
+
+// This tells SWIG to treat char ** as a special case
+%typemap(in) char ** {
+  /* Check if is a list */
+  if (PyList_Check($input)) {
+    int size = PyList_Size($input);
+    int i = 0;
+    $1 = (char **) malloc((size+1)*sizeof(char *));
+    for (i = 0; i < size; i++) {
+      PyObject *o = PyList_GetItem($input,i);
+      if (PyString_Check(o))
+	$1[i] = PyString_AsString(PyList_GetItem($input,i));
+      else {
+	PyErr_SetString(PyExc_TypeError,"list must contain strings");
+	free($1);
+	return NULL;
+      }
+    }
+    $1[i] = 0;
+  } else {
+    PyErr_SetString(PyExc_TypeError,"not a list");
+    return NULL;
+  }
+}
+
+// This cleans up the char ** array we malloc'd before the function call
+%typemap(freearg) char ** {
+  free((char *) $1);
+}
+
+// Now a test function
+%inline %{
+int print_args(char **argv) {
+    int i = 0;
+    while (argv[i]) {
+         printf("argv[%d] = %s\n", i,argv[i]);
+         i++;
+    }
+    return i;
+}
+%}
+
+
      + +

      +When this module is compiled, the wrapped C function now operates as +follows : +

      + +
      +>>> from argv import *
+>>> print_args(["Dave","Mike","Mary","Jane","John"])
+argv[0] = Dave
+argv[1] = Mike
+argv[2] = Mary
+argv[3] = Jane
+argv[4] = John
+5
+
      + +

      +In the example, two different typemaps are used. The "in" typemap is +used to receive an input argument and convert it to a C array. Since dynamic +memory allocation is used to allocate memory for the array, the +"freearg" typemap is used to later release this memory after the execution of +the C function. +

      + +

      31.9.2 Expanding a Python object into multiple arguments

      + + +

      +Suppose that you had a collection of C functions with arguments +such as the following: +

      + +
      +
      +int foo(int argc, char **argv);
+
      +
      + +

      +In the previous example, a typemap was written to pass a Python list as the char **argv. This +allows the function to be used from Python as follows: +

      + +
      +
      +>>> foo(4, ["foo","bar","spam","1"])
+
      +
      + +

      +Although this works, it's a little awkward to specify the argument count. To fix this, a multi-argument +typemap can be defined. This is not very difficult--you only have to make slight modifications to the +previous example: +

      + +
      +
      +%typemap(in) (int argc, char **argv) {
+  /* Check if is a list */
+  if (PyList_Check($input)) {
+    int i;
+    $1 = PyList_Size($input);
+    $2 = (char **) malloc(($1+1)*sizeof(char *));
+    for (i = 0; i < $1; i++) {
+      PyObject *o = PyList_GetItem($input,i);
+      if (PyString_Check(o))
+	$2[i] = PyString_AsString(PyList_GetItem($input,i));
+      else {
+	PyErr_SetString(PyExc_TypeError,"list must contain strings");
+	free($2);
+	return NULL;
+      }
+    }
+    $2[i] = 0;
+  } else {
+    PyErr_SetString(PyExc_TypeError,"not a list");
+    return NULL;
+  }
+}
+
+%typemap(freearg) (int argc, char **argv) {
+  free((char *) $2);
+}
+
      +
      + +

      +When writing a multiple-argument typemap, each of the types is referenced by a variable such +as $1 or $2. The typemap code simply fills in the appropriate values from +the supplied Python object. +

      + +

      +With the above typemap in place, you will find it no longer necessary +to supply the argument count. This is automatically set by the typemap code. For example: +

      + +
      +
      +>>> foo(["foo","bar","spam","1"])
+
      +
      + +

      31.9.3 Using typemaps to return arguments

      + + +

      +A common problem in some C programs is that values may be returned in +arguments rather than in the return value of a function. For example: +

      + +
      +/* Returns a status value and two values in out1 and out2 */
+int spam(double a, double b, double *out1, double *out2) {
+	... Do a bunch of stuff ...
+	*out1 = result1;
+	*out2 = result2;
+	return status;
+};
+
+
      + +

      +A typemap can be used to handle this case as follows : +

      + +
      +%module outarg
+
+// This tells SWIG to treat an double * argument with name 'OutValue' as
+// an output value.  We'll append the value to the current result which 
+// is guaranteed to be a List object by SWIG.
+
+%typemap(argout) double *OutValue {
+    PyObject *o, *o2, *o3;
+    o = PyFloat_FromDouble(*$1);
+    if ((!$result) || ($result == Py_None)) {
+        $result = o;
+    } else {
+        if (!PyTuple_Check($result)) {
+            PyObject *o2 = $result;
+            $result = PyTuple_New(1);
+            PyTuple_SetItem(target,0,o2);
+        }
+        o3 = PyTuple_New(1);
+        PyTuple_SetItem(o3,0,o);
+        o2 = $result;
+        $result = PySequence_Concat(o2,o3);
+        Py_DECREF(o2);
+        Py_DECREF(o3);
+    }
+}
+
+int spam(double a, double b, double *OutValue, double *OutValue);
+
+
      + +

      +The typemap works as follows. First, a check is made to see if any previous result +exists. If so, it is turned into a tuple and the new output value is concatenated to it. +Otherwise, the result is returned normally. For the sample function spam(), there +are three output values--meaning that the function will return a 3-tuple of the results. +

      + +

      +As written, the function must accept 4 arguments as input values, +last two being pointers to doubles. If these arguments are only used to hold output values (and have +no meaningful input value), an additional typemap can be written. For example: +

      + +
      +%typemap(in,numinputs=0) double *OutValue(double temp) {
+    $1 = &temp;
+}
+
+
      + +

      +By specifying numinputs=0, the input value is ignored. However, since the argument still has to be set to +some meaningful value before calling C, it is set to point to a local variable temp. When the function +stores its output value, it will simply be placed in this local variable. As a result, the +function can now be used as follows: +

      + +
      +>>> a = spam(4,5)
+>>> print a
+(0, 2.45, 5.0)
+>>> x,y,z = spam(4,5)
+>>>
+
      + +

      31.9.4 Mapping Python tuples into small arrays

      + + +

      +In some applications, it is sometimes desirable to pass small arrays +of numbers as arguments. For example : +

      + +
      +extern void set_direction(double a[4]);       // Set direction vector
+
      + +

      +This too, can be handled used typemaps as follows : +

      + +
      +// Grab a 4 element array as a Python 4-tuple
+%typemap(in) double[4](double temp[4]) {   // temp[4] becomes a local variable
+  int i;
+  if (PyTuple_Check($input)) {
+    if (!PyArg_ParseTuple($input,"dddd",temp,temp+1,temp+2,temp+3)) {
+      PyErr_SetString(PyExc_TypeError,"tuple must have 4 elements");
+      return NULL;
+    }
+    $1 = &temp[0];
+  } else {
+    PyErr_SetString(PyExc_TypeError,"expected a tuple.");
+    return NULL;
+  }
+}
+
+
      + +

      +This allows our set_direction function to be called from +Python as follows : +

      + +
      +>>> set_direction((0.5,0.0,1.0,-0.25))
+
      + +

      +Since our mapping copies the contents of a Python tuple into a C +array, such an approach would not be recommended for huge arrays, but +for small structures, this approach works fine. +

      + +

      31.9.5 Mapping sequences to C arrays

      + + +

      +Suppose that you wanted to generalize the previous example to handle C +arrays of different sizes. To do this, you might write a typemap as follows: +

      + +
      +// Map a Python sequence into any sized C double array
+%typemap(in) double[ANY](double temp[$1_dim0]) {
+  int i;
+  if (!PySequence_Check($input)) {
+      PyErr_SetString(PyExc_TypeError,"Expecting a sequence");
+      return NULL;
+  }
+  if (PyObject_Length($input) != $1_dim0) {
+      PyErr_SetString(PyExc_ValueError,"Expecting a sequence with $1_dim0 elements");
+      return NULL;
+  }
+  for (i =0; i < $1_dim0; i++) {
+      PyObject *o = PySequence_GetItem($input,i);
+      if (!PyFloat_Check(o)) {
+         Py_XDECREF(o);
+         PyErr_SetString(PyExc_ValueError,"Expecting a sequence of floats");
+         return NULL;
+      }
+      temp[i] = PyFloat_AsDouble(o);
+      Py_DECREF(o);
+  }
+  $1 = &temp[0];
+}
+
      +
      + +

      +In this case, the variable $1_dim0 is expanded to match the +array dimensions actually used in the C code. This allows the typemap +to be applied to types such as: +

      + +
      +
      +void foo(double x[10]);
+void bar(double a[4], double b[8]);
+
      +
      + +

      +Since the above typemap code gets inserted into every wrapper function where used, it might make sense +to use a helper function instead. This will greatly reduce the amount of wrapper code. For example: +

      + +
      +
      +%{
+static int convert_darray(PyObject *input, double *ptr, int size) {
+  int i;
+  if (!PySequence_Check(input)) {
+      PyErr_SetString(PyExc_TypeError,"Expecting a sequence");
+      return 0;
+  }
+  if (PyObject_Length(input) != size) {
+      PyErr_SetString(PyExc_ValueError,"Sequence size mismatch");
+      return 0;
+  }
+  for (i =0; i < size; i++) {
+      PyObject *o = PySequence_GetItem(input,i);
+      if (!PyFloat_Check(o)) {
+         Py_XDECREF(o);
+         PyErr_SetString(PyExc_ValueError,"Expecting a sequence of floats");
+         return 0;
+      }
+      ptr[i] = PyFloat_AsDouble(o);
+      Py_DECREF(o);
+  }
+  return 1;
+}
+%}
+
+%typemap(in) double [ANY](double temp[$1_dim0]) {
+   if (!convert_darray($input,temp,$1_dim0))) {
+      return NULL;
+   }
+   $1 = &temp[0];
+}
+
      +
      + +

      31.9.6 Pointer handling

      + + +

      +Occasionally, it might be necessary to convert pointer values that have +been stored using the SWIG typed-pointer representation. Since there are +several ways in which pointers can be represented, the following two +functions are used to safely perform this conversion: +

      + +

      + +int SWIG_ConvertPtr(PyObject *obj, void **ptr, swig_type_info *ty, int flags) +

      + +
      +Converts a Python object obj to a C pointer. The result of the conversion is placed +into the pointer located at ptr. ty is a SWIG type descriptor structure. +flags is used to handle error checking and other aspects of conversion. It is the +bitwise-or of several flag values including SWIG_POINTER_EXCEPTION and +SWIG_POINTER_DISOWN. The first flag makes the function raise an exception on type +error. The second flag additionally +steals ownership of an object. Returns 0 on success and -1 on error. +
      + +

      + +PyObject *SWIG_NewPointerObj(void *ptr, swig_type_info *ty, int own) +

      + +
      +Creates a new Python pointer object. ptr is the pointer to convert, ty is the SWIG type descriptor structure that +describes the type, and own is a flag that indicates whether or not Python should take ownership of the +pointer. +
      + +

      +Both of these functions require the use of a special SWIG +type-descriptor structure. This structure contains information about +the mangled name of the datatype, type-equivalence information, as +well as information about converting pointer values under C++ +inheritance. For a type of Foo *, the type descriptor structure +is usually accessed as follows: +

      + +
      +
      +Foo *f;
+if (SWIG_ConvertPtr($input, (void **) &f, SWIGTYPE_p_Foo, SWIG_POINTER_EXCEPTION) == -1)
+  return NULL;
+
+PyObject *obj;
+obj = SWIG_NewPointerObj(f, SWIGTYPE_p_Foo, 0);
+
      +
      + +

      +In a typemap, the type descriptor should always be accessed using the special typemap +variable $1_descriptor. For example: +

      + +
      +
      +%typemap(in) Foo * {
+if ((SWIG_ConvertPtr($input,(void **) &$1, $1_descriptor,SWIG_POINTER_EXCEPTION)) == -1)
+  return NULL;
+}
+
      +
      + +

      +If necessary, the descriptor for any type can be obtained using the $descriptor() macro in a typemap. +For example: +

      + +
      +
      +%typemap(in) Foo * {
+if ((SWIG_ConvertPtr($input,(void **) &$1, $descriptor(Foo *), 
+                                               SWIG_POINTER_EXCEPTION)) == -1)
+  return NULL;
+}
+
      +
      + +

      +Although the pointer handling functions are primarily intended for +manipulating low-level pointers, both functions are fully aware of +Python proxy classes. Specifically, +SWIG_ConvertPtr() will retrieve a pointer from any object +that has a this attribute. In addition, +SWIG_NewPointerObj() can automatically generate a proxy +class object (if applicable). +

      + + + +

      31.10 Docstring Features

      + + +

      +Using docstrings in Python code is becoming more and more important +and more tools are coming on the scene that take advantage of them, +everything from full-blown documentation generators to class browsers +and popup call-tips in Python-aware IDEs. Given the way that SWIG +generates the proxy code by default, your users will normally get +something like "function_name(*args)" in the popup calltip of +their IDE which is next to useless when the real function prototype +might be something like this: +

      + +
      +
      +bool function_name(int x, int y, Foo* foo=NULL, Bar* bar=NULL);
+
      +
      + +

      +The features described in this section make it easy for you to add +docstrings to your modules, functions and methods that can then be +used by the various tools out there to make the programming experience +of your users much simpler. +

      + + +

      31.10.1 Module docstring

      + + +

      +Python allows a docstring at the beginning of the .py file +before any other statements, and it is typically used to give a +general description of the entire module. SWIG supports this by +setting an option of the %module directive. For example: +

      + +
      +
      +%module(docstring="This is the example module's docstring") example
+
      +
      + +

      +When you have more than just a line or so then you can retain the easy +readability of the %module directive by using a macro. For +example: +

      + +
      +
      +%define DOCSTRING
+"The `XmlResource` class allows program resources defining menus, 
+layout of controls on a panel, etc. to be loaded from an XML file."
+%enddef
+
+%module(docstring=DOCSTRING) xrc
+
      +
      + + +

      31.10.2 %feature("autodoc")

      + + +

      +As alluded to above SWIG will generate all the function and method +proxy wrappers with just "*args" (or "*args, **kwargs" if the -keyword +option is used) for a parameter list and will then sort out the +individual parameters in the C wrapper code. This is nice and simple +for the wrapper code, but makes it difficult to be programmer and tool +friendly as anyone looking at the .py file will not be able +to find out anything about the parameters that the functions accept. +

      + +

      But since SWIG does know everything about the function it is +possible to generate a docstring containing the parameter types, names +and default values. Since many of the docstring tools are adopting a +standard of recognizing if the first thing in the docstring is a +function prototype then using that instead of what they found from +introspection, then life is good once more. + +

      SWIG's Python module provides support for the "autodoc" feature, +which when attached to a node in the parse tree will cause a docstring +to be generated that includes the name of the function, parameter +names, default values if any, and return type if any. There are also +three options for autodoc controlled by the value given to the +feature, described below. + +

      31.10.2.1 %feature("autodoc", "0")

      + + +

      +When the "0" option is given then the types of the parameters will +not be included in the autodoc string. For example, given +this function prototype: +

      + +
      +
      +%feature("autodoc", "0");
+bool function_name(int x, int y, Foo* foo=NULL, Bar* bar=NULL);
+
      +
      + +

      +Then Python code like this will be generated: +

      + +
      +
      +def function_name(*args, **kwargs):
+    """function_name(x, y, foo=None, bar=None) -> bool"""
+    ...
+
      +
      + + +

      31.10.2.2 %feature("autodoc", "1")

      + + +

      +When the "1" option is used then the parameter types will be +used in the autodoc string. In addition, an attempt is made to +simplify the type name such that it makes more sense to the Python +user. Pointer, reference and const info is removed, +%rename's are evaluated, etc. (This is not always +successful, but works most of the time. See the next section for what +to do when it doesn't.) Given the example above, then turning on the +parameter types with the "1" option will result in Python code like +this: +

      + +
      +
      +def function_name(*args, **kwargs):
+    """function_name(int x, int y, Foo foo=None, Bar bar=None) -> bool"""
+    ...
+
      +
      + + + +

      31.10.2.3 %feature("autodoc", "docstring")

      + + +

      +Finally, there are times when the automatically generated autodoc +string will make no sense for a Python programmer, particularly when a +typemap is involved. So if you give an explicit value for the autodoc +feature then that string will be used in place of the automatically +generated string. For example: +

      + +
      +
      +%feature("autodoc", "GetPosition() -> (x, y)") GetPosition;
+void GetPosition(int* OUTPUT, int* OUTPUT);
+
      +
      + + +

      31.10.3 %feature("docstring")

      + + +

      +In addition to the autodoc strings described above, you can also +attach any arbitrary descriptive text to a node in the parse tree with +the "docstring" feature. When the proxy module is generated then any +docstring associated with classes, function or methods are output. +If an item already has an autodoc string then it is combined with the +docstring and they are output together. If the docstring is all on a +single line then it is output like this:: +

      + +
      +
      +"""This is the docstring"""
+
      +
      + +

      +Otherwise, to aid readability it is output like this: +

      + +
      +
      +"""
+This is a multi-line docstring
+with more than one line.
+"""
+
      +
      + +

      31.11 Python Packages

      + + +

      +Using the package option of the %module directive +allows you to specify what Python package that the module will be +living in when installed. +

      + +
      +
      +%module(package="wx") xrc
+
      +
      + +

      +This is useful when the .i file is %imported by +another .i file. By default SWIG will assume that the +importer is able to find the importee with just the module name, but +if they live in separate Python packages then that won't work. +However if the importee specifies what its package is with the +%module option then the Python code generated for the +importer will use that package name when importing the other module +and also in base class declarations, etc. if the package name is +different than its own. +

      + +

      31.12 Python 3 Support

      + + +

      +SWIG is able to support Python 3.0. The wrapper code generated by +SWIG can be compiled with both Python 2.x or 3.0. Further more, by +passing the -py3 command line option to SWIG, wrapper code +with some Python 3 specific features can be generated (see below +subsections for details of these features). The -py3 option also +disables some incompatible features for Python 3, such as +-classic. + +

      +There is a list of known-to-be-broken features in Python 3: +

      +
        +
      • No more support for FILE* typemaps, because PyFile_AsFile has been dropped + in Python 3.
        • +
      • The -apply command line option is removed and generating + code using apply() is no longer supported.
        • +
      + +

      +The following are Python 3.0 new features that are currently supported by +SWIG. +

      + +

      31.12.1 Function annotation

      + + +

      +The -py3 option will enable function annotation support. When used +SWIG is able to generate proxy method definitions like this: +

      + +
      +  def foo(self, bar : "int" = 0) -> "void" : ...
+
      + +

      +Also, even if without passing SWIG the -py3 option, the parameter list +still could be generated: +

      + +
      +  def foo(self, bar = 0): ...
+
      + +

      +But for overloaded function or method, the parameter list would fallback to +*args or self, *args, and **kwargs may be append +depend on whether you enabled the keyword argument. This fallback is due to +all overloaded functions share the same function in SWIG generated proxy class. +

      + +

      +For detailed usage of function annotation, see PEP 3107. +

      + +

      31.12.2 Buffer interface

      + + +

      +Buffer protocols were revised in Python 3. SWIG also gains a series of +new typemaps to support buffer interfaces. These typemap macros are +defined in pybuffer.i, which must be included in order to use them. +By using these typemaps, your wrapped function will be able to +accept any Python object that exposes a suitable buffer interface. +

      + +

      +For example, the get_path() function puts the path string +into the memory pointed to by its argument: +

      + +
      +void get_path(char *s);
+
      + +

      +Then you can write a typemap like this: (the following example is +applied to both Python 3.0 and 2.6, since the bytearray type +is backported to 2.6. +

      + + +
      +%include <pybuffer.i>
+%pybuffer_mutable_string(char *str);
+void get_path(char *s);
+
      + +

      +And then on the Python side the wrapped get_path could be used in this +way: +

      + +
      +>>> p = bytearray(10)
+>>> get_path(p)
+>>> print(p)
+bytearray(b'/Foo/Bar/\x00')
+
      + +

      +The macros defined in pybuffer.i are similar to those in +cstring.i: +

      + +

      +%pybuffer_mutable_binary(parm, size_parm) +

      + +
      + +

      +The macro can be used to generate a typemap which maps a buffer of an +object to a pointer provided by parm and a size argument +provided by size_parm. For example: +

      + +
      +%pybuffer_mutable_binary(char *str, size_t size);
+...
+int snprintf(char *str, size_t size, const char *format, ...);
+
      + +

      +In Python: +

      + +
      +>>> buf = bytearray(6)
+>>> snprintf(buf, "Hello world!")
+>>> print(buf)
+bytearray(b'Hello\x00')
+>>> 
+
      + +
      + +

      +%pybuffer_mutable_string(parm) +

      + +
      + +

      +This typemap macro requires the buffer to be a zero terminated string, +and maps the pointer of the buffer to parm. For example: +

      + +
      +%pybuffer_mutable_string(char *str);
+...
+size_t make_upper(char *str);
+
      + +

      +In Python: +

      + +
      +>>> buf = bytearray(b'foo\x00')
+>>> make_upper(buf)
+>>> print(buf)
+bytearray(b'FOO\x00')
+>>>
+
      + +

      +Both %pybuffer_mutable_binary and %pybuffer_mutable_string +require the provided buffer to be mutable, eg. they can accept a +bytearray type but can't accept an immutable byte +type. +

      + +
      + +

      +%pybuffer_binary(parm, size_parm) +

      + +
      + +

      +This macro maps an object's buffer to a pointer parm and a +size size_parm. It is similar to +%pybuffer_mutable_binary, except the +%pybuffer_binary an accept both mutable and immutable +buffers. As a result, the wrapped function should not modify the buffer. +

      + +
      + +

      +%pybuffer_string(parm) +

      + +
      + +

      +This macro maps an object's buffer as a string pointer parm. +It is similar to %pybuffer_mutable_string but the buffer +could be both mutable and immutable. And your function should not +modify the buffer. +

      + +
      + + +

      31.12.3 Abstract base classes

      + + +

      +By including pyabc.i and using the -py3 command +line option when calling SWIG, the proxy classes of the STL containers +will automatically gain an appropriate abstract base class. For +example, the following SWIG interface: +

      + +
      +%include <pyabc.i>
+%include <std_map.i>
+%include <std_list.i>
+
+namespace std {
+  %template(Mapii) map<int, int>;
+  %template(IntList) list<int>;
+}
+
      + +

      +will generate a Python proxy class Mapii inheriting from +collections.MutableMap and a proxy class IntList +inheriting from collections.MutableSequence. +

      + +

      +pyabc.i also provides a macro %pythonabc that could be +used to define an abstract base class for your own C++ class: +

      + +
      +%pythonabc(MySet, collections.MutableSet);
+
      + +

      +For details of abstract base class, please see PEP 3119. +

      + + + + + + + + diff --git a/Doc/Manual/R.html b/Doc/Manual/R.html new file mode 100644 index 0000000..0ed43fc --- /dev/null +++ b/Doc/Manual/R.html @@ -0,0 +1,160 @@ + + + +SWIG and R + + + + +

      34 SWIG and R

      + +
      + +
      + + + + +

      +R is a GPL'ed open source statistical and plotting environment. +Information about R can be found at www.r-project.org. + +The R bindings are under active development. They have been used to +compile and run an R interface to QuantLib running on Mandriva Linux +with gcc. The R bindings also work on Microsoft Windows using Visual C++. +

      + +

      34.1 Bugs

      + + +

      +Currently the following features are not implemented or broken: +

      + +
        +
      • Garbage collection of created objects +
      • C Array wrappings +
      + +

      34.2 Using R and SWIG

      + + +

      +To use R and SWIG in C mode, execute the following commands where +example.c is the name of the file with the functions in them +

      + +
      +
      +swig -r example.i
+PKG_LIBS="example.c" R CMD SHLIB example_wrap.c
+
      +
      + +

      +The corresponding comments for C++ mode are +

      + +
      +
      +swig -c++ -r -o example_wrap.cpp example.i
+PKG_LIBS="example.cxx" R CMD SHLIB example_wrap.cpp
+
      +
      + +

      +Note that R is sensitive to the name of the file and to the file +extension in C and C++ mode. The name of the wrapper file must be the +name of the library. Also in C++ mode, the file extension must be .cpp +rather than .cxx for the R compile command to recognize it. +

      + +

      +The commands produces two files. A dynamic shared object file called +example.so, or example.dll, and an R wrapper file called example.R. To load these +files, start up R and type in the following commands +

      + +
      +
      +dyn.load(paste("example", .Platform$dynlib.ext, sep=""))
+source("example.R")
+cacheMetaData(1)
+
      +
      + +The cacheMetaData(1) will cause R to refresh its object tables. +Without it, inheritance of wrapped objects may fail. + +

      +These two files can be loaded in any order +

      + +

      34.3 Precompiling large R files

      + + +In cases where the R file is large, one make save a lot of loading +time by precompiling the R wrapper. This can be done by creating the +file makeRData.R which contains the following + +
      +source('BigFile.R')
+save(list=ls(all=TRUE),file="BigFile.RData", compress=TRUE)
+q(save="no")
+
      + +This will generate a compiled R file called BigFile.RData that +will save a large amount of loading time. + + + +

      34.4 General policy

      + + +

      +The general policy of the module is to treat the C/C++ as a basic +wrapping over the underlying functions and rely on the R type system +to provide R syntax. +

      + +

      34.5 Language conventions

      + + +

      +getitem and setitem use C++ conventions (i.e. zero based indices). [<- +and [ are overloaded to allow for R syntax (one based indices and +slices) +

      + +

      34.6 C++ classes

      + + +

      +C++ objects are implemented as external pointer objects with the class +being the mangled name of the class. The C++ classes are encapsulated +as an SEXP with an external pointer type. The class is the mangled +name of the class. The nice thing about R is that is allows you to +keep track of the pointer object which removes the necessity for a lot +of the proxy class baggage you see in other languages. +

      + +

      34.7 Enumerations

      + + +

      +enumerations are characters which are then converted back and forth to +ints before calling the C routines. All of the enumeration code is +done in R. +

      + + + diff --git a/Doc/Manual/README b/Doc/Manual/README new file mode 100644 index 0000000..f01013d --- /dev/null +++ b/Doc/Manual/README @@ -0,0 +1,21 @@ +This directory contains the HTML for the SWIG users manual. + +All of this HTML is hand-written. However, section numbering, indices, +and the table of contents is generated automatically by the 'maketoc.py' +script. The Makefile has further information on how the various alternative +forms of the documentation is generated from the hand-written HTML. + +There are 4 types of boxes that code or whatever can be inside: + -
      ...
      + This is for text that shows the output of running commands on the shell. + -
      ...
      + This is for either C, C++, or SWIG code + -
      ...
      + This is for code in a target scripting language + -
      ...
      + This is for text that is not code or a shell + +The general format is +
      +whatever here
+
      diff --git a/Doc/Manual/Ruby.html b/Doc/Manual/Ruby.html new file mode 100644 index 0000000..98fa315 --- /dev/null +++ b/Doc/Manual/Ruby.html @@ -0,0 +1,10745 @@ + + + + + + + + + + + + + + + + + + SWIG and Ruby + + + + + + + + + + +

      32 SWIG and Ruby

      + +
      + +
      + + + + +

      This chapter describes SWIG's support of Ruby.

      + + + + + +

      32.1 Preliminaries

      + + +

      SWIG 1.3 is known to work with Ruby versions 1.6 and later. +Given the choice, you should use the latest stable version of Ruby. You +should also determine if your system supports shared libraries and +dynamic loading. SWIG will work with or without dynamic loading, but +the compilation process will vary.

      + + + + + +

      This chapter covers most SWIG features, but in less depth than +is found in earlier chapters. At the very least, make sure you also +read the "SWIG Basics" +chapter. It is also assumed that the reader has a basic understanding +of Ruby.

      + + + + + +

      32.1.1 Running SWIG

      + + +

      To build a Ruby module, run SWIG using the -ruby +option:

      + + + + + +
      +
      $ swig -ruby example.i
+
      + + + + + +
      + + + + + +

      If building a C++ extension, add the -c++ +option:

      + + + + + +
      +
      $ swig -c++ -ruby example.i
+
      + + + + + +
      + + + + + +

      This creates a file example_wrap.c (example_wrap.cxx +if compiling a C++ extension) that contains all of the code needed to +build a Ruby extension module. To finish building the module, you need +to compile this file and link it with the rest of your program.

      + + + + + +

      32.1.2 Getting the right header files

      + + +

      In order to compile the wrapper code, the compiler needs the ruby.h +header file. This file is usually contained in a directory such as

      + + + + + +
      +
      /usr/lib/ruby/1.8/x86_64-linux-gnu/ruby.h
      /usr/local/lib/ruby/1.6/i686-linux/ruby.h
      + + + + + +
      + + + + + +

      The exact location may vary on your machine, but the above +location is typical. If you are not entirely sure where Ruby is +installed, you can run Ruby to find out. For example:

      + + + + + +
      +
      $ ruby -e 'puts $:.join("\n")'
      /usr/local/lib/ruby/site_ruby/1.6 /usr/local/lib/ruby/site_ruby/1.6/i686-linux
      /usr/local/lib/ruby/site_ruby /usr/local/lib/ruby/1.6 /usr/local/lib/ruby/1.6/i686-linux .
      + + + + + +
      + + + + + +

      32.1.3 Compiling a dynamic module

      + + +

      Ruby extension modules are typically compiled into shared +libraries that the interpreter loads dynamically at runtime. Since the +exact commands for doing this vary from platform to platform, your best +bet is to follow the steps described in the README.EXT +file from the Ruby distribution:

      + + + + + +
        + + + + + +
      1. + + + + +

        Create a file called extconf.rb that +looks like the following:

        + + + + + + + + + +
        + + + + + 
        require 'mkmf'
        create_makefile('example')
        + + + + + +
        + + + + + +
        2. + + + + + +
      2. + + + + +

        Type the following to build the extension:

        + + + + + + + + + +
        + + + + + 
        $ ruby extconf.rb
        $ make
        $ make install
+
        + + + + + +
        + + + + + +
        3. + + + + + +
      + + + + + +

      Of course, there is the problem that mkmf does not work +correctly on all platforms, e.g, HPUX. If you need to add your own make +rules to the file that extconf.rb produces, you +can add this:

      + + + + + +
      +
      open("Makefile", "a") { |mf|
       puts <<EOM
       # Your make rules go here
       EOM
      }
      + + + + + +
      + + + + + +

      to the end of the extconf.rb file. If +for some reason you don't want to use the standard approach, you'll +need to determine the correct compiler and linker flags for your build +platform. For example, a typical sequence of commands for the Linux +operating system would look something like this:

      + + + + + +
      +
      $ swig -ruby example.i
      $ gcc -c example.c
      $ gcc -c example_wrap.c -I/usr/local/lib/ruby/1.6/i686-linux 
      $ gcc -shared example.o example_wrap.o -o example.so
+
      + + + + + +
      + + + + + +

      For other platforms it may be necessary to compile with the -fPIC +option to generate position-independent code. If in doubt, consult the +manual pages for your compiler and linker to determine the correct set +of options. You might also check the SWIG Wiki +for additional information.

      + +

      32.1.4 Using your module

      + + +

      Ruby module names must be capitalized, +but the convention for Ruby feature names is to use +lowercase names. So, for example, the Etc extension +module is imported by requiring the etc feature:

      + + + + + +
      +
      # The feature name begins with a lowercase letter...
      require 'etc'

      # ... but the module name begins with an uppercase letter
      puts "Your login name: #{Etc.getlogin}"
      + + + + + +
      + + + + + +

      To stay consistent with this practice, you should always +specify a lowercase module name with SWIG's %module +directive. SWIG will automatically correct the resulting Ruby module +name for your extension. So for example, a SWIG interface file that +begins with:

      + + + + + +
      +
      %module example
      + + + + + +
      + + + + + +

      will result in an extension module using the feature name +"example" and Ruby module name "Example".

      + + + + + +

      32.1.5 Static linking

      + + +

      An alternative approach to dynamic linking is to rebuild the +Ruby interpreter with your extension module added to it. In the past, +this approach was sometimes necessary due to limitations in dynamic +loading support on certain machines. However, the situation has +improved greatly over the last few years and you should not consider +this approach unless there is really no other option.

      + + + + + +

      The usual procedure for adding a new module to Ruby involves +finding the Ruby source, adding an entry to the ext/Setup +file, adding your directory to the list of extensions in the file, and +finally rebuilding Ruby.

      + + + +

      32.1.6 Compilation of C++ extensions

      + + +

      On most machines, C++ extension modules should be linked +using the C++ compiler. For example:

      + + + + + +
      +
      $ swig -c++ -ruby example.i
      $ g++ -c example.cxx
      $ g++ -c example_wrap.cxx -I/usr/local/lib/ruby/1.6/i686-linux
      $ g++ -shared example.o example_wrap.o -o example.so
+
      + + + + + +
      + + + + + +

      If you've written an extconf.rb script +to automatically generate a Makefile for your C++ +extension module, keep in mind that (as of this writing) Ruby still +uses gcc and not g++ as its +linker. As a result, the required C++ runtime library support will not +be automatically linked into your extension module and it may fail to +load on some platforms. A workaround for this problem is use the mkmf +module's append_library() method to add one of +the C++ runtime libraries to the list of libraries linked into your +extension, e.g.

      + + + + + +
      +
      require 'mkmf'
      $libs = append_library($libs, "supc++")
      create_makefile('example')
      + + + + + +
      + + + + + +

      32.2 Building Ruby Extensions under Windows 95/NT

      + + +

      Building a SWIG extension to Ruby under Windows 95/NT is +roughly similar to the process used with Unix. Normally, you will want +to produce a DLL that can be loaded into the Ruby interpreter. For all +recent versions of Ruby, the procedure described above (i.e. using an extconf.rb +script) will work with Windows as well; you should be able to build +your code into a DLL by typing:

      + + + + + +
      +
      C:\swigtest> ruby extconf.rb
      C:\swigtest> nmake
      C:\swigtest> nmake install
+
      + + + + + +
      + + + + + +

      The remainder of this section covers the process of compiling +SWIG-generated Ruby extensions with Microsoft Visual C++ 6 (i.e. within +the Developer Studio IDE, instead of using the command line tools). In +order to build extensions, you may need to download the source +distribution to the Ruby package, as you will need the Ruby header +files.

      + + + + + +

      32.2.1 Running SWIG from Developer Studio

      + + +

      If you are developing your application within Microsoft +developer studio, SWIG can be invoked as a custom build option. The +process roughly follows these steps :

      + + + + + +
        + + + + + +
      • Open up a new workspace and use the AppWizard to select a +DLL project.
        • + + + + + +
      • Add both the SWIG interface file (the .i file), any +supporting C files, and the name of the wrapper file that will be +created by SWIG (i.e. example_wrap.c). Note : If +using C++, choose a different suffix for the wrapper file such as example_wrap.cxx. +Don't worry if the wrapper file doesn't exist yet--Developer Studio +will keep a reference to it around.
        • + + + + + +
      • Select the SWIG interface file and go to the settings +menu. Under settings, select the "Custom Build" option.
        • + + + + + +
      • Enter "SWIG" in the description field.
        • + + + + + +
      • Enter "swig -ruby -o +$(ProjDir)\$(InputName)_wrap.c $(InputPath)" in the "Build +command(s) field". You may have to include the path to swig.exe.
        • + + + + + +
      • Enter "$(ProjDir)\$(InputName)_wrap.c" +in the "Output files(s) field".
        • + + + + + +
      • Next, select the settings for the entire project and go to +the C/C++ tab and select the Preprocessor category. Add NT=1 to the +Preprocessor definitions. This must be set else you will get +compilation errors. Also add IMPORT to the preprocessor definitions, +else you may get runtime errors. Also add the include directories for +your Ruby installation under "Additional include directories".
        • + + + + + +
      • Next, select the settings for the entire project and go to +the Link tab and select the General category. Set the name of the +output file to match the name of your Ruby module (i.e.. example.dll). +Next add the Ruby library file to your link libraries under +Object/Library modules. For example "mswin32-ruby16.lib. You also need +to add the path to the library under the Input tab - Additional library +path.
        • + + + + + +
      • Build your project.
        • + + + + + +
      + + + + + +

      Now, assuming all went well, SWIG will be automatically +invoked when you build your project. Any changes made to the interface +file will result in SWIG being automatically invoked to produce a new +version of the wrapper file. To run your new Ruby extension, simply run +Ruby and use the require command as normal. For +example if you have this ruby file run.rb:

      + + + + + +
      +
      # file: run.rb
      require 'Example'

      # Call a c function
      print "Foo = ", Example.Foo, "\n"
      + + + + + +
      + + + + + +

      Ensure the dll just built is in your path or current +directory, then run the Ruby script from the DOS/Command prompt:

      + + + + + +
      +
      C:\swigtest> ruby run.rb
      Foo = 3.0
      + + + + + +
      + + + + + +

      32.3 The Ruby-to-C/C++ Mapping

      + + +

      This section describes the basics of how SWIG maps C or C++ +declarations in your SWIG interface files to Ruby constructs.

      + + + + + +

      32.3.1 Modules

      + + +

      The SWIG %module directive specifies +the name of the Ruby module. If you specify:

      + + + + + +
      +
      %module example
      + + + + + +
      + + + + + +

      then everything is wrapped into a Ruby module named Example +that is nested directly under the global module. You can specify a more +deeply nested module by specifying the fully-qualified module name in +quotes, e.g.

      + + + + + +
      +
      %module "foo::bar::spam"
      + + + + + +
      + + + + + +

      An alternate method of specifying a nested module name is to +use the -prefix +option on the SWIG command line. The prefix that you specify with this +option will be prepended to the module name specified with the %module +directive in your SWIG interface file. So for example, this declaration +at the top of your SWIG interface file:
      + + + + + +

      + + + + + +
      +
      %module "foo::bar::spam"
      + + + + + +
      + + + + + +

      will result in a nested module name of Foo::Bar::Spam, +but you can achieve the same +effect by specifying:
      + + + + + +

      + + + + + +
      +
      %module spam
      + + + + + +
      + + + + + +

      and then running SWIG with the -prefix command +line option:
      + + + + + +

      + + + + + +
      +
      $ swig -ruby -prefix "foo::bar::" example.i
      + + + + + +
      + + + + + +

      Starting with SWIG 1.3.20, you can also choose to wrap +everything into the global module by specifying the -globalmodule +option on the SWIG command line, i.e.

      + + + + + +
      +
      $ swig -ruby -globalmodule example.i
      + + + + + +
      + + + + + +

      Note that this does not relieve you of the requirement of +specifying the SWIG module name with the %module +directive (or the -module command-line option) as +described earlier.

      + + + + + +

      When choosing a module name, do not use the same name as a +built-in Ruby command or standard module name, as the results may be +unpredictable. Similarly, if you're using the -globalmodule +option to wrap everything into the global module, take care that the +names of your constants, classes and methods don't conflict with any of +Ruby's built-in names.

      + + + + + +

      32.3.2 Functions

      + + +

      Global functions are wrapped as Ruby module methods. For +example, given the SWIG interface file example.i: +

      + + + + + +
      +
      %module example

      int fact(int n);
      + + + + + +
      + + + + + +

      and C source file example.c:

      + + + + + +
      +
      int fact(int n) {
       if (n == 0)
       return 1;
       return (n * fact(n-1));
      }
      + + + + + +
      + + + + + +

      SWIG will generate a method fact in the Example +module that can be used like so:

      + + + + + +
      +
      $ irb
      irb(main):001:0> require 'example'
      true
      irb(main):002:0> Example.fact(4)
      24
      + + + + + +
      + + + + + +

      32.3.3 Variable Linking

      + + +

      C/C++ global variables are wrapped as a pair of singleton +methods for the module: one to get the value of the global variable and +one to set it. For example, the following SWIG interface file declares +two global variables:

      + + + + + +
      +
      // SWIG interface file with global variables
      %module example
      ...
      %inline %{
      extern int variable1;
      extern double Variable2;
      %}
      ...
      + + + + + +
      + + + + + +

      Now look at the Ruby interface:

      + + + + + +
      +
      $ irb
      irb(main):001:0> require 'Example'
      true
      irb(main):002:0> Example.variable1 = 2
      2
      irb(main):003:0> Example.Variable2 = 4 * 10.3
      41.2
      irb(main):004:0> Example.Variable2
      41.2
      + + + + + +
      + + + + + +

      If you make an error in variable assignment, you will receive +an error message. For example:

      + + + + + +
      +
      irb(main):005:0> Example.Variable2 = "hello"
      TypeError: no implicit conversion to float from string
      from (irb):5:in `Variable2='
      from (irb):5
      + + + + + +
      + + + + + +

      If a variable is declared as const, it +is wrapped as a read-only variable. Attempts to modify its value will +result in an error.

      + + + + + +

      To make ordinary variables read-only, you can also use the %immutable +directive. For example:

      + + + + + +
      +
      %immutable;
      %inline %{
      extern char *path;
      %}
      %mutable;
      + + + + + +
      + + + + + +

      The %immutable directive stays in +effect until it is explicitly disabled using %mutable. +

      + + + + + +

      32.3.4 Constants

      + + +

      C/C++ constants are wrapped as module constants initialized +to the appropriate value. To create a constant, use #define +or the %constant directive. For example:

      + + + + + +
      +
      #define PI 3.14159
      #define VERSION "1.0"

      %constant int FOO = 42;
      %constant const char *path = "/usr/local";

      const int BAR = 32;
      + + + + + +
      + + + + + +

      Remember to use the :: operator in Ruby to get at these +constant values, e.g.

      + + + + + +
      +
      $ irb
      irb(main):001:0> require 'Example'
      true
      irb(main):002:0> Example::PI
      3.14159
      + + + + + +
      + + + + + +

      32.3.5 Pointers

      + + +

      "Opaque" pointers to arbitrary C/C++ types (i.e. types that +aren't explicitly declared in your SWIG interface file) are wrapped as +data objects. So, for example, consider a SWIG interface file +containing only the declarations:

      + + + + + +
      +
      Foo *get_foo();
      void set_foo(Foo *foo);
      + + + + + +
      + + + + + +

      For this case, the get_foo() method +returns an instance of an internally generated Ruby class:

      + + + + + +
      +
      irb(main):001:0> foo = Example::get_foo()
      #<SWIG::TYPE_p_Foo:0x402b1654>
      + + + + + +
      + + + + + +

      A NULL pointer is always represented by +the Ruby nil object.

      + + + + + +

      32.3.6 Structures

      + + +

      C/C++ structs are wrapped as Ruby classes, with accessor +methods (i.e. "getters" and "setters") for all of the struct members. +For example, this struct declaration:

      + + + + + +
      +
      struct Vector {
       double x, y;
      };
      + + + + + +
      + + + + + +

      gets wrapped as a Vector class, with +Ruby instance methods x, x=, +y and y=. These methods can +be used to access structure data from Ruby as follows:

      + + + + + +
      +
      $ irb
      irb(main):001:0> require 'Example'
      true
      irb(main):002:0> f = Example::Vector.new
      #<Example::Vector:0x4020b268>
      irb(main):003:0> f.x = 10
      nil
      irb(main):004:0> f.x
      10.0
      + + + + + +
      + + + + + +

      Similar access is provided for unions and the public data +members of C++ classes.

      + + + + + +

      const members of a structure are +read-only. Data members can also be forced to be read-only using the %immutable +directive (in C++, private may also be used). For +example:

      + + + + + +
      +
      struct Foo {
       ...
       %immutable;
       int x; /* Read-only members */
       char *name;
       %mutable;
       ...
      };
      + + + + + +
      + + + + + +

      When char * members of a structure are +wrapped, the contents are assumed to be dynamically allocated using malloc +or new (depending on whether or not SWIG is run +with the -c++ option). When the structure member +is set, the old contents will be released and a new value created. If +this is not the behavior you want, you will have to use a typemap +(described shortly).

      + + + + + +

      Array members are normally wrapped as read-only. For example, +this code:

      + + + + + +
      +
      struct Foo {
       int x[50];
      };
      + + + + + +
      + + + + + +

      produces a single accessor function like this:

      + + + + + +
      +
      int *Foo_x_get(Foo *self) {
       return self->x;
      };
      + + + + + +
      + + + + + +

      If you want to set an array member, you will need to supply a +"memberin" typemap described in the section on typemaps. +As a special case, SWIG does generate code to set array members of type +char (allowing you to store a Ruby string in the +structure).

      + + + + + +

      When structure members are wrapped, they are handled as +pointers. For example,

      + + + + + +
      +
      struct Foo {
       ...
      };

      struct Bar {
       Foo f;
      };
      + + + + + +
      + + + + + +

      generates accessor functions such as this:

      + + + + + +
      +
      Foo *Bar_f_get(Bar *b) {
       return &b->f;
      }

      void Bar_f_set(Bar *b, Foo *val) {
       b->f = *val;
      }
      + + + + + +
      + + + + + +

      32.3.7 C++ classes

      + + +

      Like structs, C++ classes are wrapped by creating a new Ruby +class of the same name with accessor methods for the public class +member data. Additionally, public member functions for the class are +wrapped as Ruby instance methods, and public static member functions +are wrapped as Ruby singleton methods. So, given the C++ class +declaration:

      + + + + + +
      +
      class List {
      public:
       List();
       ~List();
       int search(char *item);
       void insert(char *item);
       void remove(char *item);
       char *get(int n);
       int length;
       static void print(List *l);
      };
      + + + + + +
      + + + + + +

      SWIG would create a List class with:

      + + + + + +
        + + + + + +
      • instance methods search, insert, + remove, and get;
        • + + + + + +
      • instance methods length and length= +(to get and set the value of the length data +member); and,
        • + + + + + +
      • a print singleton method for the +class.
        • + + + + + +
      + + + + + +

      In Ruby, these functions are used as follows:

      + + + + + +
      +
      require 'Example'

      l = Example::List.new

      l.insert("Ale")
      l.insert("Stout")
      l.insert("Lager")
      Example.print(l)
      l.length()
      ----- produces the following output 
      Lager
      Stout
      Ale
      3
      + + + + + +
      + + + + + +

      32.3.8 C++ Inheritance

      + + +

      The SWIG type-checker is fully aware of C++ inheritance. +Therefore, if you have classes like this:

      + + + + + +
      +
      class Parent {
       ...
      };

      class Child : public Parent {
       ...
      };
      + + + + + +
      + + + + + +

      those classes are wrapped into a hierarchy of Ruby classes +that reflect the same inheritance structure. All of the usual Ruby +utility methods work normally:

      + + + + + +
      +
      irb(main):001:0> c = Child.new
      #<Bar:0x4016efd4>
      irb(main):002:0> c.instance_of? Child
      true
      irb(main):003:0> b.instance_of? Parent
      false
      irb(main):004:0> b.is_a? Child
      true
      irb(main):005:0> b.is_a? Parent
      true
      irb(main):006:0> Child < Parent
      true
      irb(main):007:0> Child > Parent
      false
      + + + + + +
      + + + + + +

      Furthermore, if you have a function like this:

      + + + + + +
      +
      void spam(Parent *f);
      + + + + + +
      + + + + + +

      then the function spam() accepts Parent* +or a pointer to any class derived from Parent.

      + + + + + +

      Until recently, the Ruby module for SWIG didn't support +multiple inheritance, and this is still the default behavior. This +doesn't mean that you can't wrap C++ classes which inherit from +multiple base classes; it simply means that only the first +base class listed in the class declaration is considered, and any +additional base classes are ignored. As an example, consider a SWIG +interface file with a declaration like this:

      + + + + + +
      +
      class Derived : public Base1, public Base2
      {
       ...
      };
      + + + + + +
      + + + + + +

      For this case, the resulting Ruby class (Derived) +will only consider Base1 as its superclass. It +won't inherit any of Base2's member functions or +data and it won't recognize Base2 as an +"ancestor" of Derived (i.e. the is_a? +relationship would fail). When SWIG processes this interface file, +you'll see a warning message like:

      + + + + + +
      +
      example.i:5: Warning(802): Warning for Derived: Base Base2 ignored.
      Multiple inheritance is not supported in Ruby.
      + + + + + +
      + + + + + +

      Starting with SWIG 1.3.20, the Ruby module for SWIG provides +limited support for multiple inheritance. Because the approach for +dealing with multiple inheritance introduces some limitations, this is +an optional feature that you can activate with the -minherit +command-line option:

      + + + + + +
      +
      $ swig -c++ -ruby -minherit example.i
      + + + + + +
      + + + + + +

      Using our previous example, if your SWIG interface file +contains a declaration like this:

      + + + + + +
      +
      class Derived : public Base1, public Base2
      {
       ...
      };
      + + + + + +
      + + + + + +

      and you run SWIG with the -minherit +command-line option, then you will end up with a Ruby class Derived +that appears to "inherit" the member data and functions from both Base1 +and Base2. What actually happens is that three +different top-level classes are created, with Ruby's Object +class as their superclass. Each of these classes defines a nested +module named Impl, and it's in these nested Impl +modules that the actual instance methods for the classes are defined, +i.e.

      + + + + + +
      +
      class Base1
       module Impl
       # Define Base1 methods here
       end
       include Impl
      end

      class Base2
       module Impl
       # Define Base2 methods here
       end
       include Impl
      end

      class Derived
       module Impl
       include Base1::Impl
       include Base2::Impl
       # Define Derived methods here
       end
       include Impl
      end
      + + + + + +
      + + + + + +

      Observe that after the nested Impl +module for a class is defined, it is mixed-in to the class itself. Also +observe that the Derived::Impl module first +mixes-in its base classes' Impl modules, thus +"inheriting" all of their behavior.

      + + + + + +

      The primary drawback is that, unlike the default mode of +operation, neither Base1 nor Base2 +is a true superclass of Derived anymore:

      + + + + + +
      +
      obj = Derived.new
      obj.is_a? Base1 # this will return false...
      obj.is_a? Base2 # ... and so will this
      + + + + + +
      + + + + + +

      In most cases, this is not a serious problem since objects of +type Derived will otherwise behave as though they +inherit from both Base1 and Base2 +(i.e. they exhibit "Duck +Typing").

      + + + + + +

      32.3.9 C++ Overloaded Functions

      + + +

      C++ overloaded functions, methods, and constructors are +mostly supported by SWIG. For example, if you have two functions like +this:

      + + + + + +
      +
      void foo(int);
      void foo(char *c);
      + + + + + +
      + + + + + +

      You can use them in Ruby in a straightforward manner:

      + + + + + +
      +
      irb(main):001:0> foo(3) # foo(int)
      irb(main):002:0> foo("Hello") # foo(char *c)
      + + + + + +
      + + + + + +

      Similarly, if you have a class like this,

      + + + + + +
      +
      class Foo {
      public:
       Foo();
       Foo(const Foo &);
       ...
      };
      + + + + + +
      + + + + + +

      you can write Ruby code like this:

      + + + + + +
      +
      irb(main):001:0> f = Foo.new # Create a Foo
      irb(main):002:0> g = Foo.new(f) # Copy f
      + + + + + +
      + + + + + +

      Overloading support is not quite as flexible as in C++. +Sometimes there are methods that SWIG can't disambiguate. For example:

      + + + + + +
      +
      void spam(int);
      void spam(short);
      + + + + + +
      + + + + + +

      or

      + + + + + +
      +
      void foo(Bar *b);
      void foo(Bar &b);
      + + + + + +
      + + + + + +

      If declarations such as these appear, you will get a warning +message like this:

      + + + + + +
      +
      example.i:12: Warning(509): Overloaded spam(short) is shadowed by spam(int)
      at example.i:11.
      + + + + + +
      + + + + + +

      To fix this, you either need to ignore or rename one of the +methods. For example:

      + + + + + +
      +
      %rename(spam_short) spam(short);
      ...
      void spam(int); 
      void spam(short); // Accessed as spam_short
      + + + + + +
      + + + + + +

      or

      + + + + + +
      +
      %ignore spam(short);
      ...
      void spam(int); 
      void spam(short); // Ignored
      + + + + + +
      + + + + + +

      SWIG resolves overloaded functions and methods using a +disambiguation scheme that ranks and sorts declarations according to a +set of type-precedence rules. The order in which declarations appear in +the input does not matter except in situations where ambiguity +arises--in this case, the first declaration takes precedence.

      + + + + + +

      Please refer to the "SWIG +and C++" chapter for more information about overloading.

      + + + + + +

      32.3.10 C++ Operators

      + + +

      For the most part, overloaded operators are handled +automatically by SWIG and do not require any special treatment on your +part. So if your class declares an overloaded addition operator, e.g.

      + + + + + +
      +
      class Complex {
       ...
       Complex operator+(Complex &);
       ...
      };
      + + + + + +
      + + + + + +

      the resulting Ruby class will also support the addition (+) +method correctly.

      + + + + + +

      For cases where SWIG's built-in support is not sufficient, C++ +operators can be wrapped using the %rename +directive (available on SWIG 1.3.10 and later releases). All you need +to do is give the operator the name of a valid Ruby identifier. For +example:

      + + + + + +
      +
      %rename(add_complex) operator+(Complex &, Complex &);
      ...
      Complex operator+(Complex &, Complex &);
      + + + + + +
      + + + + + +

      Now, in Ruby, you can do this:

      + + + + + +
      +
      a = Example::Complex.new(2, 3)
      b = Example::Complex.new(4, -1)
      c = Example.add_complex(a, b)
      + + + + + +
      + + + + + +

      More details about wrapping C++ operators into Ruby operators +is discussed in the section +on operator overloading.

      + + + + + +

      32.3.11 C++ namespaces

      + + +

      SWIG is aware of C++ namespaces, but namespace names do not +appear in the module nor do namespaces result in a module that is +broken up into submodules or packages. For example, if you have a file +like this,

      + + + + + +
      +
      %module example

      namespace foo {
       int fact(int n);
       struct Vector {
       double x,y,z;
       };
      };
      + + + + + +
      + + + + + +

      it works in Ruby as follows:

      + + + + + +
      +
      irb(main):001:0> require 'example'
      true
      irb(main):002:0> Example.fact(3)
      6
      irb(main):003:0> v = Example::Vector.new
      #<Example::Vector:0x4016f4d4>
      irb(main):004:0> v.x = 3.4
      3.4
      irb(main):004:0> v.y
      0.0
      + + + + + +
      + + + + + +

      If your program has more than one namespace, name conflicts +(if any) can be resolved using %rename For +example:

      + + + + + +
      +
      %rename(Bar_spam) Bar::spam;

      namespace Foo {
       int spam();
      }

      namespace Bar {
       int spam();
      }
      + + + + + +
      + + + + + +

      If you have more than one namespace and your want to keep +their symbols separate, consider wrapping them as separate SWIG +modules. For example, make the module name the same as the namespace +and create extension modules for each namespace separately. If your +program utilizes thousands of small deeply nested namespaces each with +identical symbol names, well, then you get what you deserve.

      + + + + + +

      32.3.12 C++ templates

      + + +

      C++ templates don't present a huge problem for SWIG. However, +in order to create wrappers, you have to tell SWIG to create wrappers +for a particular template instantiation. To do this, you use the %template +directive. For example:

      + + + + + +
      +
      %module example

      %{
      #include "pair.h"
      %}

      template<class T1, class T2>
      struct pair {
       typedef T1 first_type;
       typedef T2 second_type;
       T1 first;
       T2 second;
       pair();
       pair(const T1&, const T2&);
       ~pair();
      };

      %template(Pairii) pair<int,int>;
      + + + + + +
      + + + + + +

      In Ruby:

      + + + + + +
      +
      irb(main):001:0> require 'example'
      true
      irb(main):002:0> p = Example::Pairii.new(3, 4)
      #<Example:Pairii:0x4016f4df>
      irb(main):003:0> p.first
      3
      irb(main):004:0> p.second
      4
      + + + + + +
      + + + + + +

      32.3.13 C++ Standard Template Library (STL)

      + + +

      On a related note, the standard SWIG library contains a +number of modules that provide typemaps for standard C++ library +classes (such as std::pair, std::string +and std::vector). These library modules don't +provide wrappers around the templates themselves, but they do make it +convenient for users of your extension module to pass Ruby objects +(such as arrays and strings) to wrapped C++ code that expects instances +of standard C++ templates. For example, suppose the C++ library you're +wrapping has a function that expects a vector of floats:

      + + + + + +
      +
      %module example

      float sum(const std::vector<float>& values);
      + + + + + +
      + + + + + +

      Rather than go through the hassle of writing an "in" typemap +to convert an array of Ruby numbers into a +std::vector<float>, you can just use the std_vector.i +module from the standard SWIG library:

      + + + + + +
      +
      %module example

      %include std_vector.i
      float sum(const std::vector<float>& values);
      + + + + + +
      + + + + + +

      Ruby's STL wrappings provide additional methods to make them +behave more similarly to Ruby's native classes.

      + + + + + +

      Thus, you can do, for example:

      + + + + + +
      +
      v = IntVector.new
      v << 2
      v << 3
      v << 4
      v.each { |x| puts x }

      => 2
      3
      4
      v.delete_if { |x| x == 3 }
      => [2,4]
      + + + + + +
      + + + + + +

      The SWIG Ruby module provides also the ability for all the STL +containers to carry around Ruby native objects (Fixnum, Classes, etc) +making them act almost like Ruby's own Array, Hash, etc.   To +do +that, you need to define a container that contains a swig::GC_VALUE, +like:

      + + + + + +
      %module +nativevector
      + + + + + +
      + + + + + +%{
      + + + + + +std::vector< swig::GC_VALUE > NativeVector;
      + + + + + +%}
      + + + + + +
      + + + + + +%template(NativeVector) std::vector< swig::GC_VALUE >;
      + + + + + +
      + + + + + +
      + + + + + +

      This vector can then contain any Ruby object, making them +almost identical to Ruby's own Array class.

      + + + + + +
      require 'nativevector'
      + + + + + +include NativeVector
      + + + + + +
      + + + + + +v = NativeVector.new
      + + + + + +v << 1
      + + + + + +v << +[1,2]
      + + + + + +v << +'hello'
      + + + + + +
      + + + + + +class A; end
      + + + + + +
      + + + + + +v << +A.new
      + + + + + +
      + + + + + +puts v
      + + + + + +=> +[1, [1,2], 'hello', #<A:0x245325>]
      + + + + + +
      + + + + + +

      Obviously, there is a lot more to template wrapping than +shown in these examples. More details can be found in the SWIG and C++ +chapter.

      + + + + + +

      32.3.14 C++ STL Functors

      + + +

      Some containers in the STL allow you to modify their default +behavior by using so called functors or function objects. + Functors are often just a very simple struct with operator() +redefined or an actual C/C++ function.  This allows you, for +example, to always keep the sort order of a STL container to your +liking.

      + + + + + +

      The Ruby STL mappings allows you to modify those containers +that +support functors using Ruby procs or methods, instead. + Currently, +this includes std::set, +set::map, +std::multiset +and std::multimap.

      + + + + + +

      The functors in swig are called swig::UnaryFunction +and swig::BinaryFunction.
      + + + + + +For C++ predicates (ie. functors that must return bool as a result) swig::UnaryPredicate +and swig::BinaryPredicate +are provided.

      + + + + + +

      As an example, if given this swig file:

      + + + + + +
      %module +intset;
      + + + + + +
      + + + + + +%include <std_set.i>
      + + + + + +
      + + + + + +%typemap(IntSet)  std::set< int, swig::BinaryPredicate +>;
      + + + + + +

      You can then use the set from Ruby with or without a proc +object as a predicate:

      + + + + + +
      require +'intset'
      + + + + + +include Intset
      + + + + + +
      + + + + + +# Default sorting behavior defined in C++
      + + + + + +a = IntSet.new
      + + + + + +a << 1
      + + + + + +a << 2
      + + + + + +a << 3
      + + + + + +a
      + + + + + +=> + [1,2,3]
      + + + + + +
      + + + + + +# Custom sorting behavior defined by a Ruby proc +
      b = IntSet.new( proc { +|a,b| a > b } )
      + + + + + +b << 1
      + + + + + +b << 2
      + + + + + +b << 3
      + + + + + +b
      + + + + + +=> + [3,2,1]
      + + + + + +
      + + + + + +

      32.3.15 C++ STL Iterators

      + + +

      The STL is well known for the use of iterators.  There +are a number of iterators possible with different properties, but in +general there are two main categories: const iterators and non-const +iterators.  The const iterators can access and not modify the +values they point at, while the non-const iterators can both read and +modify the values.

      + + + + + +

      The Ruby STL wrappings support both type of iterators by using +a proxy class in-between.  This proxy class is swig::Iterator or +swig::ConstIterator.  Derived from them are template +classes that need to be initialized with the actual iterator for the +container you are wrapping and often times with the beginning and +ending points of the iteration range. 

      + + + + + +

      The SWIG STL library already provides typemaps to all the +standard containers to do this wrapping automatically for you, but if +you have your own STL-like iterator, you will need to write your own +typemap for them.  For out typemaps, the special functions make_const_iterator and make_nonconst_iterator are provided.

      + +

      These can be used either like:

      + +
      make_const_iterator( iterator, rubyclass );
      + +make_const_iterator( iterator, iterator_begin, iterator_end, rubyclass );
      + + + + + +

      The iterators support a next() and previous() member function to +just change the iterator without returning anything.  previous() +should obviously only be used for bidirectional iterators.  You +can also advance the iterator multiple steps by using standard math +operations like +=.

      + +

      The +value the iterator points at can be accessed with value() -- this is equivalent to dereferencing it with *i. +  For non-const iterators, a value=() function +is also provided which allows you to change the value pointed by the +iterator.  This is equivalent to the C++ construct of dereferencing and assignment, like *i = something. 

      + + + + + +

      Thus, given say a vector class of doubles defined as:

      + + + + + +
      %module doublevector
      + + + + + +
      + + + + + +%include std_vector.i
      + + + + + +
      + + + + + +%template(DoubleVector) std::vector<double>;
      + + + + + +

      Its iterator can then be used from Ruby like:

      + + + + + +
      require +'doublevector'
      + + + + + +include Doublevector
      + +
      + + + + + +v = DoubleVector.new
      + + + + + +v << 1
      + + + + + +v << 2
      + + + + + +v << 3
      + +
      + +#
      + +# an elaborate and less efficient way of doing v.map! { |x| x+2 }
      + +#
      + + + + + +i = v.begin
      + + + + + +e = v.end
      + + + + + +while i != e
      + + + + + +  val = i.value
      + + + + + +  val += 2
      + + + + + +  i.value = val
      + + + + + +  i.next
      + + + + + +end
      + + + + +i
      + + + + +>> [3, 4, 5 ]
      + + + + + +
      + +

      If you'd rather have STL classes without any iterators, you should define -DSWIG_NO_EXPORT_ITERATOR_METHODS when running swig.

      + + + + + +

      32.3.16 C++ Smart Pointers

      + + +

      In certain C++ programs, it is common to use classes that +have been wrapped by so-called "smart pointers." Generally, this +involves the use of a template class that implements operator->() +like this:

      + + + + + +
      +
      template<class T> class SmartPtr {
       ...
       T *operator->();
       ...
      }
      + + + + + +
      + + + + + +

      Then, if you have a class like this,

      + + + + + +
      +
      class Foo {
      public:
       int x;
       int bar();
      };
      + + + + + +
      + + + + + +

      A smart pointer would be used in C++ as follows:

      + + + + + +
      +
      SmartPtr<Foo> p = CreateFoo(); // Created somehow (not shown)
      ...
      p->x = 3; // Foo::x
      int y = p->bar(); // Foo::bar
      + + + + + +
      + + + + + +

      To wrap this in Ruby, simply tell SWIG about the SmartPtr +class and the low-level Foo object. Make sure you +instantiate SmartPtr using %template +if necessary. For example:

      + + + + + +
      +
      %module example
      ...
      %template(SmartPtrFoo) SmartPtr<Foo>;
      ...
      + + + + + +
      + + + + + +

      Now, in Ruby, everything should just "work":

      + + + + + +
      +
      irb(main):001:0> p = Example::CreateFoo() # Create a smart-pointer somehow
      #<Example::SmartPtrFoo:0x4016f4df>
      irb(main):002:0> p.x = 3 # Foo::x
      3
      irb(main):003:0> p.bar() # Foo::bar
      + + + + + +
      + + + + + +

      If you ever need to access the underlying pointer returned by +operator->() itself, simply use the __deref__() +method. For example:

      + + + + + +
      +
      irb(main):004:0> f = p.__deref__() # Returns underlying Foo *
      + + + + + +
      + + + + + +

      32.3.17 Cross-Language Polymorphism

      + + +

      SWIG's Ruby module supports cross-language polymorphism +(a.k.a. the "directors" feature) similar to that for SWIG's Python +module. Rather than duplicate the information presented in the Python chapter, this +section just notes the differences that you need to be aware of when +using this feature with Ruby.

      + + + + + +

      32.3.17.1 Exception Unrolling

      + + +

      Whenever a C++ director class routes one of its virtual +member function calls to a Ruby instance method, there's always the +possibility that an exception will be raised in the Ruby code. By +default, those exceptions are ignored, which simply means that the +exception will be exposed to the Ruby interpreter. If you would like to +change this behavior, you can use the %feature("director:except") +directive to indicate what action should be taken when a Ruby exception +is raised. The following code should suffice in most cases:

      + + + + + +
      +
      %feature("director:except") {
       throw Swig::DirectorMethodException($error);
      }
      + + + + + +
      + + + + + +

      When this feature is activated, the call to the Ruby instance +method is "wrapped" using the rb_rescue2() +function from Ruby's C API. If any Ruby exception is raised, it will be +caught here and a C++ exception is raised in its place.

      + + + + + +

      32.4 Naming

      + + +

      Ruby has several common naming conventions. Constants are +generally +in upper case, module and class names are in camel case and methods are +in lower case with underscores. For example:

      + + + + + +
      +
        + + + + + +
      • MATH::PI is a constant name
        • + + + + + +
      • MyClass is a class name
        • + + + + + +
      • my_method is a method name
        • + + + + + +
      + + + + + +
      + + + + + +

      Prior to version 1.3.28, SWIG did not support these Ruby +conventions. The only modifications it made to names was to capitalize +the first letter of constants (which includes module and class names).

      + + + + + +

      SWIG 1.3.28 introduces the new -autorename command line +parameter. +When this parameter is specified, SWIG will automatically change +constant, class and method names to conform with the standard Ruby +naming conventions. For example:

      + + + + + +
      +
      $ swig -ruby -autorename example.i
+
      + + + + + +
      + + + + + +

      To disable renaming use the -noautorename command line option.

      + + + + + +

      Since this change significantly changes the wrapper code +generated +by SWIG, it is turned off by default in SWIG 1.3.28. However, it is +planned to become the default option in future releases.

      + + + + + +

      32.4.1 Defining Aliases

      + + +

      It's a fairly common practice in the Ruby built-ins and +standard library to provide aliases for method names. For example, Array#size +is an alias for Array#length. If you would like +to provide an alias for one of your class' instance methods, one +approach is to use SWIG's %extend directive to +add a new method of the aliased name that calls the original function. +For example:

      + + + + + +
      +
      class MyArray {
      public:
       // Construct an empty array
       MyArray();
       
       // Return the size of this array
       size_t length() const;
      };

      %extend MyArray {
       // MyArray#size is an alias for MyArray#length
       size_t size() const {
       return $self->length();
       }
      }
      + + + + + +
      + + + + + +

      A better solution is to use the %alias +directive (unique to SWIG's Ruby module). The previous example could +then be rewritten as:

      + + + + + +
      +
      // MyArray#size is an alias for MyArray#length
      %alias MyArray::length "size";

      class MyArray {
      public:
       // Construct an empty array
       MyArray();
       
       // Return the size of this array
       size_t length() const;
      };

      + + + + + +
      + + + + + +

      Multiple aliases can be associated with a method by providing +a comma-separated list of aliases to the %alias +directive, e.g.

      + + + + + +
      +
      %alias MyArray::length "amount,quantity,size";
      + + + + + +
      + + + + + +

      From an end-user's standpoint, there's no functional +difference between these two approaches; i.e. they should get the same +result from calling either MyArray#size or MyArray#length. +However, when the %alias directive is used, SWIG +doesn't need to generate all of the wrapper code that's usually +associated with added methods like our MyArray::size() +example.

      + + + + + +

      Note that the %alias directive is +implemented using SWIG's "features" mechanism and so the same name +matching rules used for other kinds of features apply (see the chapter +on "Customization +Features") for more details).

      + + + + + +

      32.4.2 Predicate Methods

      + + +

      Ruby methods that return a boolean value and end in a +question mark +are known as predicate methods. Examples of predicate methods in +standard Ruby classes include Array#empty? (which +returns true for an array containing no elements) +and Object#instance_of? (which returns true +if the object is an instance of the specified class). For consistency +with Ruby conventions, methods that return boolean values should be +marked as predicate methods.

      + + + + + +

      One cumbersome solution to this problem is to rename the +method (using SWIG's %rename directive) and +provide a custom typemap that converts the function's actual return +type to Ruby's true or false. +For example:

      + + + + + +
      +
      %rename("is_it_safe?") is_it_safe();

      %typemap(out) int is_it_safe 
       "$result = ($1 != 0) ? Qtrue : Qfalse;";

      int is_it_safe();

      + + + + + +
      + + + + + +

      A better solution is to use the %predicate +directive (unique to SWIG's Ruby module) to designate a method as a +predicate method. For the previous example, this would look like:

      + + + + + +
      +
      %predicate is_it_safe();

      int is_it_safe();

      + + + + + +
      + + + + + +

      This method would be invoked from Ruby code like this:

      + + + + + +
      +
      irb(main):001:0> Example::is_it_safe?
      true

      + + + + + +
      + + + + + +

      The %predicate directive is implemented +using SWIG's "features" mechanism and so the same name matching rules +used for other kinds of features apply (see the chapter on "Customization +Features") for more details).

      + + + + + +

      32.4.3 Bang Methods

      + + +

      Ruby methods that modify an object in-place and end in an +exclamation mark are known as bang methods. An example of a bang method +is Array#sort! which changes the ordering of +items in an array. Contrast this with Array#sort, +which returns a copy of the array with the items sorted instead of +modifying the original array. For consistency with Ruby conventions, +methods that modify objects in place should be marked as bang methods.

      + + + + + +

      Bang methods can be marked using the %bang +directive which is unique to the Ruby module and was introduced in SWIG +1.3.28. For example:

      + + + + + +
      +
      %bang sort!(arr);

      int sort(int arr[]);
      + + + + + +
      + + + + + +

      This method would be invoked from Ruby code like this:

      + + + + + +
      +
      irb(main):001:0> Example::sort!(arr)
      + + + + + +
      + + + + + +

      The %bang directive is implemented +using SWIG's "features" mechanism and so the same name matching rules +used for other kinds of features apply (see the chapter on "Customization +Features") for more details).

      + + + + + +

      32.4.4 Getters and Setters

      + + +

      Often times a C++ library will expose properties through +getter and setter methods. For example:

      + + + + + +
      +
      class Foo {
      	Foo() {}

       int getValue() { return value_; }

       void setValue(int value) { value_ = value; }

      private:
       int value_;
      };
      + + + + + +
      + + + + + +

      By default, SWIG will expose these methods to Ruby as get_value +and set_value. However, it more natural for these +methods to be exposed in Ruby as value and value=. + That allows the methods to be used like this:

      + + + + + +
      +
      irb(main):001:0> foo = Foo.new()
      irb(main):002:0> foo.value = 5
      irb(main):003:0> puts foo.value
      + + + + + +
      + + + + + +

      This can be done by using the %rename directive:

      + + + + + +
      +
      %rename("value") Foo::getValue();
      %rename("value=") Foo::setValue(int value);
      + + + + + +
      + + + + + +

       

      + + + + + +

      32.5 Input and output parameters

      + + +

      A common problem in some C programs is handling parameters +passed as simple pointers. For example:

      + + + + + +
      +
      void add(int x, int y, int *result) {
       *result = x + y;
      }
      or
      int sub(int *x, int *y) {
       return *x-*y;
      }
      + + + + + +
      + + + + + +

      The easiest way to handle these situations is to use the typemaps.i +file. For example:

      + + + + + +
      +
      %module Example
      %include "typemaps.i"

      void add(int, int, int *OUTPUT);
      int sub(int *INPUT, int *INPUT);
      + + + + + +
      + + + + + +

      In Ruby, this allows you to pass simple values. For example:

      + + + + + +
      +
      a = Example.add(3,4)
      puts a
      7
      b = Example.sub(7,4)
      puts b
      3
      + + + + + +
      + + + + + +

      Notice how the INPUT parameters allow +integer values to be passed instead of pointers and how the OUTPUT +parameter creates a return result.

      + + + + + +

      If you don't want to use the names INPUT +or OUTPUT, use the %apply +directive. For example:

      + + + + + +
      +
      %module Example
      %include "typemaps.i"

      %apply int *OUTPUT { int *result };
      %apply int *INPUT { int *x, int *y};

      void add(int x, int y, int *result);
      int sub(int *x, int *y);
      + + + + + +
      + + + + + +

      If a function mutates one of its parameters like this,

      + + + + + +
      +
      void negate(int *x) {
       *x = -(*x);
      }
      + + + + + +
      + + + + + +

      you can use INOUT like this:

      + + + + + +
      +
      %include "typemaps.i"
      ...
      void negate(int *INOUT);
      + + + + + +
      + + + + + +

      In Ruby, a mutated parameter shows up as a return value. For +example:

      + + + + + +
      +
      a = Example.negate(3)
      print a
      -3

      + + + + + +
      + + + + + +

      The most common use of these special typemap rules is to +handle functions that return more than one value. For example, +sometimes a function returns a result as well as a special error code:

      + + + + + +
      +
      /* send message, return number of bytes sent, success code, and error_code */
      int send_message(char *text, int *success, int *error_code);
      + + + + + +
      + + + + + +

      To wrap such a function, simply use the OUTPUT +rule above. For example:

      + + + + + +
      +
      %module example
      %include "typemaps.i"
      ...
      int send_message(char *, int *OUTPUT, int *OUTPUT);
      + + + + + +
      + + + + + +

      When used in Ruby, the function will return an array of +multiple values.

      + + + + + +
      +
      bytes, success, error_code = send_message("Hello World")
      if not success
       print "error #{error_code} : in send_message"
      else
       print "Sent", bytes
      end
      + + + + + +
      + + + + + +

      Another way to access multiple return values is to use the %apply +rule. In the following example, the parameters rows and columns are +related to SWIG as OUTPUT values through the use +of %apply

      + + + + + +
      +
      %module Example
      %include "typemaps.i"
      %apply int *OUTPUT { int *rows, int *columns };
      ...
      void get_dimensions(Matrix *m, int *rows, int*columns);
      + + + + + +
      + + + + + +

      In Ruby:

      + + + + + +
      +
      r, c = Example.get_dimensions(m)
      + + + + + +
      + + + + + +

      32.6 Exception handling

      + + +

      32.6.1 Using the %exception directive

      + + +

      The SWIG %exception directive can be +used to define a user-definable exception handler that can convert +C/C++ errors into Ruby exceptions. The chapter on Customization +Features contains more details, but suppose you have a C++ +class like the following :

      + + + + + +
      +
      class DoubleArray {
       private:
       int n;
       double *ptr;
       public:
       // Create a new array of fixed size
       DoubleArray(int size) {
       ptr = new double[size];
       n = size;
       }

       // Destroy an array
       ~DoubleArray() {
       delete ptr;
       } 

       // Return the length of the array
       int length() {
       return n;
       }

       // Get an array item and perform bounds checking.
       double getitem(int i) {
       if ((i >= 0) && (i < n))
       return ptr[i];
       else
       throw RangeError();
       }

       // Set an array item and perform bounds checking.
       void setitem(int i, double val) {
       if ((i >= 0) && (i < n))
       ptr[i] = val;
       else {
       throw RangeError();
       }
       }
       };
      + + + + + +
      + + + + + +

      Since several methods in this class can throw an exception +for an out-of-bounds access, you might want to catch this in the Ruby +extension by writing the following in an interface file:

      + + + + + +
      +
      %exception {
       try {
       $action
       }
       catch (const RangeError&) {
       static VALUE cpperror = rb_define_class("CPPError", rb_eStandardError);
       rb_raise(cpperror, "Range error.");
       }
      }

      class DoubleArray {
       ...
      };
      + + + + + +
      + + + + + +

      The exception handling code is inserted directly into +generated wrapper functions. When an exception handler is defined, +errors can be caught and used to gracefully raise a Ruby exception +instead of forcing the entire program to terminate with an uncaught +error.

      + + + + + +

      As shown, the exception handling code will be added to every +wrapper function. Because this is somewhat inefficient, you might +consider refining the exception handler to only apply to specific +methods like this:

      + + + + + +
      +
      %exception getitem {
       try {
       $action
       }
       catch (const RangeError&) {
       static VALUE cpperror = rb_define_class("CPPError", rb_eStandardError);
       rb_raise(cpperror, "Range error in getitem.");
       }
      }

      %exception setitem {
       try {
       $action
       }
       catch (const RangeError&) {
       static VALUE cpperror = rb_define_class("CPPError", rb_eStandardError);
       rb_raise(cpperror, "Range error in setitem.");
       }
      }
      + + + + + +
      + + + + + +

      In this case, the exception handler is only attached to +methods and functions named getitem and setitem. +

      + + + + + +

      Since SWIG's exception handling is user-definable, you are not +limited to C++ exception handling. See the chapter on Customization +Features for more examples.

      + + + + + +

      32.6.2 Handling Ruby Blocks

      + + +

      One of the highlights of Ruby and most of its standard library +is +the use of blocks, which allow the easy creation of continuations and +other niceties.  Blocks in ruby are also often used to +simplify the passing of many arguments to a class.

      + + + + + +

      In order to make your class constructor support blocks, you +can take advantage of the %exception directive, which will get run +after the C++ class' constructor was called. 

      + + + + + +

      For example, this yields the class over after its +construction: +
      + + + + + +

      + + + + + +
      +
      class Window
      {
      public:
       Window(int x, int y, int w, int h);
      // .... other methods here ....
      };

      // Add support for yielding self in the Class' constructor.
      %exception Window::Window {
       $action
       if (rb_block_given_p()) {
       rb_yield(self);
       }
      }
      + + + + + +
      + + + + + +

      Then, in ruby, it can be used like:

      + + + + + +
      Window.new(0,0,360,480) +{ |w|
      + + + + + +    w.color = Fltk::RED
      + + + + + +    w.border = false
      + + + + + +}
      + + + + + +
      + + + + + +

      For other methods, you can usually use a dummy parameter with +a special in typemap, like:

      + + + + + +
      //
      + + + + + +// original function was:
      + + + + + +//
      + + + + + +// void func(int x);
      + + + + + +
      + + + + + +%typemap(in,numinputs=0) int RUBY_YIELD_SELF {
      + + + + + +     if ( !rb_block_given_p() )
      + + + + + +            +rb_raise("No block given");
      + + + + + +     return rb_yield(self);
      + + + + + +}
      + + + + + +
      + + + + + +%extend {
      + + + + + +        void func(int x, int +RUBY_YIELD_SELF );
      + + + + + +}
      + + + + + +

      For more information on typemaps, see Typemaps.

      + + +

      32.6.3 Raising exceptions

      + + +

      There are three ways to raise exceptions from C++ code to +Ruby.

      + + + + + +

      The first way is to use SWIG_exception(int code, +const char *msg). The following table shows the mappings +from SWIG error codes to Ruby exceptions:

      + + + + + +
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      + + + + +
      SWIG_MemoryError
      + + + + + +       		+ + + + +
      rb_eNoMemError
      + + + + + +
      + + + + +
      SWIG_IOError
      + + + + + +       		+ + + + +
      rb_eIOError
      + + + + + +
      + + + + +
      SWIG_RuntimeError
      + + + + + +       		+ + + + +
      rb_eRuntimeError
      + + + + + +
      + + + + +
      SWIG_IndexError
      + + + + + +       		+ + + + +
      rb_eIndexError
      + + + + + +
      + + + + +
      SWIG_TypeError
      + + + + + +       		+ + + + +
      rb_eTypeError
      + + + + + +
      + + + + +
      SWIG_DivisionByZero
      + + + + + +       		+ + + + +
      rb_eZeroDivError
      + + + + + +
      + + + + +
      SWIG_OverflowError
      + + + + + +       		+ + + + +
      rb_eRangeError
      + + + + + +
      + + + + +
      SWIG_SyntaxError
      + + + + + +       		+ + + + +
      rb_eSyntaxError
      + + + + + +
      + + + + +
      SWIG_ValueError
      + + + + + +       		+ + + + +
      rb_eArgError
      + + + + + +
      + + + + +
      SWIG_SystemError
      + + + + + +       		+ + + + +
      rb_eFatal
      + + + + + +
      + + + + +
      SWIG_AttributeError
      + + + + + +       		+ + + + +
      rb_eRuntimeError
      + + + + + +
      + + + + +
      SWIG_NullReferenceError
      + + + + + +       		+ + + + +
      rb_eNullReferenceError*
      + + + + + +
      + + + + +
      SWIG_ObjectPreviouslyDeletedError
      + + + + + +       		+ + + + +
      rb_eObjectPreviouslyDeleted*
      + + + + + +
      + + + + +
      SWIG_UnknownError
      + + + + + +       		+ + + + +
      rb_eRuntimeError
      + + + + + +
      + + + + +
      * These error classes are created by +SWIG and are not built-in Ruby exception classes
      + + + + + +
      + + + + + +
      + + + + + +

      The second way to raise errors is to use SWIG_Raise(obj, +type, desc). +Obj is a C++ instance of an exception class, type is a string +specifying the type of exception (for example, "MyError") and desc is +the SWIG description of the exception class. For example:

      + + + + + +
      +%raise(SWIG_NewPointerObj(e, +SWIGTYPE_p_AssertionFailedException, +0), ":AssertionFailedException", SWIGTYPE_p_AssertionFailedException);
      + + + + + +

      This is useful when you want to pass the current exception +object +directly to Ruby, particularly when the object is an instance of class +marked as an %exceptionclass (see the next +section for more information).

      + + + + + +

      Last, you can raise an exception by directly calling Ruby's C +api. This is done by invoking the rb_raise() +function. The first argument passed to rb_raise() +is the exception type. You can raise a custom exception type or one of +the built-in Ruby exception types.

      + + + + + +

      32.6.4 Exception classes

      + + +

      Starting with SWIG 1.3.28, the Ruby module supports the %exceptionclass +directive, which is used to identify C++ classes that are used as +exceptions. Classes that are marked with the %exceptionclass +directive are exposed in Ruby as child classes of rb_eRuntimeError. +This allows C++ exceptions to be directly mapped to Ruby exceptions, +providing for a more natural integration between C++ code and Ruby code.

      + + + + + +
      +
      	%exceptionclass CustomError;
      	
      	%inline %{
      	class CustomError { };
      	
      	class Foo { 
      	public:
      	void test() { throw CustomError; }
      	};
      	}
      + + + + + +
      + + + + + +

      From Ruby you can now call this method like this:

      + + + + + +
      +
      foo = Foo.new
      begin
       foo.test()
      rescue CustomError => e
       puts "Caught custom error"
      end
      + + + + + +
      + + + + + +

      For another example look at swig/Examples/ruby/exception_class.
      + + + + + +

      + + + + + +

      32.7 Typemaps

      + + +

      This section describes how you can modify SWIG's default +wrapping behavior for various C/C++ datatypes using the %typemap +directive. This is an advanced topic that assumes familiarity with the +Ruby C API as well as the material in the "Typemaps" +chapter.  +

      + + + + + +

      Before proceeding, it should be stressed that typemaps are not +a required part of using SWIG---the default wrapping behavior is enough +in most cases. Typemaps are only used if you want to change some aspect +of the primitive C-Ruby interface.

      + + + + + +

      32.7.1 What is a typemap?

      + + +

      A typemap is nothing more than a code generation rule that is +attached to a specific C datatype. The general form of this declaration +is as follows ( parts enclosed in [...] are optional +):    

      + + + + + +
      %typemap( method [, modifiers...] ) typelist +code;
      + + + + + +

      method is a simply a name that specifies +what kind of typemap is being defined. It is usually a name like "in", +"out", or "argout" (or its +director variations). The purpose of these methods is described later.

      + + + + + +

      modifiers is an optional comma separated +list of +name="value" values. These are sometimes to attach extra +information to a typemap and is often target-language dependent.

      + + + + + +

      typelist is a list of the C++ type +patterns that the typemap will match. The general form of this list is +as follows:

      + + + + + +
      +
      typelist : typepattern [, typepattern, typepattern, ... ] ;

      typepattern : type [ (parms) ]
       | type name [ (parms) ]
       | ( typelist ) [ (parms) ]
      + + + + + +
      + + + + + +

      Each type pattern is either a simple type, a simple type and +argument name, or a list of types in the case of multi-argument +typemaps. In addition, each type pattern can be parameterized with a +list of temporary variables (parms). The purpose of these variables +will be explained shortly.

      + + + + + +

      code specifies the C code used in the +typemap. It can take any one of the following forms:

      + + + + + +
      +
      code : { ... }
       | " ... "
       | %{ ... %}
      + + + + + +
      + + + + + +

      For example, to convert integers +from Ruby to C, you might define a typemap like this:

      + + + + + +
      +
      %module example

      %typemap(in) int {
       $1 = (int) NUM2INT($input);
       printf("Received an integer : %d\n",$1);
      }

      %inline %{
      extern int fact(int n);
      %}
      + + + + + +
      + + + + + +

      Typemaps are always associated with some specific aspect of +code generation. In this case, the "in" method refers to the conversion +of input arguments to C/C++. The datatype int is +the datatype to which the typemap will be applied. The supplied C code +is used to convert values. In this code a number of special variables +prefaced by a $ are used. The $1 +variable is placeholder for a local variable of type int. +The $input variable is the input Ruby object.

      + + + + + +

      When this example is compiled into a Ruby module, the +following sample code:

      + + + + + +
      +
      require 'example'

      puts Example.fact(6)
      + + + + + +
      + + + + + +

      prints the result:

      + + + + + +
      +
      Received an integer : 6
      720
      + + + + + +
      + + + + + +

      In this example, the typemap is applied to all occurrences of +the int datatype. You can refine this by +supplying an optional parameter name. For example:

      + + + + + +
      +
      %module example

      %typemap(in) int n {
       $1 = (int) NUM2INT($input);
       printf("n = %d\n",$1);
      }

      %inline %{
      extern int fact(int n);
      %}
      + + + + + +
      + + + + + +

      In this case, the typemap code is only attached to arguments +that exactly match "int n".

      + + + + + +

      The application of a typemap to specific datatypes and +argument names involves more than simple text-matching--typemaps are +fully integrated into the SWIG type-system. When you define a typemap +for int, that typemap applies to int +and qualified variations such as const int. In +addition, the typemap system follows typedef +declarations. For example:

      + + + + + +
      +
      %typemap(in) int n {
       $1 = (int) NUM2INT($input);
       printf("n = %d\n",$1);
      }

      typedef int Integer;
      extern int fact(Integer n); // Above typemap is applied
      + + + + + +
      + + + + + +

      However, the matching of typedef only +occurs in one direction. If you defined a typemap for Integer, +it is not applied to arguments of type int.

      + + + + + +

      Typemaps can also be defined for groups of consecutive +arguments. For example:

      + + + + + +
      +
      %typemap(in) (char *str, int len) {
       $1 = STR2CSTR($input);
       $2 = (int) RSTRING($input)->len;
      };

      int count(char c, char *str, int len);
      + + + + + +
      + + + + + +

      When a multi-argument typemap is defined, the arguments are +always handled as a single Ruby object. This allows the function count +to be used as follows (notice how the length parameter is omitted):

      + + + + + +
      +
      puts Example.count('o','Hello World')
      2
      + + + + + +
      + + + + + +

      32.7.2 Typemap scope

      + + +

      Once defined, a typemap remains in effect for all of the +declarations that follow. A typemap may be redefined for different +sections of an input file. For example:

      + + + + + +
      +
      // typemap1
      %typemap(in) int {
      ...
      }

      int fact(int); // typemap1
      int gcd(int x, int y); // typemap1

      // typemap2
      %typemap(in) int {
      ...
      }

      int isprime(int); // typemap2
      + + + + + +
      + + + + + +

      One exception to the typemap scoping rules pertains to the +%extend declaration. %extend is used +to attach new declarations to a class or structure definition. Because +of this, all of the declarations in an %extend +block are subject to the typemap rules that are in effect at the point +where the class itself is defined. For example:

      + + + + + +
      +
      class Foo {
       ...
      };

      %typemap(in) int {
       ...
      }

      %extend Foo {
       int blah(int x); // typemap has no effect. Declaration is attached to Foo which 
       // appears before the %typemap declaration.
      };
      + + + + + +
      + + + + + +

      32.7.3 Copying a typemap

      + + +

      A typemap is copied by using assignment. For example:

      + + + + + +
      +
      %typemap(in) Integer = int;
      + + + + + +
      + + + + + +

      or this:

      + + + + + +
      +
      %typemap(in) Integer, Number, int32_t = int;
      + + + + + +
      + + + + + +

      Types are often managed by a collection of different +typemaps. For example:

      + + + + + +
      +
      %typemap(in) int { ... }
      %typemap(out) int { ... }
      %typemap(varin) int { ... }
      %typemap(varout) int { ... }
      + + + + + +
      + + + + + +

      To copy all of these typemaps to a new type, use %apply. +For example:

      + + + + + +
      +
      %apply int { Integer }; // Copy all int typemaps to Integer
      %apply int { Integer, Number }; // Copy all int typemaps to both Integer and Number
      + + + + + +
      + + + + + +

      The patterns for %apply follow the same +rules as for +%typemap. For example:

      + + + + + +
      +
      %apply int *output { Integer *output }; // Typemap with name
      %apply (char *buf, int len) { (char *buffer, int size) }; // Multiple arguments
      + + + + + +
      + + + + + +

      32.7.4 Deleting a typemap

      + + +

      A typemap can be deleted by simply defining no code. For +example:

      + + + + + +
      +
      %typemap(in) int; // Clears typemap for int
      %typemap(in) int, long, short; // Clears typemap for int, long, short
      %typemap(in) int *output;
      + + + + + +
      + + + + + +

      The %clear directive clears all +typemaps for a given type. For example:

      + + + + + +
      +
      %clear int; // Removes all types for int
      %clear int *output, long *output;
      + + + + + +
      + + + + + +

      Note: Since SWIG's default behavior is +defined by typemaps, clearing a fundamental type like int +will make that type unusable unless you also define a new set of +typemaps immediately after the clear operation.

      + + + + + +

      32.7.5 Placement of typemaps

      + + +

      Typemap declarations can be declared in the global scope, +within a C++ namespace, and within a C++ class. For example:

      + + + + + +
      +
      %typemap(in) int {
       ...
      }

      namespace std {
       class string;
       %typemap(in) string {
       ...
       }
      }

      class Bar {
      public:
       typedef const int & const_reference;
       %typemap(out) const_reference {
       ...
       }
      };
      + + + + + +
      + + + + + +

      When a typemap appears inside a namespace or class, it stays +in effect until the end of the SWIG input (just like before). However, +the typemap takes the local scope into account. Therefore, this code

      + + + + + +
      +
      namespace std {
       class string;
       %typemap(in) string {
       ...
       }
      }
      + + + + + +
      + + + + + +

      is really defining a typemap for the type std::string. +You could have code like this:

      + + + + + +
      +
      namespace std {
       class string;
       %typemap(in) string { /* std::string */
       ...
       }
      }

      namespace Foo {
       class string;
       %typemap(in) string { /* Foo::string */
       ...
       }
      }
      + + + + + +
      + + + + + +

      In this case, there are two completely distinct typemaps that +apply to two completely different types (std::string +and +Foo::string).

      + + + + + +

      It should be noted that for scoping to work, SWIG has to know +that +string is a typename defined within a particular namespace. +In this example, this is done using the class declaration class +string +.

      + + + + + +

      32.7.6 Ruby typemaps

      + + +

      The following list details all of the typemap methods that +can be used by the Ruby module:

      + + + + + +

      32.7.6.1  "in" typemap

      + + +

      Converts Ruby objects to input +function arguments. For example: +

      + + + + + +
      +
      %typemap(in) int {
       $1 = NUM2INT($input);
      }
      + + + + + +
      + + + + + +

      The following special variables are available:

      + + + + + +
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      $input Input object +holding value to be converted.
      $symname Name of +function/method being wrapped
      $1...n Argument being +sent to the function
      $1_name Name of the +argument (if provided)
      $1_type The actual C +datatype matched by the typemap.
      $1_ltype The assignable +version of the C datatype matched by the typemap.
      + + + + + +
      + + + + + +

      This is probably the most commonly redefined typemap because +it can be used to implement customized conversions.

      + + + + + +

      In addition, the "in" typemap allows the number of converted +arguments to be specified. For example:

      + + + + + +
      +
      // Ignored argument.
      %typemap(in, numinputs=0) int *out (int temp) {
       $1 = &temp;
      }
      + + + + + +
      + + + + + +

      At this time, only zero or one arguments may be converted.

      + + + + + +

      32.7.6.2 "typecheck" typemap

      + + +

      The "typecheck" typemap is used to support overloaded +functions and methods. It merely checks an argument to see whether or +not it matches a specific type. For example:

      + + + + + +
      +
      %typemap(typecheck,precedence=SWIG_TYPECHECK_INTEGER) int {
       $1 = FIXNUM_P($input) ? 1 : 0;
      }
      + + + + + +
      + + + + + +

      For typechecking, the $1 variable is always a simple integer +that is set to 1 or 0 depending on whether or not the input argument is +the correct type.

      + + + + + +

      If you define new "in" typemaps and your +program uses overloaded methods, you should also define a collection of +"typecheck" typemaps. More details about this follow in a later section +on "Typemaps and Overloading."

      + + + + + +

      32.7.6.3  "out" typemap

      + + +

      Converts return value of a C function +to a Ruby object.

      + + + + + +

      + + + + + +%typemap(out) int {
      + + + + + +   $result = INT2NUM( $1 );
      + + + + + +}
      + + + + + +
      + + + + + +

      The following special variables are available.

      + + + + + +
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      $result Result object +returned to target language.
      $symname Name of +function/method being wrapped
      $1...n Argument being +wrapped
      $1_name Name of the +argument (if provided)
      $1_type The actual C +datatype matched by the typemap.
      $1_ltype The assignable +version of the C datatype matched by the typemap.
      + + + + + +
      + + + + + +
      + + + + + +

      32.7.6.4 "arginit" typemap

      + + +

      The "arginit" typemap is used to set the initial value of a +function argument--before any conversion has occurred. This is not +normally necessary, but might be useful in highly specialized +applications. For example:

      + + + + + +
      +
      // Set argument to NULL before any conversion occurs
      %typemap(arginit) int *data {
       $1 = NULL;
      }
      + + + + + +
      + + + + + +

      32.7.6.5 "default" typemap

      + + +

      The "default" typemap is used to turn an argument into a +default argument. For example:

      + + + + + +
      +
      %typemap(default) int flags {
       $1 = DEFAULT_FLAGS;
      }
      ...
      int foo(int x, int y, int flags);
      + + + + + +
      + + + + + +

      The primary use of this typemap is to either change the +wrapping of default arguments or specify a default argument in a +language where they aren't supported (like C). Target languages that do +not support optional arguments, such as Java and C#, effectively ignore +the value specified by this typemap as all arguments must be given.

      + + + + + +

      Once a default typemap has been applied to an argument, all +arguments that follow must have default values. See the +Default/optional arguments section for further information on +default argument wrapping.

      + + + + + +

      32.7.6.6 "check" typemap

      + + +

      The "check" typemap is used to supply value checking code +during argument conversion. The typemap is applied after +arguments have been converted. For example:

      + + + + + +
      +
      %typemap(check) int positive {
       if ($1 <= 0) {
       SWIG_exception(SWIG_ValueError,"Expected positive value.");
       }
      }
      + + + + + +
      + + + + + +

      32.7.6.7 "argout" typemap

      + + +

      The "argout" typemap is used to return values from arguments. +This is most commonly used to write wrappers for C/C++ functions that +need to return multiple values. The "argout" typemap is almost always +combined with an "in" typemap---possibly to ignore the input value. For +example:

      + + + + + +
      +
      /* Set the input argument to point to a temporary variable */
      %typemap(in, numinputs=0) int *out (int temp) {
       $1 = &temp;
      }

      %typemap(argout, fragment="output_helper") int *out {
       // Append output value $1 to $result (assuming a single integer in this case)
       $result = output_helper( $result, INT2NUM(*$1) );
      }
      + + + + + +
      + + + + + +

      The following special variables are available.

      + + + + + +
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      $result Result object +returned to target language.
      $input The original +input object passed.
      $symname Name of +function/method being wrapped.
      + + + + + +
      + + + + + +

      The code supplied to the "argout" typemap is always placed +after the "out" typemap. If multiple return values are used, the extra +return values are often appended to return value of the function.

      + + + + + +

      Output helper is a fragment that usually defines a macro to +some function like SWIG_Ruby_AppendOutput.

      + + + + + +

      See the typemaps.i library for examples.

      + + + + + +

      32.7.6.8 "freearg" typemap

      + + +

      The "freearg" typemap is used to cleanup argument data. It is +only used when an argument might have allocated resources that need to +be cleaned up when the wrapper function exits. The "freearg" typemap +usually cleans up argument resources allocated by the "in" typemap. For +example:

      + + + + + +
      +
      // Get a list of integers
      %typemap(in) int *items {
       int nitems = Length($input); 
       $1 = (int *) malloc(sizeof(int)*nitems);
      }
      // Free the list 
      %typemap(freearg) int *items {
       free($1);
      }
      + + + + + +
      + + + + + +

      The "freearg" typemap inserted at the end of the wrapper +function, just before control is returned back to the target language. +This code is also placed into a special variable $cleanup +that may be used in other typemaps whenever a wrapper function needs to +abort prematurely.

      + + + + + +

      32.7.6.9 "newfree" typemap

      + + +

      The "newfree" typemap is used in conjunction with the %newobject +directive and is used to deallocate memory used by the return result of +a function. For example:

      + + + + + +
      +
      %typemap(newfree) string * {
       delete $1;
      }
      %typemap(out) string * {
       $result = PyString_FromString($1->c_str());
      }
      ...

      %newobject foo;
      ...
      string *foo();
      + + + + + +
      + + + + + +

      See Object +ownership and %newobject for further details.

      + + + + + +

      32.7.6.10 "memberin" typemap

      + + +

      The "memberin" typemap is used to copy data from an +already converted input value into a structure member. It is +typically used to handle array members and other special cases. For +example:

      + + + + + +
      +
      %typemap(memberin) int [4] {
       memmove($1, $input, 4*sizeof(int));
      }
      + + + + + +
      + + + + + +

      It is rarely necessary to write "memberin" typemaps---SWIG +already provides a default implementation for arrays, strings, and +other objects.

      + + + + + +

      32.7.6.11 "varin" typemap

      + + +

      The "varin" typemap is used to convert objects in the target +language to C for the purposes of assigning to a C/C++ global variable. +This is implementation specific.

      + + + + + +

      32.7.6.12 "varout" typemap

      + + +

      The "varout" typemap is used to convert a C/C++ object to an +object in the target language when reading a C/C++ global variable. +This is implementation specific.

      + + + + + +

      32.7.6.13 "throws" typemap

      + + +

      The "throws" typemap is only used when SWIG parses a C++ +method with an exception specification or has the %catches +feature attached to the method. It provides a default mechanism for +handling C++ methods that have declared the exceptions they will throw. +The purpose of this typemap is to convert a C++ exception into an error +or exception in the target language. It is slightly different to the +other typemaps as it is based around the exception type rather than the +type of a parameter or variable. For example:

      + + + + + +
      +
      %typemap(throws) const char * %{
       rb_raise(rb_eRuntimeError, $1);
       SWIG_fail;
      %}
      void bar() throw (const char *);
      + + + + + +
      + + + + + +

      As can be seen from the generated code below, SWIG generates +an exception handler with the catch block comprising the "throws" +typemap content.

      + + + + + +
      +
      ...
      try {
       bar();
      }
      catch(char const *_e) {
       rb_raise(rb_eRuntimeError, _e);
       SWIG_fail;
      }
      ...
      + + + + + +
      + + + + + +

      Note that if your methods do not have an exception +specification yet they do throw exceptions, SWIG cannot know how to +deal with them. For a neat way to handle these, see the Exception +handling with %exception section.

      + + + + + +

      32.7.6.14 directorin typemap

      + + +

      Converts C++ objects in director +member functions to ruby objects. It is roughly the opposite +of the "in" typemap, making its typemap rule often similar to the "out" +typemap. +

      + + + + + +

      + + + + + +%typemap(directorin) int {
      + + + + + +     $result = INT2NUM($1);
      + + + + + +}
      + + + + + +
      + + + + + +

      The following special variables are available.

      + + + + + +
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      $result Result object +returned to target language.
      $symname Name of +function/method being wrapped
      $1...n Argument being +wrapped
      $1_name Name of the +argument (if provided)
      $1_type The actual C +datatype matched by the typemap.
      $1_ltype The assignable +version of the C datatype matched by the typemap.
      this C++ this, +referring to the class itself.
      + + + + + +
      + + + + + +

      32.7.6.15 directorout typemap

      + + +

      Converts Ruby objects in director +member functions to C++ objects.  It is roughly the opposite +of the "out" typemap, making its rule often similar to the "in" +typemap. +

      + + + + + +

      + + + + + +%typemap(directorout) int {
      + + + + + +   $result = NUM2INT($1);
      + + + + + +}
      + + + + + +
      + + + + + +

      The following special variables are available:

      + + + + + +
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      $symname Name of +function/method being wrapped
      $1...n Argument being +sent to the function
      $1_name Name of the +argument (if provided)
      $1_type The actual C +datatype matched by the typemap.
      $1_ltype The assignable +version of the C datatype matched by the typemap.
      this C++ this, +referring to the class itself.
      + + + + + +
      + + + + + +

      Currently, the directorout nor the out typemap support the +option numoutputs, +but the Ruby module provides that functionality through a %feature +directive.  Thus, a function can be made to return "nothing" +if you do:

      + + + + + +
      %feature("numoutputs","0") +MyClass::function;
      + + + + + +

      This feature can be useful if a function returns a status +code, which you want to discard but still use the typemap to raise an +exception.
      + + + + + +

      + + + + + +

      32.7.6.16 directorargout typemap

      + + +

      Output argument processing in director +member functions.

      + + + + + +
      %typemap(directorargout, +fragment="output_helper") int {
      + + + + + +$result = output_helper( $result, NUM2INT($1) );
      + + + + + +}
      + + + + + +

      The following special variables are available:

      + + + + + +
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      $resultResult that the +director function returns
      $symnamename of the +function/method being wrapped
      $1...nArgument being +sent to the function
      $1_nameName of the +argument (if provided)
      $1_typeThe actual C +datatype matched by the typemap
      $1_ltypeThe assignable +version of the C datatype matched by the typemap
      thisC++ this, +referring to the instance of the class itself
      + + + + + +
      + + + + + +

      32.7.6.17 ret typemap

      + + +

      Cleanup of function return values +

      + + + + + +

      32.7.6.18 globalin typemap

      + + +

      Setting of C global variables +

      + + + + + +

      32.7.7 Typemap variables

      + + +

      +Within a typemap, a number of special variables prefaced with a $ +may appear. A full list of variables can be found in the "Typemaps" chapter. +This is a list of the most common variables: +

      + + + + + +

      $1

      + + + + + +
      A C local variable corresponding to +the actual type specified in the %typemap +directive. For input values, this is a C local variable that is +supposed to hold an argument value. For output values, this is the raw +result that is supposed to be returned to Ruby.
      + + + + + +

      $input

      + + + + + +
      A VALUE holding +a raw Ruby object with an argument or variable value.
      + + + + + +

      $result

      + + + + + +
      A VALUE that +holds the result to be returned to Ruby.
      + + + + + +

      $1_name

      + + + + + +
      The parameter name that was matched.
      + + + + + +

      $1_type

      + + + + + +
      The actual C datatype matched by the +typemap.
      + + + + + +

      $1_ltype

      + + + + + +
      An assignable version of the datatype +matched by the typemap (a type that can appear on the left-hand-side of +a C assignment operation). This type is stripped of qualifiers and may +be an altered version of $1_type. All arguments +and local variables in wrapper functions are declared using this type +so that their values can be properly assigned.
      + + + + + +

      $symname

      + + + + + +
      The Ruby name of the wrapper function +being created.
      + + + + + +

      32.7.8 Useful Functions

      + + +

      When you write a typemap, you usually have to work directly +with Ruby objects. The following functions may prove to be useful. +(These functions plus many more can be found in Programming +Ruby, by David Thomas and Andrew Hunt.) 

      +

      In addition, we list equivalent functions that Swig defines, which +provide a language neutral conversion (these functions are defined for +each swig language supported).  If you are trying to create a swig +file that will work under multiple languages, it is recommended you +stick to the swig functions instead of the native Ruby functions. + That should help you avoid having to rewrite a lot of typemaps +across multiple languages.

      + + + + + + + + + + +

      32.7.8.1 C Datatypes to Ruby Objects

      + + +
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      RUBYSwig
      INT2NUM(long or int) SWIG_From_int(int x) int to Fixnum or Bignum
      INT2FIX(long or int) int to Fixnum (faster than INT2NUM)
      CHR2FIX(char) SWIG_From_char(char x) char to Fixnum
      rb_str_new2(char*) SWIG_FromCharPtrAndSize(char*, size_t) char* to String
      rb_float_new(double) SWIG_From_double(double),
      +SWIG_From_float(float)      		float/double to Float
      + + + + + +
      + + + + + +

      32.7.8.2 Ruby Objects to C Datatypes

      + + +

      Here, while the Ruby versions return the value directly, the SWIG +versions do not, but return a status value to indicate success (SWIG_OK). While more akward to use, this allows you to write typemaps that report more helpful error messages, like:

      +

      +%typemap(in) size_t (int ok)
      + 
      +  ok = SWIG_AsVal_size_t($input, &$1);
      +  if (!SWIG_IsOK(ok)) {
      +    SWIG_exception_fail(SWIG_ArgError(ok), +Ruby_Format_TypeError( "$1_name", "$1_type","$symname", $argnum, $input +));
      +   }
      +
      +}
      +
        
      +
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      int NUM2INT(Numeric)SWIG_AsVal_int(VALUE, int*)
      int FIX2INT(Numeric)SWIG_AsVal_int(VALUE, int*)
      unsigned int NUM2UINT(Numeric)SWIG_AsVal_unsigned_SS_int(VALUE, int*)
      unsigned int FIX2UINT(Numeric)SWIG_AsVal_unsigned_SS_int(VALUE, int*)
      long NUM2LONG(Numeric)SWIG_AsVal_long(VALUE, long*)
      long FIX2LONG(Numeric)SWIG_AsVal_long(VALUE, long*)
      unsigned long FIX2ULONG(Numeric)SWIG_AsVal_unsigned_SS_long(VALUE, unsigned long*)
      char NUM2CHR(Numeric or String)SWIG_AsVal_char(VALUE, int*)
      char * STR2CSTR(String)SWIG_AsCharPtrAndSize(VALUE, char*, size_t, int* alloc)
      char * rb_str2cstr(String, int*length)
      double NUM2DBL(Numeric)(double) SWIG_AsVal_int(VALUE) or similar
      + + + + + +
      + + + + + +

      32.7.8.3 Macros for VALUE

      + + +

      RSTRING_LEN(str)

      + + + + + +
      length of the Ruby string
      + + + + + +

      RSTRING_PTR(str)

      + + + + + +
      pointer to string storage
      + + + + + +

      RARRAY_LEN(arr)

      + + + + + +
      length of the Ruby array
      + + + + + +

      RARRAY(arr)->capa

      + + + + + +
      capacity of the Ruby array
      + + + + + +

      RARRAY_PTR(arr)

      + + + + + +
      pointer to array storage
      + + + + + +

      32.7.8.4 Exceptions

      + + +

      void rb_raise(VALUE exception, const char *fmt, +...)

      + + + + + +
      Raises an exception. The given format +string fmt and remaining arguments are interpreted +as with printf().
      + + + + + +

      void rb_fatal(const char *fmt, ...)

      + + + + + +
      Raises a fatal exception, terminating +the process. No rescue blocks are called, but ensure blocks will be +called. The given format string fmt and remaining +arguments are interpreted as with printf().
      + + + + + +

      void rb_bug(const char *fmt, ...)

      + + + + + +
      Terminates the process immediately -- +no handlers of any sort will be called. The given format string fmt +and remaining arguments are interpreted as with printf(). +You should call this function only if a fatal bug has been exposed.
      + + + + + +

      void rb_sys_fail(const char *msg)

      + + + + + +
      Raises a platform-specific exception +corresponding to the last known system error, with the given string msg. +
      + + + + + +

      VALUE rb_rescue(VALUE (*body)(VALUE), VALUE args, +VALUE(*rescue)(VALUE, VALUE), VALUE rargs)

      + + + + + +
      Executes body +with the given args. If a StandardError +exception is raised, then execute rescue with the +given rargs.
      + + + + + +

      VALUE rb_ensure(VALUE(*body)(VALUE), VALUE args, +VALUE(*ensure)(VALUE), VALUE eargs)

      + + + + + +
      Executes body +with the given args. Whether or not an exception is +raised, execute ensure with the given rargs +after body has completed.
      + + + + + +

      VALUE rb_protect(VALUE (*body)(VALUE), VALUE args, +int *result)

      + + + + + +
      Executes body +with the given args and returns nonzero in result +if any exception was raised.
      + + + + + +

      void rb_notimplement()

      + + + + + +
      Raises a NotImpError +exception to indicate that the enclosed function is not implemented +yet, or not available on this platform.
      + + + + + +

      void rb_exit(int status)

      + + + + + +
      Exits Ruby with the given status. +Raises a SystemExit exception and calls +registered exit functions and finalizers.
      + + + + + +

      void rb_warn(const char *fmt, ...)

      + + + + + +
      Unconditionally issues a warning +message to standard error. The given format string fmt +and remaining arguments are interpreted as with printf(). +
      + + + + + +

      void rb_warning(const char *fmt, ...)

      + + + + + +
      Conditionally issues a warning +message to standard error if Ruby was invoked with the -w +flag. The given format string fmt and remaining +arguments are interpreted as with printf().
      + + + + + +

      32.7.8.5 Iterators

      + + +

      void rb_iter_break()

      + + + + + +
      Breaks out of the enclosing iterator +block.
      + + + + + +

      VALUE rb_each(VALUE obj)

      + + + + + +
      Invokes the each +method of the given obj.
      + + + + + +

      VALUE rb_yield(VALUE arg)

      + + + + + +
      Transfers execution to the iterator +block in the current context, passing arg as an +argument. Multiple values may be passed in an array.
      + + + + + +

      int rb_block_given_p()

      + + + + + +
      Returns true if +yield would execute a block in the current +context; that is, if a code block was passed to the current method and +is available to be called.
      + + + + + +

      VALUE rb_iterate(VALUE (*method)(VALUE), VALUE args, +VALUE (*block)(VALUE, VALUE), VALUE arg2)

      + + + + + +
      Invokes method +with argument args and block block. +A yield from that method will invoke block +with the argument given to yield, and a second +argument arg2.
      + + + + + +

      VALUE rb_catch(const char *tag, VALUE (*proc)(VALUE, +VALUE), VALUE value)

      + + + + + +
      Equivalent to Ruby's catch. +
      + + + + + +

      void rb_throw(const char *tag, VALUE value)

      + + + + + +
      Equivalent to Ruby's throw. +
      + + + + + +

      32.7.9 Typemap Examples

      + + +

      This section includes a few examples of typemaps. For more +examples, you might look at the examples in the Example/ruby +directory.

      + + + + + +

      32.7.10 Converting a Ruby array to a char **

      + + +

      A common problem in many C programs is the processing of +command line arguments, which are usually passed in an array of NULL +terminated strings. The following SWIG interface file allows a Ruby +Array instance to be used as a char ** object.

      + + + + + +
      +
      %module argv

      // This tells SWIG to treat char ** as a special case
      %typemap(in) char ** {
       /* Get the length of the array */
       int size = RARRAY($input)->len; 
       int i;
       $1 = (char **) malloc((size+1)*sizeof(char *));
       /* Get the first element in memory */
       VALUE *ptr = RARRAY($input)->ptr; 
       for (i=0; i < size; i++, ptr++)
       /* Convert Ruby Object String to char* */
       $1[i]= STR2CSTR(*ptr); 
       $1[i]=NULL; /* End of list */
      }

      // This cleans up the char ** array created before 
      // the function call

      %typemap(freearg) char ** {
       free((char *) $1);
      }

      // Now a test function
      %inline %{
      int print_args(char **argv) {
       int i = 0;
       while (argv[i]) {
       printf("argv[%d] = %s\n", i,argv[i]);
       i++;
       }
       return i;
      }
      %}

      + + + + + +
      + + + + + +

      When this module is compiled, the wrapped C function now +operates as follows :

      + + + + + +
      +
      require 'Argv'
      Argv.print_args(["Dave","Mike","Mary","Jane","John"])
      argv[0] = Dave
      argv[1] = Mike
      argv[2] = Mary
      argv[3] = Jane
      argv[4] = John
      + + + + + +
      + + + + + +

      In the example, two different typemaps are used. The "in" +typemap is used to receive an input argument and convert it to a C +array. Since dynamic memory allocation is used to allocate memory for +the array, the "freearg" typemap is used to later release this memory +after the execution of the C function.

      + + + + + +

      32.7.11 Collecting arguments in a hash

      + + +

      Ruby's solution to the "keyword arguments" capability of some +other languages is to allow the programmer to pass in one or more +key-value pairs as arguments to a function. All of those key-value +pairs are collected in a single Hash argument +that's presented to the function. If it makes sense, you might want to +provide similar functionality for your Ruby interface. For example, +suppose you'd like to wrap this C function that collects information +about people's vital statistics:

      + + + + + +
      +
      void setVitalStats(const char *person, int nattributes, const char **names, int *values);
      + + + + + +
      + + + + + +

      and you'd like to be able to call it from Ruby by passing in +an arbitrary number of key-value pairs as inputs, e.g.

      + + + + + +
      +
      setVitalStats("Fred",
       'weight' => 270,
      	'age' => 42
      	)
      + + + + + +
      + + + + + +

      To make this work, you need to write a typemap that expects a +Ruby Hash as its input and somehow extracts the +last three arguments (nattributes, names +and values) needed by your C function. Let's start +with the basics:

      + + + + + +
      +
      %typemap(in) (int nattributes, const char **names, const int *values)
       (VALUE keys_arr, int i, VALUE key, VALUE val) {
      }
      + + + + + +
      + + + + + +

      This %typemap directive tells SWIG that +we want to match any function declaration that has the specified types +and names of arguments somewhere in the argument list. The fact that we +specified the argument names (nattributes, names +and values) in our typemap is significant; this +ensures that SWIG won't try to apply this typemap to other +functions it sees that happen to have a similar declaration with +different argument names. The arguments that appear in the second set +of parentheses (keys_arr, i, key +and val) define local variables that our typemap +will need.

      + + + + + +

      Since we expect the input argument to be a Hash, +let's next add a check for that:

      + + + + + +
      +
      %typemap(in) (int nattributes, const char **names, const int *values)
       (VALUE keys_arr, int i, VALUE key, VALUE val) {
       Check_Type($input, T_HASH);
      }
      + + + + + +
      + + + + + +

      Check_Type() is just a macro (defined +in the Ruby header files) that confirms that the input argument is of +the correct type; if it isn't, an exception will be raised.

      + + + + + +

      The next task is to determine how many key-value pairs are +present in the hash; we'll assign this number to the first typemap +argument ($1). This is a little tricky since the +Ruby/C API doesn't provide a public function for querying the size of a +hash, but we can get around that by calling the hash's size +method directly and converting its result to a C int +value:

      + + + + + +
      +
      %typemap(in) (int nattributes, const char **names, const int *values)
       (VALUE keys_arr, int i, VALUE key, VALUE val) {
       Check_Type($input, T_HASH);
       $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, NULL));
      }
      + + + + + +
      + + + + + +

      So now we know the number of attributes. Next we need to +initialize the second and third typemap arguments (i.e. the two C +arrays) to NULL and set the stage for extracting +the keys and values from the hash:

      + + + + + +
      +
      %typemap(in) (int nattributes, const char **names, const int *values)
       (VALUE keys_arr, int i, VALUE key, VALUE val) {
       Check_Type($input, T_HASH);
       $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, NULL));
       $2 = NULL;
       $3 = NULL;
       if ($1 > 0) {
       $2 = (char **) malloc($1*sizeof(char *));
       $3 = (int *) malloc($1*sizeof(int));
       }
      }
      + + + + + +
      + + + + + +

      There are a number of ways we could extract the keys and +values from the input hash, but the simplest approach is to first call +the hash's keys method (which returns a Ruby array +of the keys) and then start looping over the elements in that array:

      + + + + + +
      +
      %typemap(in) (int nattributes, const char **names, const int *values)
       (VALUE keys_arr, int i, VALUE key, VALUE val) {
       Check_Type($input, T_HASH);
       $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, NULL));
       $2 = NULL;
       $3 = NULL;
       if ($1 > 0) {
       $2 = (char **) malloc($1*sizeof(char *));
       $3 = (int *) malloc($1*sizeof(int));
       keys_arr = rb_funcall($input, rb_intern("keys"), 0, NULL);
       for (i = 0; i < $1; i++) {
       }
      }
      }
      + + + + + +
      + + + + + +

      Recall that keys_arr and i +are local variables for this typemap. For each element in the keys_arr +array, we want to get the key itself, as well as the value +corresponding to that key in the hash:

      + + + + + +
      +
      %typemap(in) (int nattributes, const char **names, const int *values)
       (VALUE keys_arr, int i, VALUE key, VALUE val) {
       Check_Type($input, T_HASH);
       $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, NULL));
       $2 = NULL;
       $3 = NULL;
       if ($1 > 0) {
       $2 = (char **) malloc($1*sizeof(char *));
       $3 = (int *) malloc($1*sizeof(int));
       keys_arr = rb_funcall($input, rb_intern("keys"), 0, NULL);
       for (i = 0; i < $1; i++) {
       key = rb_ary_entry(keys_arr, i);
       val = rb_hash_aref($input, key);
      }
      }
      }
      + + + + + +
      + + + + + +

      To be safe, we should again use the Check_Type() +macro to confirm that the key is a String and the +value is a Fixnum:

      + + + + + +
      +
      %typemap(in) (int nattributes, const char **names, const int *values)
       (VALUE keys_arr, int i, VALUE key, VALUE val) {
       Check_Type($input, T_HASH);
       $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, NULL));
       $2 = NULL;
       $3 = NULL;
       if ($1 > 0) {
       $2 = (char **) malloc($1*sizeof(char *));
       $3 = (int *) malloc($1*sizeof(int));
       keys_arr = rb_funcall($input, rb_intern("keys"), 0, NULL);
       for (i = 0; i < $1; i++) {
       key = rb_ary_entry(keys_arr, i);
       val = rb_hash_aref($input, key);
       Check_Type(key, T_STRING);
       Check_Type(val, T_FIXNUM);
      }
      }
      }
      + + + + + +
      + + + + + +

      Finally, we can convert these Ruby objects into their C +equivalents and store them in our local C arrays:

      + + + + + +
      +
      %typemap(in) (int nattributes, const char **names, const int *values)
       (VALUE keys_arr, int i, VALUE key, VALUE val) {
       Check_Type($input, T_HASH);
       $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, NULL));
       $2 = NULL;
       $3 = NULL;
       if ($1 > 0) {
       $2 = (char **) malloc($1*sizeof(char *));
       $3 = (int *) malloc($1*sizeof(int));
       keys_arr = rb_funcall($input, rb_intern("keys"), 0, NULL);
       for (i = 0; i < $1; i++) {
       key = rb_ary_entry(keys_arr, i);
       val = rb_hash_aref($input, key);
       Check_Type(key, T_STRING);
       Check_Type(val, T_FIXNUM);
       $2[i] = STR2CSTR(key);
       $3[i] = NUM2INT(val);
      }
      }
      }
      + + + + + +
      + + + + + +

      We're not done yet. Since we used malloc() +to dynamically allocate the memory used for the names +and values arguments, we need to provide a +corresponding "freearg" typemap to free that memory so that there is no +memory leak. Fortunately, this typemap is a lot easier to write:

      + + + + + +
      +
      %typemap(freearg) (int nattributes, const char **names, const int *values) {
       free((void *) $2);
       free((void *) $3);
      }
      + + + + + +
      + + + + + +

      All of the code for this example, as well as a sample Ruby +program that uses the extension, can be found in the Examples/ruby/hashargs +directory of the SWIG distribution.

      + + + + + +

      32.7.12 Pointer handling

      + + +

      Occasionally, it might be necessary to convert pointer values +that have been stored using the SWIG typed-pointer representation. +Since there are several ways in which pointers can be represented, the +following two functions are used to safely perform this conversion:

      + + + + + +

      int SWIG_ConvertPtr(VALUE obj, void **ptr, +swig_type_info *ty, int flags)

      + + + + + +
      Converts a Ruby object obj +to a C pointer whose address is ptr (i.e. ptr +is a pointer to a pointer). The third argument, ty, +is a pointer to a SWIG type descriptor structure. If ty +is not NULL, that type information is used to +validate type compatibility and other aspects of the type conversion. +If flags is non-zero, any type errors encountered +during this validation result in a Ruby TypeError +exception being raised; if flags is zero, such type +errors will cause SWIG_ConvertPtr() to return -1 +but not raise an exception. If ty is NULL, +no type-checking is performed.
      + + + + + +

      VALUE SWIG_NewPointerObj(void *ptr, swig_type_info +*ty, int own)

      + + + + + +
      Creates a new Ruby pointer object. +Here, ptr is the pointer to convert, ty +is the SWIG type descriptor structure that describes the type, and own +is a flag that indicates whether or not Ruby should take ownership of +the pointer (i.e. whether Ruby should free this data when the +corresponding Ruby instance is garbage-collected).
      + + + + + +

      Both of these functions require the use of a special SWIG +type-descriptor structure. This structure contains information about +the mangled name of the datatype, type-equivalence information, as well +as information about converting pointer values under C++ inheritance. +For a type of Foo *, the type descriptor +structure is usually accessed as follows:

      + + + + + +
      +
      Foo *foo;
      SWIG_ConvertPtr($input, (void **) &foo, SWIGTYPE_p_Foo, 1);

      VALUE obj;
      obj = SWIG_NewPointerObj(f, SWIGTYPE_p_Foo, 0);
      + + + + + +
      + + + + + +

      In a typemap, the type descriptor should always be accessed +using the special typemap variable $1_descriptor. +For example:

      + + + + + +
      +
      %typemap(in) Foo * {
       SWIG_ConvertPtr($input, (void **) &$1, $1_descriptor, 1);
      }
      + + + + + +
      + + + + + +

      32.7.12.1 Ruby Datatype Wrapping

      + + +

      VALUE Data_Wrap_Struct(VALUE class, void +(*mark)(void *), void (*free)(void *), void *ptr)

      + + + + + +
      Given a pointer ptr +to some C data, and the two garbage collection routines for this data (mark +and free), return a VALUE for +the Ruby object.
      + + + + + +

      VALUE Data_Make_Struct(VALUE class, c-type, +void (*mark)(void *), void (*free)(void *), c-type +*ptr)

      + + + + + +
      Allocates a new instance of a C data +type c-type, assigns it to the pointer ptr, +then wraps that pointer with Data_Wrap_Struct() +as above.
      + + + + + +

      Data_Get_Struct(VALUE obj, c-type, +c-type *ptr)

      + + + + + +
      Retrieves the original C pointer of +type c-type from the data object obj +and assigns that pointer to ptr.
      + + + + + +

      32.7.13 Example: STL Vector to Ruby Array

      + + +

      Another use for macros and type maps is to create a Ruby array +from a STL vector of pointers. In essence, copy of all the pointers in +the vector into a Ruby array. The use of the macro is to make the +typemap so generic that any vector with pointers can use the type map. +The following is an example of how to construct this type of +macro/typemap and should give insight into constructing similar +typemaps for other STL structures:

      + + + + + +
      +
      %define PTR_VECTOR_TO_RUBY_ARRAY(vectorclassname, classname)
      %typemap(out) vectorclassname &, const vectorclassname & {
       VALUE arr = rb_ary_new2($1->size());
       vectorclassname::iterator i = $1->begin(), iend = $1->end();
       for ( ; i!=iend; i++ )
       rb_ary_push(arr, Data_Wrap_Struct(c ## classname.klass, 0, 0, *i));
       $result = arr;
      }
      %typemap(out) vectorclassname, const vectorclassname {
       VALUE arr = rb_ary_new2($1.size());
       vectorclassname::iterator i = $1.begin(), iend = $1.end();
       for ( ; i!=iend; i++ )
       rb_ary_push(arr, Data_Wrap_Struct(c ## classname.klass, 0, 0, *i));
       $result = arr;
      }
      %enddef
      + + + + + +
      + + + + + +

      Note, that the "c ## classname.klass" is +used in the preprocessor step to determine the actual object from the +class name.

      + + + + + +

      To use the macro with a class Foo, the following is used:

      + + + + + +
      +
      PTR_VECTOR_TO_RUBY_ARRAY(vector<foo *="">, Foo)
      + + + + + +
      + + + + + +

      It is also possible to create a STL vector of Ruby objects:

      + + + + + +
      +
      %define RUBY_ARRAY_TO_PTR_VECTOR(vectorclassname, classname)
      %typemap(in) vectorclassname &, const vectorclassname & {
       Check_Type($input, T_ARRAY);
       vectorclassname *vec = new vectorclassname;
       int len = RARRAY($input)->len;
       for (int i=0; i!=len; i++) {
       VALUE inst = rb_ary_entry($input, i);
       //The following _should_ work but doesn't on HPUX
       // Check_Type(inst, T_DATA);
       classname *element = NULL;
       Data_Get_Struct(inst, classname, element);
       vec->push_back(element);
       }
       $1 = vec;
      }

      %typemap(freearg) vectorclassname &, const vectorclassname & {
       delete $1;
      }
      %enddef
      + + + + + +
      + + + + + +

      It is also possible to create a Ruby array from a vector of +static data types:

      + + + + + +
      +
      %define VECTOR_TO_RUBY_ARRAY(vectorclassname, classname)
      %typemap(out) vectorclassname &, const vectorclassname & {
       VALUE arr = rb_ary_new2($1->size()); 
       vectorclassname::iterator i = $1->begin(), iend = $1->end();
       for ( ; i!=iend; i++ )
       rb_ary_push(arr, Data_Wrap_Struct(c ## classname.klass, 0, 0, &(*i)));
       $result = arr;
      }
      %typemap(out) vectorclassname, const vectorclassname {
       VALUE arr = rb_ary_new2($1.size()); 
       vectorclassname::iterator i = $1.begin(), iend = $1.end();
       for ( ; i!=iend; i++ )
       rb_ary_push(arr, Data_Wrap_Struct(c ## classname.klass, 0, 0, &(*i)));
       $result = arr;
      }
      %enddef
      + + + + + +
      + + + + + +
      + + + + + +Note that this is mostly an example of typemaps. If you want to use the +STL with ruby, you are advised to use the standard swig STL library, +which does much more than this.  Refer to the section called +the C++ Standard Template Library.
      + + + + + +

      32.8 Docstring Features

      + + +

      +Using ri and rdoc web pages in Ruby libraries is a common practice. +Given the way that SWIG generates the extensions by default, your users +will normally not get +any documentation for it, even if they run 'rdoc' on the resulting .c +or .cxx file.

      + + + + + +

      The features described in this section make it easy for you to +add +rdoc strings to your modules, functions and methods that can then be +read by Ruby's rdoc tool to generate html web pages, ri documentation, +Windows chm file and an .xml description.

      + + + + + +

      rdoc can then be run from a console or shell window on a swig +generated file. 

      + + + + + +

      For example, to generate html web pages from a C++ file, you'd +do: 

      + + + + + +
      +$ +rdoc -E cxx=c -f html file_wrap.cxx
      + + + + + +

      To +generate ri documentation from a c wrap file, you could do:

      + + + + + +
      $ rdoc +-r file_wrap.c +
      + + + + + +

      32.8.1 Module docstring

      + + +

      +Ruby allows a docstring at the beginning of the file +before any other statements, and it is typically used to give a +general description of the entire module. SWIG supports this by +setting an option of the %module directive. For +example: +

      + + + + + +
      +
      %module(docstring="This is the example module's docstring") example
      + + + + + +
      + + + + + +

      +When you have more than just a line or so then you can retain the easy +readability of the %module directive by using a +macro. For example: +

      + + + + + +
      +
      %define DOCSTRING
      "The `XmlResource` class allows program resources defining menus, 
      layout of controls on a panel, etc. to be loaded from an XML file."
      %enddef

      %module(docstring=DOCSTRING) xrc
      + + + + + +
      + + + + + +

      32.8.2 %feature("autodoc")

      + + +

      Since SWIG does know everything about the function it wraps, +it is possible to generate an rdoc containing the parameter types, +names +and default values. Since Ruby ships with one of the best documentation +systems of any language, it makes sense to take advantage of it. +

      + + + + + +

      SWIG's Ruby module provides support for the "autodoc" +feature, +which when attached to a node in the parse tree will cause an rdoc +comment +to be generated in the wrapper file that includes the name of the +function, parameter +names, default values if any, and return type if any. There are also +several options for autodoc controlled by the value given to the +feature, described below. +

      + + + + + +

      32.8.2.1 %feature("autodoc", "0")

      + + +

      +When the "0" option is given then the types of the parameters will +not be included in the autodoc string. For +example, given +this function prototype: +

      + + + + + +
      +
      %feature("autodoc", "0");
      bool function_name(int x, int y, Foo* foo=NULL, Bar* bar=NULL);
      + + + + + +
      + + + + + +

      +Then Ruby code like this will be generated: +

      + + + + + +
      +
      function_name(x, y, foo=nil, bar=nil) -> bool
       ...
      + + + + + +
      + + + + + +

      32.8.2.2 %feature("autodoc", "1")

      + + +

      +When the "1" option is used then the parameter types will +be used in the rdoc string. In addition, an attempt is made to +simplify the type name such that it makes more sense to the Ruby +user. Pointer, reference and const info is removed, +%rename's are evaluated, etc. (This is not always +successful, but works most of the time. See the next section for what +to do when it doesn't.) Given the example above, then turning on the +parameter types with the "1" option will result in rdoc code like +this: +

      + + + + + +
      +
      function_name(int x, int y, Foo foo=nil, Bar bar=nil) -> bool
       ...
      + + + + + +
      + + + + + +

      32.8.2.3 %feature("autodoc", "2")

      + + +

      +When the "2" option is used then the parameter types will not +be +used in the rdoc string. However, they will be listed in full after the +function.  Given the example above, then turning on the +parameter types with the "2" option will result in Ruby code like +this: +

      + + + + + +

      32.8.2.4 %feature("autodoc", "3")

      + + +

      +When the "3" option is used then the function will be documented using +a combination of "1" and "2" above.  Given the example above, +then turning on the +parameter types with the "2" option will result in Ruby code like +this: +

      + + + + + +
      +
      function_name(int x, int y, Foo foo=nil, Bar bar=nil) -> bool

      Parameters:
      	x - int
      	y - int
      	foo - Foo
      	bar - Bar
      + + + + + +
      + + + + + +

      32.8.2.5 %feature("autodoc", "docstring")

      + + +

      +Finally, there are times when the automatically generated autodoc +string will make no sense for a Ruby programmer, particularly when a +typemap is involved. So if you give an explicit value for the autodoc +feature then that string will be used in place of the automatically +generated string. For example: +

      + + + + + +
      +
      %feature("autodoc", "GetPosition() -> (x, y)") GetPosition;
      void GetPosition(int* OUTPUT, int* OUTPUT);
      + + + + + +
      + + + + + +

      32.8.3 %feature("docstring")

      + + +

      +In addition to the autodoc strings described above, you can also +attach any arbitrary descriptive text to a node in the parse tree with +the "docstring" feature. When the proxy module is generated then any +docstring associated with classes, function or methods are output. +If an item already has an autodoc string then it is combined with the +docstring and they are output together.

      + + + + + +

      32.9 Advanced Topics

      + + +

      32.9.1 Operator overloading

      + + +

      SWIG allows operator overloading with, by using the %extend +or %rename commands in SWIG and the following +operator names (derived from Python):

      + + + + + +
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      General
      __repr__ inspect
      __str__ to_s
      __cmp__ <=>
      __hash__ hash
      __nonzero__ nonzero?
      Callable
      __call__ call
      Collection
      __len__ length
      __getitem__ []
      __setitem__ []=
      Numeric
      __add__ +
      __sub__ -
      __mul__ *
      __div__ /
      __mod__ %
      __divmod__ divmod
      __pow__ **
      __lshift__ <<
      __rshift__ >>
      __and__ &
      __xor__ ^
      __or__ |
      __neg__ -@
      __pos__ +@
      __abs__ abs
      __invert__ ~
      __int__ to_i
      __float__ to_f
      __coerce__ coerce
      Additions in 1.3.13
      __lt__ <
      __le__ <=
      __eq__ ==
      __gt__ >
      __ge__ >=
      + + + + + +
      + + + + + +

      Note that although SWIG supports the __eq__ +magic method name for defining an equivalence operator, there is no +separate method for handling inequality since Ruby +parses the expression a != b as !(a == b). +

      + + + + + +

      32.9.2 Creating Multi-Module Packages

      + + +

      The chapter on Working +with Modules discusses the basics of creating multi-module +extensions with SWIG, and in particular the considerations for sharing +runtime type information among the different modules.

      + + + + + +

      As an example, consider one module's interface file (shape.i) +that defines our base class:

      + + + + + +
      +
      %module shape

      %{
      #include "Shape.h"
      %}

      class Shape {
      protected:
       double xpos;
       double ypos;
      protected:
       Shape(double x, double y);
      public:
       double getX() const;
       double getY() const;
      };
      + + + + + +
      + + + + + +

      We also have a separate interface file (circle.i) +that defines a derived class:

      + + + + + +
      +
      %module circle

      %{
      #include "Shape.h"
      #include "Circle.h"
      %}

      // Import the base class definition from Shape module
      %import shape.i

      class Circle : public Shape {
      protected:
       double radius;
      public:
       Circle(double x, double y, double r);
       double getRadius() const;
      };
      + + + + + +
      + + + + + +

      We'll start by building the Shape +extension module:

      + + + + + +
      +
      $ swig -c++ -ruby shape.i
+
      + + + + + +
      + + + + + +

      SWIG generates a wrapper file named shape_wrap.cxx. +To compile this into a dynamically loadable extension for Ruby, prepare +an extconf.rb script using this template:

      + + + + + +
      +
      require 'mkmf'

      # Since the SWIG runtime support library for Ruby
      # depends on the Ruby library, make sure it's in the list
      # of libraries.
      $libs = append_library($libs, Config::CONFIG['RUBY_INSTALL_NAME'])

      # Create the makefile
      create_makefile('shape')
      + + + + + +
      + + + + + +

      Run this script to create a Makefile +and then type make to build the shared library:

      + + + + + +
      +
      $ ruby extconf.rb
      creating Makefile
      $ make
      g++ -fPIC -g -O2 -I. -I/usr/local/lib/ruby/1.7/i686-linux \
      -I. -c shape_wrap.cxx
      gcc -shared -L/usr/local/lib -o shape.so shape_wrap.o -L. \
      -lruby -lruby -lc
      + + + + + +
      + + + + + +

      Note that depending on your installation, the outputs may be +slightly different; these outputs are those for a Linux-based +development environment. The end result should be a shared library +(here, shape.so) containing the extension module +code. Now repeat this process in a separate directory for the Circle +module:

      + + + + + +
        + + + + + +
      1. Run SWIG to generate the wrapper code (circle_wrap.cxx); +
        2. + + + + + +
      2. Write an extconf.rb script that your +end-users can use to create a platform-specific Makefile +for the extension;
        3. + + + + + +
      3. Build the shared library for this extension by typing make. +
        4. + + + + + +
      + + + + + +

      Once you've built both of these extension modules, you can +test them interactively in IRB to confirm that the Shape +and Circle modules are properly loaded and +initialized:

      + + + + + +
      +
      $ irb
      irb(main):001:0> require 'shape'
      true
      irb(main):002:0> require 'circle'
      true
      irb(main):003:0> c = Circle::Circle.new(5, 5, 20)
      #<Circle::Circle:0xa097208>
      irb(main):004:0> c.kind_of? Shape::Shape
      true
      irb(main):005:0> c.getX()
      5.0
      + + + + + +
      + + + + + +

      32.9.3 Specifying Mixin Modules

      + + +

      The Ruby language doesn't support multiple inheritance, but +it does allow you to mix one or more modules into a class using Ruby's include +method. For example, if you have a Ruby class that defines an each +instance method, e.g.

      + + + + + +
      +
      class Set
       def initialize
       @members = []
       end
       
       def each
       @members.each { |m| yield m }
       end
      end
      + + + + + +
      + + + + + +

      then you can mix-in Ruby's Enumerable +module to easily add a lot of functionality to your class:

      + + + + + +
      +
      class Set
       include Enumerable
      def initialize
      @members = []
      end
      def each
      @members.each { |m| yield m }
      end
      end
      + + + + + +
      + + + + + +

      To get the same benefit for your SWIG-wrapped classes, you +can use the %mixin directive to specify the names +of one or more modules that should be mixed-in to a class. For the +above example, the SWIG interface specification might look like this:

      + + + + + +
      +
      %mixin Set "Enumerable";

      class Set {
      public:
       // Constructor
       Set();
       
       // Iterates through set members
       void each();
      };
      + + + + + +
      + + + + + +

      Multiple modules can be mixed into a class by providing a +comma-separated list of module names to the %mixin +directive, e.g.

      + + + + + +
      +
      %mixin Set "Fee,Fi,Fo,Fum";
      + + + + + +
      + + + + + +

      Note that the %mixin directive is +implemented using SWIG's "features" mechanism and so the same name +matching rules used for other kinds of features apply (see the chapter +on "Customization +Features") for more details).

      + + + + + +

      32.10 Memory Management

      + + +

      One of the most common issues in generating SWIG bindings for +Ruby is proper memory management. The key to proper memory management +is clearly defining whether a wrapper Ruby object owns the underlying C +struct or C++ class. There are two possibilities:

      + + + + + +
        + + + + + +
      • The Ruby object is responsible for freeing the C struct or +C++ object
        • + + + + + +
      • The Ruby object should not free the C struct or C++ object +because it will be freed by the underlying C or C++ code
        • + + + + + +
      + + + + + +

      To complicate matters, object ownership may transfer from Ruby +to C++ (or vice versa) depending on what function or methods are +invoked. Clearly, developing a SWIG wrapper requires a thorough +understanding of how the underlying library manages memory.

      + + + + + +

      32.10.1 Mark and Sweep Garbage Collector

      + + +

      Ruby uses a mark and sweep garbage collector. When the garbage +collector runs, it finds all the "root" objects, including local +variables, global variables, global constants, hardware registers and +the C stack. For each root object, the garbage collector sets its mark +flag to true and calls rb_gc_mark on the object. +The job of rb_gc_mark is to recursively mark all +the objects that a Ruby object has a reference to (ignoring those +objects that have already been marked). Those objects, in turn, may +reference other objects. This process will continue until all active +objects have been "marked." After the mark phase comes the sweep phase. +In the sweep phase, all objects that have not been marked will be +garbage collected. For more information about the Ruby garbage +collector please refer to http://rubygarden.org/ruby/ruby?GCAndExtensions.

      + + + + + +

      The Ruby C/API provides extension developers two hooks into +the garbage collector - a "mark" function and a "sweep" function. By +default these functions are set to NULL.

      + + + + + +

      If a C struct or C++ class references any other Ruby objects, +then it must provide a "mark" function. The "mark" function should +identify any referenced Ruby objects by calling the rb_gc_mark function +for each one. Unsurprisingly, this function will be called by the Ruby +garbage during the "mark" phase.

      + + + + + +

      During the sweep phase, Ruby destroys any unused objects. If +any memory has been allocated in creating the underlying C struct or +C++ struct, then a "free" function must be defined that deallocates +this memory.

      + + + + + +

      32.10.2 Object Ownership

      + + +

      As described above, memory management depends on clearly +defining who is responsible for freeing the underlying C struct or C++ +class. If the Ruby object is responsible for freeing the C++ object, +then a "free" function must be registered for the object. If the Ruby +object is not responsible for freeing the underlying memory, then a +"free" function must not be registered for the object.

      + + + + + +

      For the most part, SWIG takes care of memory management +issues. The rules it uses are:

      + + + + + +
        + + + + + +
      • When calling a C++ object's constructor from Ruby, SWIG +will assign a "free" function thereby making the Ruby object +responsible for freeing the C++ object
        • + + + + + +
      • When calling a C++ member function that returns a pointer, +SWIG will not assign a "free" function thereby making the underlying +library responsible for freeing the object.
        • + + + + + +
      + + + + + +

      To make this clearer, let's look at an example. Assume we have +a Foo and a Bar class.

      + + + + + +
      +
      /* File "RubyOwernshipExample.h" */

      class Foo
      {
      public:
       Foo() {}
       ~Foo() {}
      };

      class Bar
      {
       Foo *foo_;
      public:
       Bar(): foo_(new Foo) {}
       ~Bar() { delete foo_; }
       Foo* get_foo() { return foo_; }
       Foo* get_new_foo() { return new Foo; }
       void set_foo(Foo *foo) { delete foo_; foo_ = foo; }
      };

      + + + + + +
      + + + + + +

      First, consider this Ruby code:

      + + + + + +
      +
      foo = Foo.new
      + + + + + +
      + + + + + +

      In this case, the Ruby code calls the underlying Foo +C++ constructor, thus creating a new foo object. +By default, SWIG will assign the new Ruby object a "free" function. +When the Ruby object is garbage collected, the "free" function will be +called. It in turn will call Foo's destructor.

      + + + + + +

      Next, consider this code:

      + + + + + +
      +
      bar = Bar.new
      foo = bar.get_foo()
      + + + + + +
      + + + + + +

      In this case, the Ruby code calls a C++ member function, get_foo. +By default, SWIG will not assign the Ruby object a "free" function. +Thus, when the Ruby object is garbage collected the underlying C++ foo +object is not affected.

      + + + + + +

      Unfortunately, the real world is not as simple as the examples +above. For example:

      + + + + + +
      +
      bar = Bar.new
      foo = bar.get_new_foo()
      + + + + + +
      + + + + + +

      In this case, the default SWIG behavior for calling member +functions is incorrect. The Ruby object should assume ownership of the +returned object. This can be done by using the %newobject directive. +See +Object ownership and %newobject for more information.

      + + + + + +

      The SWIG default mappings are also incorrect in this case:

      + + + + + +
      +
      foo = Foo.new
      bar = Bar.new
      bar.set_foo(foo)
      + + + + + +
      + + + + + +

      Without modification, this code will cause a segmentation +fault. When the Ruby foo object goes out of +scope, it will free the underlying C++ foo +object. However, when the Ruby bar object goes out of scope, it will +call the C++ bar destructor which will also free the C++ foo +object. The problem is that object ownership is transferred from the +Ruby object to the C++ object when the set_foo +method is called. This can be done by using the special DISOWN type +map, which was added to the Ruby bindings in SWIG-1.3.26.

      + + + + + +

      Thus, a correct SWIG interface file correct mapping for these +classes is:

      + + + + + +
      +
      /* File RubyOwnershipExample.i */

      %module RubyOwnershipExample

      %{
      #include "RubyOwnershipExample.h"
      %}

      class Foo
      {
      public:
       Foo();
       ~Foo();
      };

      class Bar
      {
       Foo *foo_;
      public:
       Bar();
       ~Bar();
       Foo* get_foo();

       %newobject get_new_foo;
       Foo* get_new_foo();

       %apply SWIGTYPE *DISOWN {Foo *foo};
       void set_foo(Foo *foo);
       %clear Foo *foo;
      };

      + + + + + +
      + + + + + +
      + + + + + +

      This code can be seen in swig/examples/ruby/tracking.

      + + + + + +
      + + + + + +

      32.10.3 Object Tracking

      + + +

      The remaining parts of this section will use the class library +shown below to illustrate different memory management techniques. The +class library models a zoo and the animals it contains.

      + + + + + +
      +
      %module zoo

      %{
      #include <string>
      #include <vector>

      #include "zoo.h"
      %}

      class Animal
      {
      private:
       typedef std::vector<Animal*> AnimalsType;
       typedef AnimalsType::iterator IterType;
      protected:
       AnimalsType animals;
      protected:
       std::string name_;
      public:
       // Construct an animal with this name
       Animal(const char* name) : name_(name) {}
       
       // Return the animal's name
       const char* get_name() const { return name.c_str(); }
      };

      class Zoo
      {
      protected:
       std::vector<animal *=""> animals;
       
      public:
       // Construct an empty zoo
       Zoo() {}
       
       /* Create a new animal. */
       static Animal* Zoo::create_animal(const char* name)
       {
       return new Animal(name);
       }

       // Add a new animal to the zoo
       void add_animal(Animal* animal) {
       animals.push_back(animal); 
       }

       Animal* remove_animal(size_t i) {
       Animal* result = this->animals[i];
       IterType iter = this->animals.begin();
       std::advance(iter, i);
       this->animals.erase(iter);

       return result;
       }
       
       // Return the number of animals in the zoo
       size_t get_num_animals() const {
       return animals.size(); 
       }
       
       // Return a pointer to the ith animal
       Animal* get_animal(size_t i) const {
       return animals[i]; 
       }
      };

      + + + + + +
      + + + + + +

      Let's say you SWIG this code and then run IRB:
      + + + + + +

      + + + + + +
      +
      $ irb
      irb(main):001:0> require 'example'
      => true

      irb(main):002:0> tiger1 = Example::Animal.new("tiger1")
      => #<Example::Animal:0x2be3820>

      irb(main):004:0> tiger1.get_name()
      => "tiger1"

      irb(main):003:0> zoo = Example::Zoo.new()
      => #<Example::Zoo:0x2be0a60>

      irb(main):006:0> zoo.add_animal(tiger)
      => nil

      irb(main):007:0> zoo.get_num_animals()
      => 1

      irb(main):007:0> tiger2 = zoo.remove_animal(0)
      => #<Example::Animal:0x2bd4a18>

      irb(main):008:0> tiger2.get_name()
      => "tiger1"

      irb(main):009:0> tiger1.equal?(tiger2)
      => false

      + + + + + +
      + + + + + +

      Pay particular attention to the code tiger1.equal?(tiger2). +Note that the two Ruby objects are not the same - but they reference +the same underlying C++ object. This can cause problems. For example:
      + + + + + +

      + + + + + +
      +
      irb(main):010:0> tiger1 = nil
      => nil

      irb(main):011:0> GC.start
      => nil

      irb(main):012:0> tiger2.get_name()
      (irb):12: [BUG] Segmentation fault

      + + + + + +
      + + + + + +

      After the the garbage collector runs, as a result of our call +to GC.start, callingtiger2.get_name() +causes a segmentation fault. The problem is that when tiger1 +is garbage collected, it frees the underlying C++ object. Thus, when tiger2 +calls the get_name() method it invokes it on a +destroyed object.

      + + + + + +

      This problem can be avoided if SWIG enforces a one-to-one +mapping between Ruby objects and C++ classes. This can be done via the +use of the %trackobjects functionality available +in SWIG-1.3.26. and later.

      + + + + + +

      When the %trackobjects is turned on, +SWIG automatically keeps track of mappings between C++ objects and Ruby +objects. Note that enabling object tracking causes a slight performance +degradation. Test results show this degradation to be about 3% to 5% +when creating and destroying 100,000 animals in a row.

      + + + + + +

      Since %trackobjects is implemented as a %feature, +it uses the same name matching rules as other kinds of features (see +the chapter on +"Customization Features") . Thus it can be applied on a +class-by-class basis if needed. To fix the example above:

      + + + + + +
      + + + + + +
      +
      %module example

      %{
      #include "example.h"
      %}

      /* Tell SWIG that create_animal creates a new object */
      %newobject Zoo::create_animal;

      /* Tell SWIG to keep track of mappings between C/C++ structs/classes. */
      %trackobjects;

      %include "example.h"
      + + + + + +
      + + + + + +

      When this code runs we see:
      + + + + + +
      + + + + + +

      + + + + + +
      +
      $ irb
      irb(main):001:0> require 'example'
      => true

      irb(main):002:0> tiger1 = Example::Animal.new("tiger1")
      => #<Example::Animal:0x2be37d8>

      irb(main):003:0> zoo = Example::Zoo.new()
      => #<Example::Zoo:0x2be0a18>

      irb(main):004:0> zoo.add_animal(tiger1)
      => nil

      irb(main):006:0> tiger2 = zoo.remove_animal(0)
      => #<Example::Animal:0x2be37d8>

      irb(main):007:0> tiger1.equal?(tiger2)
      => true

      irb(main):008:0> tiger1 = nil
      => nil

      irb(main):009:0> GC.start
      => nil

      irb(main):010:0> tiger.get_name()
      => "tiger1"
      irb(main):011:0>

      + + + + + +
      + + + + + +

      For those who are interested, object tracking is implemented +by storing Ruby objects in a hash table and keying them on C++ +pointers. The underlying API is:
      + + + + + +

      + + + + + +
      +
      static void SWIG_RubyAddTracking(void* ptr, VALUE object);
      static VALUE SWIG_RubyInstanceFor(void* ptr) ;
      static void SWIG_RubyRemoveTracking(void* ptr);
      static void SWIG_RubyUnlinkObjects(void* ptr);
      + + + + + +
      + + + + + +

      When an object is created, SWIG will automatically call the SWIG_RubyAddTracking +method. Similarly, when an object is deleted, SWIG will call the SWIG_RubyRemoveTracking. +When an object is returned to Ruby from C++, SWIG will use the SWIG_RubyInstanceFor +method to ensure a one-to-one mapping from Ruby to C++ objects. Last, +the RubyUnlinkObjects method unlinks a Ruby +object from its underlying C++ object.

      + + + + + +

      In general, you will only need to use the SWIG_RubyInstanceFor, +which is required for implementing mark functions as shown below. +However, if you implement your own free functions (see below) you may +also have to call the SWIG_RubyRemoveTracking and RubyUnlinkObjects +methods.

      + + + + + +

      32.10.4 Mark Functions

      + + +

      With a bit more testing, we see that our class library still +has problems. For example:
      + + + + + +

      + + + + + +
      +
      $ irb
      irb(main):001:0> require 'example'
      => true

      irb(main):002:0> tiger1 = Example::Animal.new("tiger1")
      => #<Example::Animal:0x2bea6a8>

      irb(main):003:0> zoo = Example::Zoo.new()
      => #<Example::Zoo:0x2be7960>

      irb(main):004:0> zoo.add_animal(tiger1)
      => nil

      irb(main):007:0> tiger1 = nil
      => nil

      irb(main):007:0> GC.start
      => nil

      irb(main):005:0> tiger2 = zoo.get_animal(0)
      (irb):12: [BUG] Segmentation fault
      + + + + + +
      + + + + + +

      The problem is that Ruby does not know that the zoo +object contains a reference to a Ruby object. Thus, when Ruby garbage +collects tiger1 +it frees the underlying C++ object.

      + + + + + +

      This can be fixed by implementing a mark +function as described above in the Mark +and Sweep Garbage Collector section. You can specify a mark +function by using the %markfunc directive. Since +the %markfunc directive is implemented using +SWIG's' "features" mechanism it uses the same name matching rules as +other kinds of features (see the chapter on "Customization +Features" for more details).

      + + + + + +

      A mark function takes a single argument, +which is a pointer to the C++ object being marked; it should, in turn, +call rb_gc_mark() for any instances that are +reachable from the current object. The mark function for our +Zoo class should therefore loop over all of the C++ animal +objects in the zoo object, look up their Ruby object equivalent, and +then call rb_gc_mark(). One possible +implementation is:

      + + + + + +
      +
      %module example

      %{
      #include "example.h"
      %}

      /* Keep track of mappings between C/C++ structs/classes
       and Ruby objects so we can implement a mark function. */
      %trackobjects;

      /* Specify the mark function */
      %markfunc Zoo "mark_Zoo";

      %include "example.h"

      %header %{

      static void mark_Zoo(void* ptr) {
       Zoo* zoo = (Zoo*) ptr;

       /* Loop over each object and tell the garbage collector
       that we are holding a reference to them. */
       int count = zoo->get_num_animals();

       for(int i = 0; i < count; ++i) {
       Animal* animal = zoo->get_animal(i);
       VALUE object = SWIG_RubyInstanceFor(animal);

       if (object != Qnil) {
       rb_gc_mark(object);
       }
       }
      }
      %}

      + + + + + +
      + + + + + +

      Note the mark function is dependent on +the SWIG_RUBY_InstanceFor method, and thus +requires that %trackobjects is enabled. For more +information, please refer to the track_object.i test case in the SWIG +test suite.

      + + + + + +

      When this code is compiled we now see:

      + + + + + +
      +
      $ irb
      irb(main):002:0> tiger1=Example::Animal.new("tiger1")
      => #<Example::Animal:0x2be3bf8>

      irb(main):003:0> Example::Zoo.new()
      => #<Example::Zoo:0x2be1780>

      irb(main):004:0> zoo = Example::Zoo.new()
      => #<Example::Zoo:0x2bde9c0>

      irb(main):005:0> zoo.add_animal(tiger1)
      => nil

      irb(main):009:0> tiger1 = nil
      => nil

      irb(main):010:0> GC.start
      => nil
      irb(main):014:0> tiger2 = zoo.get_animal(0)
      => #<Example::Animal:0x2be3bf8>

      irb(main):015:0> tiger2.get_name()
      => "tiger1"
      irb(main):016:0>

      + + + + + +
      + + + + + +
      + + + + + +

      This code can be seen in swig/examples/ruby/mark_function.

      + + + + + +

      32.10.5 Free Functions

      + + +

      By default, SWIG creates a "free" function that is called when +a Ruby object is garbage collected. The free function simply calls the +C++ object's destructor.

      + + + + + +

      However, sometimes an appropriate destructor does not exist or +special processing needs to be performed before the destructor is +called. Therefore, SWIG allows you to manually specify a "free" +function via the use of the %freefunc directive. +The %freefunc directive is implemented using +SWIG's' "features" mechanism and so the same name matching rules used +for other kinds of features apply (see the chapter on "Customization +Features") for more details).

      + + + + + +

      IMPORTANT ! - If you define your own free function, then you +must ensure that you call the underlying C++ object's destructor. In +addition, if object tracking is activated for the object's class, you +must also call the SWIG_RubyRemoveTracking +function (of course call this before you destroy the C++ object). Note +that it is harmless to call this method if object tracking if off so it +is advised to always call it.

      + + + + + +

      Note there is a subtle interaction between object ownership +and free functions. A custom defined free function will only be called +if the Ruby object owns the underlying C++ object. This also to Ruby +objects which are created, but then transfer ownership to C++ objects +via the use of the disown typemap described +above.

      + + + + + +

      To show how to use the %freefunc +directive, let's slightly change our example. Assume that the zoo +object is responsible for freeing animal that it contains. This means +that the Zoo::add_animal +function should be marked with a DISOWN typemap +and the destructor should be updated as below::

      + + + + + +
      +
      Zoo::~Zoo() {
       IterType iter = this->animals.begin();
       IterType end = this->animals.end();

       for(iter; iter != end; ++iter) {
       Animal* animal = *iter;
       delete animal;
       }
      }
      + + + + + +
      + + + + + +

      When we use these objects in IRB we see:

      + + + + + +
      +
      $irb
      irb(main):002:0> require 'example'
      => true

      irb(main):003:0> zoo = Example::Zoo.new()
      => #<Example::Zoo:0x2be0fe8>

      irb(main):005:0> tiger1 = Example::Animal.new("tiger1")
      => #<Example::Animal:0x2bda760>

      irb(main):006:0> zoo.add_animal(tiger1)
      => nil

      irb(main):007:0> zoo = nil
      => nil

      irb(main):008:0> GC.start
      => nil

      irb(main):009:0> tiger1.get_name()
      (irb):12: [BUG] Segmentation fault

      + + + + + +
      + + + + + +

      The error happens because the C++ animal +object is freed when the zoo object is freed. +Although this error is unavoidable, we can at least prevent the +segmentation fault. To do this requires enabling object tracking and +implementing a custom free function that calls the SWIG_RubyUnlinkObjects +function for each animal object that is destroyed. The SWIG_RubyUnlinkObjects +function notifies SWIG that a Ruby object's underlying C++ object is no +longer valid. Once notified, SWIG will intercept any calls from the +existing Ruby object to the destroyed C++ object and raise an exception.
      + + + + + +

      + + + + + +
      +
      %module example

      %{
      #include "example.h"
      %}

      /* Specify that ownership is transferred to the zoo
      	when calling add_animal */
      %apply SWIGTYPE *DISOWN { Animal* animal };

      /* Track objects */
      %trackobjects;

      /* Specify the mark function */
      %freefunc Zoo "free_Zoo";

      %include "example.h"

      %header %{
       static void free_Zoo(void* ptr) {
       Zoo* zoo = (Zoo*) ptr;

       /* Loop over each animal */
       int count = zoo->get_num_animals();

       for(int i = 0; i < count; ++i) {
       /* Get an animal */
       Animal* animal = zoo->get_animal(i);

       /* Unlink the Ruby object from the C++ object */
       SWIG_RubyUnlinkObjects(animal);

       /* Now remove the tracking for this animal */
       SWIG_RubyRemoveTracking(animal);
       }

       /* Now call SWIG_RubyRemoveTracking for the zoo */
       SWIG_RubyRemoveTracking(ptr);
       
       /* Now free the zoo which will free the animals it contains */
       delete zoo;
       }
      %}
      + + + + + +
      + + + + + +

      Now when we use these objects in IRB we see:

      + + + + + +
      +
      $irb
      irb(main):002:0> require 'example'
      => true

      irb(main):003:0> zoo = Example::Zoo.new()
      => #<Example::Zoo:0x2be0fe8>

      irb(main):005:0> tiger1 = Example::Animal.new("tiger1")
      => #<Example::Animal:0x2bda760>

      irb(main):006:0> zoo.add_animal(tiger1)
      => nil

      irb(main):007:0> zoo = nil
      => nil

      irb(main):008:0> GC.start
      => nil

      irb(main):009:0> tiger1.get_name()
      RuntimeError: This Animal * already released
       from (irb):10:in `get_name'
       from (irb):10
      irb(main):011:0>
      + + + + + +
      + + + + + +

      Notice that SWIG can now detect the underlying C++ object has +been freed, and thus raises a runtime exception.

      + + + + + +

      This code can be seen in swig/examples/ruby/free_function.

      + + + + + +

      32.10.6 Embedded Ruby and the C++ Stack

      + + +

      As has been said, the Ruby GC runs and marks objects before +its +sweep phase.  When the garbage collector is called, it will +also +try to mark any Ruby objects (VALUE) it finds in the machine registers +and in the C++ stack.

      + + + + + +

      The stack is basically the history of the functions that have +been +called and also contains local variables, such as the ones you define +whenever you do inside a function:

      + + + + + +
      VALUE obj;
      + + + + + +

      For ruby to determine where its stack space begins, during +initialization a normal Ruby interpreter will call the ruby_init() +function which in turn will call a function called Init_stack or +similar.  This function will store a pointer to the location +where +the stack points at at that point in time.

      + + + + + +

      ruby_init() is presumed to always be called within the main() +function of your program and whenever the GC is called, ruby will +assume that the memory between the current location in memory and the +pointer that was stored previously represents the stack, which may +contain local (and temporary) VALUE ruby objects.   Ruby will +then be careful not to remove any of those objects in that location.

      + + + + + +

      So far so good.  For a normal Ruby session, all the +above is +completely transparent and magic to the extensions developer. +  

      + + + + + +

      However, with an embedded Ruby, it may not always be possible +to +modify main() to make sure ruby_init() is called there.   As +such, +ruby_init() will likely end up being called from within some other +function.  This can lead Ruby to measure incorrectly where the +stack begins and can result in Ruby incorrectly collecting +those +temporary VALUE objects that are created once another function +is +called.  The end result: random crashes and segmentation +faults.

      + + + + + +

      This problem will often be seen in director functions that are +used for callbacks, for example.  

      + + + + + +

      To solve the problem, SWIG can now generate code with director +functions containing the optional macros SWIG_INIT_STACK and +SWIG_RELEASE_STACK.   These macros will try to force Ruby to +reinitiliaze the beginning of the stack the first time a +director +function is called.  This will lead Ruby to measure and not +collect any VALUE objects defined from that point on.  

      + + + + + +

      To mark functions to either reset the ruby stack or not, you +can use:

      + + + + + +
      %initstack +  Class::memberfunction;  // only re-init the stack +in this director method
      + + + + + +%ignorestack Class::memberfunction;  // do not re-init the +stack in this director method
      + + + + + +%initstack   Class;       +        // init the stack on all +the methods of this class
      + + + + + +%initstack;   // all director functions will +re-init the stack
      + + + + diff --git a/Doc/Manual/SWIG.html b/Doc/Manual/SWIG.html new file mode 100644 index 0000000..8705fa1 --- /dev/null +++ b/Doc/Manual/SWIG.html @@ -0,0 +1,3077 @@ + + + +SWIG Basics + + + + +

      5 SWIG Basics

      + +
      + +
      + + + + +

      +This chapter describes the basic operation of SWIG, the structure of its +input files, and how it handles standard ANSI C declarations. C++ support is +described in the next chapter. However, C++ programmers should still read this +chapter to understand the basics. +Specific details about each target language are described in later +chapters. +

      + +

      5.1 Running SWIG

      + + +

      +To run SWIG, use the swig command with options options and a filename like this: +

      + +
      +swig [ options ] filename
+
      + +

      +where filename is a SWIG interface file or a C/C++ header file. +Below is a subset of options that can be used. +Additional options are also defined for each target language. A full list +can be obtained by typing swig -help or swig +-lang -help. +

      + +
      +-allegrocl            Generate ALLEGROCL wrappers
+-chicken              Generate CHICKEN wrappers
+-clisp                Generate CLISP wrappers
+-cffi                 Generate CFFI wrappers
+-csharp               Generate C# wrappers
+-guile                Generate Guile wrappers
+-java                 Generate Java wrappers
+-lua                  Generate Lua wrappers
+-modula3              Generate Modula 3 wrappers
+-mzscheme             Generate Mzscheme wrappers
+-ocaml                Generate Ocaml wrappers
+-perl                 Generate Perl wrappers
+-php                  Generate PHP wrappers
+-pike                 Generate Pike wrappers
+-python               Generate Python wrappers
+-r                    Generate R (aka GNU S) wrappers
+-ruby                 Generate Ruby wrappers
+-sexp                 Generate Lisp S-Expressions wrappers
+-tcl                  Generate Tcl wrappers
+-uffi                 Generate Common Lisp / UFFI wrappers
+-xml                  Generate XML wrappers
+
+-c++                  Enable C++ parsing
+-Dsymbol              Define a preprocessor symbol
+-Fstandard            Display error/warning messages in commonly used format
+-Fmicrosoft           Display error/warning messages in Microsoft format
+-help                 Display all options
+-Idir                 Add a directory to the file include path
+-lfile                Include a SWIG library file.
+-module name          Set the name of the SWIG module
+-o outfile            Name of output file
+-outcurrentdir	      Set default output dir to current dir instead of input file's path
+-outdir dir           Set language specific files output directory
+-swiglib              Show location of SWIG library
+-version              Show SWIG version number
+
+
      + +

      5.1.1 Input format

      + + +

      +As input, SWIG expects a file containing ANSI C/C++ declarations and +special SWIG directives. More often than not, this is a special SWIG +interface file which is usually denoted with a special .i or +.swg suffix. In certain cases, SWIG can be used directly on +raw header files or source files. However, this is not the most +typical case and there are several reasons why you might not want to +do this (described later). +

      + +

      +The most common format of a SWIG interface is as follows: +

      + +
      +%module mymodule 
+%{
+#include "myheader.h"
+%}
+// Now list ANSI C/C++ declarations
+int foo;
+int bar(int x);
+...
+
      +

      +The module name is supplied using the special %module +directive. Modules are described further in the Modules Introduction section. +

      + +

      +Everything in the %{ ... %} block is simply copied verbatim +to the resulting wrapper file created by SWIG. This section is almost +always used to include header files and other declarations that are +required to make the generated wrapper code compile. It is important +to emphasize that just because you include a declaration in a SWIG +input file, that declaration does not automatically appear in +the generated wrapper code---therefore you need to make sure you +include the proper header files in the %{ ... %} section. It +should be noted that the text enclosed in %{ ... %} is not +parsed or interpreted by SWIG. The %{...%} syntax and +semantics in SWIG is analogous to that of the declarations section +used in input files to parser generation tools such as yacc or bison. +

      + +

      5.1.2 SWIG Output

      + + +

      +The output of SWIG is a C/C++ file that contains all of the wrapper +code needed to build an extension module. SWIG may generate some +additional files depending on the target language. By default, an input file +with the name file.i is transformed into a file +file_wrap.c or file_wrap.cxx (depending on whether +or not the -c++ option has been used). The name of the +output file can be changed using the -o option. In certain +cases, file suffixes are used by the compiler to determine the source +language (C, C++, etc.). Therefore, you have to use the +-o option to change the suffix of the SWIG-generated wrapper +file if you want something different than the default. For example: +

      + +
      +$ swig -c++ -python -o example_wrap.cpp example.i
+
      + +

      +The C/C++ output file created by SWIG often +contains everything that is needed to construct a extension module +for the target scripting language. SWIG is not a stub compiler nor is it +usually necessary to edit the output file (and if you look at the output, +you probably won't want to). To build the final extension module, the +SWIG output file is compiled and linked with the rest of your C/C++ +program to create a shared library. +

      + +

      +Many target languages will also generate proxy class files in the +target language. The default output directory for these language +specific files is the same directory as the generated C/C++ file. This +can be modified using the -outdir option. For example: +

      + +
      +$ swig -c++ -python -outdir pyfiles -o cppfiles/example_wrap.cpp example.i
+
      +

      +If the directories cppfiles and pyfiles exist, the following +will be generated:

      +
      +cppfiles/example_wrap.cpp
+pyfiles/example.py
+
      + +

      +If the -outcurrentdir option is used (without -o) +then SWIG behaves like a typical C/C++ +compiler and the default output directory is then the current directory. Without +this option the default output directory is the path to the input file. +If -o and +-outcurrentdir are used together, -outcurrentdir is effectively ignored +as the output directory for the language files is the same directory as the +generated C/C++ file if not overidden with -outdir. +

      + +

      5.1.3 Comments

      + + +

      +C and C++ style comments may appear anywhere in interface files. In +previous versions of SWIG, comments were used to generate +documentation files. However, this feature is currently under repair +and will reappear in a later SWIG release. +

      + +

      5.1.4 C Preprocessor

      + + +

      +Like C, SWIG preprocesses all input files through an enhanced version +of the C preprocessor. All standard preprocessor features are +supported including file inclusion, conditional compilation and +macros. However, #include statements are ignored unless the +-includeall command line option has been supplied. The +reason for disabling includes is that SWIG is sometimes used to +process raw C header files. In this case, you usually only want the +extension module to include functions in the supplied header file +rather than everything that might be included by that header file +(i.e., system headers, C library functions, etc.). +

      + +

      +It should also be noted that the SWIG preprocessor skips all text +enclosed inside a %{...%} block. In addition, the +preprocessor includes a number of macro handling enhancements that +make it more powerful than the normal C preprocessor. These +extensions are described in the "Preprocessor" chapter. +

      + +

      5.1.5 SWIG Directives

      + + +

      +Most of SWIG's operation is controlled by special directives that are +always preceded by a "%" to distinguish them from normal C +declarations. These directives are used to give SWIG hints or to alter +SWIG's parsing behavior in some manner. +

      + +

      +Since SWIG directives are not legal C syntax, it is generally not +possible to include them in header files. However, SWIG directives can be +included in C header files using conditional compilation like this: +

      + +
      +/* header.h  --- Some header file */
+
+/* SWIG directives -- only seen if SWIG is running */ 
+#ifdef SWIG
+%module foo
+#endif
+
      +
      + +

      +SWIG is a special preprocessing symbol defined by SWIG when +it is parsing an input file. +

      + +

      5.1.6 Parser Limitations

      + + +

      +Although SWIG can parse most C/C++ declarations, it does not +provide a complete C/C++ parser implementation. Most of these +limitations pertain to very complicated type declarations and certain +advanced C++ features. Specifically, the following features are not +currently supported: +

      + +
        +
      • Non-conventional type declarations. +For example, SWIG does not support declarations such as the following +(even though this is legal C): + +
        +
        +/* Non-conventional placement of storage specifier (extern) */
+const int extern Number;
+
+/* Extra declarator grouping */
+Matrix (foo);    // A global variable
+
+/* Extra declarator grouping in parameters */
+void bar(Spam (Grok)(Doh));
+
+
        +
        + +

        +In practice, few (if any) C programmers actually write code like +this since this style is never featured in programming books. However, +if you're feeling particularly obfuscated, you can certainly break SWIG (although why would you want to?). +

        +
        • + +
      • Running SWIG on C++ source files (what would appear in a .C or .cxx file) +is not recommended. Even though SWIG can parse C++ class declarations, +it ignores declarations that are decoupled from their +original class definition (the declarations are parsed, but a lot of warning +messages may be generated). For example: + +
        +
        +/* Not supported by SWIG */
+int foo::bar(int) {
+    ... whatever ...
+}
+
        +
        +
        • + +
      • Certain advanced features of C++ such as nested classes +are not yet supported. Please see the section on using SWIG +with C++ for more information. +
      + +

      +In the event of a parsing error, conditional compilation can be used to skip +offending code. For example: +

      + +
      +
      +#ifndef SWIG
+... some bad declarations ...
+#endif
+
      +
      +

      +Alternatively, you can just delete the offending code from the interface file. +

      + +

      +One of the reasons why SWIG does not provide a full C++ parser +implementation is that it has been designed to work with incomplete +specifications and to be very permissive in its handling of C/C++ +datatypes (e.g., SWIG can generate interfaces even when there are +missing class declarations or opaque datatypes). Unfortunately, this +approach makes it extremely difficult to implement certain parts of a +C/C++ parser as most compilers use type information to assist in the +parsing of more complex declarations (for the truly curious, the +primary complication in the implementation is that the SWIG parser +does not utilize a separate typedef-name terminal symbol as +described on p. 234 of K&R). +

      + +

      5.2 Wrapping Simple C Declarations

      + + +

      +SWIG wraps simple C declarations by creating an interface that closely matches +the way in which the declarations would be used in a C program. +For example, consider the following interface file: +

      + +
      +%module example
+
+%inline %{
+extern double sin(double x);
+extern int strcmp(const char *, const char *);
+extern int Foo;
+%}
+#define STATUS 50
+#define VERSION "1.1"
+
      +

      +In this file, there are two functions sin() and strcmp(), +a global variable Foo, and two constants STATUS and +VERSION. When SWIG creates an extension module, these +declarations are accessible as scripting language functions, variables, and +constants respectively. For example, in Tcl: +

      + +
      +% sin 3
+5.2335956
+% strcmp Dave Mike
+-1
+% puts $Foo
+42
+% puts $STATUS
+50
+% puts $VERSION
+1.1
+
      +

      +Or in Python: +

      + +
      +>>> example.sin(3)
+5.2335956
+>>> example.strcmp('Dave','Mike')
+-1
+>>> print example.cvar.Foo
+42
+>>> print example.STATUS
+50
+>>> print example.VERSION
+1.1
+
      +

      +Whenever possible, SWIG creates an interface that closely matches the underlying C/C++ +code. However, due to subtle differences between languages, run-time +environments, and semantics, it is not always possible to do so. The +next few sections describes various aspects of this mapping. +

      + +

      5.2.1 Basic Type Handling

      + + +

      +In order to build an interface, SWIG has to convert C/C++ datatypes to +equivalent types in the target language. Generally, +scripting languages provide a more limited set of primitive types than C. +Therefore, this conversion process involves a certain amount of type +coercion. +

      + +

      +Most scripting languages provide a single integer type that is implemented using +the int or long datatype in C. The following list shows +all of the C datatypes that SWIG will convert to and from integers in the target language: +

      + +
      +int
+short
+long
+unsigned
+signed
+unsigned short
+unsigned long
+unsigned char
+signed char
+bool
+
      + +

      +When an integral value is converted from C, a cast is used to convert it to +the representation in the target language. +Thus, a 16 bit short in C may be promoted to a 32 bit integer. When integers are +converted in the other direction, the value is cast back into the original C type. +If the value is too large to fit, it is silently truncated. + +

      + +

      +unsigned char and signed char are special cases that +are handled as small 8-bit integers. Normally, the char +datatype is mapped as a one-character ASCII string.

      + +

      +The bool datatype is cast to and from an integer value of 0 +and 1 unless the target language provides a special boolean type.

      + +

      +Some care is required when working with large integer values. Most +scripting languages use 32-bit integers so mapping a 64-bit long +integer may lead to truncation errors. Similar problems may arise with +32 bit unsigned integers (which may appear as large negative +numbers). As a rule of thumb, the int datatype and all +variations of char and short datatypes are safe to +use. For unsigned int and long datatypes, you will +need to carefully check the correct operation of your program after +it has been wrapped with SWIG. +

      + +

      +Although the SWIG parser supports the long long datatype, not +all language modules support it. This is because long long +usually exceeds the integer precision available in the target +language. In certain modules such as Tcl and Perl5, long +long integers are encoded as strings. This allows the full range +of these numbers to be represented. However, it does not allow +long long values to be used in arithmetic expressions. It +should also be noted that although long long is part +of the ISO C99 standard, it is not universally supported by all C +compilers. Make sure you are using a compiler that supports long +long before trying to use this type with SWIG. +

      + +

      +SWIG recognizes the following floating point types :

      + +
      +float
+double
+
      + +

      +Floating point numbers are mapped to and from the natural +representation of floats in the target language. This is almost always +a C double. The rarely used datatype of long double +is not supported by SWIG.

      + +

      +The char datatype is mapped into a NULL terminated ASCII +string with a single character. When used in a scripting language it +shows up as a tiny string containing the character value. When +converting the value back into C, SWIG takes a character string +from the scripting language and strips off the first character as the +char value. Thus if the value "foo" is assigned to a +char datatype, it gets the value `f'.

      + +

      +The char * datatype is handled as a NULL-terminated ASCII +string. SWIG maps this into a 8-bit character string in the target +scripting language. SWIG converts character strings in the target +language to NULL terminated strings before passing them into +C/C++. The default handling of these strings does not allow them to +have embedded NULL bytes. Therefore, the char * datatype is +not generally suitable for passing binary data. However, it is +possible to change this behavior by defining a SWIG typemap. See the chapter +on Typemaps for details about this. +

      + +

      +At this time, SWIG provides limited support for Unicode and +wide-character strings (the C wchar_t type). +Some languages provide typemaps for wchar_t, but bear in mind these +might not be portable across different operating systems. This is a +delicate topic that is poorly understood by many programmers and not +implemented in a consistent manner across languages. For those +scripting languages that provide Unicode support, Unicode strings are +often available in an 8-bit representation such as UTF-8 that can be +mapped to the char * type (in which case the SWIG interface +will probably work). If the program you are wrapping uses Unicode, +there is no guarantee that Unicode characters in the target language +will use the same internal representation (e.g., UCS-2 vs. UCS-4). +You may need to write some special conversion functions. +

      + +

      5.2.2 Global Variables

      + + +

      +Whenever possible, SWIG maps C/C++ global variables into scripting language +variables. For example, +

      + +
      +%module example
+double foo;
+
+
      +

      +results in a scripting language variable like this: +

      + +
      +# Tcl
+set foo [3.5]                   ;# Set foo to 3.5
+puts $foo                       ;# Print the value of foo
+
+# Python
+cvar.foo = 3.5                  # Set foo to 3.5
+print cvar.foo                  # Print value of foo
+
+# Perl
+$foo = 3.5;                     # Set foo to 3.5
+print $foo,"\n";                # Print value of foo
+
+# Ruby
+Module.foo = 3.5               # Set foo to 3.5
+print Module.foo, "\n"         # Print value of foo
+
      +

      +Whenever the scripting language variable is used, the underlying C +global variable is accessed. Although SWIG makes every +attempt to make global variables work like scripting language +variables, it is not always possible to do so. For instance, in +Python, all global variables must be accessed through a special +variable object known as cvar (shown above). In Ruby, variables are +accessed as attributes of the module. Other languages may +convert variables to a pair of accessor functions. For example, the +Java module generates a pair of functions double get_foo() +and set_foo(double val) that are used to manipulate the +value. +

      + +

      +Finally, if a global variable has been declared as const, it +only supports read-only access. Note: this behavior is new to SWIG-1.3. +Earlier versions of SWIG incorrectly handled const and created +constants instead. +

      + +

      5.2.3 Constants

      + + +

      +Constants can be created using #define, enumerations, +or a special %constant directive. The following +interface file shows a few valid constant declarations :

      + +
      +#define I_CONST       5               // An integer constant
+#define PI            3.14159         // A Floating point constant
+#define S_CONST       "hello world"   // A string constant
+#define NEWLINE       '\n'            // Character constant
+
+enum boolean {NO=0, YES=1};
+enum months {JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG,
+             SEP, OCT, NOV, DEC};
+%constant double BLAH = 42.37;
+#define PI_4 PI/4
+#define FLAGS 0x04 | 0x08 | 0x40
+
+
      +

      +In #define declarations, the type of a constant is inferred +by syntax. For example, a number with a decimal point is assumed to be +floating point. In addition, SWIG must be able to fully resolve all +of the symbols used in a #define in order for a constant to +actually be created. This restriction is necessary because +#define is also used to define preprocessor macros that are +definitely not meant to be part of the scripting language interface. +For example: +

      + +
      +
      +#define EXTERN extern
+
+EXTERN void foo();
+
      +
      +

      +In this case, you probably don't want to create a constant called +EXTERN (what would the value be?). In general, +SWIG will not create constants for macros unless the value can +be completely determined by the preprocessor. For instance, in the above example, +the declaration +

      + +
      +
      +#define PI_4  PI/4
+
      +
      +

      +defines a constant because PI was already defined as a +constant and the value is known. +However, for the same conservative reasons even a constant with a simple cast will be ignored, such as +

      + +
      +
      +#define F_CONST (double) 5            // A floating pointer constant with cast
+
      +
      + +

      +The use of constant expressions is allowed, but SWIG does not evaluate +them. Rather, it passes them through to the output file and lets the C +compiler perform the final evaluation (SWIG does perform a limited +form of type-checking however).

      + +

      +For enumerations, it is critical that the original enum definition be +included somewhere in the interface file (either in a header file or +in the %{,%} block). SWIG only translates the enumeration +into code needed to add the constants to a scripting language. It +needs the original enumeration declaration in order to get the correct +enum values as assigned by the C compiler. +

      + +

      +The %constant directive is used to more precisely create +constants corresponding to different C datatypes. Although it is not +usually not needed for simple values, it is more useful when working +with pointers and other more complex datatypes. Typically, %constant +is only used when you want to add constants to the scripting language +interface that are not defined in the original header file. +

      + +

      5.2.4 A brief word about const

      + + +

      +A common confusion with C programming is the semantic meaning of the +const qualifier in declarations--especially when it is mixed +with pointers and other type modifiers. In fact, previous versions of SWIG +handled const incorrectly--a situation that SWIG-1.3.7 and newer +releases have fixed. +

      + +

      +Starting with SWIG-1.3, all variable declarations, regardless of any +use of const, are wrapped as global variables. If a +declaration happens to be declared as const, it is wrapped as +a read-only variable. To tell if a variable is const or not, +you need to look at the right-most occurrence of the const +qualifier (that appears before the variable name). If the right-most +const occurs after all other type modifiers (such as +pointers), then the variable is const. Otherwise, it is not. +

      + +

      +Here are some examples of const declarations. +

      + +
      +
      +const char a;           // A constant character
+char const b;           // A constant character (the same)
+char *const c;          // A constant pointer to a character
+const char *const d;    // A constant pointer to a constant character
+
      +
      +

      +Here is an example of a declaration that is not const: +

      + +
      +
      +const char *e;          // A pointer to a constant character.  The pointer
+                        // may be modified.
+
      +
      +

      +In this case, the pointer e can change---it's only the value +being pointed to that is read-only. +

      + +

      +Compatibility Note: One reason for changing SWIG to handle +const declarations as read-only variables is that there are +many situations where the value of a const variable might +change. For example, a library might export a symbol as +const in its public API to discourage modification, but still +allow the value to change through some other kind of internal +mechanism. Furthermore, programmers often overlook the fact that with +a constant declaration like char *const, the underlying data +being pointed to can be modified--it's only the pointer itself that is +constant. In an embedded system, a const declaration might +refer to a read-only memory address such as the location of a +memory-mapped I/O device port (where the value changes, but writing to +the port is not supported by the hardware). Rather than trying to +build a bunch of special cases into the const qualifier, the +new interpretation of const as "read-only" is simple and +exactly matches the actual semantics of const in C/C++. If +you really want to create a constant as in older versions of SWIG, use +the %constant directive instead. For example: +

      + +
      +
      +%constant double PI = 3.14159;
+
      +
      + +

      +or +

      + +
      +
      +#ifdef SWIG
+#define const %constant
+#endif
+const double foo = 3.4;
+const double bar = 23.4;
+const int    spam = 42;
+#ifdef SWIG
+#undef const
+#endif
+...
+
+
      +
      + +

      5.2.5 A cautionary tale of char *

      + + +

      +Before going any further, there is one bit of caution involving +char * that must now be mentioned. When strings are passed +from a scripting language to a C char *, the pointer usually +points to string data stored inside the interpreter. It is almost +always a really bad idea to modify this data. Furthermore, some +languages may explicitly disallow it. For instance, in Python, +strings are supposed be immutable. If you violate this, you will probably +receive a vast amount of wrath when you unleash your module on the world. +

      + +

      +The primary source of problems are functions that might modify string data in place. +A classic example would be a function like this: +

      + +
      +
      +char *strcat(char *s, const char *t)
+
      +
      + +

      +Although SWIG will certainly generate a wrapper for this, its behavior +will be undefined. In fact, it will probably cause your application +to crash with a segmentation fault or other memory related problem. +This is because s refers to some internal data in the target +language---data that you shouldn't be touching. +

      + +

      +The bottom line: don't rely on char * for anything other than read-only +input values. However, it must be noted that you could change the behavior of SWIG +using typemaps. +

      + +

      5.3 Pointers and complex objects

      + + +

      +Most C programs manipulate arrays, structures, and other types of objects. This section +discusses the handling of these datatypes. +

      + +

      5.3.1 Simple pointers

      + + +

      +Pointers to primitive C datatypes such as

      + +
      +int *
+double ***
+char **
+
      +

      +are fully supported by SWIG. Rather than trying to convert the data being pointed to into a scripting +representation, SWIG simply encodes the pointer itself into a +representation that contains the actual value of the pointer and a type-tag. +Thus, the SWIG representation of the above +pointers (in Tcl), might look like this:

      + +
      +_10081012_p_int
+_1008e124_ppp_double
+_f8ac_pp_char
+
      + +

      +A NULL pointer is represented by the string "NULL" or the value 0 +encoded with type information.

      + +

      +All pointers are treated as opaque objects by SWIG. Thus, a pointer +may be returned by a function and passed around to other C functions +as needed. For all practical purposes, the scripting language +interface works in exactly the same way as you would use the +pointer in a C program. The only difference is that there is no mechanism for +dereferencing the pointer since this would require the target language +to understand the memory layout of the underlying object. +

      + +

      +The scripting language representation of a pointer value should never be +manipulated directly. Even though the values shown look like hexadecimal +addresses, the numbers used may differ from the actual machine address (e.g., +on little-endian machines, the digits may appear in reverse order). +Furthermore, SWIG does not +normally map pointers into high-level objects such as associative +arrays or lists (for example, converting an +int * into an list of integers). There are several reasons +why SWIG does not do this:

      + +
        +
      • There is not enough information in a C declaration to properly map +pointers into higher level constructs. For example, an int * +may indeed be an array of integers, but if it contains ten million +elements, converting it into a list object is probably a bad idea. +
        • + +
      • The underlying semantics associated with a pointer is not known +by SWIG. For instance, an int * might not be an array at all--perhaps it +is an output value! +
        • + +
      • By handling all pointers in a consistent manner, the implementation of SWIG is greatly +simplified and less prone to error. +
        • +
      + +

      5.3.2 Run time pointer type checking

      + + +

      +By allowing pointers to be manipulated from a scripting language, extension modules +effectively bypass compile-time type checking in the C/C++ +compiler. To prevent errors, a type signature is encoded into all +pointer values and is used to perform run-time type checking. This +type-checking process is an integral part of SWIG and can not be +disabled or modified without using typemaps (described in later +chapters). +

      + +

      +Like C, void * matches any kind of pointer. Furthermore, +NULL pointers can be passed to any function that expects to +receive a pointer. Although this has the potential to cause a crash, +NULL pointers are also sometimes used +as sentinel values or to denote a missing/empty value. Therefore, +SWIG leaves NULL pointer checking up to the application. +

      + +

      5.3.3 Derived types, structs, and classes

      + + +

      +For everything else (structs, classes, arrays, etc...) SWIG applies a +very simple rule :

      + +
      +Everything else is a pointer +
      + +

      +In other words, SWIG manipulates everything else by reference. This +model makes sense because most C/C++ programs make heavy use of +pointers and SWIG can use the type-checked pointer mechanism already +present for handling pointers to basic datatypes.

      + +

      +Although this probably sounds complicated, it's really quite +simple. Suppose you have an interface file like this :

      + +
      +%module fileio
+FILE *fopen(char *, char *);
+int fclose(FILE *);
+unsigned fread(void *ptr, unsigned size, unsigned nobj, FILE *);
+unsigned fwrite(void *ptr, unsigned size, unsigned nobj, FILE *);
+void *malloc(int nbytes);
+void free(void *);
+
+
      + +

      +In this file, SWIG doesn't know what a FILE is, but since it's used +as a pointer, so it doesn't really matter what it is. If you wrapped +this module into Python, you can use the functions just like you +expect :

      + +
      +# Copy a file 
+def filecopy(source,target):
+	f1 = fopen(source,"r")
+	f2 = fopen(target,"w")
+	buffer = malloc(8192)
+	nbytes = fread(buffer,8192,1,f1)
+	while (nbytes > 0):
+		fwrite(buffer,8192,1,f2)
+		nbytes = fread(buffer,8192,1,f1)
+	free(buffer)
+
+
      + +

      +In this case f1, f2, and buffer are all +opaque objects containing C pointers. It doesn't matter what value +they contain--our program works just fine without this knowledge.

      + +

      5.3.4 Undefined datatypes

      + + +

      +When SWIG encounters an undeclared datatype, it automatically assumes +that it is a structure or class. For example, suppose the following +function appeared in a SWIG input file:

      + +
      +void matrix_multiply(Matrix *a, Matrix *b, Matrix *c);
+
      + +

      +SWIG has no idea what a "Matrix" is. However, it is obviously +a pointer to something so SWIG generates a wrapper using its generic pointer +handling code. +

      + +

      +Unlike C or C++, SWIG does not actually care whether Matrix +has been previously defined in the interface file or not. This +allows SWIG to generate interfaces from +only partial or limited information. In some cases, you may not care +what a Matrix really is as long as you can pass an opaque reference to +one around in the scripting language interface. +

      + +

      +An important detail to mention is that SWIG will gladly generate +wrappers for an interface when there are unspecified type names. +However, all unspecified types are internally handled as pointers +to structures or classes! For example, consider the following declaration: +

      + +
      +
      +void foo(size_t num);
+
      +
      + +

      +If size_t is undeclared, SWIG generates wrappers +that expect to receive a type of size_t * (this mapping is described shortly). +As a result, the scripting interface might behave strangely. For example: +

      + +
      +
      +foo(40);
+TypeError: expected a _p_size_t.
+
      +
      + +

      +The only way to fix this problem is to make sure you properly declare type names using +typedef. +

      + + + +

      5.3.5 Typedef

      + + +

      +Like C, typedef can be used to define new type names in SWIG. For example: +

      + +
      +typedef unsigned int size_t;
+
      + +

      +typedef definitions appearing in a SWIG interface +are not propagated to the generated wrapper code. Therefore, they +either need to be defined in an included header file or placed in the +declarations section like this: +

      + +
      +
      +%{
+/* Include in the generated wrapper file */
+typedef unsigned int size_t;
+%}
+/* Tell SWIG about it */
+typedef unsigned int size_t;
+
      +
      + +

      +or +

      + +
      +
      +%inline %{
+typedef unsigned int size_t;
+%}
+
      +
      + +

      +In certain cases, you might be able to include other header files to collect type information. +For example: +

      + +
      +
      +%module example
+%import "sys/types.h"
+
      +
      + +

      +In this case, you might run SWIG as follows: +

      + +
      +
      +$ swig -I/usr/include -includeall example.i
+
      +
      + +

      +It should be noted that your mileage will vary greatly here. +System headers are notoriously complicated and may rely upon a variety +of non-standard C coding extensions (e.g., such as special directives +to GCC). Unless you exactly specify the right include directories and +preprocessor symbols, this may not work correctly (you will have to +experiment). +

      + +

      +SWIG tracks typedef declarations and uses this information +for run-time type checking. For instance, if you use the above typedef and +had the following function declaration: +

      + +
      +
      +void foo(unsigned int *ptr);
+
      +
      + +

      +The corresponding wrapper function will accept arguments of +type unsigned int * or size_t *. +

      + +

      5.4 Other Practicalities

      + + +

      +So far, this chapter has presented almost everything you need to know to use SWIG +for simple interfaces. However, some C programs use idioms that are somewhat +more difficult to map to a scripting language interface. This section describes +some of these issues. +

      + +

      5.4.1 Passing structures by value

      + + +

      +Sometimes a C function takes structure parameters that are passed +by value. For example, consider the following function: +

      + +
      +double dot_product(Vector a, Vector b);
+
      + +

      +To deal with this, SWIG transforms the function to use pointers by +creating a wrapper equivalent to the following: +

      + +
      +double wrap_dot_product(Vector *a, Vector *b) {
+    Vector x = *a;
+    Vector y = *b;
+    return dot_product(x,y);
+}
+
      + +

      +In the target language, the dot_product() function now accepts pointers +to Vectors instead of Vectors. For the most part, this transformation +is transparent so you might not notice. +

      + +

      5.4.2 Return by value

      + + +

      +C functions that return structures or classes datatypes by value are more difficult +to handle. Consider the following function:

      + +
      +Vector cross_product(Vector v1, Vector v2);
+
      + +

      +This function wants to return Vector, but SWIG only really supports +pointers. As a result, SWIG creates a wrapper like this: +

      + +
      +Vector *wrap_cross_product(Vector *v1, Vector *v2) {
+        Vector x = *v1;
+        Vector y = *v2;
+        Vector *result;
+        result = (Vector *) malloc(sizeof(Vector));
+        *(result) = cross(x,y);
+        return result;
+}
+
      + +

      +or if SWIG was run with the -c++ option:

      + +
      +Vector *wrap_cross(Vector *v1, Vector *v2) {
+        Vector x = *v1;
+        Vector y = *v2;
+        Vector *result = new Vector(cross(x,y)); // Uses default copy constructor
+        return result;
+}
+
      + +

      +In both cases, SWIG allocates a new object and returns a reference to it. It +is up to the user to delete the returned object when it is no longer +in use. Clearly, this will leak memory if you are unaware of the implicit +memory allocation and don't take steps to free the result. That said, it should be +noted that some language modules can now automatically track newly created objects and +reclaim memory for you. Consult the documentation for each language module for more details. +

      + +

      +It should also be noted that the handling of pass/return by value in +C++ has some special cases. For example, the above code fragments +don't work correctly if Vector doesn't define a default +constructor. The section on SWIG and C++ has more information about this case. +

      + +

      5.4.3 Linking to structure variables

      + + +

      +When global variables or class members involving structures are +encountered, SWIG handles them as pointers. For example, a global +variable like this

      + +
      +Vector unit_i;
+
      + +

      +gets mapped to an underlying pair of set/get functions like this :

      + +
      +Vector *unit_i_get() {
+	return &unit_i;
+}
+void unit_i_set(Vector *value) {
+	unit_i = *value;
+}
+
      + +

      +Again some caution is in order. A global variable created in this +manner will show up as a pointer in the target scripting language. It +would be an extremely bad idea to free or destroy such a pointer. Also, +C++ classes must supply a properly defined copy constructor in order for +assignment to work correctly. +

      + +

      5.4.4 Linking to char *

      + + +

      +When a global variable of type char * appears, SWIG uses malloc() or +new to allocate memory for the new value. Specifically, if you have a variable +like this +

      + +
      +
      +char *foo;
+
      +
      + +

      +SWIG generates the following code: +

      + +
      +
      +/* C mode */
+void foo_set(char *value) {
+   if (foo) free(foo);
+   foo = (char *) malloc(strlen(value)+1);
+   strcpy(foo,value);
+}
+
+/* C++ mode.  When -c++ option is used */
+void foo_set(char *value) {
+   if (foo) delete [] foo;
+   foo = new char[strlen(value)+1];
+   strcpy(foo,value);
+}
+
      +
      + +

      +If this is not the behavior that you want, consider making the variable read-only using the +%immutable directive. Alternatively, you might write a short assist-function to set the value +exactly like you want. For example: +

      + +
      +
      +%inline %{
+  void set_foo(char *value) {
+       strncpy(foo,value, 50);
+   }
+%}
+
      +
      + +

      +Note: If you write an assist function like this, you will have to call +it as a function from the target scripting language (it does not work +like a variable). For example, in Python you will have to write: +

      + +
      +
      +>>> set_foo("Hello World")
+
      +
      + +

      +A common mistake with char * variables is to link to a variable declared like this: +

      + +
      +
      +char *VERSION = "1.0";
+
      +
      + +

      +In this case, the variable will be readable, but any attempt to change +the value results in a segmentation or general protection fault. This +is due to the fact that SWIG is trying to release the old value using +free or delete when the string literal value currently assigned to the variable wasn't +allocated using malloc() or new. +To fix this behavior, you can +either mark the variable as read-only, write a typemap (as described in Chapter 6), +or write a special set function as shown. Another alternative is to declare the +variable as an array: +

      + +
      +
      +char VERSION[64] = "1.0";
+
      +
      + +

      +When variables of type const char * are declared, SWIG still generates functions for setting and +getting the value. However, the default behavior does not release the previous contents (resulting in +a possible memory leak). In fact, you may get a warning message such as this when wrapping such a variable: +

      + +
      +
      +example.i:20. Typemap warning. Setting const char * variable may leak memory
+
      +
      + +

      +The reason for this behavior is that const char * variables are often used to point to string literals. +For example: +

      + +
      +
      +const char *foo = "Hello World\n";
+
      +
      + +

      +Therefore, it's a really bad idea to call free() on such a +pointer. On the other hand, it is legal to change the +pointer to point to some other value. When setting a variable of this +type, SWIG allocates a new string (using malloc or new) and changes +the pointer to point to the new value. However, repeated +modifications of the value will result in a memory leak since the old +value is not released. +

      + + + + +

      5.4.5 Arrays

      + + +

      +Arrays are fully supported by SWIG, but they are always handled as pointers instead +of mapping them to a special array object or list in the target language. Thus, the +following declarations :

      + +
      +int foobar(int a[40]);
+void grok(char *argv[]);
+void transpose(double a[20][20]);
+
      + +

      +are processed as if they were really declared like this: +

      + +
      +int foobar(int *a);
+void grok(char **argv);
+void transpose(double (*a)[20]);
+
      + +

      +Like C, SWIG does not perform array bounds checking. +It is up to the +user to make sure the pointer points a suitably allocated region of memory. +

      + +

      +Multi-dimensional arrays are transformed into a pointer to an array of one less +dimension. For example: +

      + +
      +
      +int [10];         // Maps to int *
+int [10][20];     // Maps to int (*)[20]
+int [10][20][30]; // Maps to int (*)[20][30]
+
      +
      + +

      +It is important to note that in the C type system, a multidimensional +array a[][] is NOT equivalent to a single pointer +*a or a double pointer such as **a. Instead, a +pointer to an array is used (as shown above) where the actual value of +the pointer is the starting memory location of the array. The +reader is strongly advised to dust off their C book and re-read the +section on arrays before using them with SWIG. +

      + +

      +Array variables are supported, but are read-only by default. For example: +

      + +
      +
      +int   a[100][200];
+
      +
      + +

      +In this case, reading the variable 'a' returns a pointer of type int (*)[200] +that points to the first element of the array &a[0][0]. Trying to modify 'a' results +in an error. This is because SWIG does not know how to copy data from the target +language into the array. To work around this limitation, you may want to write +a few simple assist functions like this: +

      + +
      +
      +%inline %{
+void a_set(int i, int j, int val) {
+   a[i][j] = val;
+}
+int a_get(int i, int j) {
+   return a[i][j];
+}
+%}
+
      +
      + +

      +To dynamically create arrays of various sizes and shapes, it may be useful to write +some helper functions in your interface. For example: +

      + +
      +
      +// Some array helpers
+%inline %{
+  /* Create any sort of [size] array */
+  int *int_array(int size) {
+     return (int *) malloc(size*sizeof(int));
+  }
+  /* Create a two-dimension array [size][10] */
+  int (*int_array_10(int size))[10] {
+     return (int (*)[10]) malloc(size*10*sizeof(int));
+  }
+%}
+
      +
      + +

      +Arrays of char are handled as a special case by SWIG. In this case, strings in the +target language can be stored in the array. For example, if you have a declaration like this, +

      + +
      +
      +char pathname[256];
+
      +
      + +

      +SWIG generates functions for both getting and setting the value that are equivalent to the following +code: +

      + +
      +
      +char *pathname_get() {
+   return pathname;
+}
+void pathname_set(char *value) {
+   strncpy(pathname,value,256);
+}
+
      +
      + +

      +In the target language, the value can be set like a normal variable. +

      + +

      5.4.6 Creating read-only variables

      + + +

      +A read-only variable can be created by using the %immutable +directive as shown :

      + +
      +// File : interface.i
+
+int 	a; 			// Can read/write
+%immutable;
+int	b,c,d			// Read only variables
+%mutable;
+double	x,y			// read/write
+
      + +

      +The %immutable directive enables read-only mode until it is +explicitly disabled using the %mutable directive. As an alternative to turning +read-only mode off and on like this, individual declarations can also be tagged as +immutable. For example: +

      + +
      +%immutable x;                   // Make x read-only
+...
+double x;                       // Read-only (from earlier %immutable directive)
+double y;                       // Read-write
+...
+
      + +

      +The %mutable and %immutable directives are actually +%feature directives defined like this: +

      + +
      +#define %immutable   %feature("immutable")
+#define %mutable     %feature("immutable","")
+
      + +

      +If you wanted to make all wrapped variables read-only, barring one or two, it might be easier to take this approach: +

      + +
      +%immutable;                     // Make all variables read-only
+%feature("immutable","0") x;    // except, make x read/write
+...
+double x;
+double y;
+double z;
+...
+
      + +

      +Read-only variables are also created when declarations are declared as const. +For example: +

      + +
      +
      +const int foo;               /* Read only variable */
+char * const version="1.0";  /* Read only variable */
+
      + +

      +Compatibility note: Read-only access used to be controlled by a pair of directives +%readonly and %readwrite. Although these directives still work, they +generate a warning message. Simply change the directives to %immutable; and +%mutable; to silence the warning. Don't forget the extra semicolon! +

      + +

      5.4.7 Renaming and ignoring declarations

      + + +

      +Normally, the name of a C declaration is used when that declaration is +wrapped into the target language. However, this may generate a +conflict with a keyword or already existing function in the scripting +language. To resolve a name conflict, you can use the %rename +directive as shown :

      + +
      +// interface.i
+
+%rename(my_print) print;
+extern void print(char *);
+
+%rename(foo) a_really_long_and_annoying_name;
+extern int a_really_long_and_annoying_name;
+
+
      + +

      +SWIG still calls the correct C function, but in this case the +function print() will really be called "my_print()" +in the target language.

      + +

      +The placement of the %rename directive is arbitrary as long as it appears +before the declarations to be renamed. A common technique is to write code for +wrapping a header file like this: +

      + +
      +// interface.i
+
+%rename(my_print) print;
+%rename(foo) a_really_long_and_annoying_name;
+
+%include "header.h"
+
      + +

      +%rename applies a renaming operation to all future +occurrences of a name. The renaming applies to functions, variables, +class and structure names, member functions, and member data. For +example, if you had two-dozen C++ classes, all with a member function +named `print' (which is a keyword in Python), you could rename them +all to `output' by specifying :

      + +
      +%rename(output) print; // Rename all `print' functions to `output'
+
      + +

      +SWIG does not normally perform any checks to see if the functions it wraps are +already defined in the target scripting language. However, if you are +careful about namespaces and your use of modules, you can usually +avoid these problems.

      + +

      +Closely related to %rename is the %ignore directive. %ignore instructs SWIG +to ignore declarations that match a given identifier. For example: +

      + +
      +
      +%ignore print;         // Ignore all declarations named print
+%ignore _HAVE_FOO_H;   // Ignore an include guard constant
+...
+%include "foo.h"       // Grab a header file
+...
+
      +
      + +

      +Any function, variable etc which matches %ignore will not be wrapped and therefore will not be available from the target language. +A common usage of %ignore is to selectively remove certain declarations from a header file without having +to add conditional compilation to the header. However, it should be stressed that this only works for simple +declarations. If you need to remove a whole section of problematic code, the SWIG preprocessor should be used instead. +

      + +

      +More powerful variants of %rename and %ignore directives can be used to help +wrap C++ overloaded functions and methods or C++ methods which use default arguments. This is described in the +Ambiguity resolution and renaming section in the C++ chapter. +

      + +

      +Compatibility note: Older versions of SWIG provided a special %name directive for renaming declarations. +For example: +

      + +
      +
      +%name(output) extern void print(char *);
+
      +
      + +

      +This directive is still supported, but it is deprecated and should probably be avoided. The %rename +directive is more powerful and better supports wrapping of raw header file information. +

      + +

      5.4.8 Default/optional arguments

      + + +

      +SWIG supports default arguments in both C and C++ code. For example: +

      + +
      +int plot(double x, double y, int color=WHITE);
+
      + +

      +In this case, SWIG generates wrapper code where the +default arguments are optional in the target language. For example, this function could be +used in Tcl as follows :

      + +
      +% plot -3.4 7.5 				# Use default value
+% plot -3.4 7.5 10				# set color to 10 instead
+
+
      + +

      +Although the ANSI C standard does not allow default arguments, default +arguments specified in a SWIG interface work with both C and C++. +

      + +

      +Note: There is a subtle semantic issue concerning the use +of default arguments and the SWIG generated wrapper code. When default +arguments are used in C code, the default values are emitted into the wrappers and the +function is invoked with a full set of arguments. This is different to when wrapping C++ +where an overloaded wrapper method is generated for each defaulted argument. +Please refer to the section on default arguments +in the C++ chapter for further details. +

      + +

      5.4.9 Pointers to functions and callbacks

      + + +

      +Occasionally, a C library may include functions that expect to receive +pointers to functions--possibly to serve as callbacks. SWIG +provides full support for function pointers provided that the callback +functions are defined in C and not in the target language. For example, +consider a function like this: +

      + +
      +int binary_op(int a, int b, int (*op)(int,int));
+
      + +

      +When you first wrap something like this into an extension module, you +may find the function to be impossible to use. For instance, in Python: +

      + +
      +>>> def add(x,y):
+...     return x+y
+...
+>>> binary_op(3,4,add)
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+TypeError: Type error. Expected _p_f_int_int__int
+>>>
+
      +
      + +

      +The reason for this error is that SWIG doesn't know how to map a scripting +language function into a C callback. However, existing C functions can +be used as arguments provided you install them as constants. +One way to do this is to use the %constant directive like this: +

      + +
      +/* Function with a callback */
+int binary_op(int a, int b, int (*op)(int,int));
+
+/* Some callback functions */
+%constant int add(int,int);
+%constant int sub(int,int);
+%constant int mul(int,int);
+
      + +

      +In this case, add, sub, and mul become function pointer +constants in the target scripting language. This allows you to use them as follows: +

      + +
      +
      +>>> binary_op(3,4,add)
+7
+>>> binary_op(3,4,mul)
+12
+>>>
+
      +
      + +

      +Unfortunately, by declaring the callback functions as constants, they are no longer accessible +as functions. For example: +

      + +
      +
      +>>> add(3,4)
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+TypeError: object is not callable: '_ff020efc_p_f_int_int__int'
+>>>
+
      +
      + +

      +If you want to make a function available as both a callback function and a function, you +can use the %callback and %nocallback directives like this: +

      + +
      +
      +/* Function with a callback */
+int binary_op(int a, int b, int (*op)(int,int));
+
+/* Some callback functions */
+%callback("%s_cb");
+int add(int,int);
+int sub(int,int);
+int mul(int,int);
+%nocallback;
+
      + +

      +The argument to %callback is a printf-style format string that +specifies the naming convention for the callback constants (%s gets replaced +by the function name). The callback mode remains in effect until it is explicitly +disabled using %nocallback. When you do this, the interface now works as follows: +

      + +
      +
      +>>> binary_op(3,4,add_cb)
+7
+>>> binary_op(3,4,mul_cb)
+12
+>>> add(3,4)
+7
+>>> mul(3,4)
+12
+
      +
      + +

      +Notice that when the function is used as a callback, special names +such as add_cb is used instead. To call the function +normally, just use the original function name such as add(). +

      + +

      +SWIG provides a number of extensions to standard C printf formatting +that may be useful in this context. For instance, the following +variation installs the callbacks as all upper-case constants such as +ADD, SUB, and MUL: +

      + +
      +/* Some callback functions */
+%callback("%(upper)s");
+int add(int,int);
+int sub(int,int);
+int mul(int,int);
+%nocallback;
+
      + +

      +A format string of "%(lower)s" converts all characters to lower-case. +A string of "%(title)s" capitalizes the first character and converts the +rest to lower case. +

      + +

      +And now, a final note about function pointer support. Although SWIG +does not normally allow callback functions to be written in the target language, this +can be accomplished with the use of typemaps and other advanced SWIG features. +This is described in a later chapter. +

      + +

      5.5 Structures and unions

      + + +

      +This section describes the behavior of SWIG when processing ANSI C structures and union declarations. Extensions to +handle C++ are described in the next section. +

      + +

      +If SWIG encounters the definition of a structure or union, it +creates a set of accessor functions. Although SWIG does not need +structure definitions to build an interface, providing definitions +make it possible to access structure members. The accessor functions +generated by SWIG simply take a pointer to an object and allow access +to an individual member. For example, the declaration :

      + +
      +struct Vector {
+	double x,y,z;
+}
+
+
      + +

      +gets transformed into the following set of accessor functions :

      + +
      +double Vector_x_get(struct Vector *obj) {
+	return obj->x;
+}
+double Vector_y_get(struct Vector *obj) { 
+	return obj->y;
+}
+double Vector_z_get(struct Vector *obj) { 
+	return obj->z;
+}
+void Vector_x_set(struct Vector *obj, double value) {
+	obj->x = value;
+}
+void Vector_y_set(struct Vector *obj, double value) {
+	obj->y = value;
+}
+void Vector_z_set(struct Vector *obj, double value) {
+	obj->z = value;
+}
+
      + +

      +In addition, SWIG creates default constructor and destructor functions if none are +defined in the interface. For example: +

      + +
      +struct Vector *new_Vector() {
+    return (Vector *) calloc(1,sizeof(struct Vector));
+}
+void delete_Vector(struct Vector *obj) {
+    free(obj);
+}
+
      +
      + +

      +Using these low-level accessor functions, an object can be minimally manipulated from the target +language using code like this: +

      + +
      +
      +v = new_Vector()
+Vector_x_set(v,2)
+Vector_y_set(v,10)
+Vector_z_set(v,-5)
+...
+delete_Vector(v)
+
      +
      + +

      +However, most of SWIG's language modules also provide a high-level interface that is more convenient. Keep reading. +

      + +

      5.5.1 Typedef and structures

      + + +

      +SWIG supports the following construct which is quite common in C +programs :

      + +
      +typedef struct {
+	double x,y,z;
+} Vector;
+
+
      + +

      +When encountered, SWIG assumes that the name of the object is `Vector' +and creates accessor functions like before. The only difference is +that the use of typedef allows SWIG to drop the +struct keyword on its generated code. For example: +

      + +
      +
      +double Vector_x_get(Vector *obj) {
+	return obj->x;
+}
+
      +
      + +

      +If two different names are used like this :

      + +
      +typedef struct vector_struct {
+	double x,y,z;
+} Vector;
+
+
      + +

      +the name Vector is used instead of vector_struct since +this is more typical C programming style. If declarations defined later in the interface use the type struct +vector_struct, SWIG knows that this is the same as +Vector and it generates the appropriate type-checking code. +

      + +

      5.5.2 Character strings and structures

      + + +

      +Structures involving character strings require some care. SWIG assumes +that all members of type char * have been dynamically +allocated using malloc() and that they are NULL-terminated +ASCII strings. When such a member is modified, the previously contents +will be released, and the new contents allocated. For example :

      + +
      +%module mymodule
+...
+struct Foo {
+	char *name;
+	...
+}
+
+
      + +

      +This results in the following accessor functions :

      + +
      +char *Foo_name_get(Foo *obj) {
+	return Foo->name;
+}
+
+char *Foo_name_set(Foo *obj, char *c) {
+	if (obj->name) free(obj->name);
+	obj->name = (char *) malloc(strlen(c)+1);
+	strcpy(obj->name,c);
+	return obj->name;
+}
+
      + +

      +If this behavior differs from what you need in your applications, +the SWIG "memberin" typemap can be used to change it. See the +typemaps chapter for further details. +

      + +

      +Note: If the -c++ option is used, new and delete are used to +perform memory allocation. +

      + +

      5.5.3 Array members

      + + +

      +Arrays may appear as the members of structures, but they will be +read-only. SWIG will write an accessor function that returns the +pointer to the first element of the array, but will not write a +function to change the contents of the array itself. +When this +situation is detected, SWIG may generate a warning message such as the +following :

      + +
      +interface.i:116. Warning. Array member will be read-only
+
      + +

      +To eliminate the warning message, typemaps can be used, but this is +discussed in a later chapter. In many cases, the warning message is +harmless. +

      + +

      5.5.4 Structure data members

      + + +

      +Occasionally, a structure will contain data members that are themselves structures. For example: +

      + +
      +
      +typedef struct Foo {
+   int x;
+} Foo;
+
+typedef struct Bar {
+   int y;
+   Foo f;           /* struct member */
+} Bar;
+
      +
      + +

      +When a structure member is wrapped, it is handled as a pointer, unless the %naturalvar directive +is used where it is handled more like a C++ reference (see C++ Member data). +The accessors to the member variable as a pointer is effectively wrapped as follows: +

      + +
      +
      +Foo *Bar_f_get(Bar *b) {
+   return &b->f;
+}
+void Bar_f_set(Bar *b, Foo *value) {
+   b->f = *value;
+}
+
      +
      + +

      +The reasons for this are somewhat subtle but have to do with the +problem of modifying and accessing data inside the data member. For +example, suppose you wanted to modify the value of f.x +of a Bar object like this: +

      + +
      +
      +Bar *b;
+b->f.x = 37;
+
      +
      + +

      +Translating this assignment to function calls (as would be used inside the scripting +language interface) results in the following code: +

      + +
      +
      +Bar *b;
+Foo_x_set(Bar_f_get(b),37);
+
      +
      + +

      +In this code, if the Bar_f_get() function were to return a Foo instead of a +Foo *, then the resulting modification would be applied to a copy of f and not +the data member f itself. Clearly that's not what you want! +

      + +

      +It should be noted that this transformation to pointers only occurs if SWIG knows that a data member +is a structure or class. For instance, if you had a structure like this, +

      + +
      +
      +struct Foo {
+   WORD   w;
+};
+
      +
      + +

      +and nothing was known about WORD, then SWIG will generate more normal accessor functions +like this: +

      + +
      +
      +WORD Foo_w_get(Foo *f) {
+    return f->w;
+}
+void Foo_w_set(FOO *f, WORD value) {
+    f->w = value;
+}
+
      +
      + + +

      +Compatibility Note: SWIG-1.3.11 and earlier releases transformed all non-primitive member datatypes +to pointers. Starting in SWIG-1.3.12, this transformation only occurs if a datatype is known to be a structure, +class, or union. This is unlikely to break existing code. However, if you need to tell SWIG that an undeclared +datatype is really a struct, simply use a forward struct declaration such as "struct Foo;". +

      + +

      5.5.5 C constructors and destructors

      + + +

      +When wrapping structures, it is generally useful to have a mechanism +for creating and destroying objects. If you don't do anything, SWIG +will automatically generate functions for creating and destroying +objects using malloc() and free(). Note: the use of +malloc() only applies when SWIG is used on C code (i.e., when the +-c++ option is not supplied on the command line). C++ is handled +differently. +

      + +

      +If you don't want SWIG to generate default constructors for your +interfaces, you can use the %nodefaultctor directive or the +-nodefaultctor command line option. For example: +

      + +
      +swig -nodefaultctor example.i 
+
      + +

      +or +

      + +
      +%module foo
+...
+%nodefaultctor;        // Don't create default constructors
+... declarations ...
+%clearnodefaultctor;   // Re-enable default constructors
+
      + +

      +If you need more precise control, %nodefaultctor can selectively target individual structure +definitions. For example: +

      + +
      +
      +%nodefaultctor Foo;      // No default constructor for Foo
+...
+struct Foo {             // No default constructor generated.
+};
+
+struct Bar {             // Default constructor generated.
+};
+
      +
      + + +

      +Since ignoring the implicit or default destructors most of the times +produce memory leaks, SWIG will always try to generate them. If +needed, however, you can selectively disable the generation of the +default/implicit destructor by using %nodefaultdtor +

      + +
      +
      +%nodefaultdtor Foo; // No default/implicit destructor for Foo
+...
+struct Foo {              // No default destructor is generated.
+};
+
+struct Bar {              // Default destructor generated.
+};
+
      +
      + + + +

      +Compatibility note: Prior to SWIG-1.3.7, SWIG did not generate default constructors +or destructors unless you explicitly turned them on using -make_default. +However, it appears that most users want to have constructor and destructor functions so it +has now been enabled as the default behavior. +

      + +

      +Note: There are also the -nodefault option and +%nodefault directive, which disable both the default or +implicit destructor generation. This could lead to memory leaks across +the target languages, and is highly recommended you don't use them. +

      + + +

      5.5.6 Adding member functions to C structures

      + + +

      +Most languages provide a mechanism for creating classes and +supporting object oriented programming. From a C standpoint, object +oriented programming really just boils down to the process of +attaching functions to structures. These functions normally operate +on an instance of the structure (or object). Although there is a +natural mapping of C++ to such a scheme, there is no direct mechanism +for utilizing it with C code. However, SWIG provides a special +%extend directive that makes it possible to attach +methods to C structures for purposes of building an object oriented +interface. Suppose you have a C header file with +the following declaration :

      + +
      +/* file : vector.h */
+...
+typedef struct {
+	double x,y,z;
+} Vector;
+
+
      + +

      +You can make a Vector look a lot like a class by writing a SWIG interface like this: +

      + +
      +// file : vector.i
+%module mymodule
+%{
+#include "vector.h"
+%}
+
+%include "vector.h"          // Just grab original C header file
+%extend Vector {             // Attach these functions to struct Vector
+	Vector(double x, double y, double z) {
+		Vector *v;
+		v = (Vector *) malloc(sizeof(Vector));
+		v->x = x;
+		v->y = y;
+		v->z = z;
+		return v;
+	}
+	~Vector() {
+		free($self);
+	}
+	double magnitude() {
+		return sqrt($self->x*$self->x+$self->y*$self->y+$self->z*$self->z);
+	}
+	void print() {
+		printf("Vector [%g, %g, %g]\n", $self->x,$self->y,$self->z);
+	}
+};
+
+
      + +

      +Note the usage of the $self special variable. +Its usage is identical to a C++ 'this' pointer and should be used whenever access to the struct instance is required. +Also note that C++ constructor and destructor syntax has been used to simulate a constructor and destructor, even for C code. +There is one subtle difference to a normal C++ constructor implementation though and that is although the constructor declaration +is as per a normal C++ constructor, the newly constructed object must be returned as if the constructor declaration +had a return value, a Vector * in this case. +

      + +

      +Now, when used with proxy classes in Python, you can do things like +this :

      + +
      +>>> v = Vector(3,4,0)                 # Create a new vector
+>>> print v.magnitude()                # Print magnitude
+5.0
+>>> v.print()                  # Print it out
+[ 3, 4, 0 ]
+>>> del v                      # Destroy it
+
      + +

      +The %extend directive can also be used inside the definition +of the Vector structure. For example:

      + +
      +// file : vector.i
+%module mymodule
+%{
+#include "vector.h"
+%}
+
+typedef struct {
+	double x,y,z;
+	%extend {
+		Vector(double x, double y, double z) { ... }
+		~Vector() { ... }
+		...
+	}
+} Vector;
+
      + +

      +Finally, %extend can be used to access externally written +functions provided they follow the naming convention used in this +example :

      + +
      +/* File : vector.c */
+/* Vector methods */
+#include "vector.h"
+Vector *new_Vector(double x, double y, double z) {
+	Vector *v;
+	v = (Vector *) malloc(sizeof(Vector));
+	v->x = x;
+	v->y = y;
+	v->z = z;
+	return v;
+}
+void delete_Vector(Vector *v) {
+	free(v);
+}
+
+double Vector_magnitude(Vector *v) {
+	return sqrt(v->x*v->x+v->y*v->y+v->z*v->z);
+}
+
+// File : vector.i
+// Interface file
+%module mymodule
+%{
+#include "vector.h"
+%}
+
+typedef struct {
+	double x,y,z;
+	%extend {
+                Vector(int,int,int); // This calls new_Vector()
+               ~Vector();            // This calls delete_Vector()
+		double magnitude();  // This will call Vector_magnitude()
+		...
+	}
+} Vector;
+
      +
      + +

      +A little known feature of the %extend directive is that +it can also be used to add synthesized attributes or to modify the +behavior of existing data attributes. For example, suppose you wanted +to make magnitude a read-only attribute of Vector +instead of a method. To do this, you might write some code like this: +

      + +
      +
      +// Add a new attribute to Vector
+%extend Vector {
+    const double magnitude;
+}
+// Now supply the implementation of the Vector_magnitude_get function
+%{
+const double Vector_magnitude_get(Vector *v) {
+  return (const double) return sqrt(v->x*v->x+v->y*v->y+v->z*v->z);
+}
+%}
+
+
      +
      + +

      +Now, for all practical purposes, magnitude will appear like an attribute +of the object. +

      + +

      +A similar technique can also be used to work with problematic data members. +For example, consider this interface: +

      + +
      +
      +struct Person {
+   char name[50];
+   ...
+}
+
      +
      + +

      +By default, the name attribute is read-only because SWIG does not +normally know how to modify arrays. However, you can rewrite the interface +as follows to change this: +

      + +
      +
      +struct Person {
+    %extend {
+       char *name;
+    }
+...
+}
+
+// Specific implementation of set/get functions
+%{
+char *Person_name_get(Person *p) {
+   return p->name;
+}
+void Person_name_set(Person *p, char *val) {
+   strncpy(p->name,val,50);
+}
+%}
+
      +
      + +

      +Finally, it should be stressed that even though %extend +can be used to add new data members, these new members can not require +the allocation of additional storage in the object (e.g., their values must +be entirely synthesized from existing attributes of the structure). +

      + +

      +Compatibility note: The %extend directive is a new +name for the %addmethods directive. Since %addmethods could +be used to extend a structure with more than just methods, a more suitable +directive name has been chosen. +

      + +

      5.5.7 Nested structures

      + + +

      +Occasionally, a C program will involve structures like this :

      + +
      +typedef struct Object {
+	int objtype;
+	union {
+		int 	ivalue;
+		double	dvalue;
+		char	*strvalue;
+		void	*ptrvalue;
+	} intRep;
+} Object;
+
+
      + +

      +When SWIG encounters this, it performs a structure splitting operation +that transforms the declaration into the equivalent of the +following:

      + +
      +typedef union {
+	int 		ivalue;
+	double		dvalue;
+	char		*strvalue;
+	void		*ptrvalue;
+} Object_intRep;
+
+typedef struct Object {
+	int objType;
+	Object_intRep intRep;
+} Object;
+
+
      + +

      +SWIG will then create an Object_intRep structure for use inside +the interface file. Accessor functions will be created for both +structures. In this case, functions like this would be created :

      + +
      +Object_intRep *Object_intRep_get(Object *o) {
+	return (Object_intRep *) &o->intRep;
+}
+int Object_intRep_ivalue_get(Object_intRep *o) {
+	return o->ivalue;
+}
+int Object_intRep_ivalue_set(Object_intRep *o, int value) {
+	return (o->ivalue = value);
+}
+double Object_intRep_dvalue_get(Object_intRep *o) {
+	return o->dvalue;
+}
+... etc ...
+
+
      + +

      +Although this process is a little hairy, it works like you would expect in the +target scripting language--especially when proxy classes are used. For instance, in Perl: +

      + +
      +# Perl5 script for accessing nested member
+$o = CreateObject();                    # Create an object somehow
+$o->{intRep}->{ivalue} = 7              # Change value of o.intRep.ivalue
+
      + +

      +If you have a lot nested structure declarations, it is +advisable to double-check them after running SWIG. Although, +there is a good chance that they will work, you may have to +modify the interface file in certain cases. + +

      5.5.8 Other things to note about structure wrapping

      + + +

      +SWIG doesn't care if the declaration of a structure in a .i file exactly matches +that used in the underlying C code (except in the case of nested +structures). For this reason, there are no problems omitting +problematic members or simply omitting the structure definition +altogether. If you are happy passing pointers around, this can +be done without ever giving SWIG a structure definition.

      + +

      +Starting with SWIG1.3, a number of improvements have been made to SWIG's +code generator. Specifically, even though structure access has been described +in terms of high-level accessor functions such as this, +

      + +
      +
      +double Vector_x_get(Vector *v) {
+   return v->x;
+}
+
      +
      + +

      +most of the generated code is actually inlined directly into wrapper +functions. Therefore, no function Vector_x_get() actually +exists in the generated wrapper file. For example, when creating a Tcl module, +the following function is generated instead: +

      + +
      +
      +static int
+_wrap_Vector_x_get(ClientData clientData, Tcl_Interp *interp, 
+                   int objc, Tcl_Obj *CONST objv[]) {
+    struct Vector *arg1 ;
+    double result ;
+    
+    if (SWIG_GetArgs(interp, objc, objv,"p:Vector_x_get self ",&arg0,
+                     SWIGTYPE_p_Vector) == TCL_ERROR)
+         return TCL_ERROR;
+    result = (double ) (arg1->x);
+    Tcl_SetObjResult(interp,Tcl_NewDoubleObj((double) result));
+    return TCL_OK;
+}
+
      +
      + +

      +The only exception to this rule are methods defined with %extend. In this +case, the added code is contained in a separate function. +

      + +

      +Finally, it is important to note that most language modules may choose to +build a more advanced interface. Although you may never use the low-level +interface described here, most of SWIG's language modules use it in +some way or another. +

      + +

      5.6 Code Insertion

      + + +

      +Sometimes it is necessary to insert special code into the resulting +wrapper file generated by SWIG. For example, you may want to include +additional C code to perform initialization or other operations. +There are four common ways to insert code, but it's useful to know how the +output of SWIG is structured first.

      + +

      5.6.1 The output of SWIG

      + + +

      +When SWIG creates its output file, it is broken up into four sections +corresponding to runtime code, headers, wrapper functions, and module +initialization code (in that order). +

      + +
        +
      • Begin section.
        +A placeholder to put code at the beginning of the C/C++ wrapper file. +
        • + +
      • Runtime code.
        +This code is internal to SWIG and is used to include +type-checking and other support functions that are used by the rest of the module. +
        • + +
      • Header section.
        +This is user-defined support code that has been included by +the %{ ... %} directive. Usually this consists of header files and +other helper functions. +
        • + +
      • Wrapper code.
        +These are the wrappers generated automatically by SWIG. +
        • + +
      • Module initialization.
        +The function generated by SWIG to initialize +the module upon loading. +
        • +
      + +

      5.6.2 Code insertion blocks

      + + +

      +Code is inserted into the appropriate code section by using one +of the code insertion directives listed below. The order of the sections in +the wrapper file is as shown: +

      + +
      +
      +%begin %{
+   ... code in begin section ...
+%}
+
+%runtime %{
+   ... code in runtime section ...
+%}
+
+%header %{
+   ... code in header section ...
+%}
+
+%wrapper %{
+   ... code in wrapper section ...
+%}
+
+%init %{
+   ... code in init section ...
+%}
+
      +
      + +

      +The bare %{ ... %} directive is a shortcut that is the same as +%header %{ ... %}. +

      + +

      +The %begin section is effectively empty as it just contains the SWIG banner by default. +This section is provided as a way for users to insert code at the top of the wrapper file before any other code is generated. +Everything in a code insertion block is copied verbatim into the output file and is +not parsed by SWIG. Most SWIG input files have at least one such block to include header +files and support C code. Additional code blocks may be placed anywhere in a +SWIG file as needed.

      + +
      +%module mymodule
+%{
+#include "my_header.h"
+%}
+... Declare functions here
+%{
+
+void some_extra_function() {
+  ...
+}
+%}
+
      + +

      +A common use for code blocks is to write "helper" functions. These +are functions that are used specifically for the purpose of building +an interface, but which are generally not visible to the normal C +program. For example :

      + +
      +%{
+/* Create a new vector */
+static Vector *new_Vector() {
+	return (Vector *) malloc(sizeof(Vector));
+}
+
+%}
+// Now wrap it 
+Vector *new_Vector();
+
      + +

      5.6.3 Inlined code blocks

      + + +

      +Since the process of writing helper functions is fairly common, +there is a special inlined form of code block that is used as follows +:

      + +
      +%inline %{
+/* Create a new vector */
+Vector *new_Vector() {
+	return (Vector *) malloc(sizeof(Vector));
+}
+%}
+
+
      + +

      +The %inline directive inserts all of the code that follows +verbatim into the header portion of an interface file. The code is +then parsed by both the SWIG preprocessor and parser. +Thus, the above example creates a new command new_Vector using only one +declaration. Since the code inside an %inline %{ ... %} block +is given to both the C compiler and SWIG, it is illegal to include any +SWIG directives inside a %{ ... %} block.

      + +

      5.6.4 Initialization blocks

      + + +

      +When code is included in the %init section, it is copied directly into the +module initialization function. For example, if you needed to perform some extra +initialization on module loading, you could write this: +

      + +
      +%init %{
+	init_variables();
+%}
+
      + +

      5.7 An Interface Building Strategy

      + + +

      +This section describes the general approach for building interface +with SWIG. The specifics related to a particular scripting language +are found in later chapters.

      + +

      5.7.1 Preparing a C program for SWIG

      + + +

      +SWIG doesn't require modifications to your C code, but if you feed it +a collection of raw C header files or source code, the results might +not be what you expect---in fact, they might be awful. Here's a series +of steps you can follow to make an interface for a C program :

      + +
        +
      • Identify the functions that you want to wrap. It's probably not +necessary to access every single function in a C program--thus, a +little forethought can dramatically simplify the resulting scripting +language interface. C header files are particularly good source for +finding things to wrap. + +
      • Create a new interface file to describe the scripting language +interface to your program. + +
      • Copy the appropriate declarations into the interface file or use +SWIG's %include directive to process an entire C +source/header file. + +
      • Make sure everything in the interface file uses ANSI C/C++ syntax. + +
      • Make sure all necessary `typedef' declarations and +type-information is available in the interface file. +In particular, ensure that the type information is specified in the correct order as required by a C/C++ compiler. +Most importantly, define a type before it is used! A C compiler will tell you +if the full type information is not available if it is needed, whereas +SWIG will usually not warn or error out as it is designed to work without +full type information. However, if type information is not specified +correctly, the wrappers can be sub-optimal and even result in uncompileable C/C++ code. + +
      • If your program has a main() function, you may need to rename it +(read on). + +
      • Run SWIG and compile. +
      + +

      +Although this may sound complicated, the process turns out to be +fairly easy once you get the hang of it. +

      + +

      +In the process of building an interface, SWIG may encounter syntax errors or +other problems. The best way to deal with this is to simply copy the offending +code into a separate interface file and edit it. However, the SWIG developers +have worked very hard to improve the SWIG parser--you should report parsing errors +to the swig-devel mailing list or to the +SWIG bug tracker. +

      + +

      5.7.2 The SWIG interface file

      + + +

      +The preferred method of using SWIG is to generate separate interface +file. Suppose you have the following C header file :

      + +
      +/* File : header.h */
+
+#include <stdio.h>
+#include <math.h>
+
+extern int foo(double);
+extern double bar(int, int);
+extern void dump(FILE *f);
+
+
      + +

      +A typical SWIG interface file for this header file would look like the +following :

      + +
      +/* File : interface.i */
+%module mymodule
+%{
+#include "header.h"
+%}
+extern int foo(double);
+extern double bar(int, int);
+extern void dump(FILE *f);
+
+
      + +

      +Of course, in this case, our header file is pretty simple so we could +use a simpler approach and use an interface file like this:

      + +
      +/* File : interface.i */
+%module mymodule
+%{
+#include "header.h"
+%}
+%include "header.h"
+
      + +

      +The main advantage of this approach is minimal maintenance of an interface file for when the header file changes in the future. +In more complex projects, an interface file containing numerous %include and #include statements like this is one of the most common approaches to interface file design due to lower maintenance overhead. +

      + +

      5.7.3 Why use separate interface files?

      + + +

      +Although SWIG can parse many header files, it is more common to write a +special .i file defining the interface to a package. There +are several reasons why you might want to do this: +

      + +
        +
      • It is rarely necessary to access every single function in a large +package. Many C functions might have little or no use in a scripted +environment. Therefore, why wrap them? + +
      • Separate interface files provide an opportunity to provide more +precise rules about how an interface is to be constructed. + +
      • Interface files can provide more structure and organization. + +
      • SWIG can't parse certain definitions that appear in header +files. Having a separate file allows you to eliminate or work around +these problems. + +
      • Interface files provide a more precise definition of what the interface +is. Users wanting to extend the system can go to the interface file +and immediately see what is available without having to dig it out of +header files. +
      + +

      5.7.4 Getting the right header files

      + + +

      +Sometimes, it is necessary to use certain header files in order for +the code generated by SWIG to compile properly. Make sure you +include certain header files by using a %{,%} block like this: +

      + +
      +%module graphics
+%{
+#include <GL/gl.h>
+#include <GL/glu.h>
+%}
+
+// Put rest of declarations here
+...
+
      + +

      5.7.5 What to do with main()

      + + +

      +If your program defines a main() function, you may need to +get rid of it or rename it in order to use a scripting language. Most +scripting languages define their own main() procedure that +is called instead. main() also makes no sense when +working with dynamic loading. There are a few approaches to solving +the main() conflict :

      + +
        +
      • Get rid of main() entirely. + +
      • Rename main() to something else. You can do this by +compiling your C program with an option like -Dmain=oldmain. + +
      • Use conditional compilation to only include main() when +not using a scripting language. +
      + +

      +Getting rid of main() may cause potential initialization +problems of a program. To handle this problem, you may consider +writing a special function called program_init() that +initializes your program upon startup. This function could then be +called either from the scripting language as the first operation, or +when the SWIG generated module is loaded.

      + +

      +As a general note, many C programs only use the main() +function to parse command line options and to set parameters. However, +by using a scripting language, you are probably trying to create a +program that is more interactive. In many cases, the old +main() program can be completely replaced by a Perl, Python, +or Tcl script.

      + +

      +Note: If some cases, you might be inclined to create a +scripting language wrapper for main(). If you do this, the +compilation will probably work and your module might even load +correctly. The only trouble is that when you call your +main() wrapper, you will find that it actually invokes the +main() of the scripting language interpreter itself! This behavior +is a side effect of the symbol binding mechanism used in the dynamic linker. +The bottom line: don't do this. +

      + + + diff --git a/Doc/Manual/SWIGDocumentation.html b/Doc/Manual/SWIGDocumentation.html new file mode 100644 index 0000000..a998b95 --- /dev/null +++ b/Doc/Manual/SWIGDocumentation.html @@ -0,0 +1,50041 @@ + + + +SWIG-1.3 Documentation + + + + +
      SWIG-1.3 Documentation
      +

      SWIG-1.3 Documentation


      +
      +
      +

      Table of Contents

      +
      +
      SWIG-1.3 Development Documentation + +1 Preface + +2 Introduction + +3 Getting started on Windows + +4 Scripting Languages + +5 SWIG Basics + +6 SWIG and C++ + +7 Preprocessing + +8 SWIG library + +9 Argument Handling + +10 Typemaps + +11 Customization Features + +12 Contracts + +13 Variable Length Arguments + +14 Warning Messages + +15 Working with Modules + +16 Using SWIG with ccache - ccache-swig(1) manpage + + +17 SWIG and Allegro Common Lisp + +18 SWIG and C# + +19 SWIG and Chicken + +20 SWIG and Guile + +21 SWIG and Java + +22 SWIG and Common Lisp + +23 SWIG and Lua + +24 SWIG and Modula-3 + +25 SWIG and MzScheme + +26 SWIG and Ocaml + +27 SWIG and Octave + +28 SWIG and Perl5 + +29 SWIG and PHP + +30 SWIG and Pike + +31 SWIG and Python + +32 SWIG and Ruby + +33 SWIG and Tcl + +34 SWIG and R + +35 Extending SWIG to support new languages + +
      +

      SWIG-1.3 Development Documentation

      + Last update : SWIG-1.3.40 (18 August 2009) +

      Sections

      +

      The SWIG documentation is being updated to reflect new SWIG features + and enhancements. However, this update process is not quite + finished--there is a lot of old SWIG-1.1 documentation and it is taking + some time to update all of it. Please pardon our dust (or volunteer to + help!).

      +

      SWIG Core Documentation

      + +

      Language Module Documentation

      + +

      Developer Documentation

      + +

      Documentation that has not yet been updated

      +

      This documentation has not been completely updated from SWIG-1.1, + but most of the topics still apply to the current release. Make sure + you read the SWIG Basics chapter before reading any + of these chapters. Also, SWIG-1.3.10 features extensive changes to the + implementation of typemaps. Make sure you read the +Typemaps chapter above if you are using this feature.

      + +
      +

      1 Preface

      + + +
      + +
      + +

      1.1 Introduction

      +

      SWIG (Simplified Wrapper and Interface Generator) is a software + development tool for building scripting language interfaces to C and + C++ programs. Originally developed in 1995, SWIG was first used by + scientists in the Theoretical Physics Division at Los Alamos National + Laboratory for building user interfaces to simulation codes running on + the Connection Machine 5 supercomputer. In this environment, scientists + needed to work with huge amounts of simulation data, complex hardware, + and a constantly changing code base. The use of a scripting language + interface provided a simple yet highly flexible foundation for solving + these types of problems. SWIG simplifies development by largely + automating the task of scripting language integration--allowing + developers and users to focus on more important problems.

      +

      Although SWIG was originally developed for scientific applications, + it has since evolved into a general purpose tool that is used in a wide + variety of applications--in fact almost anything where C/C++ + programming is involved.

      +

      1.2 Special Introduction for Version 1.3

      +

      Since SWIG was released in 1996, its user base and applicability has + continued to grow. Although its rate of development has varied, an + active development effort has continued to make improvements to the + system. Today, nearly a dozen developers are working to create + SWIG-2.0---a system that aims to provide wrapping support for nearly + all of the ANSI C++ standard and approximately ten target languages + including Guile, Java, Mzscheme, Ocaml, Perl, Pike, PHP, Python, Ruby, + and Tcl.

      +

      1.3 SWIG Versions

      +

      For several years, the most stable version of SWIG has been release + 1.1p5. Starting with version 1.3, a new version numbering scheme has + been adopted. Odd version numbers (1.3, 1.5, etc.) represent + development versions of SWIG. Even version numbers (1.4, 1.6, etc.) + represent stable releases. Currently, developers are working to create + a stable SWIG-2.0 release. Don't let the development status of SWIG-1.3 + scare you---it is much more stable (and capable) than SWIG-1.1p5.

      +

      1.4 SWIG resources

      +

      The official location of SWIG related material is

      +
      +
      +http://www.swig.org
+
      +
      +

      This site contains the latest version of the software, users guide, + and information regarding bugs, installation problems, and + implementation tricks.

      +

      You can also subscribe to the swig-user mailing list by visiting the + page

      +
      +
      +http://www.swig.org/mail.html
+
      +
      +

      The mailing list often discusses some of the more technical aspects + of SWIG along with information about beta releases and future work.

      +

      SVN access to the latest version of SWIG is also available. More + information about this can be obtained at:

      +
      +
      +http://www.swig.org/svn.html
+
      +
      +

      1.5 Prerequisites

      +

      This manual assumes that you know how to write C/C++ programs and + that you have at least heard of scripting languages such as Tcl, + Python, and Perl. A detailed knowledge of these scripting languages is + not required although some familiarity won't hurt. No prior experience + with building C extensions to these languages is required---after all, + this is what SWIG does automatically. However, you should be reasonably + familiar with the use of compilers, linkers, and makefiles since making + scripting language extensions is somewhat more complicated than writing + a normal C program.

      +

      Recent SWIG releases have become significantly more capable in their + C++ handling--especially support for advanced features like namespaces, + overloaded operators, and templates. Whenever possible, this manual + tries to cover the technicalities of this interface. However, this + isn't meant to be a tutorial on C++ programming. For many of the gory + details, you will almost certainly want to consult a good C++ + reference. If you don't program in C++, you may just want to skip those + parts of the manual.

      +

      1.6 Organization of this manual

      +

      The first few chapters of this manual describe SWIG in general and + provide an overview of its capabilities. The remaining chapters are + devoted to specific SWIG language modules and are self contained. Thus, + if you are using SWIG to build Python interfaces, you can probably skip + to that chapter and find almost everything you need to know. Caveat: we + are currently working on a documentation rewrite and many of the older + language module chapters are still somewhat out of date.

      +

      1.7 How to avoid reading the manual

      +

      If you hate reading manuals, glance at the "Introduction" which + contains a few simple examples. These examples contain about 95% of + everything you need to know to use SWIG. After that, simply use the + language-specific chapters as a reference. The SWIG distribution also + comes with a large directory of examples that illustrate different + topics.

      +

      1.8 Backwards Compatibility

      +

      If you are a previous user of SWIG, don't expect recent versions of + SWIG to provide backwards compatibility. In fact, backwards + compatibility issues may arise even between successive 1.3.x releases. + Although these incompatibilities are regrettable, SWIG-1.3 is an active + development project. The primary goal of this effort is to make SWIG + better---a process that would simply be impossible if the developers + are constantly bogged down with backwards compatibility issues.

      +

      On a positive note, a few incompatibilities are a small price to pay + for the large number of new features that have been added---namespaces, + templates, smart pointers, overloaded methods, operators, and more.

      +

      If you need to work with different versions of SWIG and backwards + compatibility is an issue, you can use the SWIG_VERSION preprocessor + symbol which holds the version of SWIG being executed. SWIG_VERSION is + a hexadecimal integer such as 0x010311 (corresponding to SWIG-1.3.11). + This can be used in an interface file to define different typemaps, + take advantage of different features etc:

      +
      +
      +#if SWIG_VERSION >= 0x010311
+/* Use some fancy new feature */
+#endif
+
      +
      +

      Note: The version symbol is not defined in the generated SWIG + wrapper file. The SWIG preprocessor has defined SWIG_VERSION since + SWIG-1.3.11.

      +

      1.9 Credits

      +

      SWIG is an unfunded project that would not be possible without the + contributions of many people. Most recent SWIG development has been + supported by Matthias Köppe, William Fulton, Lyle Johnson, Richard + Palmer, Thien-Thi Nguyen, Jason Stewart, Loic Dachary, Masaki + Fukushima, Luigi Ballabio, Sam Liddicott, Art Yerkes, Marcelo Matus, + Harco de Hilster, John Lenz, and Surendra Singhi.

      +

      Historically, the following people contributed to early versions of + SWIG. Peter Lomdahl, Brad Holian, Shujia Zhou, Niels Jensen, and Tim + Germann at Los Alamos National Laboratory were the first users. Patrick + Tullmann at the University of Utah suggested the idea of automatic + documentation generation. John Schmidt and Kurtis Bleeker at the + University of Utah tested out the early versions. Chris Johnson + supported SWIG's developed at the University of Utah. John Buckman, + Larry Virden, and Tom Schwaller provided valuable input on the first + releases and improving the portability of SWIG. David Fletcher and Gary + Holt have provided a great deal of input on improving SWIG's Perl5 + implementation. Kevin Butler contributed the first Windows NT port.

      +

      1.10 Bug reports

      +

      Although every attempt has been made to make SWIG bug-free, we are + also trying to make feature improvements that may introduce bugs. To + report a bug, either send mail to the SWIG developer list at the +swig-devel mailing list or report a bug at the +SWIG bug tracker. In your report, be as specific as possible, + including (if applicable), error messages, tracebacks (if a core dump + occurred), corresponding portions of the SWIG interface file used, and + any important pieces of the SWIG generated wrapper code. We can only + fix bugs if we know about them.

      +
      +

      2 Introduction

      + + +
      + +
      + +

      2.1 What is SWIG?

      +

      SWIG is a software development tool that simplifies the task of + interfacing different languages to C and C++ programs. In a nutshell, + SWIG is a compiler that takes C declarations and creates the wrappers + needed to access those declarations from other languages including + including Perl, Python, Tcl, Ruby, Guile, and Java. SWIG normally + requires no modifications to existing code and can often be used to + build a usable interface in only a few minutes. Possible applications + of SWIG include:

      +
        +
      • Building interpreted interfaces to existing C programs.
        • +
      • Rapid prototyping and application development.
        • +
      • Interactive debugging.
        • +
      • Reengineering or refactoring of legacy software into a scripting + language components.
        • +
      • Making a graphical user interface (using Tk for example).
        • +
      • Testing of C libraries and programs (using scripts).
        • +
      • Building high performance C modules for scripting languages.
        • +
      • Making C programming more enjoyable (or tolerable depending on your + point of view).
        • +
      • Impressing your friends.
        • +
      • Obtaining vast sums of research funding (although obviously not + applicable to the author).
        • +
      +

      SWIG was originally designed to make it extremely easy for + scientists and engineers to build extensible scientific software + without having to get a degree in software engineering. Because of + this, the use of SWIG tends to be somewhat informal and ad-hoc (e.g., + SWIG does not require users to provide formal interface specifications + as you would find in a dedicated IDL compiler). Although this style of + development isn't appropriate for every project, it is particularly + well suited to software development in the small; especially the + research and development work that is commonly found in scientific and + engineering projects.

      +

      2.2 Why use SWIG?

      +

      As stated in the previous section, the primary purpose of SWIG is to + simplify the task of integrating C/C++ with other programming + languages. However, why would anyone want to do that? To answer that + question, it is useful to list a few strengths of C/C++ programming:

      +
        +
      • Excellent support for writing programming libraries.
        • +
      • High performance (number crunching, data processing, graphics, + etc.).
        • +
      • Systems programming and systems integration.
        • +
      • Large user community and software base.
        • +
      +

      Next, let's list a few problems with C/C++ programming

      +
        +
      • Writing a user interface is rather painful (i.e., consider + programming with MFC, X11, GTK, or any number of other libraries).
        • +
      • Testing is time consuming (the compile/debug cycle).
        • +
      • Not easy to reconfigure or customize without recompilation.
        • +
      • Modularization can be tricky.
        • +
      • Security concerns (buffer overflow for instance).
        • +
      +

      To address these limitations, many programmers have arrived at the + conclusion that it is much easier to use different programming + languages for different tasks. For instance, writing a graphical user + interface may be significantly easier in a scripting language like + Python or Tcl (consider the reasons why millions of programmers have + used languages like Visual Basic if you need more proof). An + interactive interpreter might also serve as a useful debugging and + testing tool. Other languages like Java might greatly simplify the task + of writing distributed computing software. The key point is that + different programming languages offer different strengths and + weaknesses. Moreover, it is extremely unlikely that any programming is + ever going to be perfect. Therefore, by combining languages together, + you can utilize the best features of each language and greatly simplify + certain aspects of software development.

      +

      From the standpoint of C/C++, a lot of people use SWIG because they + want to break out of the traditional monolithic C programming model + which usually results in programs that resemble this:

      +
        +
      • A collection of functions and variables that do something useful.
        • +
      • A main() program that starts everything.
        • +
      • A horrible collection of hacks that form some kind of user interface + (but which no-one really wants to touch).
        • +
      +

      Instead of going down that route, incorporating C/C++ into a higher + level language often results in a more modular design, less code, + better flexibility, and increased programmer productivity.

      +

      SWIG tries to make the problem of C/C++ integration as painless as + possible. This allows you to focus on the underlying C program and + using the high-level language interface, but not the tedious and + complex chore of making the two languages talk to each other. At the + same time, SWIG recognizes that all applications are different. + Therefore, it provides a wide variety of customization features that + let you change almost every aspect of the language bindings. This is + the main reason why SWIG has such a large user manual ;-).

      +

      2.3 A SWIG example

      +

      The best way to illustrate SWIG is with a simple example. Consider + the following C code:

      +
      +
      +/* File : example.c */
+
+double  My_variable  = 3.0;
+
+/* Compute factorial of n */
+int  fact(int n) {
+	if (n <= 1) return 1;
+	else return n*fact(n-1);
+}
+
+/* Compute n mod m */
+int my_mod(int n, int m) {
+	return(n % m);
+}
+
      +
      +

      Suppose that you wanted to access these functions and the global + variable My_variable from Tcl. You start by making a SWIG + interface file as shown below (by convention, these files carry a .i + suffix) :

      +

      2.3.1 SWIG interface file

      +
      +
      +/* File : example.i */
+%module example
+%{
+/* Put headers and other declarations here */
+extern double My_variable;
+extern int    fact(int);
+extern int    my_mod(int n, int m);
+%}
+
+extern double My_variable;
+extern int    fact(int);
+extern int    my_mod(int n, int m);
+
      +
      +

      The interface file contains ANSI C function prototypes and variable + declarations. The %module directive defines the name of the + module that will be created by SWIG. The %{,%} block provides + a location for inserting additional code such as C header files or + additional C declarations.

      +

      2.3.2 The swig command

      +

      SWIG is invoked using the swig command. We can use this to + build a Tcl module (under Linux) as follows :

      +
      +
      +unix > swig -tcl example.i
+unix > gcc -c -fpic example.c example_wrap.c -I/usr/local/include
+unix > gcc -shared example.o example_wrap.o -o example.so
+unix > tclsh
+% load ./example.so
+% fact 4
+24
+% my_mod 23 7
+2
+% expr $My_variable + 4.5
+7.5
+%
+
      +
      +

      The swig command produced a new file called +example_wrap.c that should be compiled along with the example.c + file. Most operating systems and scripting languages now support + dynamic loading of modules. In our example, our Tcl module has been + compiled into a shared library that can be loaded into Tcl. When + loaded, Tcl can now access the functions and variables declared in the + SWIG interface. A look at the file example_wrap.c reveals a + hideous mess. However, you almost never need to worry about it.

      +

      2.3.3 Building a Perl5 module

      +

      Now, let's turn these functions into a Perl5 module. Without making + any changes type the following (shown for Solaris):

      +
      +
      +unix > swig -perl5 example.i
+unix > gcc -c example.c example_wrap.c \
+	-I/usr/local/lib/perl5/sun4-solaris/5.003/CORE
+unix > ld -G example.o example_wrap.o -o example.so		# This is for Solaris
+unix > perl5.003
+use example;
+print example::fact(4), "\n";
+print example::my_mod(23,7), "\n";
+print $example::My_variable + 4.5, "\n";
+<ctrl-d>
+24
+2
+7.5
+unix >
+
      +
      +

      2.3.4 Building a Python module

      +

      Finally, let's build a module for Python (shown for Irix).

      +
      +
      +unix > swig -python example.i
+unix > gcc -c -fpic example.c example_wrap.c -I/usr/local/include/python2.0
+unix > gcc -shared example.o example_wrap.o -o _example.so
+unix > python
+Python 2.0 (#6, Feb 21 2001, 13:29:45)
+[GCC egcs-2.91.66 19990314/Linux (egcs-1.1.2 release)] on linux2
+Type "copyright", "credits" or "license" for more information.     
+>>> import example
+>>> example.fact(4)
+24
+>>> example.my_mod(23,7)
+2
+>>> example.cvar.My_variable + 4.5
+7.5
+
      +
      +

      2.3.5 Shortcuts

      +

      To the truly lazy programmer, one may wonder why we needed the extra + interface file at all. As it turns out, you can often do without it. + For example, you could also build a Perl5 module by just running SWIG + on the C header file and specifying a module name as follows

      +
      +
      +unix > swig -perl5 -module example example.h
+unix > gcc -c example.c example_wrap.c \
+	-I/usr/local/lib/perl5/sun4-solaris/5.003/CORE
+unix > ld -G example.o example_wrap.o -o example.so
+unix > perl5.003
+use example;
+print example::fact(4), "\n";
+print example::my_mod(23,7), "\n";
+print $example::My_variable + 4.5, "\n";
+<ctrl-d>
+24
+2
+7.5
+
      +
      +

      2.4 Supported C/C++ language + features

      +

      A primary goal of the SWIG project is to make the language binding + process extremely easy. Although a few simple examples have been shown, + SWIG is quite capable in supporting most of C++. Some of the major + features include:

      +
        +
      • Full C99 preprocessing.
        • +
      • All ANSI C and C++ datatypes.
        • +
      • Functions, variables, and constants.
        • +
      • Classes.
        • +
      • Single and multiple inheritance.
        • +
      • Overloaded functions and methods.
        • +
      • Overloaded operators.
        • +
      • C++ templates (including member templates, specialization, and + partial specialization).
        • +
      • Namespaces.
        • +
      • Variable length arguments.
        • +
      • C++ smart pointers.
        • +
      +

      Currently, the only major C++ feature not supported is nested + classes--a limitation that will be removed in a future release.

      +

      It is important to stress that SWIG is not a simplistic C++ lexing + tool like several apparently similar wrapper generation tools. SWIG not + only parses C++, it implements the full C++ type system and it is able + to understand C++ semantics. SWIG generates its wrappers with full + knowledge of this information. As a result, you will find SWIG to be + just as capable of dealing with nasty corner cases as it is in wrapping + simple C++ code. In fact, SWIG is able handle C++ code that stresses + the very limits of many C++ compilers.

      +

      2.5 Non-intrusive interface building

      +

      When used as intended, SWIG requires minimal (if any) modification + to existing C or C++ code. This makes SWIG extremely easy to use with + existing packages and promotes software reuse and modularity. By making + the C/C++ code independent of the high level interface, you can change + the interface and reuse the code in other applications. It is also + possible to support different types of interfaces depending on the + application.

      +

      2.6 Incorporating SWIG into + a build system

      +

      SWIG is a command line tool and as such can be incorporated into any + build system that supports invoking external tools/compilers. SWIG is + most commonly invoked from within a Makefile, but is also known to be + invoked from from popular IDEs such as Microsoft Visual Studio.

      +

      If you are using the GNU Autotools ( +Autoconf/ Automake +/ Libtool) to + configure SWIG use in your project, the SWIG Autoconf macros can be + used. The primary macro is ac_pkg_swig, see +http://www.gnu.org/software/ac-archive/htmldoc/ac_pkg_swig.html. The + ac_python_devel macro is also helpful for generating Python + extensions. See the +Autoconf Macro Archive for further information on this and other + Autoconf macros.

      +

      There is growing support for SWIG in some build tools, for example CMake is a cross-platform, open-source + build manager with built in support for SWIG. CMake can detect the SWIG + executable and many of the target language libraries for linking + against. CMake knows how to build shared libraries and loadable modules + on many different operating systems. This allows easy cross platform + SWIG development. It also can generate the custom commands necessary + for driving SWIG from IDE's and makefiles. All of this can be done from + a single cross platform input file. The following example is a CMake + input file for creating a python wrapper for the SWIG interface file, + example.i:

      +
      +
      +
+# This is a CMake example for Python
+
+FIND_PACKAGE(SWIG REQUIRED)
+INCLUDE(${SWIG_USE_FILE})
+
+FIND_PACKAGE(PythonLibs)
+INCLUDE_DIRECTORIES(${PYTHON_INCLUDE_PATH})
+
+INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})
+
+SET(CMAKE_SWIG_FLAGS "")
+
+SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES CPLUSPLUS ON)
+SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES SWIG_FLAGS "-includeall")
+SWIG_ADD_MODULE(example python example.i example.cxx)
+SWIG_LINK_LIBRARIES(example ${PYTHON_LIBRARIES})
+
+
      +
      +

      The above example will generate native build files such as + makefiles, nmake files and Visual Studio projects which will invoke + SWIG and compile the generated C++ files into _example.so (UNIX) or + _example.pyd (Windows). For other target languages on Windows a dll, + instead of a .pyd file, is usually generated.

      +

      2.7 Hands off code generation

      +

      SWIG is designed to produce working code that needs no + hand-modification (in fact, if you look at the output, you probably + won't want to modify it). You should think of your target language + interface being defined entirely by the input to SWIG, not the + resulting output file. While this approach may limit flexibility for + hard-core hackers, it allows others to forget about the low-level + implementation details.

      +

      2.8 SWIG and freedom

      +

      No, this isn't a special section on the sorry state of world + politics. However, it may be useful to know that SWIG was written with + a certain "philosophy" about programming---namely that programmers are + smart and that tools should just stay out of their way. Because of + that, you will find that SWIG is extremely permissive in what it lets + you get away with. In fact, you can use SWIG to go well beyond + "shooting yourself in the foot" if dangerous programming is your goal. + On the other hand, this kind of freedom may be exactly what is needed + to work with complicated and unusual C/C++ applications.

      +

      Ironically, the freedom that SWIG provides is countered by an + extremely conservative approach to code generation. At it's core, SWIG + tries to distill even the most advanced C++ code down to a small + well-defined set of interface building techniques based on ANSI C + programming. Because of this, you will find that SWIG interfaces can be + easily compiled by virtually every C/C++ compiler and that they can be + used on any platform. Again, this is an important part of staying out + of the programmer's way----the last thing any developer wants to do is + to spend their time debugging the output of a tool that relies on + non-portable or unreliable programming features.

      +
      +

      3 Getting started on Windows

      + + +
      + +
      + +

      This chapter describes SWIG usage on Microsoft Windows. Installing + SWIG and running the examples is covered as well as building the SWIG + executable. Usage within the Unix like environments MinGW and Cygwin is + also detailed.

      +

      3.1 Installation on Windows

      +

      SWIG does not come with the usual Windows type installation program, + however it is quite easy to get started. The main steps are:

      +
        +
      • Download the swigwin zip package from the +SWIG website and unzip into a directory. This is all that needs + downloading for the Windows platform.
        • +
      • Set environment variables as described in the +SWIG Windows Examples section in order to run examples using Visual + C++.
        • +
      +

      3.1.1 Windows Executable

      +

      The swigwin distribution contains the SWIG Windows executable, + swig.exe, which will run on 32 bit versions of Windows, ie Windows + 95/98/ME/NT/2000/XP. If you want to build your own swig.exe have a look + at Building swig.exe on Windows.

      +

      3.2 SWIG Windows Examples

      +

      Using Microsoft Visual C++ is the most common approach to compiling + and linking SWIG's output. The Examples directory has a few Visual C++ + project files (.dsp files). These were produced by Visual C++ 6, + although they should also work in Visual C++ 5. Later versions of + Visual Studio should also be able to open and convert these project + files. The C# examples come with .NET 2003 solution (.sln) and project + files instead of Visual C++ 6 project files. The project files have + been set up to execute SWIG in a custom build rule for the SWIG + interface (.i) file. Alternatively run the +examples using Cygwin.

      +

      More information on each of the examples is available with the + examples distributed with SWIG (Examples/index.html).

      +

      3.2.1 Instructions for using the + Examples with Visual Studio

      +

      Ensure the SWIG executable is as supplied in the SWIG root directory + in order for the examples to work. Most languages require some + environment variables to be set before running Visual C++. Note + that Visual C++ must be re-started to pick up any changes in + environment variables. Open up an example .dsp file, Visual C++ will + create a workspace for you (.dsw file). Ensure the Release build is + selected then do a Rebuild All from the Build menu. The required + environment variables are displayed with their current values.

      +

      The list of required environment variables for each module language + is also listed below. They are usually set from the Control Panel and + System properties, but this depends on which flavour of Windows you are + running. If you don't want to use environment variables then change all + occurrences of the environment variables in the .dsp files with hard + coded values. If you are interested in how the project files are set up + there is explanatory information in some of the language module's + documentation.

      +

      3.2.1.1 C#

      +

      The C# examples do not require any environment variables to be set + as a C# project file is included. Just open up the .sln solution file + in Visual Studio .NET 2003 or later, select Release Build, and do a + Rebuild All from the Build menu. The accompanying C# and C++ project + files are automatically used by the solution file.

      +

      3.2.1.2 Java

      +

      JAVA_INCLUDE : Set this to the directory containing + jni.h +
      JAVA_BIN : Set this to the bin directory containing + javac.exe

      +

      Example using JDK1.3: +
      JAVA_INCLUDE: D:\jdk1.3\include +
      JAVA_BIN: D:\jdk1.3\bin +

      +

      3.2.1.3 Perl

      +

      PERL5_INCLUDE : Set this to the directory containing + perl.h +
      PERL5_LIB : Set this to the Perl library including + path for linking

      +

      Example using nsPerl 5.004_04:

      +

      PERL5_INCLUDE: D:\nsPerl5.004_04\lib\CORE +
      PERL5_LIB: D:\nsPerl5.004_04\lib\CORE\perl.lib +

      +

      3.2.1.4 Python

      +

      PYTHON_INCLUDE : Set this to the directory that + contains python.h +
      PYTHON_LIB : Set this to the python library + including path for linking

      +

      Example using Python 2.1.1: +
      PYTHON_INCLUDE: D:\python21\include +
      PYTHON_LIB: D:\python21\libs\python21.lib +

      +

      3.2.1.5 TCL

      +

      TCL_INCLUDE : Set this to the directory containing + tcl.h +
      TCL_LIB : Set this to the TCL library including + path for linking

      +

      Example using ActiveTcl 8.3.3.3 +
      TCL_INCLUDE: D:\tcl\include +
      TCL_LIB: D:\tcl\lib\tcl83.lib +

      +

      3.2.1.6 R

      +

      R_INCLUDE : Set this to the directory containing R.h +
      R_LIB : Set this to the R library (Rdll.lib) + including path for linking. The library needs to be built as described + in the R README.packages file (the pexports.exe approach is the + easiest).

      +

      Example using R 2.5.1: +
      R_INCLUDE: C:\Program Files\R\R-2.5.1\include +
      R_LIB: C:\Program Files\R\R-2.5.1\bin\Rdll.lib +

      +

      3.2.1.7 Ruby

      +

      RUBY_INCLUDE : Set this to the directory containing + ruby.h +
      RUBY_LIB : Set this to the ruby library including + path for linking

      +

      Example using Ruby 1.6.4: +
      RUBY_INCLUDE: D:\ruby\lib\ruby\1.6\i586-mswin32 +
      RUBY_LIB: D:\ruby\lib\mswin32-ruby16.lib +

      +

      3.2.2 Instructions for using + the Examples with other compilers

      +

      If you do not have access to Visual C++ you will have to set up + project files / Makefiles for your chosen compiler. There is a section + in each of the language modules detailing what needs setting up using + Visual C++ which may be of some guidance. Alternatively you may want to + use Cygwin as described in the following section.

      +

      3.3 SWIG on Cygwin and MinGW

      +

      SWIG can also be compiled and run using +Cygwin or MinGW which provides a + Unix like front end to Windows and comes free with gcc, an ANSI C/C++ + compiler. However, this is not a recommended approach as the prebuilt + executable is supplied.

      +

      3.3.1 Building swig.exe on Windows

      +

      If you want to replicate the build of swig.exe that comes with the + download, follow the MinGW instructions below. This is not necessary to + use the supplied swig.exe. This information is provided for those that + want to modify the SWIG source code in a Windows environment. Normally + this is not needed, so most people will want to ignore this section.

      +

      3.3.1.1 Building swig.exe using + MinGW and MSYS

      +

      The short abbreviated instructions follow...

      +
        +
      • Install MinGW and MSYS from the MinGW + site. This provides a Unix environment on Windows.
        • +
      • Follow the usual Unix instructions in the README file in the SWIG + root directory to build swig.exe from the MinGW command prompt.
        • +
      +

      The step by step instructions to download and install MinGW and + MSYS, then download and build the latest version of SWIG from SVN + follow... Note that the instructions for obtaining SWIG from SVN are + also online at SWIG SVN.

      +

      Pitfall note: Execute the steps in the order shown and don't + use spaces in path names. In fact it is best to use the default + installation directories.

      +
        +
      1. Download the following packages from the +MinGW download page or +MinGW SourceForge download page. Note that at the time of writing, + the majority of these are in the Current release list and some are in + the Snapshot or Previous release list. +
          +
        • MinGW-3.1.0-1.exe
          • +
        • MSYS-1.0.11-2004.04.30-1.exe
          • +
        • msysDTK-1.0.1.exe
          • +
        • bison-2.0-MSYS.tar.gz
          • +
        • msys-autoconf-2.59.tar.bz2
          • +
        • msys-automake-1.8.2.tar.bz2
          • +
        +
        2. +
      2. Install MinGW-3.1.0-1.exe (C:\MinGW is default location.)
        3. +
      3. Install MSYS-1.0.11-2004.04.30-1.exe. Make sure you install it on + the same windows drive letter as MinGW (C:\msys\1.0 is default). In the + post install script, +
          +
        • Answer y to the "do you wish to continue with the post install?"
          • +
        • Answer y to the "do you have MinGW installed?"
          • +
        • Type in the the folder in which you installed MinGW (C:/MinGW is + default)
          • +
        +
        4. +
      4. Install msysDTK-1.0.1.exe to the same folder that you installed + MSYS (C:\msys\1.0 is default).
        5. +
      5. Copy the following to the MSYS install folder (C:\msys\1.0 is + default): +
          +
        • msys-automake-1.8.2.tar.bz2
          • +
        • msys-autoconf-2.59.tar.bz2
          • +
        • bison-2.0-MSYS.tar.gz
          • +
        +
        6. +
      6. Start the MSYS command prompt and execute:
        +
        +cd /
+tar -jxf msys-automake-1.8.2.tar.bz2 
+tar -jxf msys-autoconf-2.59.tar.bz2
+tar -zxf bison-2.0-MSYS.tar.gz   
+
        +
        7. +
      7. To get the latest SWIG SVN (version from Subversion source + control), type in the following:
        +
        +mkdir /usr/src
+cd /usr/src
+svn co https://swig.svn.sourceforge.net/svnroot/swig/trunk swig
+
        +
        Pitfall note: If you want to check out SWIG to a different + folder to the proposed /usr/src/swig, do not use MSYS emulated windows + drive letters, because the autotools will fail miserably on those.
        8. +
      8. You are now ready to build SWIG. Execute the following commands to + build swig.exe:
        +
        +cd /usr/src/swig
+./autogen.sh
+./configure
+make
+
        +
        9. +
      +

      3.3.1.2 Building swig.exe using Cygwin

      +

      Note that SWIG can also be built using Cygwin. However, SWIG will + then require the Cygwin DLL when executing. Follow the Unix + instructions in the README file in the SWIG root directory. Note that + the Cygwin environment will also allow one to regenerate the autotool + generated files which are supplied with the release distribution. These + files are generated using the autogen.sh script and will only + need regenerating in circumstances such as changing the build system.

      +

      3.3.1.3 Building + swig.exe alternatives

      +

      If you don't want to install Cygwin or MinGW, use a different + compiler to build SWIG. For example, all the source code files can be + added to a Visual C++ project file in order to build swig.exe from the + Visual C++ IDE.

      +

      3.3.2 Running the examples on + Windows using Cygwin

      +

      The examples and test-suite work as successfully on Cygwin as on any + other Unix operating system. The modules which are known to work are + Python, Tcl, Perl, Ruby, Java and C#. Follow the Unix instructions in + the README file in the SWIG root directory to build the examples.

      +

      3.4 Microsoft extensions and + other Windows quirks

      +

      A common problem when using SWIG on Windows are the Microsoft + function calling conventions which are not in the C++ standard. SWIG + parses ISO C/C++ so cannot deal with proprietary conventions such as +__declspec(dllimport), __stdcall etc. There is a Windows + interface file, windows.i, to deal with these calling + conventions though. The file also contains typemaps for handling + commonly used Windows specific types such as __int64, BOOL +, DWORD etc. Include it like you would any other interface + file, for example:

      +
      +
      +%include <windows.i>
+
+__declspec(dllexport) ULONG __stdcall foo(DWORD, __int32);
+
      +
      +

      4 Scripting Languages

      + + +
      + +
      + +

      This chapter provides a brief overview of scripting language + extension programming and the mechanisms by which scripting language + interpreters access C and C++ code.

      +

      4.1 The two language view of the world

      +

      When a scripting language is used to control a C program, the + resulting system tends to look as follows:

      +
      Scripting language input - C/C++ functions output
      +

      In this programming model, the scripting language interpreter is + used for high level control whereas the underlying functionality of the + C/C++ program is accessed through special scripting language + "commands." If you have ever tried to write your own simple command + interpreter, you might view the scripting language approach to be a + highly advanced implementation of that. Likewise, If you have ever used + a package such as MATLAB or IDL, it is a very similar model--the + interpreter executes user commands and scripts. However, most of the + underlying functionality is written in a low-level language like C or + Fortran.

      +

      The two-language model of computing is extremely powerful because it + exploits the strengths of each language. C/C++ can be used for maximal + performance and complicated systems programming tasks. Scripting + languages can be used for rapid prototyping, interactive debugging, + scripting, and access to high-level data structures such associative + arrays.

      +

      4.2 How does a scripting language talk + to C?

      +

      Scripting languages are built around a parser that knows how to + execute commands and scripts. Within this parser, there is a mechanism + for executing commands and accessing variables. Normally, this is used + to implement the builtin features of the language. However, by + extending the interpreter, it is usually possible to add new commands + and variables. To do this, most languages define a special API for + adding new commands. Furthermore, a special foreign function interface + defines how these new commands are supposed to hook into the + interpreter.

      +

      Typically, when you add a new command to a scripting interpreter you + need to do two things; first you need to write a special "wrapper" + function that serves as the glue between the interpreter and the + underlying C function. Then you need to give the interpreter + information about the wrapper by providing details about the name of + the function, arguments, and so forth. The next few sections illustrate + the process.

      +

      4.2.1 Wrapper functions

      +

      Suppose you have an ordinary C function like this :

      +
      +
      +int fact(int n) {
+	if (n <= 1) return 1;
+	else return n*fact(n-1);
+}
+
      +
      +

      In order to access this function from a scripting language, it is + necessary to write a special "wrapper" function that serves as the glue + between the scripting language and the underlying C function. A wrapper + function must do three things :

      +
        +
      • Gather function arguments and make sure they are valid.
        • +
      • Call the C function.
        • +
      • Convert the return value into a form recognized by the scripting + language.
        • +
      +

      As an example, the Tcl wrapper function for the fact() + function above example might look like the following :

      +
      +
      +int wrap_fact(ClientData clientData, Tcl_Interp *interp,
+		int argc, char *argv[]) {
+	int result;
+	int arg0;
+	if (argc != 2) {
+		interp->result = "wrong # args";
+		return TCL_ERROR;
+	}
+	arg0 = atoi(argv[1]);
+	result = fact(arg0);
+	sprintf(interp->result,"%d", result);
+	return TCL_OK;
+}
+
+
      +
      +

      Once you have created a wrapper function, the final step is to tell + the scripting language about the new function. This is usually done in + an initialization function called by the language when the module is + loaded. For example, adding the above function to the Tcl interpreter + requires code like the following :

      +
      +
      +int Wrap_Init(Tcl_Interp *interp) {
+	Tcl_CreateCommand(interp, "fact", wrap_fact, (ClientData) NULL,
+				(Tcl_CmdDeleteProc *) NULL);
+	return TCL_OK;
+}
+
      +
      +

      When executed, Tcl will now have a new command called "fact +" that you can use like any other Tcl command.

      +

      Although the process of adding a new function to Tcl has been + illustrated, the procedure is almost identical for Perl and Python. + Both require special wrappers to be written and both need additional + initialization code. Only the specific details are different.

      +

      4.2.2 Variable linking

      +

      Variable linking refers to the problem of mapping a C/C++ global + variable to a variable in the scripting language interpreter. For + example, suppose you had the following variable:

      +
      +
      +double Foo = 3.5;
+
      +
      +

      It might be nice to access it from a script as follows (shown for + Perl):

      +
      +
      +$a = $Foo * 2.3;   # Evaluation
+$Foo = $a + 2.0;   # Assignment
+
      +
      +

      To provide such access, variables are commonly manipulated using a + pair of get/set functions. For example, whenever the value of a + variable is read, a "get" function is invoked. Similarly, whenever the + value of a variable is changed, a "set" function is called.

      +

      In many languages, calls to the get/set functions can be attached to + evaluation and assignment operators. Therefore, evaluating a variable + such as $Foo might implicitly call the get function. + Similarly, typing $Foo = 4 would call the underlying set + function to change the value.

      +

      4.2.3 Constants

      +

      In many cases, a C program or library may define a large collection + of constants. For example:

      +
      +
      +#define RED   0xff0000
+#define BLUE  0x0000ff
+#define GREEN 0x00ff00
+
      +
      +

      To make constants available, their values can be stored in scripting + language variables such as $RED, $BLUE, and +$GREEN. Virtually all scripting languages provide C functions for + creating variables so installing constants is usually a trivial + exercise.

      +

      4.2.4 Structures and classes

      +

      Although scripting languages have no trouble accessing simple + functions and variables, accessing C/C++ structures and classes present + a different problem. This is because the implementation of structures + is largely related to the problem of data representation and layout. + Furthermore, certain language features are difficult to map to an + interpreter. For instance, what does C++ inheritance mean in a Perl + interface?

      +

      The most straightforward technique for handling structures is to + implement a collection of accessor functions that hide the underlying + representation of a structure. For example,

      +
      +
      +struct Vector {
+	Vector();
+	~Vector();
+	double x,y,z;
+};
+
+
      +
      +

      can be transformed into the following set of functions :

      +
      +
      +Vector *new_Vector();
+void delete_Vector(Vector *v);
+double Vector_x_get(Vector *v);
+double Vector_y_get(Vector *v);
+double Vector_z_get(Vector *v);
+void Vector_x_set(Vector *v, double x);
+void Vector_y_set(Vector *v, double y);
+void Vector_z_set(Vector *v, double z);
+
+
      +
      +

      Now, from an interpreter these function might be used as follows:

      +
      +
      +% set v [new_Vector]
+% Vector_x_set $v 3.5
+% Vector_y_get $v
+% delete_Vector $v
+% ...
+
      +
      +

      Since accessor functions provide a mechanism for accessing the + internals of an object, the interpreter does not need to know anything + about the actual representation of a Vector.

      +

      4.2.5 Proxy classes

      +

      In certain cases, it is possible to use the low-level accessor + functions to create a proxy class, also known as a shadow class. A + proxy class is a special kind of object that gets created in a + scripting language to access a C/C++ class (or struct) in a way that + looks like the original structure (that is, it proxies the real C++ + class). For example, if you have the following C definition :

      +
      +
      +class Vector {
+public:
+	Vector();
+	~Vector();
+	double x,y,z;
+};
+
      +
      +

      A proxy classing mechanism would allow you to access the structure + in a more natural manner from the interpreter. For example, in Python, + you might want to do this:

      +
      +
      +>>> v = Vector()
+>>> v.x = 3
+>>> v.y = 4
+>>> v.z = -13
+>>> ...
+>>> del v
+
      +
      +

      Similarly, in Perl5 you may want the interface to work like this:

      +
      +
      +$v = new Vector;
+$v->{x} = 3;
+$v->{y} = 4;
+$v->{z} = -13;
+
+
      +
      +

      Finally, in Tcl :

      +
      +
      +Vector v
+v configure -x 3 -y 4 -z 13
+
+
      +
      +

      When proxy classes are used, two objects are at really work--one in + the scripting language, and an underlying C/C++ object. Operations + affect both objects equally and for all practical purposes, it appears + as if you are simply manipulating a C/C++ object.

      +

      4.3 Building scripting language + extensions

      +

      The final step in using a scripting language with your C/C++ + application is adding your extensions to the scripting language itself. + There are two primary approaches for doing this. The preferred + technique is to build a dynamically loadable extension in the form a + shared library. Alternatively, you can recompile the scripting language + interpreter with your extensions added to it.

      +

      4.3.1 Shared libraries and dynamic + loading

      +

      To create a shared library or DLL, you often need to look at the + manual pages for your compiler and linker. However, the procedure for a + few common machines is shown below:

      +
      +
      +# Build a shared library for Solaris
+gcc -c example.c example_wrap.c -I/usr/local/include
+ld -G example.o example_wrap.o -o example.so
+
+# Build a shared library for Linux
+gcc -fpic -c example.c example_wrap.c -I/usr/local/include
+gcc -shared example.o example_wrap.o -o example.so
+
+# Build a shared library for Irix
+gcc -c example.c example_wrap.c -I/usr/local/include
+ld -shared example.o example_wrap.o -o example.so
+
+
      +
      +

      To use your shared library, you simply use the corresponding command + in the scripting language (load, import, use, etc...). This will import + your module and allow you to start using it. For example:

      +
      +
      +% load ./example.so
+% fact 4
+24
+%
+
      +
      +

      When working with C++ codes, the process of building shared + libraries may be more complicated--primarily due to the fact that C++ + modules may need additional code in order to operate correctly. On many + machines, you can build a shared C++ module by following the above + procedures, but changing the link line to the following :

      +
      +
      +c++ -shared example.o example_wrap.o -o example.so
+
      +
      +

      4.3.2 Linking with shared libraries

      +

      When building extensions as shared libraries, it is not uncommon for + your extension to rely upon other shared libraries on your machine. In + order for the extension to work, it needs to be able to find all of + these libraries at run-time. Otherwise, you may get an error such as + the following :

      +
      +
      +>>> import graph
+Traceback (innermost last):
+  File "<stdin>", line 1, in ?
+  File "/home/sci/data1/beazley/graph/graph.py", line 2, in ?
+    import graphc
+ImportError:  1101:/home/sci/data1/beazley/bin/python: rld: Fatal Error: cannot 
+successfully map soname 'libgraph.so' under any of the filenames /usr/lib/libgraph.so:/
+lib/libgraph.so:/lib/cmplrs/cc/libgraph.so:/usr/lib/cmplrs/cc/libgraph.so:
+>>>
+
      +
      +

      What this error means is that the extension module created by SWIG + depends upon a shared library called "libgraph.so" that the + system was unable to locate. To fix this problem, there are a few + approaches you can take.

      +
        +
      • Link your extension and explicitly tell the linker where the + required libraries are located. Often times, this can be done with a + special linker flag such as -R, -rpath, etc. This is + not implemented in a standard manner so read the man pages for your + linker to find out more about how to set the search path for shared + libraries.
        • +
      • Put shared libraries in the same directory as the executable. This + technique is sometimes required for correct operation on non-Unix + platforms.
        • +
      • Set the UNIX environment variable LD_LIBRARY_PATH to the + directory where shared libraries are located before running Python. + Although this is an easy solution, it is not recommended. Consider + setting the path using linker options instead.
        • +
      +

      4.3.3 Static linking

      +

      With static linking, you rebuild the scripting language interpreter + with extensions. The process usually involves compiling a short main + program that adds your customized commands to the language and starts + the interpreter. You then link your program with a library to produce a + new scripting language executable.

      +

      Although static linking is supported on all platforms, this is not + the preferred technique for building scripting language extensions. In + fact, there are very few practical reasons for doing this--consider + using shared libraries instead.

      +
      +

      5 SWIG Basics

      + + +
      + +
      + +

      This chapter describes the basic operation of SWIG, the structure of + its input files, and how it handles standard ANSI C declarations. C++ + support is described in the next chapter. However, C++ programmers + should still read this chapter to understand the basics. Specific + details about each target language are described in later chapters.

      +

      5.1 Running SWIG

      +

      To run SWIG, use the swig command with options options and + a filename like this:

      +
      +
      +swig [ options ] filename
+
      +
      +

      where filename is a SWIG interface file or a C/C++ header + file. Below is a subset of options that can be used. + Additional options are also defined for each target language. A full + list can be obtained by typing swig -help or swig - +lang -help.

      +
      +
      +-allegrocl            Generate ALLEGROCL wrappers
+-chicken              Generate CHICKEN wrappers
+-clisp                Generate CLISP wrappers
+-cffi                 Generate CFFI wrappers
+-csharp               Generate C# wrappers
+-guile                Generate Guile wrappers
+-java                 Generate Java wrappers
+-lua                  Generate Lua wrappers
+-modula3              Generate Modula 3 wrappers
+-mzscheme             Generate Mzscheme wrappers
+-ocaml                Generate Ocaml wrappers
+-perl                 Generate Perl wrappers
+-php                  Generate PHP wrappers
+-pike                 Generate Pike wrappers
+-python               Generate Python wrappers
+-r                    Generate R (aka GNU S) wrappers
+-ruby                 Generate Ruby wrappers
+-sexp                 Generate Lisp S-Expressions wrappers
+-tcl                  Generate Tcl wrappers
+-uffi                 Generate Common Lisp / UFFI wrappers
+-xml                  Generate XML wrappers
+
+-c++                  Enable C++ parsing
+-Dsymbol              Define a preprocessor symbol
+-Fstandard            Display error/warning messages in commonly used format
+-Fmicrosoft           Display error/warning messages in Microsoft format
+-help                 Display all options
+-Idir                 Add a directory to the file include path
+-lfile                Include a SWIG library file.
+-module name          Set the name of the SWIG module
+-o outfile            Name of output file
+-outcurrentdir	      Set default output dir to current dir instead of input file's path
+-outdir dir           Set language specific files output directory
+-swiglib              Show location of SWIG library
+-version              Show SWIG version number
+
+
      +
      +

      5.1.1 Input format

      +

      As input, SWIG expects a file containing ANSI C/C++ declarations and + special SWIG directives. More often than not, this is a special SWIG + interface file which is usually denoted with a special .i or +.swg suffix. In certain cases, SWIG can be used directly on raw + header files or source files. However, this is not the most typical + case and there are several reasons why you might not want to do this + (described later).

      +

      The most common format of a SWIG interface is as follows:

      +
      +
      +%module mymodule 
+%{
+#include "myheader.h"
+%}
+// Now list ANSI C/C++ declarations
+int foo;
+int bar(int x);
+...
+
      +
      +

      The module name is supplied using the special %module + directive. Modules are described further in the +Modules Introduction section.

      +

      Everything in the %{ ... %} block is simply copied verbatim + to the resulting wrapper file created by SWIG. This section is almost + always used to include header files and other declarations that are + required to make the generated wrapper code compile. It is important to + emphasize that just because you include a declaration in a SWIG input + file, that declaration does not automatically appear in the + generated wrapper code---therefore you need to make sure you include + the proper header files in the %{ ... %} section. It should be + noted that the text enclosed in %{ ... %} is not parsed or + interpreted by SWIG. The %{...%} syntax and semantics in SWIG + is analogous to that of the declarations section used in input files to + parser generation tools such as yacc or bison.

      +

      5.1.2 SWIG Output

      +

      The output of SWIG is a C/C++ file that contains all of the wrapper + code needed to build an extension module. SWIG may generate some + additional files depending on the target language. By default, an input + file with the name file.i is transformed into a file +file_wrap.c or file_wrap.cxx (depending on whether or not + the -c++ option has been used). The name of the output file + can be changed using the -o option. In certain cases, file + suffixes are used by the compiler to determine the source language (C, + C++, etc.). Therefore, you have to use the -o option to change + the suffix of the SWIG-generated wrapper file if you want something + different than the default. For example:

      +
      +
      +$ swig -c++ -python -o example_wrap.cpp example.i
+
      +
      +

      The C/C++ output file created by SWIG often contains everything that + is needed to construct a extension module for the target scripting + language. SWIG is not a stub compiler nor is it usually necessary to + edit the output file (and if you look at the output, you probably won't + want to). To build the final extension module, the SWIG output file is + compiled and linked with the rest of your C/C++ program to create a + shared library.

      +

      Many target languages will also generate proxy class files in the + target language. The default output directory for these language + specific files is the same directory as the generated C/C++ file. This + can be modified using the -outdir option. For example:

      +
      +
      +$ swig -c++ -python -outdir pyfiles -o cppfiles/example_wrap.cpp example.i
+
      +
      +

      If the directories cppfiles and pyfiles exist, the + following will be generated:

      +
      +
      +cppfiles/example_wrap.cpp
+pyfiles/example.py
+
      +
      +

      If the -outcurrentdir option is used (without -o) + then SWIG behaves like a typical C/C++ compiler and the default output + directory is then the current directory. Without this option the + default output directory is the path to the input file. If -o + and -outcurrentdir are used together, -outcurrentdir + is effectively ignored as the output directory for the language files + is the same directory as the generated C/C++ file if not overidden with + -outdir.

      +

      5.1.3 Comments

      +

      C and C++ style comments may appear anywhere in interface files. In + previous versions of SWIG, comments were used to generate documentation + files. However, this feature is currently under repair and will + reappear in a later SWIG release.

      +

      5.1.4 C Preprocessor

      +

      Like C, SWIG preprocesses all input files through an enhanced + version of the C preprocessor. All standard preprocessor features are + supported including file inclusion, conditional compilation and macros. + However, #include statements are ignored unless the +-includeall command line option has been supplied. The reason for + disabling includes is that SWIG is sometimes used to process raw C + header files. In this case, you usually only want the extension module + to include functions in the supplied header file rather than everything + that might be included by that header file (i.e., system headers, C + library functions, etc.).

      +

      It should also be noted that the SWIG preprocessor skips all text + enclosed inside a %{...%} block. In addition, the preprocessor + includes a number of macro handling enhancements that make it more + powerful than the normal C preprocessor. These extensions are described + in the "Preprocessor" chapter.

      +

      5.1.5 SWIG Directives

      +

      Most of SWIG's operation is controlled by special directives that + are always preceded by a "%" to distinguish them from normal C + declarations. These directives are used to give SWIG hints or to alter + SWIG's parsing behavior in some manner.

      +

      Since SWIG directives are not legal C syntax, it is generally not + possible to include them in header files. However, SWIG directives can + be included in C header files using conditional compilation like this:

      +
      +
      +/* header.h  --- Some header file */
+
+/* SWIG directives -- only seen if SWIG is running */ 
+#ifdef SWIG
+%module foo
+#endif
+
      +
      +

      SWIG is a special preprocessing symbol defined by SWIG when + it is parsing an input file.

      +

      5.1.6 Parser Limitations

      +

      Although SWIG can parse most C/C++ declarations, it does not provide + a complete C/C++ parser implementation. Most of these limitations + pertain to very complicated type declarations and certain advanced C++ + features. Specifically, the following features are not currently + supported:

      +
        +
      • Non-conventional type declarations. For example, SWIG does not + support declarations such as the following (even though this is legal + C):
        +
        +/* Non-conventional placement of storage specifier (extern) */
+const int extern Number;
+
+/* Extra declarator grouping */
+Matrix (foo);    // A global variable
+
+/* Extra declarator grouping in parameters */
+void bar(Spam (Grok)(Doh));
+
+
        +
        +

        In practice, few (if any) C programmers actually write code like + this since this style is never featured in programming books. However, + if you're feeling particularly obfuscated, you can certainly break SWIG + (although why would you want to?).

        +
        • +
      • Running SWIG on C++ source files (what would appear in a .C or .cxx + file) is not recommended. Even though SWIG can parse C++ class + declarations, it ignores declarations that are decoupled from their + original class definition (the declarations are parsed, but a lot of + warning messages may be generated). For example:
        +
        +/* Not supported by SWIG */
+int foo::bar(int) {
+    ... whatever ...
+}
+
        +
        • +
      • Certain advanced features of C++ such as nested classes are not yet + supported. Please see the section on using SWIG with C++ for more + information.
        • +
      +

      In the event of a parsing error, conditional compilation can be used + to skip offending code. For example:

      +
      +
      +#ifndef SWIG
+... some bad declarations ...
+#endif
+
      +
      +

      Alternatively, you can just delete the offending code from the + interface file.

      +

      One of the reasons why SWIG does not provide a full C++ parser + implementation is that it has been designed to work with incomplete + specifications and to be very permissive in its handling of C/C++ + datatypes (e.g., SWIG can generate interfaces even when there are + missing class declarations or opaque datatypes). Unfortunately, this + approach makes it extremely difficult to implement certain parts of a + C/C++ parser as most compilers use type information to assist in the + parsing of more complex declarations (for the truly curious, the + primary complication in the implementation is that the SWIG parser does + not utilize a separate typedef-name terminal symbol as + described on p. 234 of K&R).

      +

      5.2 Wrapping Simple C Declarations

      +

      SWIG wraps simple C declarations by creating an interface that + closely matches the way in which the declarations would be used in a C + program. For example, consider the following interface file:

      +
      +
      +%module example
+
+%inline %{
+extern double sin(double x);
+extern int strcmp(const char *, const char *);
+extern int Foo;
+%}
+#define STATUS 50
+#define VERSION "1.1"
+
      +
      +

      In this file, there are two functions sin() and +strcmp(), a global variable Foo, and two constants +STATUS and VERSION. When SWIG creates an extension module, + these declarations are accessible as scripting language functions, + variables, and constants respectively. For example, in Tcl:

      +
      +
      +% sin 3
+5.2335956
+% strcmp Dave Mike
+-1
+% puts $Foo
+42
+% puts $STATUS
+50
+% puts $VERSION
+1.1
+
      +
      +

      Or in Python:

      +
      +
      +>>> example.sin(3)
+5.2335956
+>>> example.strcmp('Dave','Mike')
+-1
+>>> print example.cvar.Foo
+42
+>>> print example.STATUS
+50
+>>> print example.VERSION
+1.1
+
      +
      +

      Whenever possible, SWIG creates an interface that closely matches + the underlying C/C++ code. However, due to subtle differences between + languages, run-time environments, and semantics, it is not always + possible to do so. The next few sections describes various aspects of + this mapping.

      +

      5.2.1 Basic Type Handling

      +

      In order to build an interface, SWIG has to convert C/C++ datatypes + to equivalent types in the target language. Generally, scripting + languages provide a more limited set of primitive types than C. + Therefore, this conversion process involves a certain amount of type + coercion.

      +

      Most scripting languages provide a single integer type that is + implemented using the int or long datatype in C. The + following list shows all of the C datatypes that SWIG will convert to + and from integers in the target language:

      +
      +
      +int
+short
+long
+unsigned
+signed
+unsigned short
+unsigned long
+unsigned char
+signed char
+bool
+
      +
      +

      When an integral value is converted from C, a cast is used to + convert it to the representation in the target language. Thus, a 16 bit + short in C may be promoted to a 32 bit integer. When integers are + converted in the other direction, the value is cast back into the + original C type. If the value is too large to fit, it is silently + truncated. + +

      +

      unsigned char and signed char are special cases + that are handled as small 8-bit integers. Normally, the char + datatype is mapped as a one-character ASCII string.

      +

      The bool datatype is cast to and from an integer value of 0 + and 1 unless the target language provides a special boolean type.

      +

      Some care is required when working with large integer values. Most + scripting languages use 32-bit integers so mapping a 64-bit long + integer may lead to truncation errors. Similar problems may arise with + 32 bit unsigned integers (which may appear as large negative numbers). + As a rule of thumb, the int datatype and all variations of +char and short datatypes are safe to use. For unsigned + int and long datatypes, you will need to carefully check + the correct operation of your program after it has been wrapped with + SWIG.

      +

      Although the SWIG parser supports the long long datatype, + not all language modules support it. This is because long long + usually exceeds the integer precision available in the target language. + In certain modules such as Tcl and Perl5, long long integers + are encoded as strings. This allows the full range of these numbers to + be represented. However, it does not allow long long values to + be used in arithmetic expressions. It should also be noted that + although long long is part of the ISO C99 standard, it is not + universally supported by all C compilers. Make sure you are using a + compiler that supports long long before trying to use this + type with SWIG.

      +

      SWIG recognizes the following floating point types :

      +
      +
      +float
+double
+
      +
      +

      Floating point numbers are mapped to and from the natural + representation of floats in the target language. This is almost always + a C double. The rarely used datatype of long double + is not supported by SWIG.

      +

      The char datatype is mapped into a NULL terminated ASCII + string with a single character. When used in a scripting language it + shows up as a tiny string containing the character value. When + converting the value back into C, SWIG takes a character string from + the scripting language and strips off the first character as the char + value. Thus if the value "foo" is assigned to a char datatype, + it gets the value `f'.

      +

      The char * datatype is handled as a NULL-terminated ASCII + string. SWIG maps this into a 8-bit character string in the target + scripting language. SWIG converts character strings in the target + language to NULL terminated strings before passing them into C/C++. The + default handling of these strings does not allow them to have embedded + NULL bytes. Therefore, the char * datatype is not generally + suitable for passing binary data. However, it is possible to change + this behavior by defining a SWIG typemap. See the chapter on +Typemaps for details about this.

      +

      At this time, SWIG provides limited support for Unicode and + wide-character strings (the C wchar_t type). Some languages + provide typemaps for wchar_t, but bear in mind these might not be + portable across different operating systems. This is a delicate topic + that is poorly understood by many programmers and not implemented in a + consistent manner across languages. For those scripting languages that + provide Unicode support, Unicode strings are often available in an + 8-bit representation such as UTF-8 that can be mapped to the char * + type (in which case the SWIG interface will probably work). If the + program you are wrapping uses Unicode, there is no guarantee that + Unicode characters in the target language will use the same internal + representation (e.g., UCS-2 vs. UCS-4). You may need to write some + special conversion functions.

      +

      5.2.2 Global Variables

      +

      Whenever possible, SWIG maps C/C++ global variables into scripting + language variables. For example,

      +
      +
      +%module example
+double foo;
+
+
      +
      +

      results in a scripting language variable like this:

      +
      +
      +# Tcl
+set foo [3.5]                   ;# Set foo to 3.5
+puts $foo                       ;# Print the value of foo
+
+# Python
+cvar.foo = 3.5                  # Set foo to 3.5
+print cvar.foo                  # Print value of foo
+
+# Perl
+$foo = 3.5;                     # Set foo to 3.5
+print $foo,"\n";                # Print value of foo
+
+# Ruby
+Module.foo = 3.5               # Set foo to 3.5
+print Module.foo, "\n"         # Print value of foo
+
      +
      +

      Whenever the scripting language variable is used, the underlying C + global variable is accessed. Although SWIG makes every attempt to make + global variables work like scripting language variables, it is not + always possible to do so. For instance, in Python, all global variables + must be accessed through a special variable object known as cvar + (shown above). In Ruby, variables are accessed as attributes of the + module. Other languages may convert variables to a pair of accessor + functions. For example, the Java module generates a pair of functions +double get_foo() and set_foo(double val) that are used to + manipulate the value.

      +

      Finally, if a global variable has been declared as const, + it only supports read-only access. Note: this behavior is new to + SWIG-1.3. Earlier versions of SWIG incorrectly handled const + and created constants instead.

      +

      5.2.3 Constants

      +

      Constants can be created using #define, enumerations, or a + special %constant directive. The following interface file + shows a few valid constant declarations :

      +
      +
      +#define I_CONST       5               // An integer constant
+#define PI            3.14159         // A Floating point constant
+#define S_CONST       "hello world"   // A string constant
+#define NEWLINE       '\n'            // Character constant
+
+enum boolean {NO=0, YES=1};
+enum months {JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG,
+             SEP, OCT, NOV, DEC};
+%constant double BLAH = 42.37;
+#define PI_4 PI/4
+#define FLAGS 0x04 | 0x08 | 0x40
+
+
      +
      +

      In #define declarations, the type of a constant is inferred + by syntax. For example, a number with a decimal point is assumed to be + floating point. In addition, SWIG must be able to fully resolve all of + the symbols used in a #define in order for a constant to + actually be created. This restriction is necessary because #define + is also used to define preprocessor macros that are definitely not + meant to be part of the scripting language interface. For example:

      +
      +
      +#define EXTERN extern
+
+EXTERN void foo();
+
      +
      +

      In this case, you probably don't want to create a constant called +EXTERN (what would the value be?). In general, SWIG will not create + constants for macros unless the value can be completely determined by + the preprocessor. For instance, in the above example, the declaration

      +
      +
      +#define PI_4  PI/4
+
      +
      +

      defines a constant because PI was already defined as a + constant and the value is known. However, for the same conservative + reasons even a constant with a simple cast will be ignored, such as

      +
      +
      +#define F_CONST (double) 5            // A floating pointer constant with cast
+
      +
      +

      The use of constant expressions is allowed, but SWIG does not + evaluate them. Rather, it passes them through to the output file and + lets the C compiler perform the final evaluation (SWIG does perform a + limited form of type-checking however).

      +

      For enumerations, it is critical that the original enum definition + be included somewhere in the interface file (either in a header file or + in the %{,%} block). SWIG only translates the enumeration into + code needed to add the constants to a scripting language. It needs the + original enumeration declaration in order to get the correct enum + values as assigned by the C compiler.

      +

      The %constant directive is used to more precisely create + constants corresponding to different C datatypes. Although it is not + usually not needed for simple values, it is more useful when working + with pointers and other more complex datatypes. Typically, +%constant is only used when you want to add constants to the + scripting language interface that are not defined in the original + header file.

      +

      5.2.4 A brief word about const

      +

      A common confusion with C programming is the semantic meaning of the + const qualifier in declarations--especially when it is mixed + with pointers and other type modifiers. In fact, previous versions of + SWIG handled const incorrectly--a situation that SWIG-1.3.7 + and newer releases have fixed.

      +

      Starting with SWIG-1.3, all variable declarations, regardless of any + use of const, are wrapped as global variables. If a + declaration happens to be declared as const, it is wrapped as + a read-only variable. To tell if a variable is const or not, + you need to look at the right-most occurrence of the const + qualifier (that appears before the variable name). If the right-most +const occurs after all other type modifiers (such as pointers), + then the variable is const. Otherwise, it is not.

      +

      Here are some examples of const declarations.

      +
      +
      +const char a;           // A constant character
+char const b;           // A constant character (the same)
+char *const c;          // A constant pointer to a character
+const char *const d;    // A constant pointer to a constant character
+
      +
      +

      Here is an example of a declaration that is not const:

      +
      +
      +const char *e;          // A pointer to a constant character.  The pointer
+                        // may be modified.
+
      +
      +

      In this case, the pointer e can change---it's only the + value being pointed to that is read-only.

      +

      Compatibility Note: One reason for changing SWIG to handle +const declarations as read-only variables is that there are many + situations where the value of a const variable might change. + For example, a library might export a symbol as const in its + public API to discourage modification, but still allow the value to + change through some other kind of internal mechanism. Furthermore, + programmers often overlook the fact that with a constant declaration + like char *const, the underlying data being pointed to can be + modified--it's only the pointer itself that is constant. In an embedded + system, a const declaration might refer to a read-only memory + address such as the location of a memory-mapped I/O device port (where + the value changes, but writing to the port is not supported by the + hardware). Rather than trying to build a bunch of special cases into + the const qualifier, the new interpretation of const + as "read-only" is simple and exactly matches the actual semantics of +const in C/C++. If you really want to create a constant as in older + versions of SWIG, use the %constant directive instead. For + example:

      +
      +
      +%constant double PI = 3.14159;
+
      +
      +

      or

      +
      +
      +#ifdef SWIG
+#define const %constant
+#endif
+const double foo = 3.4;
+const double bar = 23.4;
+const int    spam = 42;
+#ifdef SWIG
+#undef const
+#endif
+...
+
+
      +
      +

      5.2.5 A cautionary tale of char *

      +

      Before going any further, there is one bit of caution involving +char * that must now be mentioned. When strings are passed from a + scripting language to a C char *, the pointer usually points + to string data stored inside the interpreter. It is almost always a + really bad idea to modify this data. Furthermore, some languages may + explicitly disallow it. For instance, in Python, strings are supposed + be immutable. If you violate this, you will probably receive a vast + amount of wrath when you unleash your module on the world.

      +

      The primary source of problems are functions that might modify + string data in place. A classic example would be a function like this:

      +
      +
      +char *strcat(char *s, const char *t)
+
      +
      +

      Although SWIG will certainly generate a wrapper for this, its + behavior will be undefined. In fact, it will probably cause your + application to crash with a segmentation fault or other memory related + problem. This is because s refers to some internal data in the + target language---data that you shouldn't be touching.

      +

      The bottom line: don't rely on char * for anything other + than read-only input values. However, it must be noted that you could + change the behavior of SWIG using typemaps.

      +

      5.3 Pointers and complex objects

      +

      Most C programs manipulate arrays, structures, and other types of + objects. This section discusses the handling of these datatypes.

      +

      5.3.1 Simple pointers

      +

      Pointers to primitive C datatypes such as

      +
      +
      +int *
+double ***
+char **
+
      +
      +

      are fully supported by SWIG. Rather than trying to convert the data + being pointed to into a scripting representation, SWIG simply encodes + the pointer itself into a representation that contains the actual value + of the pointer and a type-tag. Thus, the SWIG representation of the + above pointers (in Tcl), might look like this:

      +
      +
      +_10081012_p_int
+_1008e124_ppp_double
+_f8ac_pp_char
+
      +
      +

      A NULL pointer is represented by the string "NULL" or the value 0 + encoded with type information.

      +

      All pointers are treated as opaque objects by SWIG. Thus, a pointer + may be returned by a function and passed around to other C functions as + needed. For all practical purposes, the scripting language interface + works in exactly the same way as you would use the pointer in a C + program. The only difference is that there is no mechanism for + dereferencing the pointer since this would require the target language + to understand the memory layout of the underlying object.

      +

      The scripting language representation of a pointer value should + never be manipulated directly. Even though the values shown look like + hexadecimal addresses, the numbers used may differ from the actual + machine address (e.g., on little-endian machines, the digits may appear + in reverse order). Furthermore, SWIG does not normally map pointers + into high-level objects such as associative arrays or lists (for + example, converting an int * into an list of integers). There + are several reasons why SWIG does not do this:

      +
        +
      • There is not enough information in a C declaration to properly map + pointers into higher level constructs. For example, an int * + may indeed be an array of integers, but if it contains ten million + elements, converting it into a list object is probably a bad idea.
        • +
      • The underlying semantics associated with a pointer is not known by + SWIG. For instance, an int * might not be an array at + all--perhaps it is an output value!
        • +
      • By handling all pointers in a consistent manner, the implementation + of SWIG is greatly simplified and less prone to error.
        • +
      +

      5.3.2 Run time pointer type checking

      +

      By allowing pointers to be manipulated from a scripting language, + extension modules effectively bypass compile-time type checking in the + C/C++ compiler. To prevent errors, a type signature is encoded into all + pointer values and is used to perform run-time type checking. This + type-checking process is an integral part of SWIG and can not be + disabled or modified without using typemaps (described in later + chapters).

      +

      Like C, void * matches any kind of pointer. Furthermore, +NULL pointers can be passed to any function that expects to receive + a pointer. Although this has the potential to cause a crash, NULL + pointers are also sometimes used as sentinel values or to denote a + missing/empty value. Therefore, SWIG leaves NULL pointer checking up to + the application.

      +

      5.3.3 Derived types, structs, and classes

      +

      For everything else (structs, classes, arrays, etc...) SWIG applies + a very simple rule :

      +
      Everything else is a pointer
      +

      In other words, SWIG manipulates everything else by reference. This + model makes sense because most C/C++ programs make heavy use of + pointers and SWIG can use the type-checked pointer mechanism already + present for handling pointers to basic datatypes.

      +

      Although this probably sounds complicated, it's really quite simple. + Suppose you have an interface file like this :

      +
      +
      +%module fileio
+FILE *fopen(char *, char *);
+int fclose(FILE *);
+unsigned fread(void *ptr, unsigned size, unsigned nobj, FILE *);
+unsigned fwrite(void *ptr, unsigned size, unsigned nobj, FILE *);
+void *malloc(int nbytes);
+void free(void *);
+
+
      +
      +

      In this file, SWIG doesn't know what a FILE is, but since + it's used as a pointer, so it doesn't really matter what it is. If you + wrapped this module into Python, you can use the functions just like + you expect :

      +
      +
      +# Copy a file 
+def filecopy(source,target):
+	f1 = fopen(source,"r")
+	f2 = fopen(target,"w")
+	buffer = malloc(8192)
+	nbytes = fread(buffer,8192,1,f1)
+	while (nbytes > 0):
+		fwrite(buffer,8192,1,f2)
+		nbytes = fread(buffer,8192,1,f1)
+	free(buffer)
+
+
      +
      +

      In this case f1, f2, and buffer are all + opaque objects containing C pointers. It doesn't matter what value they + contain--our program works just fine without this knowledge.

      +

      5.3.4 Undefined datatypes

      +

      When SWIG encounters an undeclared datatype, it automatically + assumes that it is a structure or class. For example, suppose the + following function appeared in a SWIG input file:

      +
      +
      +void matrix_multiply(Matrix *a, Matrix *b, Matrix *c);
+
      +
      +

      SWIG has no idea what a "Matrix" is. However, it is + obviously a pointer to something so SWIG generates a wrapper using its + generic pointer handling code.

      +

      Unlike C or C++, SWIG does not actually care whether Matrix + has been previously defined in the interface file or not. This allows + SWIG to generate interfaces from only partial or limited information. + In some cases, you may not care what a Matrix really is as + long as you can pass an opaque reference to one around in the scripting + language interface.

      +

      An important detail to mention is that SWIG will gladly generate + wrappers for an interface when there are unspecified type names. + However, all unspecified types are internally handled as pointers to + structures or classes! For example, consider the following + declaration:

      +
      +
      +void foo(size_t num);
+
      +
      +

      If size_t is undeclared, SWIG generates wrappers that + expect to receive a type of size_t * (this mapping is + described shortly). As a result, the scripting interface might behave + strangely. For example:

      +
      +
      +foo(40);
+TypeError: expected a _p_size_t.
+
      +
      +

      The only way to fix this problem is to make sure you properly + declare type names using typedef.

      + + +

      5.3.5 Typedef

      +

      Like C, typedef can be used to define new type names in + SWIG. For example:

      +
      +
      +typedef unsigned int size_t;
+
      +
      +

      typedef definitions appearing in a SWIG interface are not + propagated to the generated wrapper code. Therefore, they either need + to be defined in an included header file or placed in the declarations + section like this:

      +
      +
      +%{
+/* Include in the generated wrapper file */
+typedef unsigned int size_t;
+%}
+/* Tell SWIG about it */
+typedef unsigned int size_t;
+
      +
      +

      or

      +
      +
      +%inline %{
+typedef unsigned int size_t;
+%}
+
      +
      +

      In certain cases, you might be able to include other header files to + collect type information. For example:

      +
      +
      +%module example
+%import "sys/types.h"
+
      +
      +

      In this case, you might run SWIG as follows:

      +
      +
      +$ swig -I/usr/include -includeall example.i
+
      +
      +

      It should be noted that your mileage will vary greatly here. System + headers are notoriously complicated and may rely upon a variety of + non-standard C coding extensions (e.g., such as special directives to + GCC). Unless you exactly specify the right include directories and + preprocessor symbols, this may not work correctly (you will have to + experiment).

      +

      SWIG tracks typedef declarations and uses this information + for run-time type checking. For instance, if you use the above +typedef and had the following function declaration:

      +
      +
      +void foo(unsigned int *ptr);
+
      +
      +

      The corresponding wrapper function will accept arguments of type +unsigned int * or size_t *.

      +

      5.4 Other Practicalities

      +

      So far, this chapter has presented almost everything you need to + know to use SWIG for simple interfaces. However, some C programs use + idioms that are somewhat more difficult to map to a scripting language + interface. This section describes some of these issues.

      +

      5.4.1 Passing structures by value

      +

      Sometimes a C function takes structure parameters that are passed by + value. For example, consider the following function:

      +
      +
      +double dot_product(Vector a, Vector b);
+
      +
      +

      To deal with this, SWIG transforms the function to use pointers by + creating a wrapper equivalent to the following:

      +
      +
      +double wrap_dot_product(Vector *a, Vector *b) {
+    Vector x = *a;
+    Vector y = *b;
+    return dot_product(x,y);
+}
+
      +
      +

      In the target language, the dot_product() function now + accepts pointers to Vectors instead of Vectors. For the most part, this + transformation is transparent so you might not notice.

      +

      5.4.2 Return by value

      +

      C functions that return structures or classes datatypes by value are + more difficult to handle. Consider the following function:

      +
      +
      +Vector cross_product(Vector v1, Vector v2);
+
      +
      +

      This function wants to return Vector, but SWIG only really + supports pointers. As a result, SWIG creates a wrapper like this:

      +
      +
      +Vector *wrap_cross_product(Vector *v1, Vector *v2) {
+        Vector x = *v1;
+        Vector y = *v2;
+        Vector *result;
+        result = (Vector *) malloc(sizeof(Vector));
+        *(result) = cross(x,y);
+        return result;
+}
+
      +
      +

      or if SWIG was run with the -c++ option:

      +
      +
      +Vector *wrap_cross(Vector *v1, Vector *v2) {
+        Vector x = *v1;
+        Vector y = *v2;
+        Vector *result = new Vector(cross(x,y)); // Uses default copy constructor
+        return result;
+}
+
      +
      +

      In both cases, SWIG allocates a new object and returns a reference + to it. It is up to the user to delete the returned object when it is no + longer in use. Clearly, this will leak memory if you are unaware of the + implicit memory allocation and don't take steps to free the result. + That said, it should be noted that some language modules can now + automatically track newly created objects and reclaim memory for you. + Consult the documentation for each language module for more details.

      +

      It should also be noted that the handling of pass/return by value in + C++ has some special cases. For example, the above code fragments don't + work correctly if Vector doesn't define a default constructor. + The section on SWIG and C++ has more information about this case.

      +

      5.4.3 Linking to structure variables

      +

      When global variables or class members involving structures are + encountered, SWIG handles them as pointers. For example, a global + variable like this

      +
      +
      +Vector unit_i;
+
      +
      +

      gets mapped to an underlying pair of set/get functions like this :

      +
      +
      +Vector *unit_i_get() {
+	return &unit_i;
+}
+void unit_i_set(Vector *value) {
+	unit_i = *value;
+}
+
      +
      +

      Again some caution is in order. A global variable created in this + manner will show up as a pointer in the target scripting language. It + would be an extremely bad idea to free or destroy such a pointer. Also, + C++ classes must supply a properly defined copy constructor in order + for assignment to work correctly.

      +

      5.4.4 Linking to char *

      +

      When a global variable of type char * appears, SWIG uses +malloc() or new to allocate memory for the new value. + Specifically, if you have a variable like this

      +
      +
      +char *foo;
+
      +
      +

      SWIG generates the following code:

      +
      +
      +/* C mode */
+void foo_set(char *value) {
+   if (foo) free(foo);
+   foo = (char *) malloc(strlen(value)+1);
+   strcpy(foo,value);
+}
+
+/* C++ mode.  When -c++ option is used */
+void foo_set(char *value) {
+   if (foo) delete [] foo;
+   foo = new char[strlen(value)+1];
+   strcpy(foo,value);
+}
+
      +
      +

      If this is not the behavior that you want, consider making the + variable read-only using the %immutable directive. + Alternatively, you might write a short assist-function to set the value + exactly like you want. For example:

      +
      +
      +%inline %{
+  void set_foo(char *value) {
+       strncpy(foo,value, 50);
+   }
+%}
+
      +
      +

      Note: If you write an assist function like this, you will have to + call it as a function from the target scripting language (it does not + work like a variable). For example, in Python you will have to write:

      +
      +
      +>>> set_foo("Hello World")
+
      +
      +

      A common mistake with char * variables is to link to a + variable declared like this:

      +
      +
      +char *VERSION = "1.0";
+
      +
      +

      In this case, the variable will be readable, but any attempt to + change the value results in a segmentation or general protection fault. + This is due to the fact that SWIG is trying to release the old value + using free or delete when the string literal value + currently assigned to the variable wasn't allocated using malloc() + or new. To fix this behavior, you can either mark the variable + as read-only, write a typemap (as described in Chapter 6), or write a + special set function as shown. Another alternative is to declare the + variable as an array:

      +
      +
      +char VERSION[64] = "1.0";
+
      +
      +

      When variables of type const char * are declared, SWIG + still generates functions for setting and getting the value. However, + the default behavior does not release the previous contents + (resulting in a possible memory leak). In fact, you may get a warning + message such as this when wrapping such a variable:

      +
      +
      +example.i:20. Typemap warning. Setting const char * variable may leak memory
+
      +
      +

      The reason for this behavior is that const char * variables + are often used to point to string literals. For example:

      +
      +
      +const char *foo = "Hello World\n";
+
      +
      +

      Therefore, it's a really bad idea to call free() on such a + pointer. On the other hand, it is legal to change the pointer + to point to some other value. When setting a variable of this type, + SWIG allocates a new string (using malloc or new) and changes the + pointer to point to the new value. However, repeated modifications of + the value will result in a memory leak since the old value is not + released.

      +

      5.4.5 Arrays

      +

      Arrays are fully supported by SWIG, but they are always handled as + pointers instead of mapping them to a special array object or list in + the target language. Thus, the following declarations :

      +
      +
      +int foobar(int a[40]);
+void grok(char *argv[]);
+void transpose(double a[20][20]);
+
      +
      +

      are processed as if they were really declared like this:

      +
      +
      +int foobar(int *a);
+void grok(char **argv);
+void transpose(double (*a)[20]);
+
      +
      +

      Like C, SWIG does not perform array bounds checking. It is up to the + user to make sure the pointer points a suitably allocated region of + memory.

      +

      Multi-dimensional arrays are transformed into a pointer to an array + of one less dimension. For example:

      +
      +
      +int [10];         // Maps to int *
+int [10][20];     // Maps to int (*)[20]
+int [10][20][30]; // Maps to int (*)[20][30]
+
      +
      +

      It is important to note that in the C type system, a + multidimensional array a[][] is NOT equivalent to a + single pointer *a or a double pointer such as **a. + Instead, a pointer to an array is used (as shown above) where the + actual value of the pointer is the starting memory location of the + array. The reader is strongly advised to dust off their C book and + re-read the section on arrays before using them with SWIG.

      +

      Array variables are supported, but are read-only by default. For + example:

      +
      +
      +int   a[100][200];
+
      +
      +

      In this case, reading the variable 'a' returns a pointer of type +int (*)[200] that points to the first element of the array +&a[0][0]. Trying to modify 'a' results in an error. This is because + SWIG does not know how to copy data from the target language into the + array. To work around this limitation, you may want to write a few + simple assist functions like this:

      +
      +
      +%inline %{
+void a_set(int i, int j, int val) {
+   a[i][j] = val;
+}
+int a_get(int i, int j) {
+   return a[i][j];
+}
+%}
+
      +
      +

      To dynamically create arrays of various sizes and shapes, it may be + useful to write some helper functions in your interface. For example:

      +
      +
      +// Some array helpers
+%inline %{
+  /* Create any sort of [size] array */
+  int *int_array(int size) {
+     return (int *) malloc(size*sizeof(int));
+  }
+  /* Create a two-dimension array [size][10] */
+  int (*int_array_10(int size))[10] {
+     return (int (*)[10]) malloc(size*10*sizeof(int));
+  }
+%}
+
      +
      +

      Arrays of char are handled as a special case by SWIG. In + this case, strings in the target language can be stored in the array. + For example, if you have a declaration like this,

      +
      +
      +char pathname[256];
+
      +
      +

      SWIG generates functions for both getting and setting the value that + are equivalent to the following code:

      +
      +
      +char *pathname_get() {
+   return pathname;
+}
+void pathname_set(char *value) {
+   strncpy(pathname,value,256);
+}
+
      +
      +

      In the target language, the value can be set like a normal variable.

      +

      5.4.6 Creating read-only + variables

      +

      A read-only variable can be created by using the %immutable + directive as shown :

      +
      +
      +// File : interface.i
+
+int 	a; 			// Can read/write
+%immutable;
+int	b,c,d			// Read only variables
+%mutable;
+double	x,y			// read/write
+
      +
      +

      The %immutable directive enables read-only mode until it is + explicitly disabled using the %mutable directive. As an + alternative to turning read-only mode off and on like this, individual + declarations can also be tagged as immutable. For example:

      +
      +
      +%immutable x;                   // Make x read-only
+...
+double x;                       // Read-only (from earlier %immutable directive)
+double y;                       // Read-write
+...
+
      +
      +

      The %mutable and %immutable directives are + actually %feature directives defined like this:

      +
      +
      +#define %immutable   %feature("immutable")
+#define %mutable     %feature("immutable","")
+
      +
      +

      If you wanted to make all wrapped variables read-only, barring one + or two, it might be easier to take this approach:

      +
      +
      +%immutable;                     // Make all variables read-only
+%feature("immutable","0") x;    // except, make x read/write
+...
+double x;
+double y;
+double z;
+...
+
      +
      +

      Read-only variables are also created when declarations are declared + as const. For example:

      +
      +
      +const int foo;               /* Read only variable */
+char * const version="1.0";  /* Read only variable */
+
      +
      +

      Compatibility note: Read-only access used to be controlled by + a pair of directives %readonly and %readwrite. + Although these directives still work, they generate a warning message. + Simply change the directives to %immutable; and %mutable; + to silence the warning. Don't forget the extra semicolon!

      +

      5.4.7 Renaming and ignoring + declarations

      +

      Normally, the name of a C declaration is used when that declaration + is wrapped into the target language. However, this may generate a + conflict with a keyword or already existing function in the scripting + language. To resolve a name conflict, you can use the %rename + directive as shown :

      +
      +
      +// interface.i
+
+%rename(my_print) print;
+extern void print(char *);
+
+%rename(foo) a_really_long_and_annoying_name;
+extern int a_really_long_and_annoying_name;
+
+
      +
      +

      SWIG still calls the correct C function, but in this case the + function print() will really be called "my_print()" + in the target language.

      +

      The placement of the %rename directive is arbitrary as long + as it appears before the declarations to be renamed. A common technique + is to write code for wrapping a header file like this:

      +
      +
      +// interface.i
+
+%rename(my_print) print;
+%rename(foo) a_really_long_and_annoying_name;
+
+%include "header.h"
+
      +
      +

      %rename applies a renaming operation to all future + occurrences of a name. The renaming applies to functions, variables, + class and structure names, member functions, and member data. For + example, if you had two-dozen C++ classes, all with a member function + named `print' (which is a keyword in Python), you could rename them all + to `output' by specifying :

      +
      +
      +%rename(output) print; // Rename all `print' functions to `output'
+
      +
      +

      SWIG does not normally perform any checks to see if the functions it + wraps are already defined in the target scripting language. However, if + you are careful about namespaces and your use of modules, you can + usually avoid these problems.

      +

      Closely related to %rename is the %ignore + directive. %ignore instructs SWIG to ignore declarations that + match a given identifier. For example:

      +
      +
      +%ignore print;         // Ignore all declarations named print
+%ignore _HAVE_FOO_H;   // Ignore an include guard constant
+...
+%include "foo.h"       // Grab a header file
+...
+
      +
      +

      Any function, variable etc which matches %ignore will not + be wrapped and therefore will not be available from the target + language. A common usage of %ignore is to selectively remove + certain declarations from a header file without having to add + conditional compilation to the header. However, it should be stressed + that this only works for simple declarations. If you need to remove a + whole section of problematic code, the SWIG preprocessor should be used + instead.

      +

      More powerful variants of %rename and %ignore + directives can be used to help wrap C++ overloaded functions and + methods or C++ methods which use default arguments. This is described + in the Ambiguity resolution + and renaming section in the C++ chapter.

      +

      Compatibility note: Older versions of SWIG provided a special + %name directive for renaming declarations. For example:

      +
      +
      +%name(output) extern void print(char *);
+
      +
      +

      This directive is still supported, but it is deprecated and should + probably be avoided. The %rename directive is more powerful + and better supports wrapping of raw header file information.

      +

      5.4.8 Default/optional arguments

      +

      SWIG supports default arguments in both C and C++ code. For example:

      +
      +
      +int plot(double x, double y, int color=WHITE);
+
      +
      +

      In this case, SWIG generates wrapper code where the default + arguments are optional in the target language. For example, this + function could be used in Tcl as follows :

      +
      +
      +% plot -3.4 7.5 				# Use default value
+% plot -3.4 7.5 10				# set color to 10 instead
+
+
      +
      +

      Although the ANSI C standard does not allow default arguments, + default arguments specified in a SWIG interface work with both C and + C++.

      +

      Note: There is a subtle semantic issue concerning the use of + default arguments and the SWIG generated wrapper code. When default + arguments are used in C code, the default values are emitted into the + wrappers and the function is invoked with a full set of arguments. This + is different to when wrapping C++ where an overloaded wrapper method is + generated for each defaulted argument. Please refer to the section on default arguments in the C++ chapter + for further details.

      +

      5.4.9 Pointers to functions and callbacks

      +

      Occasionally, a C library may include functions that expect to + receive pointers to functions--possibly to serve as callbacks. SWIG + provides full support for function pointers provided that the callback + functions are defined in C and not in the target language. For example, + consider a function like this:

      +
      +
      +int binary_op(int a, int b, int (*op)(int,int));
+
      +
      +

      When you first wrap something like this into an extension module, + you may find the function to be impossible to use. For instance, in + Python:

      +
      +
      +>>> def add(x,y):
+...     return x+y
+...
+>>> binary_op(3,4,add)
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+TypeError: Type error. Expected _p_f_int_int__int
+>>>
+
      +
      +

      The reason for this error is that SWIG doesn't know how to map a + scripting language function into a C callback. However, existing C + functions can be used as arguments provided you install them as + constants. One way to do this is to use the %constant + directive like this:

      +
      +
      +/* Function with a callback */
+int binary_op(int a, int b, int (*op)(int,int));
+
+/* Some callback functions */
+%constant int add(int,int);
+%constant int sub(int,int);
+%constant int mul(int,int);
+
      +
      +

      In this case, add, sub, and mul become + function pointer constants in the target scripting language. This + allows you to use them as follows:

      +
      +
      +>>> binary_op(3,4,add)
+7
+>>> binary_op(3,4,mul)
+12
+>>>
+
      +
      +

      Unfortunately, by declaring the callback functions as constants, + they are no longer accessible as functions. For example:

      +
      +
      +>>> add(3,4)
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+TypeError: object is not callable: '_ff020efc_p_f_int_int__int'
+>>>
+
      +
      +

      If you want to make a function available as both a callback function + and a function, you can use the %callback and %nocallback + directives like this:

      +
      +
      +/* Function with a callback */
+int binary_op(int a, int b, int (*op)(int,int));
+
+/* Some callback functions */
+%callback("%s_cb");
+int add(int,int);
+int sub(int,int);
+int mul(int,int);
+%nocallback;
+
      +
      +

      The argument to %callback is a printf-style format string + that specifies the naming convention for the callback constants (%s + gets replaced by the function name). The callback mode remains in + effect until it is explicitly disabled using %nocallback. When + you do this, the interface now works as follows:

      +
      +
      +>>> binary_op(3,4,add_cb)
+7
+>>> binary_op(3,4,mul_cb)
+12
+>>> add(3,4)
+7
+>>> mul(3,4)
+12
+
      +
      +

      Notice that when the function is used as a callback, special names + such as add_cb is used instead. To call the function normally, + just use the original function name such as add().

      +

      SWIG provides a number of extensions to standard C printf formatting + that may be useful in this context. For instance, the following + variation installs the callbacks as all upper-case constants such as +ADD, SUB, and MUL:

      +
      +
      +/* Some callback functions */
+%callback("%(upper)s");
+int add(int,int);
+int sub(int,int);
+int mul(int,int);
+%nocallback;
+
      +
      +

      A format string of "%(lower)s" converts all characters to + lower-case. A string of "%(title)s" capitalizes the first + character and converts the rest to lower case.

      +

      And now, a final note about function pointer support. Although SWIG + does not normally allow callback functions to be written in the target + language, this can be accomplished with the use of typemaps and other + advanced SWIG features. This is described in a later chapter.

      +

      5.5 Structures and unions

      +

      This section describes the behavior of SWIG when processing ANSI C + structures and union declarations. Extensions to handle C++ are + described in the next section.

      +

      If SWIG encounters the definition of a structure or union, it + creates a set of accessor functions. Although SWIG does not need + structure definitions to build an interface, providing definitions make + it possible to access structure members. The accessor functions + generated by SWIG simply take a pointer to an object and allow access + to an individual member. For example, the declaration :

      +
      +
      +struct Vector {
+	double x,y,z;
+}
+
+
      +
      +

      gets transformed into the following set of accessor functions :

      +
      +
      +double Vector_x_get(struct Vector *obj) {
+	return obj->x;
+}
+double Vector_y_get(struct Vector *obj) { 
+	return obj->y;
+}
+double Vector_z_get(struct Vector *obj) { 
+	return obj->z;
+}
+void Vector_x_set(struct Vector *obj, double value) {
+	obj->x = value;
+}
+void Vector_y_set(struct Vector *obj, double value) {
+	obj->y = value;
+}
+void Vector_z_set(struct Vector *obj, double value) {
+	obj->z = value;
+}
+
      +
      +

      In addition, SWIG creates default constructor and destructor + functions if none are defined in the interface. For example:

      +
      +
      +struct Vector *new_Vector() {
+    return (Vector *) calloc(1,sizeof(struct Vector));
+}
+void delete_Vector(struct Vector *obj) {
+    free(obj);
+}
+
      +
      +

      Using these low-level accessor functions, an object can be minimally + manipulated from the target language using code like this:

      +
      +
      +v = new_Vector()
+Vector_x_set(v,2)
+Vector_y_set(v,10)
+Vector_z_set(v,-5)
+...
+delete_Vector(v)
+
      +
      +

      However, most of SWIG's language modules also provide a high-level + interface that is more convenient. Keep reading.

      +

      5.5.1 Typedef and structures

      +

      SWIG supports the following construct which is quite common in C + programs :

      +
      +
      +typedef struct {
+	double x,y,z;
+} Vector;
+
+
      +
      +

      When encountered, SWIG assumes that the name of the object is + `Vector' and creates accessor functions like before. The only + difference is that the use of typedef allows SWIG to drop the +struct keyword on its generated code. For example:

      +
      +
      +double Vector_x_get(Vector *obj) {
+	return obj->x;
+}
+
      +
      +

      If two different names are used like this :

      +
      +
      +typedef struct vector_struct {
+	double x,y,z;
+} Vector;
+
+
      +
      +

      the name Vector is used instead of vector_struct + since this is more typical C programming style. If declarations defined + later in the interface use the type struct vector_struct, SWIG + knows that this is the same as Vector and it generates the + appropriate type-checking code.

      +

      5.5.2 Character strings and structures

      +

      Structures involving character strings require some care. SWIG + assumes that all members of type char * have been dynamically + allocated using malloc() and that they are NULL-terminated + ASCII strings. When such a member is modified, the previously contents + will be released, and the new contents allocated. For example :

      +
      +
      +%module mymodule
+...
+struct Foo {
+	char *name;
+	...
+}
+
+
      +
      +

      This results in the following accessor functions :

      +
      +
      +char *Foo_name_get(Foo *obj) {
+	return Foo->name;
+}
+
+char *Foo_name_set(Foo *obj, char *c) {
+	if (obj->name) free(obj->name);
+	obj->name = (char *) malloc(strlen(c)+1);
+	strcpy(obj->name,c);
+	return obj->name;
+}
+
      +
      +

      If this behavior differs from what you need in your applications, + the SWIG "memberin" typemap can be used to change it. See the typemaps + chapter for further details.

      +

      Note: If the -c++ option is used, new and +delete are used to perform memory allocation.

      +

      5.5.3 Array members

      +

      Arrays may appear as the members of structures, but they will be + read-only. SWIG will write an accessor function that returns the + pointer to the first element of the array, but will not write a + function to change the contents of the array itself. When this + situation is detected, SWIG may generate a warning message such as the + following :

      +
      +
      +interface.i:116. Warning. Array member will be read-only
+
      +
      +

      To eliminate the warning message, typemaps can be used, but this is + discussed in a later chapter. In many cases, the warning message is + harmless.

      +

      5.5.4 Structure data + members

      +

      Occasionally, a structure will contain data members that are + themselves structures. For example:

      +
      +
      +typedef struct Foo {
+   int x;
+} Foo;
+
+typedef struct Bar {
+   int y;
+   Foo f;           /* struct member */
+} Bar;
+
      +
      +

      When a structure member is wrapped, it is handled as a pointer, + unless the %naturalvar directive is used where it is handled + more like a C++ reference (see C++ + Member data). The accessors to the member variable as a pointer is + effectively wrapped as follows:

      +
      +
      +Foo *Bar_f_get(Bar *b) {
+   return &b->f;
+}
+void Bar_f_set(Bar *b, Foo *value) {
+   b->f = *value;
+}
+
      +
      +

      The reasons for this are somewhat subtle but have to do with the + problem of modifying and accessing data inside the data member. For + example, suppose you wanted to modify the value of f.x of a +Bar object like this:

      +
      +
      +Bar *b;
+b->f.x = 37;
+
      +
      +

      Translating this assignment to function calls (as would be used + inside the scripting language interface) results in the following code:

      +
      +
      +Bar *b;
+Foo_x_set(Bar_f_get(b),37);
+
      +
      +

      In this code, if the Bar_f_get() function were to return a +Foo instead of a Foo *, then the resulting modification + would be applied to a copy of f and not the data + member f itself. Clearly that's not what you want!

      +

      It should be noted that this transformation to pointers only occurs + if SWIG knows that a data member is a structure or class. For instance, + if you had a structure like this,

      +
      +
      +struct Foo {
+   WORD   w;
+};
+
      +
      +

      and nothing was known about WORD, then SWIG will generate + more normal accessor functions like this:

      +
      +
      +WORD Foo_w_get(Foo *f) {
+    return f->w;
+}
+void Foo_w_set(FOO *f, WORD value) {
+    f->w = value;
+}
+
      +
      +

      Compatibility Note: SWIG-1.3.11 and earlier releases + transformed all non-primitive member datatypes to pointers. Starting in + SWIG-1.3.12, this transformation only occurs if a datatype is + known to be a structure, class, or union. This is unlikely to break + existing code. However, if you need to tell SWIG that an undeclared + datatype is really a struct, simply use a forward struct declaration + such as "struct Foo;".

      +

      5.5.5 C constructors and destructors

      +

      When wrapping structures, it is generally useful to have a mechanism + for creating and destroying objects. If you don't do anything, SWIG + will automatically generate functions for creating and destroying + objects using malloc() and free(). Note: the use of +malloc() only applies when SWIG is used on C code (i.e., when the +-c++ option is not supplied on the command line). C++ is + handled differently.

      +

      If you don't want SWIG to generate default constructors for your + interfaces, you can use the %nodefaultctor directive or the +-nodefaultctor command line option. For example:

      +
      +
      +swig -nodefaultctor example.i 
+
      +
      +

      or

      +
      +
      +%module foo
+...
+%nodefaultctor;        // Don't create default constructors
+... declarations ...
+%clearnodefaultctor;   // Re-enable default constructors
+
      +
      +

      If you need more precise control, %nodefaultctor can + selectively target individual structure definitions. For example:

      +
      +
      +%nodefaultctor Foo;      // No default constructor for Foo
+...
+struct Foo {             // No default constructor generated.
+};
+
+struct Bar {             // Default constructor generated.
+};
+
      +
      +

      Since ignoring the implicit or default destructors most of the times + produce memory leaks, SWIG will always try to generate them. If needed, + however, you can selectively disable the generation of the + default/implicit destructor by using %nodefaultdtor

      +
      +
      +%nodefaultdtor Foo; // No default/implicit destructor for Foo
+...
+struct Foo {              // No default destructor is generated.
+};
+
+struct Bar {              // Default destructor generated.
+};
+
      +
      +

      Compatibility note: Prior to SWIG-1.3.7, SWIG did not + generate default constructors or destructors unless you explicitly + turned them on using -make_default. However, it appears that + most users want to have constructor and destructor functions so it has + now been enabled as the default behavior.

      +

      Note: There are also the -nodefault option and +%nodefault directive, which disable both the default or implicit + destructor generation. This could lead to memory leaks across the + target languages, and is highly recommended you don't use them.

      +

      5.5.6 Adding member + functions to C structures

      +

      Most languages provide a mechanism for creating classes and + supporting object oriented programming. From a C standpoint, object + oriented programming really just boils down to the process of attaching + functions to structures. These functions normally operate on an + instance of the structure (or object). Although there is a natural + mapping of C++ to such a scheme, there is no direct mechanism for + utilizing it with C code. However, SWIG provides a special %extend + directive that makes it possible to attach methods to C structures for + purposes of building an object oriented interface. Suppose you have a C + header file with the following declaration :

      +
      +
      +/* file : vector.h */
+...
+typedef struct {
+	double x,y,z;
+} Vector;
+
+
      +
      +

      You can make a Vector look a lot like a class by writing a + SWIG interface like this:

      +
      +
      +// file : vector.i
+%module mymodule
+%{
+#include "vector.h"
+%}
+
+%include "vector.h"          // Just grab original C header file
+%extend Vector {             // Attach these functions to struct Vector
+	Vector(double x, double y, double z) {
+		Vector *v;
+		v = (Vector *) malloc(sizeof(Vector));
+		v->x = x;
+		v->y = y;
+		v->z = z;
+		return v;
+	}
+	~Vector() {
+		free($self);
+	}
+	double magnitude() {
+		return sqrt($self->x*$self->x+$self->y*$self->y+$self->z*$self->z);
+	}
+	void print() {
+		printf("Vector [%g, %g, %g]\n", $self->x,$self->y,$self->z);
+	}
+};
+
+
      +
      +

      Note the usage of the $self special variable. Its usage is + identical to a C++ 'this' pointer and should be used whenever access to + the struct instance is required. Also note that C++ constructor and + destructor syntax has been used to simulate a constructor and + destructor, even for C code. There is one subtle difference to a normal + C++ constructor implementation though and that is although the + constructor declaration is as per a normal C++ constructor, the newly + constructed object must be returned as if the constructor + declaration had a return value, a Vector * in this case.

      +

      Now, when used with proxy classes in Python, you can do things like + this :

      +
      +
      +>>> v = Vector(3,4,0)                 # Create a new vector
+>>> print v.magnitude()                # Print magnitude
+5.0
+>>> v.print()                  # Print it out
+[ 3, 4, 0 ]
+>>> del v                      # Destroy it
+
      +
      +

      The %extend directive can also be used inside the + definition of the Vector structure. For example:

      +
      +
      +// file : vector.i
+%module mymodule
+%{
+#include "vector.h"
+%}
+
+typedef struct {
+	double x,y,z;
+	%extend {
+		Vector(double x, double y, double z) { ... }
+		~Vector() { ... }
+		...
+	}
+} Vector;
+
      +
      +

      Finally, %extend can be used to access externally written + functions provided they follow the naming convention used in this + example :

      +
      +
      +/* File : vector.c */
+/* Vector methods */
+#include "vector.h"
+Vector *new_Vector(double x, double y, double z) {
+	Vector *v;
+	v = (Vector *) malloc(sizeof(Vector));
+	v->x = x;
+	v->y = y;
+	v->z = z;
+	return v;
+}
+void delete_Vector(Vector *v) {
+	free(v);
+}
+
+double Vector_magnitude(Vector *v) {
+	return sqrt(v->x*v->x+v->y*v->y+v->z*v->z);
+}
+
+// File : vector.i
+// Interface file
+%module mymodule
+%{
+#include "vector.h"
+%}
+
+typedef struct {
+	double x,y,z;
+	%extend {
+                Vector(int,int,int); // This calls new_Vector()
+               ~Vector();            // This calls delete_Vector()
+		double magnitude();  // This will call Vector_magnitude()
+		...
+	}
+} Vector;
+
      +
      +

      A little known feature of the %extend directive is that it + can also be used to add synthesized attributes or to modify the + behavior of existing data attributes. For example, suppose you wanted + to make magnitude a read-only attribute of Vector + instead of a method. To do this, you might write some code like this:

      +
      +
      +// Add a new attribute to Vector
+%extend Vector {
+    const double magnitude;
+}
+// Now supply the implementation of the Vector_magnitude_get function
+%{
+const double Vector_magnitude_get(Vector *v) {
+  return (const double) return sqrt(v->x*v->x+v->y*v->y+v->z*v->z);
+}
+%}
+
+
      +
      +

      Now, for all practical purposes, magnitude will appear like + an attribute of the object.

      +

      A similar technique can also be used to work with problematic data + members. For example, consider this interface:

      +
      +
      +struct Person {
+   char name[50];
+   ...
+}
+
      +
      +

      By default, the name attribute is read-only because SWIG + does not normally know how to modify arrays. However, you can rewrite + the interface as follows to change this:

      +
      +
      +struct Person {
+    %extend {
+       char *name;
+    }
+...
+}
+
+// Specific implementation of set/get functions
+%{
+char *Person_name_get(Person *p) {
+   return p->name;
+}
+void Person_name_set(Person *p, char *val) {
+   strncpy(p->name,val,50);
+}
+%}
+
      +
      +

      Finally, it should be stressed that even though %extend can + be used to add new data members, these new members can not require the + allocation of additional storage in the object (e.g., their values must + be entirely synthesized from existing attributes of the structure).

      +

      Compatibility note: The %extend directive is a new + name for the %addmethods directive. Since %addmethods + could be used to extend a structure with more than just methods, a more + suitable directive name has been chosen.

      +

      5.5.7 Nested structures

      +

      Occasionally, a C program will involve structures like this :

      +
      +
      +typedef struct Object {
+	int objtype;
+	union {
+		int 	ivalue;
+		double	dvalue;
+		char	*strvalue;
+		void	*ptrvalue;
+	} intRep;
+} Object;
+
+
      +
      +

      When SWIG encounters this, it performs a structure splitting + operation that transforms the declaration into the equivalent of the + following:

      +
      +
      +typedef union {
+	int 		ivalue;
+	double		dvalue;
+	char		*strvalue;
+	void		*ptrvalue;
+} Object_intRep;
+
+typedef struct Object {
+	int objType;
+	Object_intRep intRep;
+} Object;
+
+
      +
      +

      SWIG will then create an Object_intRep structure for use + inside the interface file. Accessor functions will be created for both + structures. In this case, functions like this would be created :

      +
      +
      +Object_intRep *Object_intRep_get(Object *o) {
+	return (Object_intRep *) &o->intRep;
+}
+int Object_intRep_ivalue_get(Object_intRep *o) {
+	return o->ivalue;
+}
+int Object_intRep_ivalue_set(Object_intRep *o, int value) {
+	return (o->ivalue = value);
+}
+double Object_intRep_dvalue_get(Object_intRep *o) {
+	return o->dvalue;
+}
+... etc ...
+
+
      +
      +

      Although this process is a little hairy, it works like you would + expect in the target scripting language--especially when proxy classes + are used. For instance, in Perl:

      +
      +
      +# Perl5 script for accessing nested member
+$o = CreateObject();                    # Create an object somehow
+$o->{intRep}->{ivalue} = 7              # Change value of o.intRep.ivalue
+
      +
      +

      If you have a lot nested structure declarations, it is advisable to + double-check them after running SWIG. Although, there is a good chance + that they will work, you may have to modify the interface file in + certain cases.

      +

      5.5.8 Other things to note about structure + wrapping

      +

      SWIG doesn't care if the declaration of a structure in a .i + file exactly matches that used in the underlying C code (except in the + case of nested structures). For this reason, there are no problems + omitting problematic members or simply omitting the structure + definition altogether. If you are happy passing pointers around, this + can be done without ever giving SWIG a structure definition.

      +

      Starting with SWIG1.3, a number of improvements have been made to + SWIG's code generator. Specifically, even though structure access has + been described in terms of high-level accessor functions such as this,

      +
      +
      +double Vector_x_get(Vector *v) {
+   return v->x;
+}
+
      +
      +

      most of the generated code is actually inlined directly into wrapper + functions. Therefore, no function Vector_x_get() actually + exists in the generated wrapper file. For example, when creating a Tcl + module, the following function is generated instead:

      +
      +
      +static int
+_wrap_Vector_x_get(ClientData clientData, Tcl_Interp *interp, 
+                   int objc, Tcl_Obj *CONST objv[]) {
+    struct Vector *arg1 ;
+    double result ;
+    
+    if (SWIG_GetArgs(interp, objc, objv,"p:Vector_x_get self ",&arg0,
+                     SWIGTYPE_p_Vector) == TCL_ERROR)
+         return TCL_ERROR;
+    result = (double ) (arg1->x);
+    Tcl_SetObjResult(interp,Tcl_NewDoubleObj((double) result));
+    return TCL_OK;
+}
+
      +
      +

      The only exception to this rule are methods defined with %extend +. In this case, the added code is contained in a separate function.

      +

      Finally, it is important to note that most language modules may + choose to build a more advanced interface. Although you may never use + the low-level interface described here, most of SWIG's language modules + use it in some way or another.

      +

      5.6 Code Insertion

      +

      Sometimes it is necessary to insert special code into the resulting + wrapper file generated by SWIG. For example, you may want to include + additional C code to perform initialization or other operations. There + are four common ways to insert code, but it's useful to know how the + output of SWIG is structured first.

      +

      5.6.1 The output of SWIG

      +

      When SWIG creates its output file, it is broken up into four + sections corresponding to runtime code, headers, wrapper functions, and + module initialization code (in that order).

      +
        +
      • Begin section. +
        A placeholder to put code at the beginning of the C/C++ wrapper + file.
        • +
      • Runtime code. +
        This code is internal to SWIG and is used to include type-checking + and other support functions that are used by the rest of the module.
        • +
      • Header section. +
        This is user-defined support code that has been included by the +%{ ... %} directive. Usually this consists of header files and + other helper functions.
        • +
      • Wrapper code. +
        These are the wrappers generated automatically by SWIG.
        • +
      • Module initialization. +
        The function generated by SWIG to initialize the module upon + loading.
        • +
      +

      5.6.2 Code insertion blocks

      +

      Code is inserted into the appropriate code section by using one of + the code insertion directives listed below. The order of the sections + in the wrapper file is as shown:

      +
      +
      +%begin %{
+   ... code in begin section ...
+%}
+
+%runtime %{
+   ... code in runtime section ...
+%}
+
+%header %{
+   ... code in header section ...
+%}
+
+%wrapper %{
+   ... code in wrapper section ...
+%}
+
+%init %{
+   ... code in init section ...
+%}
+
      +
      +

      The bare %{ ... %} directive is a shortcut that is the same + as %header %{ ... %}.

      +

      The %begin section is effectively empty as it just contains + the SWIG banner by default. This section is provided as a way for users + to insert code at the top of the wrapper file before any other code is + generated. Everything in a code insertion block is copied verbatim into + the output file and is not parsed by SWIG. Most SWIG input files have + at least one such block to include header files and support C code. + Additional code blocks may be placed anywhere in a SWIG file as needed.

      +
      +
      +%module mymodule
+%{
+#include "my_header.h"
+%}
+... Declare functions here
+%{
+
+void some_extra_function() {
+  ...
+}
+%}
+
      +
      +

      A common use for code blocks is to write "helper" functions. These + are functions that are used specifically for the purpose of building an + interface, but which are generally not visible to the normal C program. + For example :

      +
      +
      +%{
+/* Create a new vector */
+static Vector *new_Vector() {
+	return (Vector *) malloc(sizeof(Vector));
+}
+
+%}
+// Now wrap it 
+Vector *new_Vector();
+
      +
      +

      5.6.3 Inlined code blocks

      +

      Since the process of writing helper functions is fairly common, + there is a special inlined form of code block that is used as follows :

      +
      +
      +%inline %{
+/* Create a new vector */
+Vector *new_Vector() {
+	return (Vector *) malloc(sizeof(Vector));
+}
+%}
+
+
      +
      +

      The %inline directive inserts all of the code that follows + verbatim into the header portion of an interface file. The code is then + parsed by both the SWIG preprocessor and parser. Thus, the above + example creates a new command new_Vector using only one + declaration. Since the code inside an %inline %{ ... %} block + is given to both the C compiler and SWIG, it is illegal to include any + SWIG directives inside a %{ ... %} block.

      +

      5.6.4 Initialization blocks

      +

      When code is included in the %init section, it is copied + directly into the module initialization function. For example, if you + needed to perform some extra initialization on module loading, you + could write this:

      +
      +
      +%init %{
+	init_variables();
+%}
+
      +
      +

      5.7 An Interface Building Strategy

      +

      This section describes the general approach for building interface + with SWIG. The specifics related to a particular scripting language are + found in later chapters.

      +

      5.7.1 Preparing a C program for SWIG

      +

      SWIG doesn't require modifications to your C code, but if you feed + it a collection of raw C header files or source code, the results might + not be what you expect---in fact, they might be awful. Here's a series + of steps you can follow to make an interface for a C program :

      +
        +
      • Identify the functions that you want to wrap. It's probably not + necessary to access every single function in a C program--thus, a + little forethought can dramatically simplify the resulting scripting + language interface. C header files are particularly good source for + finding things to wrap.
        • +
      • Create a new interface file to describe the scripting language + interface to your program.
        • +
      • Copy the appropriate declarations into the interface file or use + SWIG's %include directive to process an entire C source/header + file.
        • +
      • Make sure everything in the interface file uses ANSI C/C++ syntax.
        • +
      • Make sure all necessary `typedef' declarations and + type-information is available in the interface file. In particular, + ensure that the type information is specified in the correct order as + required by a C/C++ compiler. Most importantly, define a type before it + is used! A C compiler will tell you if the full type information is not + available if it is needed, whereas SWIG will usually not warn or error + out as it is designed to work without full type information. However, + if type information is not specified correctly, the wrappers can be + sub-optimal and even result in uncompileable C/C++ code.
        • +
      • If your program has a main() function, you may need to rename it + (read on).
        • +
      • Run SWIG and compile.
        • +
      +

      Although this may sound complicated, the process turns out to be + fairly easy once you get the hang of it.

      +

      In the process of building an interface, SWIG may encounter syntax + errors or other problems. The best way to deal with this is to simply + copy the offending code into a separate interface file and edit it. + However, the SWIG developers have worked very hard to improve the SWIG + parser--you should report parsing errors to the +swig-devel mailing list or to the +SWIG bug tracker.

      +

      5.7.2 The SWIG interface file

      +

      The preferred method of using SWIG is to generate separate interface + file. Suppose you have the following C header file :

      +
      +
      +/* File : header.h */
+
+#include <stdio.h>
+#include <math.h>
+
+extern int foo(double);
+extern double bar(int, int);
+extern void dump(FILE *f);
+
+
      +
      +

      A typical SWIG interface file for this header file would look like + the following :

      +
      +
      +/* File : interface.i */
+%module mymodule
+%{
+#include "header.h"
+%}
+extern int foo(double);
+extern double bar(int, int);
+extern void dump(FILE *f);
+
+
      +
      +

      Of course, in this case, our header file is pretty simple so we + could use a simpler approach and use an interface file like this:

      +
      +
      +/* File : interface.i */
+%module mymodule
+%{
+#include "header.h"
+%}
+%include "header.h"
+
      +
      +

      The main advantage of this approach is minimal maintenance of an + interface file for when the header file changes in the future. In more + complex projects, an interface file containing numerous %include + and #include statements like this is one of the most common + approaches to interface file design due to lower maintenance overhead.

      +

      5.7.3 Why use separate interface files?

      +

      Although SWIG can parse many header files, it is more common to + write a special .i file defining the interface to a package. + There are several reasons why you might want to do this:

      +
        +
      • It is rarely necessary to access every single function in a large + package. Many C functions might have little or no use in a scripted + environment. Therefore, why wrap them?
        • +
      • Separate interface files provide an opportunity to provide more + precise rules about how an interface is to be constructed.
        • +
      • Interface files can provide more structure and organization.
        • +
      • SWIG can't parse certain definitions that appear in header files. + Having a separate file allows you to eliminate or work around these + problems.
        • +
      • Interface files provide a more precise definition of what the + interface is. Users wanting to extend the system can go to the + interface file and immediately see what is available without having to + dig it out of header files.
        • +
      +

      5.7.4 Getting the right header files

      +

      Sometimes, it is necessary to use certain header files in order for + the code generated by SWIG to compile properly. Make sure you include + certain header files by using a %{,%} block like this:

      +
      +
      +%module graphics
+%{
+#include <GL/gl.h>
+#include <GL/glu.h>
+%}
+
+// Put rest of declarations here
+...
+
      +
      +

      5.7.5 What to do with main()

      +

      If your program defines a main() function, you may need to + get rid of it or rename it in order to use a scripting language. Most + scripting languages define their own main() procedure that is + called instead. main() also makes no sense when working with + dynamic loading. There are a few approaches to solving the main() + conflict :

      +
        +
      • Get rid of main() entirely.
        • +
      • Rename main() to something else. You can do this by + compiling your C program with an option like -Dmain=oldmain.
        • +
      • Use conditional compilation to only include main() when not + using a scripting language.
        • +
      +

      Getting rid of main() may cause potential initialization + problems of a program. To handle this problem, you may consider writing + a special function called program_init() that initializes your + program upon startup. This function could then be called either from + the scripting language as the first operation, or when the SWIG + generated module is loaded.

      +

      As a general note, many C programs only use the main() + function to parse command line options and to set parameters. However, + by using a scripting language, you are probably trying to create a + program that is more interactive. In many cases, the old main() + program can be completely replaced by a Perl, Python, or Tcl script.

      +

      Note: If some cases, you might be inclined to create a + scripting language wrapper for main(). If you do this, the + compilation will probably work and your module might even load + correctly. The only trouble is that when you call your main() + wrapper, you will find that it actually invokes the main() of + the scripting language interpreter itself! This behavior is a side + effect of the symbol binding mechanism used in the dynamic linker. The + bottom line: don't do this.

      +
      +

      6 SWIG and C++

      + + +
      + +
      + +

      This chapter describes SWIG's support for wrapping C++. As a + prerequisite, you should first read the chapter SWIG + Basics to see how SWIG wraps ANSI C. Support for C++ builds upon + ANSI C wrapping and that material will be useful in understanding this + chapter.

      +

      6.1 Comments on C++ Wrapping

      +

      Because of its complexity and the fact that C++ can be difficult to + integrate with itself let alone other languages, SWIG only provides + support for a subset of C++ features. Fortunately, this is now a rather + large subset.

      +

      In part, the problem with C++ wrapping is that there is no + semantically obvious (or automatic ) way to map many of its advanced + features into other languages. As a simple example, consider the + problem of wrapping C++ multiple inheritance to a target language with + no such support. Similarly, the use of overloaded operators and + overloaded functions can be problematic when no such capability exists + in a target language.

      +

      A more subtle issue with C++ has to do with the way that some C++ + programmers think about programming libraries. In the world of SWIG, + you are really trying to create binary-level software components for + use in other languages. In order for this to work, a "component" has to + contain real executable instructions and there has to be some kind of + binary linking mechanism for accessing its functionality. In contrast, + C++ has increasingly relied upon generic programming and templates for + much of its functionality. Although templates are a powerful feature, + they are largely orthogonal to the whole notion of binary components + and libraries. For example, an STL vector does not define any + kind of binary object for which SWIG can just create a wrapper. To + further complicate matters, these libraries often utilize a lot of + behind the scenes magic in which the semantics of seemingly basic + operations (e.g., pointer dereferencing, procedure call, etc.) can be + changed in dramatic and sometimes non-obvious ways. Although this + "magic" may present few problems in a C++-only universe, it greatly + complicates the problem of crossing language boundaries and provides + many opportunities to shoot yourself in the foot. You will just have to + be careful.

      +

      6.2 Approach

      +

      To wrap C++, SWIG uses a layered approach to code generation. At the + lowest level, SWIG generates a collection of procedural ANSI-C style + wrappers. These wrappers take care of basic type conversion, type + checking, error handling, and other low-level details of the C++ + binding. These wrappers are also sufficient to bind C++ into any target + language that supports built-in procedures. In some sense, you might + view this layer of wrapping as providing a C library interface to C++. + On top of the low-level procedural (flattened) interface, SWIG + generates proxy classes that provide a natural object-oriented (OO) + interface to the underlying code. The proxy classes are typically + written in the target language itself. For instance, in Python, a real + Python class is used to provide a wrapper around the underlying C++ + object.

      +

      It is important to emphasize that SWIG takes a deliberately + conservative and non-intrusive approach to C++ wrapping. SWIG does not + encapsulate C++ classes inside a special C++ adaptor, it does not rely + upon templates, nor does it add in additional C++ inheritance when + generating wrappers. The last thing that most C++ programs need is even + more compiler magic. Therefore, SWIG tries to maintain a very strict + and clean separation between the implementation of your C++ application + and the resulting wrapper code. You might say that SWIG has been + written to follow the principle of least surprise--it does not play + sneaky tricks with the C++ type system, it doesn't mess with your class + hierarchies, and it doesn't introduce new semantics. Although this + approach might not provide the most seamless integration with C++, it + is safe, simple, portable, and debuggable.

      +

      Some of this chapter focuses on the low-level procedural interface + to C++ that is used as the foundation for all language modules. Keep in + mind that the target languages also provide the high-level OO interface + via proxy classes. More detailed coverage can be found in the + documentation for each target language.

      +

      6.3 Supported C++ features

      +

      SWIG currently supports most C++ features including the following:

      +
        +
      • Classes
        • +
      • Constructors and destructors
        • +
      • Virtual functions
        • +
      • Public inheritance (including multiple inheritance)
        • +
      • Static functions
        • +
      • Function and method overloading
        • +
      • Operator overloading for many standard operators
        • +
      • References
        • +
      • Templates (including specialization and member templates)
        • +
      • Pointers to members
        • +
      • Namespaces
        • +
      • Default parameters
        • +
      • Smart pointers
        • +
      +

      The following C++ features are not currently supported:

      +
        +
      • Overloaded versions of certain operators (new, delete, etc.)
        • +
      • Nested classes, see Nested + classes for workarounds.
        • +
      +

      As a rule of thumb, SWIG should not be used on raw C++ source files, + use header files only.

      +

      SWIG's C++ support is an ongoing project so some of these + limitations may be lifted in future releases. However, we make no + promises. Also, submitting a bug report is a very good way to get + problems fixed (wink).

      +

      6.4 Command line options and compilation

      +

      When wrapping C++ code, it is critical that SWIG be called with the + `-c++' option. This changes the way a number of critical + features such as memory management are handled. It also enables the + recognition of C++ keywords. Without the -c++ flag, SWIG will + either issue a warning or a large number of syntax errors if it + encounters C++ code in an interface file.

      +

      When compiling and linking the resulting wrapper file, it is normal + to use the C++ compiler. For example:

      +
      +
      +$ swig -c++ -tcl example.i
+$ c++ -c example_wrap.cxx 
+$ c++ example_wrap.o $(OBJS) -o example.so
+
      +
      +

      Unfortunately, the process varies slightly on each platform. Make + sure you refer to the documentation on each target language for further + details. The SWIG Wiki also has further details.

      + Compatibility Note: Early versions of SWIG generated just a + flattened low-level C style API to C++ classes by default. The +-noproxy commandline option is recognised by many target languages + and will generate just this interface as in earlier versions. +

      6.5 Proxy classes

      +

      In order to provide a natural mapping from C++ classes to the target + language classes, SWIG's target languages mostly wrap C++ classes with + special proxy classes. These proxy classes are typically implemented in + the target language itself. For example, if you're building a Python + module, each C++ class is wrapped by a Python proxy class. Or if you're + building a Java module, each C++ class is wrapped by a Java proxy + class.

      +

      6.5.1 Construction of proxy classes

      +

      Proxy classes are always constructed as an extra layer of wrapping + that uses low-level accessor functions. To illustrate, suppose you had + a C++ class like this:

      +
      +
      +class Foo {
+public:
+      Foo();
+     ~Foo();
+      int  bar(int x);
+      int  x;
+};
+
      +
      +

      Using C++ as pseudocode, a proxy class looks something like this:

      +
      +
      +class FooProxy {
+private:
+      Foo    *self;
+public:
+      FooProxy() {
+            self = new_Foo();
+      }
+     ~FooProxy() {
+            delete_Foo(self);
+      }
+      int bar(int x) {
+            return Foo_bar(self,x);
+      }
+      int x_get() {
+            return Foo_x_get(self);
+      }
+      void x_set(int x) {
+            Foo_x_set(self,x);
+      }
+};
+
      +
      +

      Of course, always keep in mind that the real proxy class is written + in the target language. For example, in Python, the proxy might look + roughly like this:

      +
      +
      +class Foo:
+    def __init__(self):
+         self.this = new_Foo()
+    def __del__(self):
+         delete_Foo(self.this)
+    def bar(self,x):
+         return Foo_bar(self.this,x)
+    def __getattr__(self,name):
+         if name == 'x':
+              return Foo_x_get(self.this)
+         ...
+    def __setattr__(self,name,value):
+         if name == 'x':
+              Foo_x_set(self.this,value)
+         ...
+
      +
      +

      Again, it's important to emphasize that the low-level accessor + functions are always used by the proxy classes. Whenever possible, + proxies try to take advantage of language features that are similar to + C++. This might include operator overloading, exception handling, and + other features.

      +

      6.5.2 Resource management in proxies

      +

      A major issue with proxies concerns the memory management of wrapped + objects. Consider the following C++ code:

      +
      +
      +class Foo {
+public:
+      Foo();
+     ~Foo();
+      int bar(int x);
+      int x;
+};
+
+class Spam {
+public:
+      Foo *value;
+      ...
+};
+
      +
      +

      Consider some script code that uses these classes:

      +
      +
      +f = Foo()               # Creates a new Foo
+s = Spam()              # Creates a new Spam
+s.value = f             # Stores a reference to f inside s
+g = s.value             # Returns stored reference
+g = 4                   # Reassign g to some other value
+del f                   # Destroy f 
+
      +
      +

      Now, ponder the resulting memory management issues. When objects are + created in the script, the objects are wrapped by newly created proxy + classes. That is, there is both a new proxy class instance and a new + instance of the underlying C++ class. In this example, both f + and s are created in this way. However, the statement +s.value is rather curious---when executed, a pointer to f + is stored inside another object. This means that the scripting proxy + class AND another C++ class share a reference to the same + object. To make matters even more interesting, consider the statement +g = s.value. When executed, this creates a new proxy class g + that provides a wrapper around the C++ object stored in s.value +. In general, there is no way to know where this object came from---it + could have been created by the script, but it could also have been + generated internally. In this particular example, the assignment of +g results in a second proxy class for f. In other words, a + reference to f is now shared by two proxy classes and + a C++ class.

      +

      Finally, consider what happens when objects are destroyed. In the + statement, g=4, the variable g is reassigned. In many + languages, this makes the old value of g available for garbage + collection. Therefore, this causes one of the proxy classes to be + destroyed. Later on, the statement del f destroys the other + proxy class. Of course, there is still a reference to the original + object stored inside another C++ object. What happens to it? Is the + object still valid?

      +

      To deal with memory management problems, proxy classes provide an + API for controlling ownership. In C++ pseudocode, ownership control + might look roughly like this:

      +
      +
      +class FooProxy {
+public:
+      Foo    *self;
+      int     thisown;
+
+      FooProxy() {
+            self = new_Foo();
+            thisown = 1;       // Newly created object
+      }
+     ~FooProxy() {
+            if (thisown) delete_Foo(self);
+      }
+      ...
+      // Ownership control API
+      void disown() {
+           thisown = 0;
+      }
+      void acquire() {
+           thisown = 1;
+      }
+};
+
+class FooPtrProxy: public FooProxy {
+public:
+      FooPtrProxy(Foo *s) {
+          self = s;
+          thisown = 0;
+      }
+};
+
+class SpamProxy {
+     ...
+     FooProxy *value_get() {
+          return FooPtrProxy(Spam_value_get(self));
+     }
+     void value_set(FooProxy *v) {
+          Spam_value_set(self,v->self);
+          v->disown();
+     }
+     ...
+};
+
      +
      +

      Looking at this code, there are a few central features:

      +
        +
      • Each proxy class keeps an extra flag to indicate ownership. C++ + objects are only destroyed if the ownership flag is set.
        • +
      • When new objects are created in the target language, the ownership + flag is set.
        • +
      • When a reference to an internal C++ object is returned, it is + wrapped by a proxy class, but the proxy class does not have ownership.
        • +
      • In certain cases, ownership is adjusted. For instance, when a value + is assigned to the member of a class, ownership is lost.
        • +
      • Manual ownership control is provided by special disown() + and acquire() methods.
        • +
      +

      Given the tricky nature of C++ memory management, it is impossible + for proxy classes to automatically handle every possible memory + management problem. However, proxies do provide a mechanism for manual + control that can be used (if necessary) to address some of the more + tricky memory management problems.

      +

      6.5.3 Language specific details

      +

      Language specific details on proxy classes are contained in the + chapters describing each target language. This chapter has merely + introduced the topic in a very general way.

      +

      6.6 Simple C++ wrapping

      +

      The following code shows a SWIG interface file for a simple C++ + class.

      +
      +
      +%module list
+%{
+#include "list.h"
+%}
+
+// Very simple C++ example for linked list
+
+class List {
+public:
+  List();
+  ~List();
+  int  search(char *value);
+  void insert(char *);
+  void remove(char *);
+  char *get(int n);
+  int  length;
+static void print(List *l);
+};
+
      +
      +

      To generate wrappers for this class, SWIG first reduces the class to + a collection of low-level C-style accessor functions which are then + used by the proxy classes.

      +

      6.6.1 Constructors and destructors

      +

      C++ constructors and destructors are translated into accessor + functions such as the following :

      +
      +
      +List * new_List(void) {
+	return new List;
+}
+void delete_List(List *l) {
+	delete l;
+}
+
+
      +
      +

      6.6.2 Default constructors, copy + constructors and implicit destructors

      +

      Following the C++ rules for implicit constructor and destructors, + SWIG will automatically assume there is one even when they are not + explicitly declared in the class interface.

      +

      In general then:

      +
        +
      • If a C++ class does not declare any explicit constructor, SWIG will + automatically generate a wrapper for one.
        • +
      • If a C++ class does not declare an explicit copy constructor, SWIG + will automatically generate a wrapper for one if the %copyctor + is used.
        • +
      • If a C++ class does not declare an explicit destructor, SWIG will + automatically generate a wrapper for one.
        • +
      +

      And as in C++, a few rules that alters the previous behavior:

      +
        +
      • A default constructor is not created if a class already defines a + constructor with arguments.
        • +
      • Default constructors are not generated for classes with pure virtual + methods or for classes that inherit from an abstract class, but don't + provide definitions for all of the pure methods.
        • +
      • A default constructor is not created unless all base classes support + a default constructor.
        • +
      • Default constructors and implicit destructors are not created if a + class defines them in a private or protected section.
        • +
      • Default constructors and implicit destructors are not created if any + base class defines a non-public default constructor or destructor.
        • +
      +

      SWIG should never generate a default constructor, copy constructor + or default destructor wrapper for a class in which it is illegal to do + so. In some cases, however, it could be necessary (if the complete + class declaration is not visible from SWIG, and one of the above rules + is violated) or desired (to reduce the size of the final interface) by + manually disabling the implicit constructor/destructor generation.

      +

      To manually disable these, the %nodefaultctor and +%nodefaultdtor feature flag + directives can be used. Note that these directives only affects the + implicit generation, and they have no effect if the default/copy + constructors or destructor are explicitly declared in the class + interface.

      +

      For example:

      +
      +
      +%nodefaultctor Foo;  // Disable the default constructor for class Foo.
+class Foo {          // No default constructor is generated, unless one is declared
+...
+};
+class Bar {          // A default constructor is generated, if possible
+...
+};
+
      +
      +

      The directive %nodefaultctor can also be applied + "globally", as in:

      +
      +
      +%nodefaultctor; // Disable creation of default constructors
+class Foo {     // No default constructor is generated, unless one is declared
+...
+};
+class Bar {   
+public:
+  Bar();        // The default constructor is generated, since one is declared
+};
+%clearnodefaultctor; // Enable the creation of default constructors again
+
      +
      +

      The corresponding %nodefaultdtor directive can be used to + disable the generation of the default or implicit destructor, if + needed. Be aware, however, that this could lead to memory leaks in the + target language. Hence, it is recommended to use this directive only in + well known cases. For example:

      +
      +
      +%nodefaultdtor Foo;   // Disable the implicit/default destructor for class Foo.
+class Foo {           // No destructor is generated, unless one is declared
+...
+};
+
      +
      +

      Compatibility Note: The generation of default + constructors/implicit destructors was made the default behavior in SWIG + 1.3.7. This may break certain older modules, but the old behavior can + be easily restored using %nodefault or the -nodefault + command line option. Furthermore, in order for SWIG to properly + generate (or not generate) default constructors, it must be able to + gather information from both the private and protected + sections (specifically, it needs to know if a private or protected + constructor/destructor is defined). In older versions of SWIG, it was + fairly common to simply remove or comment out the private and protected + sections of a class due to parser limitations. However, this removal + may now cause SWIG to erroneously generate constructors for classes + that define a constructor in those sections. Consider restoring those + sections in the interface or using %nodefault to fix the + problem.

      +

      Note: The %nodefault directive/-nodefault + options described above, which disable both the default constructor and + the implicit destructors, could lead to memory leaks, and so it is + strongly recommended to not use them.

      +

      6.6.3 When constructor wrappers aren't + created

      +

      If a class defines a constructor, SWIG normally tries to generate a + wrapper for it. However, SWIG will not generate a constructor wrapper + if it thinks that it will result in illegal wrapper code. There are + really two cases where this might show up.

      +

      First, SWIG won't generate wrappers for protected or private + constructors. For example:

      +
      +
      +class Foo {
+protected:
+     Foo();         // Not wrapped.
+public:
+      ...
+};
+
      +
      +

      Next, SWIG won't generate wrappers for a class if it appears to be + abstract--that is, it has undefined pure virtual methods. Here are some + examples:

      +
      +
      +class Bar {
+public:
+     Bar();               // Not wrapped.  Bar is abstract.
+     virtual void spam(void) = 0; 
+};
+
+class Grok : public Bar {
+public:
+      Grok();            // Not wrapped. No implementation of abstract spam().
+};
+
      +
      +

      Some users are surprised (or confused) to find missing constructor + wrappers in their interfaces. In almost all cases, this is caused when + classes are determined to be abstract. To see if this is the case, run + SWIG with all of its warnings turned on:

      +
      +
      +% swig -Wall -python module.i
+
      +
      +

      In this mode, SWIG will issue a warning for all abstract classes. It + is possible to force a class to be non-abstract using this:

      +
      +
      +%feature("notabstract") Foo;
+
+class Foo : public Bar {
+public:
+     Foo();    // Generated no matter what---not abstract. 
+     ...
+};
+
      +
      +

      More information about %feature can be found in the +Customization features chapter.

      +

      6.6.4 Copy constructors

      +

      If a class defines more than one constructor, its behavior depends + on the capabilities of the target language. If overloading is + supported, the copy constructor is accessible using the normal + constructor function. For example, if you have this:

      +
      +
      +class List {
+public:
+    List();    
+    List(const List &);      // Copy constructor
+    ...
+};
+
      +
      +

      then the copy constructor can be used as follows:

      +
      +
      +x = List()               # Create a list
+y = List(x)              # Copy list x
+
      +
      +

      If the target language does not support overloading, then the copy + constructor is available through a special function like this:

      +
      +
      +List *copy_List(List *f) {
+    return new List(*f);
+}
+
      +
      +

      Note: For a class X, SWIG only treats a constructor + as a copy constructor if it can be applied to an object of type X + or X *. If more than one copy constructor is defined, only the + first definition that appears is used as the copy constructor--other + definitions will result in a name-clash. Constructors such as +X(const X &), X(X &), and X(X *) are handled as + copy constructors in SWIG.

      +

      Note: SWIG does not generate a copy constructor + wrapper unless one is explicitly declared in the class. This differs + from the treatment of default constructors and destructors. However, + copy constructor wrappers can be generated if using the copyctor + feature flag. For example:

      +
      +
      +%copyctor List;
+
+class List {
+public:
+    List();    
+};
+
      +
      +

      Will generate a copy constructor wrapper for List.

      +

      Compatibility note: Special support for copy constructors was + not added until SWIG-1.3.12. In previous versions, copy constructors + could be wrapped, but they had to be renamed. For example:

      +
      +
      +class Foo {
+public:
+    Foo();
+  %name(CopyFoo) Foo(const Foo &);
+    ...
+};
+
      +
      +

      For backwards compatibility, SWIG does not perform any special + copy-constructor handling if the constructor has been manually renamed. + For instance, in the above example, the name of the constructor is set + to new_CopyFoo(). This is the same as in older versions.

      +

      6.6.5 Member functions

      +

      All member functions are roughly translated into accessor functions + like this :

      +
      +
      +int List_search(List *obj, char *value) {
+	return obj->search(value);
+}
+
+
      +
      +

      This translation is the same even if the member function has been + declared as virtual.

      +

      It should be noted that SWIG does not actually create a C + accessor function in the code it generates. Instead, member access such + as obj->search(value) is directly inlined into the generated + wrapper functions. However, the name and calling convention of the + low-level procedural wrappers match the accessor function prototype + described above.

      +

      6.6.6 Static members

      +

      Static member functions are called directly without making any + special transformations. For example, the static member function +print(List *l) directly invokes List::print(List *l) in + the generated wrapper code.

      +

      6.6.7 Member data

      +

      Member data is handled in exactly the same manner as for C + structures. A pair of accessor functions are effectively created. For + example :

      +
      +
      +int List_length_get(List *obj) {
+	return obj->length;
+}
+int List_length_set(List *obj, int value) {
+	obj->length = value;
+	return value;
+}
+
+
      +
      +

      A read-only member can be created using the %immutable and +%mutable feature flag + directive. For example, we probably wouldn't want the user to change + the length of a list so we could do the following to make the value + available, but read-only.

      +
      +
      +class List {
+public:
+...
+%immutable;
+	int length;
+%mutable;
+...
+};
+
      +
      +

      Alternatively, you can specify an immutable member in advance like + this:

      +
      +
      +%immutable List::length;
+...
+class List {
+   ...
+   int length;         // Immutable by above directive
+   ...
+};
+
      +
      +

      Similarly, all data attributes declared as const are + wrapped as read-only members.

      +

      There are some subtle issues when wrapping data members that are + themselves classes. For instance, if you had another class like this,

      +
      +
      +class Foo {
+public:
+    List items;
+    ...
+
      +
      +

      then the low-level accessor to the items member actually + uses pointers. For example:

      +
      +
      +List *Foo_items_get(Foo *self) {
+    return &self->items;
+}
+void Foo_items_set(Foo *self, List *value) {
+    self->items = *value;
+}
+
      +
      +

      More information about this can be found in the SWIG Basics chapter, + Structure data members + section.

      +

      The wrapper code to generate the accessors for classes comes from + the pointer typemaps. This can be somewhat unnatural for some types. + For example, a user would expect the STL std::string class member + variables to be wrapped as a string in the target language, rather than + a pointer to this class. The const reference typemaps offer this type + of marshalling, so there is a feature to tell SWIG to use the const + reference typemaps rather than the pointer typemaps. It is the +%naturalvar directive and is used as follows:

      +
      +
      +// All List variables will use const List& typemaps
+%naturalvar List;
+
+// Only Foo::myList will use const List& typemaps
+%naturalvar Foo::myList;
+struct Foo {
+  List myList;
+};
+
+// All variables will use const reference typemaps
+%naturalvar;
+
      +
      +

      The observant reader will notice that %naturalvar works + like any other feature flag + directive, except it can also be attached to class types. The first of + the example usages above show %naturalvar attaching to the +List class. Effectively this feature changes the way accessors are + generated to the following:

      +
      +
      +const List &Foo_items_get(Foo *self) {
+    return self->items;
+}
+void Foo_items_set(Foo *self, const List &value) {
+    self->items = value;
+}
+
      +
      +

      In fact it is generally a good idea to use this feature globally as + the reference typemaps have extra NULL checking compared to the pointer + typemaps. A pointer can be NULL, whereas a reference cannot, so the + extra checking ensures that the target language user does not pass in a + value that translates to a NULL pointer and thereby preventing any + potential NULL pointer dereferences. The %naturalvar feature + will apply to global variables in addition to member variables in some + language modules, eg C# and Java.

      +

      Other alternatives for turning this feature on globally are to use + the swig -naturalvar commandline option or the module mode + option, %module(naturalvar=1)

      +

      Compatibility note: The %naturalvar feature was + introduced in SWIG-1.3.28, prior to which it was necessary to manually + apply the const reference typemaps, eg %apply const std::string & { + std::string * }, but this example would also apply the typemaps to + methods taking a std::string pointer.

      +

      Compatibility note: Read-only access used to be controlled by + a pair of directives %readonly and %readwrite. + Although these directives still work, they generate a warning message. + Simply change the directives to %immutable; and %mutable; + to silence the warning. Don't forget the extra semicolon!

      +

      Compatibility note: Prior to SWIG-1.3.12, all members of + unknown type were wrapped into accessor functions using pointers. For + example, if you had a structure like this

      +
      +
      +struct Foo {
+   size_t  len;
+};
+
      +
      +

      and nothing was known about size_t, then accessors would be + written to work with size_t *. Starting in SWIG-1.3.12, this + behavior has been modified. Specifically, pointers will only + be used if SWIG knows that a datatype corresponds to a structure or + class. Therefore, the above code would be wrapped into accessors + involving size_t. This change is subtle, but it smooths over a + few problems related to structure wrapping and some of SWIG's + customization features.

      +

      6.7 Default arguments

      +

      SWIG will wrap all types of functions that have default arguments. + For example member functions:

      +
      +
      +class Foo {
+public:
+    void bar(int x, int y = 3, int z = 4);
+};
+
      +
      +

      SWIG handles default arguments by generating an extra overloaded + method for each defaulted argument. SWIG is effectively handling + methods with default arguments as if it was wrapping the equivalent + overloaded methods. Thus for the example above, it is as if we had + instead given the following to SWIG:

      +
      +
      +class Foo {
+public:
+    void bar(int x, int y, int z);
+    void bar(int x, int y);
+    void bar(int x);
+};
+
      +
      +

      The wrappers produced are exactly the same as if the above code was + instead fed into SWIG. Details of this are covered later in the +Wrapping Overloaded Functions and Methods section. This approach + allows SWIG to wrap all possible default arguments, but can be verbose. + For example if a method has ten default arguments, then eleven wrapper + methods are generated.

      +

      Please see the +Features and default arguments section for more information on using + %feature with functions with default arguments. The +Ambiguity resolution and renaming section also deals with using +%rename and %ignore on methods with default arguments. If + you are writing your own typemaps for types used in methods with + default arguments, you may also need to write a typecheck + typemap. See the Typemaps and + overloading section for details or otherwise use the +compactdefaultargs feature flag as mentioned below.

      +

      Compatibility note: Versions of SWIG prior to SWIG-1.3.23 + wrapped default arguments slightly differently. Instead a single + wrapper method was generated and the default values were copied into + the C++ wrappers so that the method being wrapped was then called with + all the arguments specified. If the size of the wrappers are a concern + then this approach to wrapping methods with default arguments can be + re-activated by using the compactdefaultargs +feature flag.

      +
      +
      +%feature("compactdefaultargs") Foo::bar;
+class Foo {
+public:
+    void bar(int x, int y = 3, int z = 4);
+};
+
      +
      +

      This is great for reducing the size of the wrappers, but the caveat + is it does not work for the statically typed languages, such as C# and + Java, which don't have optional arguments in the language, Another + restriction of this feature is that it cannot handle default arguments + that are not public. The following example illustrates this:

      +
      +
      +class Foo {
+private:
+   static const int spam;
+public:
+   void bar(int x, int y = spam);   // Won't work with %feature("compactdefaultargs") -
+                                    // private default value
+};
+
      +
      +

      This produces uncompileable wrapper code because default values in + C++ are evaluated in the same scope as the member function whereas SWIG + evaluates them in the scope of a wrapper function (meaning that the + values have to be public).

      +

      This feature is automatically turned on when wrapping +C code with default arguments and whenever keyword arguments + (kwargs) are specified for either C or C++ code. Keyword arguments are + a language feature of some scripting languages, for example Ruby and + Python. SWIG is unable to support kwargs when wrapping overloaded + methods, so the default approach cannot be used.

      +

      6.8 Protection

      +

      SWIG wraps class members that are public following the C++ + conventions, i.e., by explicit public declaration or by the use of the +using directive. In general, anything specified in a private or + protected section will be ignored, although the internal code generator + sometimes looks at the contents of the private and protected sections + so that it can properly generate code for default constructors and + destructors. Directors could also modify the way non-public virtual + protected members are treated.

      +

      By default, members of a class definition are assumed to be private + until you explicitly give a `public:' declaration (This is the + same convention used by C++).

      +

      6.9 Enums and constants

      +

      Enumerations and constants are handled differently by the different + language modules and are described in detail in the appropriate + language chapter. However, many languages map enums and constants in a + class definition into constants with the classname as a prefix. For + example :

      +
      +
      +class Swig {
+public:
+	enum {ALE, LAGER, PORTER, STOUT};
+};
+
+
      +
      +

      Generates the following set of constants in the target scripting + language :

      +
      +
      +Swig_ALE = Swig::ALE
+Swig_LAGER = Swig::LAGER
+Swig_PORTER = Swig::PORTER
+Swig_STOUT = Swig::STOUT
+
+
      +
      +

      Members declared as const are wrapped as read-only members + and do not create constants.

      +

      6.10 Friends

      +

      Friend declarations are recognised by SWIG. For example, if you have + this code:

      +
      +
      +class Foo {
+public:
+     ...
+     friend void blah(Foo *f);
+     ...
+};
+
      +
      +

      then the friend declaration does result in a wrapper code + equivalent to one generated for the following declaration

      +
      +
      +class Foo {
+public:
+    ...
+};
+
+void blah(Foo *f);    
+
      +
      +

      A friend declaration, as in C++, is understood to be in the same + scope where the class is declared, hence, you can have

      +
      +
      +
+%ignore bar::blah(Foo *f);
+
+namespace bar {
+
+  class Foo {
+  public:
+     ...
+     friend void blah(Foo *f);
+     ...
+  };
+}
+
      +
      +

      and a wrapper for the method 'blah' will not be generated.

      +

      6.11 References and pointers

      +

      C++ references are supported, but SWIG transforms them back into + pointers. For example, a declaration like this :

      +
      +
      +class Foo {
+public:
+	double bar(double &a);
+}
+
      +
      +

      has a low-level accessor

      +
      +
      +double Foo_bar(Foo *obj, double *a) {
+	obj->bar(*a);
+}
+
      +
      +

      As a special case, most language modules pass const + references to primitive datatypes (int, short, +float, etc.) by value instead of pointers. For example, if you have + a function like this,

      +
      +
      +void foo(const int &x);
+
      +
      +

      it is called from a script as follows:

      +
      +
      +foo(3)              # Notice pass by value
+
      +
      +

      Functions that return a reference are remapped to return a pointer + instead. For example:

      +
      +
      +class Bar {
+public:
+     Foo &spam();
+};
+
      +
      +

      Generates an accessor like this:

      +
      +
      +Foo *Bar_spam(Bar *obj) {
+   Foo &result = obj->spam();
+   return &result;
+}
+
      +
      +

      However, functions that return const references to + primitive datatypes (int, short, etc.) normally + return the result as a value rather than a pointer. For example, a + function like this,

      +
      +
      +const int &bar();
+
      +
      +

      will return integers such as 37 or 42 in the target scripting + language rather than a pointer to an integer.

      +

      Don't return references to objects allocated as local variables on + the stack. SWIG doesn't make a copy of the objects so this will + probably cause your program to crash.

      +

      Note: The special treatment for references to primitive + datatypes is necessary to provide more seamless integration with more + advanced C++ wrapping applications---especially related to templates + and the STL. This was first added in SWIG-1.3.12.

      +

      6.12 Pass and return by value

      +

      Occasionally, a C++ program will pass and return class objects by + value. For example, a function like this might appear:

      +
      +
      +Vector cross_product(Vector a, Vector b);
+
      +
      +

      If no information is supplied about Vector, SWIG creates a + wrapper function similar to the following:

      +
      +
      +Vector *wrap_cross_product(Vector *a, Vector *b) {
+   Vector x = *a;
+   Vector y = *b;
+   Vector r = cross_product(x,y);
+   return new Vector(r);
+}
      +
      +

      In order for the wrapper code to compile, Vector must + define a copy constructor and a default constructor.

      +

      If Vector is defined as a class in the interface, but it + does not support a default constructor, SWIG changes the wrapper code + by encapsulating the arguments inside a special C++ template wrapper + class, through a process called the "Fulton Transform". This produces a + wrapper that looks like this:

      +
      +
      +Vector cross_product(Vector *a, Vector *b) {
+   SwigValueWrapper<Vector> x = *a;
+   SwigValueWrapper<Vector> y = *b;
+   SwigValueWrapper<Vector> r = cross_product(x,y);
+   return new Vector(r);
+}
+
      +
      +

      This transformation is a little sneaky, but it provides support for + pass-by-value even when a class does not provide a default constructor + and it makes it possible to properly support a number of SWIG's + customization options. The definition of SwigValueWrapper can + be found by reading the SWIG wrapper code. This class is really nothing + more than a thin wrapper around a pointer.

      +

      Although SWIG usually detects the classes to which the Fulton + Transform should be applied, in some situations it's necessary to + override it. That's done with %feature("valuewrapper") to + ensure it is used and %feature("novaluewrapper") to ensure it + is not used:

      +
      +
      +%feature("novaluewrapper") A;    
+class A;
+
+%feature("valuewrapper") B;
+struct B { 
+    B();
+    // ....
+};   
+
      +
      +

      It is well worth considering turning this feature on for classes + that do have a default constructor. It will remove a redundant + constructor call at the point of the variable declaration in the + wrapper, so will generate notably better performance for large objects + or for classes with expensive construction. Alternatively consider + returning a reference or a pointer.

      +

      Note: this transformation has no effect on typemaps or any + other part of SWIG---it should be transparent except that you may see + this code when reading the SWIG output file.

      +

      Note: This template transformation is new in SWIG-1.3.11 and + may be refined in future SWIG releases. In practice, it is only + absolutely necessary to do this for classes that don't define a default + constructor.

      +

      Note: The use of this template only occurs when objects are + passed or returned by value. It is not used for C++ pointers or + references.

      +

      6.13 Inheritance

      +

      SWIG supports C++ inheritance of classes and allows both single and + multiple inheritance, as limited or allowed by the target language. The + SWIG type-checker knows about the relationship between base and derived + classes and allows pointers to any object of a derived class to be used + in functions of a base class. The type-checker properly casts pointer + values and is safe to use with multiple inheritance.

      +

      SWIG treats private or protected inheritance as close to the C++ + spirit, and target language capabilities, as possible. In most cases, + this means that SWIG will parse the non-public inheritance + declarations, but that will have no effect in the generated code, + besides the implicit policies derived for constructor and destructors.

      +

      The following example shows how SWIG handles inheritance. For + clarity, the full C++ code has been omitted.

      +
      +
      +// shapes.i
+%module shapes
+%{
+#include "shapes.h"
+%}
+
+class Shape {
+public:
+        double x,y;
+	virtual double area() = 0;
+	virtual double perimeter() = 0;
+	void    set_location(double x, double y);
+};
+class Circle : public Shape {
+public:
+	Circle(double radius);
+	~Circle();
+	double area();
+	double perimeter();
+};
+class Square : public Shape {
+public:
+	Square(double size);
+	~Square();
+	double area();
+	double perimeter();
+}
+
      +
      +

      When wrapped into Python, we can perform the following operations + (shown using the low level Python accessors):

      +
      +
      +$ python
+>>> import shapes
+>>> circle = shapes.new_Circle(7)
+>>> square = shapes.new_Square(10)
+>>> print shapes.Circle_area(circle)
+153.93804004599999757
+>>> print shapes.Shape_area(circle)
+153.93804004599999757
+>>> print shapes.Shape_area(square)
+100.00000000000000000
+>>> shapes.Shape_set_location(square,2,-3)
+>>> print shapes.Shape_perimeter(square)
+40.00000000000000000
+>>>
+
      +
      +

      In this example, Circle and Square objects have been created. Member + functions can be invoked on each object by making calls to +Circle_area, Square_area, and so on. However, the same + results can be accomplished by simply using the Shape_area + function on either object.

      +

      One important point concerning inheritance is that the low-level + accessor functions are only generated for classes in which they are + actually declared. For instance, in the above example, the method +set_location() is only accessible as Shape_set_location() + and not as Circle_set_location() or Square_set_location() +. Of course, the Shape_set_location() function will accept any + kind of object derived from Shape. Similarly, accessor functions for + the attributes x and y are generated as +Shape_x_get(), Shape_x_set(), Shape_y_get(), and +Shape_y_set(). Functions such as Circle_x_get() are not + available--instead you should use Shape_x_get().

      +

      Note that there is a one to one correlation between the low-level + accessor functions and the proxy methods and therefore there is also a + one to one correlation between the C++ class methods and the generated + proxy class methods.

      +

      Note: For the best results, SWIG requires all base classes to + be defined in an interface. Otherwise, you may get a warning message + like this:

      +
      +
      +example.i:18: Warning(401): Nothing known about base class 'Foo'. Ignored.
+
      +
      +

      If any base class is undefined, SWIG still generates correct type + relationships. For instance, a function accepting a Foo * will + accept any object derived from Foo regardless of whether or + not SWIG actually wrapped the Foo class. If you really don't + want to generate wrappers for the base class, but you want to silence + the warning, you might consider using the %import directive to + include the file that defines Foo. %import simply + gathers type information, but doesn't generate wrappers. Alternatively, + you could just define Foo as an empty class in the SWIG + interface or use warning suppression +.

      +

      Note: typedef-names can be used as base + classes. For example:

      +
      +
      +class Foo {
+...
+};
+
+typedef Foo FooObj;
+class Bar : public FooObj {     // Ok.  Base class is Foo
+...
+};
+
      +
      +

      Similarly, typedef allows unnamed structures to be used as + base classes. For example:

      +
      +
      +typedef struct {
+   ...
+} Foo;
+
+class Bar : public Foo {    // Ok. 
+...
+};
+
      +
      +

      Compatibility Note: Starting in version 1.3.7, SWIG only + generates low-level accessor wrappers for the declarations that are + actually defined in each class. This differs from SWIG1.1 which used to + inherit all of the declarations defined in base classes and regenerate + specialized accessor functions such as Circle_x_get(), +Square_x_get(), Circle_set_location(), and +Square_set_location(). This behavior resulted in huge amounts of + replicated code for large class hierarchies and made it awkward to + build applications spread across multiple modules (since accessor + functions are duplicated in every single module). It is also + unnecessary to have such wrappers when advanced features like proxy + classes are used. Note: Further optimizations are enabled when + using the -fvirtual option, which avoids the regenerating of + wrapper functions for virtual members that are already defined in a + base class.

      +

      6.14 A brief discussion of multiple + inheritance, pointers, and type checking

      +

      When a target scripting language refers to a C++ object, it normally + uses a tagged pointer object that contains both the value of the + pointer and a type string. For example, in Tcl, a C++ pointer might be + encoded as a string like this:

      +
      +
      +_808fea88_p_Circle
+
      +
      +

      A somewhat common question is whether or not the type-tag could be + safely removed from the pointer. For instance, to get better + performance, could you strip all type tags and just use simple integers + instead?

      +

      In general, the answer to this question is no. In the wrappers, all + pointers are converted into a common data representation in the target + language. Typically this is the equivalent of casting a pointer to +void *. This means that any C++ type information associated with + the pointer is lost in the conversion.

      +

      The problem with losing type information is that it is needed to + properly support many advanced C++ features--especially multiple + inheritance. For example, suppose you had code like this:

      +
      +
      +class A {
+public:
+   int x;
+};
+
+class B {
+public:
+   int y;
+};
+
+class C : public A, public B {
+};
+
+int A_function(A *a) {
+   return a->x;
+}
+
+int B_function(B *b) {
+   return b->y;
+}
+
      +
      +

      Now, consider the following code that uses void *.

      +
      +
      +C *c = new C();
+void *p = (void *) c;
+...
+int x = A_function((A *) p);
+int y = B_function((B *) p);
+
      +
      +

      In this code, both A_function() and B_function() + may legally accept an object of type C * (via inheritance). + However, one of the functions will always return the wrong result when + used as shown. The reason for this is that even though p + points to an object of type C, the casting operation doesn't + work like you would expect. Internally, this has to do with the data + representation of C. With multiple inheritance, the data from + each base class is stacked together. For example:

      +
      +
      +             ------------    <--- (C *),  (A *)
+            |     A      |
+            |------------|   <--- (B *)
+            |     B      |
+             ------------   
+
      +
      +

      Because of this stacking, a pointer of type C * may change + value when it is converted to a A * or B *. However, + this adjustment does not occur if you are converting from a +void *.

      +

      The use of type tags marks all pointers with the real type of the + underlying object. This extra information is then used by SWIG + generated wrappers to correctly cast pointer values under inheritance + (avoiding the above problem).

      +

      Some of the language modules are able to solve the problem by + storing multiple instances of the pointer, for example, A *, + in the A proxy class as well as C * in the C proxy class. The + correct cast can then be made by choosing the correct void * + pointer to use and is guaranteed to work as the cast to a void pointer + and back to the same type does not lose any type information:

      +
      +
      +C *c = new C();
+void *p = (void *) c;
+void *pA = (void *) c;
+void *pB = (void *) c;
+...
+int x = A_function((A *) pA);
+int y = B_function((B *) pB);
+
      +
      +

      In practice, the pointer is held as an integral number in the target + language proxy class.

      +

      6.15 Wrapping Overloaded + Functions and Methods

      +

      In many language modules, SWIG provides partial support for + overloaded functions, methods, and constructors. For example, if you + supply SWIG with overloaded functions like this:

      +
      +
      +void foo(int x) {
+   printf("x is %d\n", x);
+}
+void foo(char *x) {
+   printf("x is '%s'\n", x);
+}
+
      +
      +

      The function is used in a completely natural way. For example:

      +
      +
      +>>> foo(3)
+x is 3
+>>> foo("hello")
+x is 'hello'
+>>>
+
      +
      +

      Overloading works in a similar manner for methods and constructors. + For example if you have this code,

      +
      +
      +class Foo {
+public:
+     Foo();
+     Foo(const Foo &);   // Copy constructor
+     void bar(int x);
+     void bar(char *s, int y);
+};
+
      +
      +

      it might be used like this

      +
      +
      +>>> f = Foo()          # Create a Foo
+>>> f.bar(3)
+>>> g = Foo(f)         # Copy Foo
+>>> f.bar("hello",2)
+
      +
      +

      6.15.1 Dispatch function generation

      +

      The implementation of overloaded functions and methods is somewhat + complicated due to the dynamic nature of scripting languages. Unlike + C++, which binds overloaded methods at compile time, SWIG must + determine the proper function as a runtime check for scripting language + targets. This check is further complicated by the typeless nature of + certain scripting languages. For instance, in Tcl, all types are simply + strings. Therefore, if you have two overloaded functions like this,

      +
      +
      +void foo(char *x);
+void foo(int x);
+
      +
      +

      the order in which the arguments are checked plays a rather critical + role.

      +

      For statically typed languages, SWIG uses the language's method + overloading mechanism. To implement overloading for the scripting + languages, SWIG generates a dispatch function that checks the number of + passed arguments and their types. To create this function, SWIG first + examines all of the overloaded methods and ranks them according to the + following rules:

      +
        +
      1. Number of required arguments. Methods are sorted by + increasing number of required arguments.
        2. +
      2. +

        Argument type precedence. All C++ datatypes are assigned a + numeric type precedence value (which is determined by the language + module).

        +
        +
        +Type              Precedence
+----------------  ----------
+TYPE *            0     (High)
+void *            20
+Integers          40
+Floating point    60
+char              80
+Strings           100   (Low)
+
        +
        +

        Using these precedence values, overloaded methods with the same + number of required arguments are sorted in increased order of + precedence values.

        +
        3. +
      +

      This may sound very confusing, but an example will help. Consider + the following collection of overloaded methods:

      +
      +
      +void foo(double);
+void foo(int);
+void foo(Bar *);
+void foo();
+void foo(int x, int y, int z, int w);
+void foo(int x, int y, int z = 3);
+void foo(double x, double y);
+void foo(double x, Bar *z);
+
      +
      +

      The first rule simply ranks the functions by required argument + count. This would produce the following list:

      +
      +
      +rank
+-----
+[0]   foo()
+[1]   foo(double);
+[2]   foo(int);
+[3]   foo(Bar *);
+[4]   foo(int x, int y, int z = 3);
+[5]   foo(double x, double y)
+[6]   foo(double x, Bar *z)
+[7]   foo(int x, int y, int z, int w);
+
      +
      +

      The second rule, simply refines the ranking by looking at argument + type precedence values.

      +
      +
      +rank
+-----
+[0]   foo()
+[1]   foo(Bar *);
+[2]   foo(int);
+[3]   foo(double);
+[4]   foo(int x, int y, int z = 3);
+[5]   foo(double x, Bar *z)
+[6]   foo(double x, double y)
+[7]   foo(int x, int y, int z, int w);
+
      +
      +

      Finally, to generate the dispatch function, the arguments passed to + an overloaded method are simply checked in the same order as they + appear in this ranking.

      +

      If you're still confused, don't worry about it---SWIG is probably + doing the right thing.

      +

      6.15.2 Ambiguity in Overloading

      +

      Regrettably, SWIG is not able to support every possible use of valid + C++ overloading. Consider the following example:

      +
      +
      +void foo(int x);
+void foo(long x);
+
      +
      +

      In C++, this is perfectly legal. However, in a scripting language, + there is generally only one kind of integer object. Therefore, which + one of these functions do you pick? Clearly, there is no way to truly + make a distinction just by looking at the value of the integer itself ( +int and long may even be the same precision). Therefore, + when SWIG encounters this situation, it may generate a warning message + like this for scripting languages:

      +
      +
      +example.i:4: Warning(509): Overloaded foo(long) is shadowed by foo(int) at example.i:3.
+
      +
      +

      or for statically typed languages like Java:

      +
      +
      +example.i:4: Warning(516): Overloaded method foo(long) ignored. Method foo(int)
+at example.i:3 used.
+
      +
      +

      This means that the second overloaded function will be inaccessible + from a scripting interface or the method won't be wrapped at all. This + is done as SWIG does not know how to disambiguate it from an earlier + method.

      +

      Ambiguity problems are known to arise in the following situations:

      +
        +
      • Integer conversions. Datatypes such as int, long, + and short cannot be disambiguated in some languages. Shown + above.
        • +
      • Floating point conversion. float and double can + not be disambiguated in some languages.
        • +
      • Pointers and references. For example, Foo * and Foo & +.
        • +
      • Pointers and arrays. For example, Foo * and Foo [4] +.
        • +
      • Pointers and instances. For example, Foo and Foo * +. Note: SWIG converts all instances to pointers.
        • +
      • Qualifiers. For example, const Foo * and Foo *.
        • +
      • Default vs. non default arguments. For example, foo(int a, int + b) and foo(int a, int b = 3).
        • +
      +

      When an ambiguity arises, methods are checked in the same order as + they appear in the interface file. Therefore, earlier methods will + shadow methods that appear later.

      +

      When wrapping an overloaded function, there is a chance that you + will get an error message like this:

      +
      +
      +example.i:3: Warning(467): Overloaded foo(int) not supported (no type checking
+rule for 'int').
+
      +
      +

      This error means that the target language module supports + overloading, but for some reason there is no type-checking rule that + can be used to generate a working dispatch function. The resulting + behavior is then undefined. You should report this as a bug to the +SWIG bug tracking database.

      +

      If you get an error message such as the following,

      +
      +
      +foo.i:6. Overloaded declaration ignored.  Spam::foo(double )
+foo.i:5. Previous declaration is Spam::foo(int )
+foo.i:7. Overloaded declaration ignored.  Spam::foo(Bar *,Spam *,int )
+foo.i:5. Previous declaration is Spam::foo(int )
+
      +
      +

      it means that the target language module has not yet implemented + support for overloaded functions and methods. The only way to fix the + problem is to read the next section.

      +

      6.15.3 Ambiguity + resolution and renaming

      +

      If an ambiguity in overload resolution occurs or if a module doesn't + allow overloading, there are a few strategies for dealing with the + problem. First, you can tell SWIG to ignore one of the methods. This is + easy---simply use the %ignore directive. For example:

      +
      +
      +%ignore foo(long);
+
+void foo(int);
+void foo(long);       // Ignored.  Oh well.
+
      +
      +

      The other alternative is to rename one of the methods. This can be + done using %rename. For example:

      +
      +
      +%rename("foo_short") foo(short);
+%rename(foo_long) foo(long);
+
+void foo(int);
+void foo(short);      // Accessed as foo_short()
+void foo(long);       // Accessed as foo_long()
+
      +
      +

      Note that the quotes around the new name are optional, however, + should the new name be a C/C++ keyword they would be essential in order + to avoid a parsing error. The %ignore and %rename + directives are both rather powerful in their ability to match + declarations. When used in their simple form, they apply to both global + functions and methods. For example:

      +
      +
      +/* Forward renaming declarations */
+%rename(foo_i) foo(int); 
+%rename(foo_d) foo(double);
+...
+void foo(int);           // Becomes 'foo_i'
+void foo(char *c);       // Stays 'foo' (not renamed)
+
+class Spam {
+public:
+   void foo(int);      // Becomes 'foo_i'
+   void foo(double);   // Becomes 'foo_d'
+   ...
+};
+
      +
      +

      If you only want the renaming to apply to a certain scope, the C++ + scope resolution operator (::) can be used. For example:

      +
      +
      +%rename(foo_i) ::foo(int);      // Only rename foo(int) in the global scope.
+                                // (will not rename class members)
+
+%rename(foo_i) Spam::foo(int);  // Only rename foo(int) in class Spam
+
      +
      +

      When a renaming operator is applied to a class as in +Spam::foo(int), it is applied to that class and all derived + classes. This can be used to apply a consistent renaming across an + entire class hierarchy with only a few declarations. For example:

      +
      +
      +%rename(foo_i) Spam::foo(int);
+%rename(foo_d) Spam::foo(double);
+
+class Spam {
+public:
+   virtual void foo(int);      // Renamed to foo_i
+   virtual void foo(double);   // Renamed to foo_d
+   ...
+};
+
+class Bar : public Spam {
+public:
+   virtual void foo(int);      // Renamed to foo_i
+   virtual void foo(double);   // Renamed to foo_d
+...
+};
+
+class Grok : public Bar {
+public:
+   virtual void foo(int);      // Renamed to foo_i
+   virtual void foo(double);   // Renamed to foo_d
+...
+};
+
      +
      +

      It is also possible to include %rename specifications in + the class definition itself. For example:

      +
      +
      +class Spam {
+   %rename(foo_i) foo(int);
+   %rename(foo_d) foo(double);
+public:
+   virtual void foo(int);      // Renamed to foo_i
+   virtual void foo(double);   // Renamed to foo_d
+   ...
+};
+
+class Bar : public Spam {
+public:
+   virtual void foo(int);      // Renamed to foo_i
+   virtual void foo(double);   // Renamed to foo_d
+...
+};
+
      +
      +

      In this case, the %rename directives still get applied + across the entire inheritance hierarchy, but it's no longer necessary + to explicitly specify the class prefix Spam::.

      +

      A special form of %rename can be used to apply a renaming + just to class members (of all classes):

      +
      +
      +%rename(foo_i) *::foo(int);   // Only rename foo(int) if it appears in a class.
+
      +
      +

      Note: the *:: syntax is non-standard C++, but the '*' is + meant to be a wildcard that matches any class name (we couldn't think + of a better alternative so if you have a better idea, send email to the + swig-devel mailing list.

      +

      Although this discussion has primarily focused on %rename + all of the same rules also apply to %ignore. For example:

      +
      +
      +%ignore foo(double);          // Ignore all foo(double)
+%ignore Spam::foo;            // Ignore foo in class Spam
+%ignore Spam::foo(double);    // Ignore foo(double) in class Spam
+%ignore *::foo(double);       // Ignore foo(double) in all classes
+
      +
      +

      When applied to a base class, %ignore forces all + definitions in derived classes to disappear. For example, %ignore + Spam::foo(double) will eliminate foo(double) in Spam + and all classes derived from Spam.

      +

      Notes on %rename and %ignore:

      +
        +
      • +

        Since, the %rename declaration is used to declare a renaming + in advance, it can be placed at the start of an interface file. This + makes it possible to apply a consistent name resolution without having + to modify header files. For example:

        +
        +
        +%module foo
+
+/* Rename these overloaded functions */
+%rename(foo_i) foo(int); 
+%rename(foo_d) foo(double);
+
+%include "header.h"
+
        +
        • +
      • +

        The scope qualifier (::) can also be used on simple names. For + example:

        +
        +
        +%rename(bar) ::foo;       // Rename foo to bar in global scope only
+%rename(bar) Spam::foo;   // Rename foo to bar in class Spam only
+%rename(bar) *::foo;      // Rename foo in classes only
+
        +
        • +
      • +

        Name matching tries to find the most specific match that is defined. + A qualified name such as Spam::foo always has higher + precedence than an unqualified name foo. Spam::foo + has higher precedence than *::foo and *::foo has + higher precedence than foo. A parameterized name has higher + precedence than an unparameterized name within the same scope level. + However, an unparameterized name with a scope qualifier has higher + precedence than a parameterized name in global scope (e.g., a renaming + of Spam::foo takes precedence over a renaming of foo(int) +).

        +
        • +
      • +

        The order in which %rename directives are defined does not + matter as long as they appear before the declarations to be renamed. + Thus, there is no difference between saying:

        +
        +
        +%rename(bar) foo;
+%rename(foo_i) Spam::foo(int);
+%rename(Foo) Spam::foo;
+
        +
        +

        and this

        +
        +
        +%rename(Foo) Spam::foo;
+%rename(bar) foo;
+%rename(foo_i) Spam::foo(int);
+
        +
        +

        (the declarations are not stored in a linked list and order has no + importance). Of course, a repeated %rename directive will + change the setting for a previous %rename directive if exactly + the same name, scope, and parameters are supplied.

        +
        • +
      • For multiple inheritance where renaming rules are defined for + multiple base classes, the first renaming rule found on a depth-first + traversal of the class hierarchy is used.
        • +
      • +

        The name matching rules strictly follow member qualification rules. + For example, if you have a class like this:

        +
        +
        +class Spam {
+public:
+   ...
+   void bar() const;
+   ...
+};
+
        +
        +

        the declaration

        +
        +
        +%rename(name) Spam::bar();
+
        +
        +

        will not apply as there is no unqualified member bar(). The + following will apply as the qualifier matches correctly:

        +
        +
        +%rename(name) Spam::bar() const;
+
        +
        +

        An often overlooked C++ feature is that classes can define two + different overloaded members that differ only in their qualifiers, like + this:

        +
        +
        +class Spam {
+public:
+   ...
+   void bar();         // Unqualified member
+   void bar() const;   // Qualified member
+   ...
+};
+
        +
        +

        %rename can then be used to target each of the overloaded methods + individually. For example we can give them separate names in the target + language:

        +
        +
        +%rename(name1) Spam::bar();
+%rename(name2) Spam::bar() const;
+
        +
        +

        Similarly, if you merely wanted to ignore one of the declarations, + use %ignore with the full qualification. For example, the + following directive would tell SWIG to ignore the const + version of bar() above:

        +
        +
        +%ignore Spam::bar() const;   // Ignore bar() const, but leave other bar() alone
+
        +
        • +
      • +

        Currently no resolution is performed in order to match function + parameters. This means function parameter types must match exactly. For + example, namespace qualifiers and typedefs will not work. The following + usage of typedefs demonstrates this:

        +
        +typedef int Integer;
+
+%rename(foo_i) foo(int);
+
+class Spam {
+public:
+   void foo(Integer);  // Stays 'foo' (not renamed)
+};
+class Ham {
+public:
+   void foo(int);      // Renamed to foo_i
+};
+
        +

        +
        • +
      • +

        The name matching rules also use default arguments for finer control + when wrapping methods that have default arguments. Recall that methods + with default arguments are wrapped as if the equivalent overloaded + methods had been parsed (Default + arguments section). Let's consider the following example class:

        +
        +
        +class Spam {
+public:
+   ...
+   void bar(int i=-1, double d=0.0);
+   ...
+};
+
        +
        +

        The following %rename will match exactly and apply to all + the target language overloaded methods because the declaration with the + default arguments exactly matches the wrapped method:

        +
        +
        +%rename(newbar) Spam::bar(int i=-1, double d=0.0);
+
        +
        +

        The C++ method can then be called from the target language with the + new name no matter how many arguments are specified, for example: +newbar(2, 2.0), newbar(2) or newbar(). However, + if the %rename does not contain the default arguments, it will + only apply to the single equivalent target language overloaded method. + So if instead we have:

        +
        +
        +%rename(newbar) Spam::bar(int i, double d);
+
        +
        +

        The C++ method must then be called from the target language with the + new name newbar(2, 2.0) when both arguments are supplied or + with the original name as bar(2) (one argument) or bar() + (no arguments). In fact it is possible to use %rename on the + equivalent overloaded methods, to rename all the equivalent overloaded + methods:

        +
        +
        +%rename(bar_2args)   Spam::bar(int i, double d);
+%rename(bar_1arg)    Spam::bar(int i);
+%rename(bar_default) Spam::bar();
+
        +
        +

        Similarly, the extra overloaded methods can be selectively ignored + using %ignore.

        +

        Compatibility note: The %rename directive introduced + the default argument matching rules in SWIG-1.3.23 at the same time as + the changes to wrapping methods with default arguments was introduced.

        +
        • +
      +

      6.15.4 Comments on overloading

      +

      Support for overloaded methods was first added in SWIG-1.3.14. The + implementation is somewhat unusual when compared to similar tools. For + instance, the order in which declarations appear is largely irrelevant + in SWIG. Furthermore, SWIG does not rely upon trial execution or + exception handling to figure out which method to invoke.

      +

      Internally, the overloading mechanism is completely configurable by + the target language module. Therefore, the degree of overloading + support may vary from language to language. As a general rule, + statically typed languages like Java are able to provide more support + than dynamically typed languages like Perl, Python, Ruby, and Tcl.

      +

      6.16 Wrapping overloaded operators

      +

      C++ overloaded operator declarations can be wrapped. For example, + consider a class like this:

      +
      +
      +class Complex {
+private:
+  double rpart, ipart;
+public:
+  Complex(double r = 0, double i = 0) : rpart(r), ipart(i) { }
+  Complex(const Complex &c) : rpart(c.rpart), ipart(c.ipart) { }
+  Complex &operator=(const Complex &c) {
+    rpart = c.rpart;
+    ipart = c.ipart;
+    return *this;
+  }
+  Complex operator+(const Complex &c) const {
+    return Complex(rpart+c.rpart, ipart+c.ipart);
+  }
+  Complex operator-(const Complex &c) const {
+    return Complex(rpart-c.rpart, ipart-c.ipart);
+  }
+  Complex operator*(const Complex &c) const {
+    return Complex(rpart*c.rpart - ipart*c.ipart,
+		   rpart*c.ipart + c.rpart*ipart);
+  }
+  Complex operator-() const {
+    return Complex(-rpart, -ipart);
+  }
+  double re() const { return rpart; }
+  double im() const { return ipart; }
+};
+
      +
      +

      When operator declarations appear, they are handled in exactly + the same manner as regular methods. However, the names of these methods + are set to strings like "operator +" or "operator -". + The problem with these names is that they are illegal identifiers in + most scripting languages. For instance, you can't just create a method + called "operator +" in Python--there won't be any way to call + it.

      +

      Some language modules already know how to automatically handle + certain operators (mapping them into operators in the target language). + However, the underlying implementation of this is really managed in a + very general way using the %rename directive. For example, in + Python a declaration similar to this is used:

      +
      +
      +%rename(__add__) Complex::operator+;
+
      +
      +

      This binds the + operator to a method called __add__ (which + is conveniently the same name used to implement the Python + operator). + Internally, the generated wrapper code for a wrapped operator will look + something like this pseudocode:

      +
      +
      +_wrap_Complex___add__(args) {
+   ... get args ...
+   obj->operator+(args);
+   ...
+}
+
      +
      +

      When used in the target language, it may now be possible to use the + overloaded operator normally. For example:

      +
      +
      +>>> a = Complex(3,4)
+>>> b = Complex(5,2)
+>>> c = a + b           # Invokes __add__ method
+
      +
      +

      It is important to realize that there is nothing magical happening + here. The %rename directive really only picks a valid method + name. If you wrote this:

      +
      +
      +%rename(add) operator+;
+
      +
      +

      The resulting scripting interface might work like this:

      +
      +
      +a = Complex(3,4)
+b = Complex(5,2)
+c = a.add(b)      # Call a.operator+(b)
+
      +
      +

      All of the techniques described to deal with overloaded functions + also apply to operators. For example:

      +
      +
      +%ignore Complex::operator=;             // Ignore = in class Complex
+%ignore *::operator=;                   // Ignore = in all classes
+%ignore operator=;                      // Ignore = everywhere.
+
+%rename(__sub__) Complex::operator-; 
+%rename(__neg__) Complex::operator-();  // Unary - 
+
      +
      +

      The last part of this example illustrates how multiple definitions + of the operator- method might be handled.

      +

      Handling operators in this manner is mostly straightforward. + However, there are a few subtle issues to keep in mind:

      +
        +
      • +

        In C++, it is fairly common to define different versions of the + operators to account for different types. For example, a class might + also include a friend function like this:

        +
        +
        +class Complex {
+public:
+  friend Complex operator+(Complex &, double);
+};
+Complex operator+(Complex &, double);
+
        +
        +

        SWIG simply ignores all friend declarations. Furthermore, + it doesn't know how to associate the associated operator+ with + the class (because it's not a member of the class).

        +

        It's still possible to make a wrapper for this operator, but you'll + have to handle it like a normal function. For example:

        +
        +
        +%rename(add_complex_double) operator+(Complex &, double);
+
        +
        • +
      • +

        Certain operators are ignored by default. For instance, new + and delete operators are ignored as well as conversion + operators.

        +
        • +
      • The semantics of certain C++ operators may not match those in the + target language.
        • +
      +

      6.17 Class extension

      +

      New methods can be added to a class using the %extend + directive. This directive is primarily used in conjunction with proxy + classes to add additional functionality to an existing class. For + example :

      +
      +
      +%module vector
+%{
+#include "vector.h"
+%}
+
+class Vector {
+public:
+	double x,y,z;
+	Vector();
+	~Vector();
+	... bunch of C++ methods ...
+	%extend {
+		char *__str__() {
+			static char temp[256];
+			sprintf(temp,"[ %g, %g, %g ]", $self->x,$self->y,$self->z);
+			return &temp[0];
+		}
+	}
+};
+
      +
      +

      This code adds a __str__ method to our class for producing + a string representation of the object. In Python, such a method would + allow us to print the value of an object using the print + command.

      +
      +
      +>>>
+>>> v = Vector();
+>>> v.x = 3
+>>> v.y = 4
+>>> v.z = 0
+>>> print(v)
+[ 3.0, 4.0, 0.0 ]
+>>>
+
+
      +
      +

      The C++ 'this' pointer is often needed to access member variables, + methods etc. The $self special variable should be used + wherever you could use 'this'. The example above demonstrates this for + accessing member variables. Note that the members dereferenced by +$self must be public members as the code is ultimately generated + into a global function and so will not have any access to non-public + members. The implicit 'this' pointer that is present in C++ methods is + not present in %extend methods. In order to access anything in + the extended class or its base class, an explicit 'this' is required. + The following example shows how one could access base class members:

      +
      +
      +struct Base {
+  virtual void method(int v) {
+    ...
+  }
+  int value;
+};
+struct Derived : Base {
+};
+%extend Derived {
+  virtual void method(int v) {
+    $self->Base::method(v); // akin to this->Base::method(v);
+    $self->value = v;       // akin to this->value = v;
+    ...
+  }
+}
+
      +
      +

      The %extend directive follows all of the same conventions + as its use with C structures. Please refer to the +Adding member functions to C structures section for further details.

      +

      Compatibility note: The %extend directive is a new + name for the %addmethods directive in SWIG1.1. Since +%addmethods could be used to extend a structure with more than just + methods, a more suitable directive name has been chosen.

      +

      6.18 Templates

      +

      Template type names may appear anywhere a type is expected in an + interface file. For example:

      +
      +
      +void foo(vector<int> *a, int n);
+void bar(list<int,100> *x);
+
      +
      +

      There are some restrictions on the use of non-type arguments. Simple + literals are supported, and so are some constant expressions. However, + use of '<' and '>' within a constant expressions currently is not + supported by SWIG ('<=' and '>=' are though). For example:

      +
      +
      +void bar(list<int,100> *x);                // OK
+void bar(list<int,2*50> *x);               // OK
+void bar(list<int,(2>1 ? 100 : 50)> *x)    // Not supported
+
      +
      +

      The type system is smart enough to figure out clever games you might + try to play with typedef. For instance, consider this code:

      +
      +
      +typedef int Integer;
+void foo(vector<int> *x, vector<Integer> *y);
+
      +
      +

      In this case, vector<Integer> is exactly the same type as +vector<int>. The wrapper for foo() will accept either + variant.

      +

      Starting with SWIG-1.3.7, simple C++ template declarations can also + be wrapped. SWIG-1.3.12 greatly expands upon the earlier + implementation. Before discussing this any further, there are a few + things you need to know about template wrapping. First, a bare C++ + template does not define any sort of runnable object-code for which + SWIG can normally create a wrapper. Therefore, in order to wrap a + template, you need to give SWIG information about a particular template + instantiation (e.g., vector<int>, array<double>, + etc.). Second, an instantiation name such as vector<int> is + generally not a valid identifier name in most target languages. Thus, + you will need to give the template instantiation a more suitable name + such as intvector when creating a wrapper.

      +

      To illustrate, consider the following template definition:

      +
      +
      +template<class T> class List {
+private:
+    T *data;
+    int nitems;
+    int maxitems;
+public:
+    List(int max) {
+      data = new T [max];
+      nitems = 0;
+      maxitems = max;
+    }
+    ~List() {
+      delete [] data;
+    };
+    void append(T obj) {
+      if (nitems < maxitems) {
+        data[nitems++] = obj;
+      }
+    }
+    int length() {
+      return nitems;
+    }
+    T get(int n) {
+      return data[n];
+    }
+};
+
      +
      +

      By itself, this template declaration is useless--SWIG simply ignores + it because it doesn't know how to generate any code until unless a + definition of T is provided.

      +

      One way to create wrappers for a specific template instantiation is + to simply provide an expanded version of the class directly like this:

      +
      +
      +%rename(intList) List<int>;       // Rename to a suitable identifier
+class List<int> {
+private:
+    int *data;
+    int nitems;
+    int maxitems;
+public:
+    List(int max);
+    ~List();
+    void append(int obj);
+    int length();
+    int get(int n);
+};
+
      +
      +

      The %rename directive is needed to give the template class + an appropriate identifier name in the target language (most languages + would not recognize C++ template syntax as a valid class name). The + rest of the code is the same as what would appear in a normal class + definition.

      +

      Since manual expansion of templates gets old in a hurry, the +%template directive can be used to create instantiations of a + template class. Semantically, %template is simply a + shortcut---it expands template code in exactly the same way as shown + above. Here are some examples:

      +
      +
      +/* Instantiate a few different versions of the template */
+%template(intList) List<int>;
+%template(doubleList) List<double>;
+
      +
      +

      The argument to %template() is the name of the + instantiation in the target language. The name you choose should not + conflict with any other declarations in the interface file with one + exception---it is okay for the template name to match that of a typedef + declaration. For example:

      +
      +
      +%template(intList) List<int>;
+...
+typedef List<int> intList;    // OK
+
      +
      +

      SWIG can also generate wrappers for function templates using a + similar technique. For example:

      +
      +
      +// Function template
+template<class T> T max(T a, T b) { return a > b ? a : b; }
+
+// Make some different versions of this function
+%template(maxint) max<int>;
+%template(maxdouble) max<double>;
+
      +
      +

      In this case, maxint and maxdouble become unique + names for specific instantiations of the function.

      +

      The number of arguments supplied to %template should match + that in the original template definition. Template default arguments + are supported. For example:

      +
      +
      +template vector<typename T, int max=100> class vector {
+...
+};
+
+%template(intvec) vector<int>;           // OK
+%template(vec1000) vector<int,1000>;     // OK
+
      +
      +

      The %template directive should not be used to wrap the same + template instantiation more than once in the same scope. This will + generate an error. For example:

      +
      +
      +%template(intList) List<int>;
+%template(Listint) List<int>;    // Error.   Template already wrapped.
+
      +
      +

      This error is caused because the template expansion results in two + identical classes with the same name. This generates a symbol table + conflict. Besides, it probably more efficient to only wrap a specific + instantiation only once in order to reduce the potential for code + bloat.

      +

      Since the type system knows how to handle typedef, it is + generally not necessary to instantiate different versions of a template + for typenames that are equivalent. For instance, consider this code:

      +
      +
      +%template(intList) vector<int>;
+typedef int Integer;
+...
+void foo(vector<Integer> *x);
+
      +
      +

      In this case, vector<Integer> is exactly the same type as +vector<int>. Any use of Vector<Integer> is mapped back to + the instantiation of vector<int> created earlier. Therefore, + it is not necessary to instantiate a new class for the type Integer + (doing so is redundant and will simply result in code bloat).

      +

      When a template is instantiated using %template, + information about that class is saved by SWIG and used elsewhere in the + program. For example, if you wrote code like this,

      +
      +
      +...
+%template(intList) List<int>;
+...
+class UltraList : public List<int> {
+   ...
+};
+
      +
      +

      then SWIG knows that List<int> was already wrapped as a + class called intList and arranges to handle the inheritance + correctly. If, on the other hand, nothing is known about List<int> +, you will get a warning message similar to this:

      +
      +
      +example.h:42. Nothing known about class 'List<int >' (ignored). 
+example.h:42. Maybe you forgot to instantiate 'List<int >' using %template. 
+
      +
      +

      If a template class inherits from another template class, you need + to make sure that base classes are instantiated before derived classes. + For example:

      +
      +
      +template<class T> class Foo {
+...
+};
+
+template<class T> class Bar : public Foo<T> {
+...
+};
+
+// Instantiate base classes first 
+%template(intFoo) Foo<int>;
+%template(doubleFoo) Foo<double>;
+
+// Now instantiate derived classes
+%template(intBar) Bar<int>;
+%template(doubleBar) Bar<double>;
+
      +
      +

      The order is important since SWIG uses the instantiation names to + properly set up the inheritance hierarchy in the resulting wrapper code + (and base classes need to be wrapped before derived classes). Don't + worry--if you get the order wrong, SWIG should generate a warning + message.

      +

      Occasionally, you may need to tell SWIG about base classes that are + defined by templates, but which aren't supposed to be wrapped. Since + SWIG is not able to automatically instantiate templates for this + purpose, you must do it manually. To do this, simply use %template + with no name. For example:

      +
      +
      +// Instantiate traits<double,double>, but don't wrap it.
+%template() traits<double,double>;
+
      +
      +

      If you have to instantiate a lot of different classes for many + different types, you might consider writing a SWIG macro. For example:

      +
      +
      +%define TEMPLATE_WRAP(prefix, T...) 
+%template(prefix ## Foo) Foo<T >;
+%template(prefix ## Bar) Bar<T >;
+...
+%enddef
+
+TEMPLATE_WRAP(int, int)
+TEMPLATE_WRAP(double, double)
+TEMPLATE_WRAP(String, char *)
+TEMPLATE_WRAP(PairStringInt, std::pair<string, int>)
+...
+
      +
      +

      Note the use of a vararg macro for the type T. If this wasn't used, + the comma in the templated type in the last example would not be + possible.

      +

      The SWIG template mechanism does support specialization. + For instance, if you define a class like this,

      +
      +
      +template<> class List<int> {
+private:
+    int *data;
+    int nitems;
+    int maxitems;
+public:
+    List(int max);
+    ~List();
+    void append(int obj);
+    int length();
+    int get(int n);
+};
+
      +
      +

      then SWIG will use this code whenever the user expands List<int> +. In practice, this may have very little effect on the underlying + wrapper code since specialization is often used to provide slightly + modified method bodies (which are ignored by SWIG). However, special + SWIG directives such as %typemap, %extend, and so + forth can be attached to a specialization to provide customization for + specific types.

      +

      Partial template specialization is partially supported by SWIG. For + example, this code defines a template that is applied when the template + argument is a pointer.

      +
      +
      +template<class T> class List<T*> {
+private:
+    T *data;
+    int nitems;
+    int maxitems;
+public:
+    List(int max);
+    ~List();
+    void append(int obj);
+    int length();
+    T get(int n);
+};
+
      +
      +

      SWIG should be able to handle most simple uses of partial + specialization. However, it may fail to match templates properly in + more complicated cases. For example, if you have this code,

      +
      +
      +template<class T1, class T2> class Foo<T1, T2 *> { };
+
      +
      +

      SWIG isn't able to match it properly for instantiations like +Foo<int *, int *>. This problem is not due to parsing, but due to + the fact that SWIG does not currently implement all of the C++ argument + deduction rules.

      +

      Member function templates are supported. The underlying principle is + the same as for normal templates--SWIG can't create a wrapper unless + you provide more information about types. For example, a class with a + member template might look like this:

      +
      +
      +class Foo {
+public:
+     template<class T> void bar(T x, T y) { ... };
+     ...
+};
+
      +
      +

      To expand the template, simply use %template inside the + class.

      +
      +
      +class Foo {
+public:
+     template<class T> void bar(T x, T y) { ... };
+     ...
+     %template(barint)    bar<int>;
+     %template(bardouble) bar<double>;
+};
+
      +
      +

      Or, if you want to leave the original class definition alone, just + do this:

      +
      +
      +class Foo {
+public:
+     template<class T> void bar(T x, T y) { ... };
+     ...
+};
+...
+%extend Foo {
+     %template(barint)    bar<int>;
+     %template(bardouble) bar<double>;
+};
+
      +
      +

      or simply

      +
      +
      +class Foo {
+public:
+     template<class T> void bar(T x, T y) { ... };
+     ...
+};
+...
+
+%template(bari) Foo::bar<int>;
+%template(bard) Foo::bar<double>;
+
      +
      +

      In this case, the %extend directive is not needed, and +%template does the exactly same job, i.e., it adds two new methods + to the Foo class.

      +

      Note: because of the way that templates are handled, the +%template directive must always appear after the + definition of the template to be expanded.

      +

      Now, if your target language supports overloading, you can even try

      +
      +
      +%template(bar) Foo::bar<int>;
+%template(bar) Foo::bar<double>;
+
      +
      +

      and since the two new wrapped methods have the same name 'bar', they + will be overloaded, and when called, the correct method will be + dispatched depending on the argument type.

      +

      When used with members, the %template directive may be + placed in another template class. Here is a slightly perverse example:

      +
      +
      +// A template
+template<class T> class Foo {
+public:
+     // A member template
+     template<class S> T bar(S x, S y) { ... };
+     ...
+};
+
+// Expand a few member templates
+%extend Foo {
+  %template(bari) bar<int>;
+  %template(bard) bar<double>;
+}
+
+// Create some wrappers for the template
+%template(Fooi) Foo<int>;
+%template(Food) Foo<double>;
+
      +
      +

      Miraculously, you will find that each expansion of Foo has + member functions bari() and bard() added.

      +

      A common use of member templates is to define constructors for + copies and conversions. For example:

      +
      +
      +template<class T1, class T2> struct pair {
+   T1 first;
+   T2 second;
+   pair() : first(T1()), second(T2()) { }
+   pair(const T1 &x, const T2 &y) : first(x), second(y) { }
+   template<class U1, class U2> pair(const pair<U1,U2> &x) 
+                                        : first(x.first),second(x.second) { }
+};
+
      +
      +

      This declaration is perfectly acceptable to SWIG, but the + constructor template will be ignored unless you explicitly expand it. + To do that, you could expand a few versions of the constructor in the + template class itself. For example:

      +
      +
      +%extend pair {
+   %template(pair) pair<T1,T2>;        // Generate default copy constructor
+};
+
      +
      +

      When using %extend in this manner, notice how you can still + use the template parameters in the original template definition.

      +

      Alternatively, you could expand the constructor template in selected + instantiations. For example:

      +
      +
      +// Instantiate a few versions
+%template(pairii) pair<int,int>;
+%template(pairdd) pair<double,double>;
+
+// Create a default constructor only 
+%extend pair<int,int> {
+   %template(paird) pair<int,int>;         // Default constructor
+};
+
+// Create default and conversion constructors 
+%extend pair<double,double> {
+   %template(paird) pair<double,dobule>;   // Default constructor
+   %template(pairc) pair<int,int>;         // Conversion constructor
+};
+
      +
      +

      And if your target language supports overloading, then you can try + instead:

      +
      +
      +// Create default and conversion constructors 
+%extend pair<double,double> {
+   %template(pair) pair<double,dobule>;   // Default constructor
+   %template(pair) pair<int,int>;         // Conversion constructor
+};
+
      +
      +

      In this case, the default and conversion constructors have the same + name. Hence, Swig will overload them and define an unique visible + constructor, that will dispatch the proper call depending on the + argument type.

      +

      If all of this isn't quite enough and you really want to make + someone's head explode, SWIG directives such as %rename, +%extend, and %typemap can be included directly in template + definitions. For example:

      +
      +
      +// File : list.h
+template<class T> class List {
+   ...
+public:
+    %rename(__getitem__) get(int);
+    List(int max);
+    ~List();
+    ...
+    T get(int index);
+    %extend {
+        char *__str__() {
+            /* Make a string representation */
+            ...
+        }
+    }
+};
+
      +
      +

      In this example, the extra SWIG directives are propagated to + every template instantiation.

      +

      It is also possible to separate these declarations from the template + class. For example:

      +
      +
      +%rename(__getitem__) List::get;
+%extend List {
+    char *__str__() {
+        /* Make a string representation */
+        ...
+    }
+    /* Make a copy */
+    T *__copy__() {
+       return new List<T>(*$self);
+    }
+};
+
+...
+template<class T> class List {
+    ...
+    public:
+    List() { };
+    T get(int index);
+    ...
+};
+
      +
      +

      When %extend is decoupled from the class definition, it is + legal to use the same template parameters as provided in the class + definition. These are replaced when the template is expanded. In + addition, the %extend directive can be used to add additional + methods to a specific instantiation. For example:

      +
      +
      +%template(intList) List<int>;
+
+%extend List<int> {
+    void blah() {
+          printf("Hey, I'm an List<int>!\n");
+    }
+};
+
      +
      +

      SWIG even supports overloaded templated functions. As usual the +%template directive is used to wrap templated functions. For + example:

      +
      +
      +template<class T> void foo(T x) { };
+template<class T> void foo(T x, T y) { };
+
+%template(foo) foo<int>;
+
      +
      +

      This will generate two overloaded wrapper methods, the first will + take a single integer as an argument and the second will take two + integer arguments.

      +

      Needless to say, SWIG's template support provides plenty of + opportunities to break the universe. That said, an important final + point is that SWIG does not perform extensive error checking of + templates! Specifically, SWIG does not perform type checking nor + does it check to see if the actual contents of the template declaration + make any sense. Since the C++ compiler will hopefully check this when + it compiles the resulting wrapper file, there is no practical reason + for SWIG to duplicate this functionality (besides, none of the SWIG + developers are masochistic enough to want to implement this right now).

      +

      Compatibility Note: The first implementation of template + support relied heavily on macro expansion in the preprocessor. + Templates have been more tightly integrated into the parser and type + system in SWIG-1.3.12 and the preprocessor is no longer used. Code that + relied on preprocessing features in template expansion will no longer + work. However, SWIG still allows the # operator to be used to generate + a string from a template argument.

      +

      Compatibility Note: In earlier versions of SWIG, the +%template directive introduced a new class name. This name could + then be used with other directives. For example:

      +
      +
      +%template(vectori) vector<int>;
+%extend vectori {
+    void somemethod() { }
+};
+
      +
      +

      This behavior is no longer supported. Instead, you should use the + original template name as the class name. For example:

      +
      +
      +%template(vectori) vector<int>;
+%extend vector<int> {
+    void somemethod() { }
+};
+
      +
      +

      Similar changes apply to typemaps and other customization features.

      +

      6.19 Namespaces

      +

      Support for C++ namespaces is a relatively late addition to SWIG, + first appearing in SWIG-1.3.12. Before describing the implementation, + it is worth noting that the semantics of C++ namespaces is extremely + non-trivial--especially with regard to the C++ type system and class + machinery. At a most basic level, namespaces are sometimes used to + encapsulate common functionality. For example:

      +
      +
      +namespace math {
+   double sin(double);
+   double cos(double);
+
+   class Complex {
+      double im,re;
+   public:
+      ...
+   };
+   ...
+};
+
      +
      +

      Members of the namespace are accessed in C++ by prepending the + namespace prefix to names. For example:

      +
      +
      +double x = math::sin(1.0);
+double magnitude(math::Complex *c);
+math::Complex c;
+...
+
      +
      +

      At this level, namespaces are relatively easy to manage. However, + things start to get very ugly when you throw in the other ways a + namespace can be used. For example, selective symbols can be exported + from a namespace with using.

      +
      +
      +using math::Complex;
+double magnitude(Complex *c);       // Namespace prefix stripped
+
      +
      +

      Similarly, the contents of an entire namespace can be made available + like this:

      +
      +
      +using namespace math;
+double x = sin(1.0);
+double magnitude(Complex *c);
+
      +
      +

      Alternatively, a namespace can be aliased:

      +
      +
      +namespace M = math;
+double x = M::sin(1.0);
+double magnitude(M::Complex *c);
+
      +
      +

      Using combinations of these features, it is possible to write + head-exploding code like this:

      +
      +
      +namespace A {
+  class Foo {
+  };
+}
+
+namespace B {
+   namespace C {
+      using namespace A;
+   }
+   typedef C::Foo FooClass;
+}
+
+namespace BIGB = B;
+
+namespace D {
+   using BIGB::FooClass;
+   class Bar : public FooClass {
+   }
+};
+
+class Spam : public D::Bar {
+};
+
+void evil(A::Foo *a, B::FooClass *b, B::C::Foo *c, BIGB::FooClass *d,
+          BIGB::C::Foo *e, D::FooClass *f);
+
+
      +
      +

      Given the possibility for such perversion, it's hard to imagine how + every C++ programmer might want such code wrapped into the target + language. Clearly this code defines three different classes. However, + one of those classes is accessible under at least six different names!

      +

      SWIG fully supports C++ namespaces in its internal type system and + class handling code. If you feed SWIG the above code, it will be parsed + correctly, it will generate compilable wrapper code, and it will + produce a working scripting language module. However, the default + wrapping behavior is to flatten namespaces in the target language. This + means that the contents of all namespaces are merged together in the + resulting scripting language module. For example, if you have code like + this,

      +
      +
      +%module foo
+namespace foo {
+   void bar(int);
+   void spam();
+}
+
+namespace bar {
+   void blah();
+}
+
+
      +
      +

      then SWIG simply creates three wrapper functions bar(), +spam(), and blah() in the target language. SWIG does not + prepend the names with a namespace prefix nor are the functions + packaged in any kind of nested scope.

      +

      There is some rationale for taking this approach. Since C++ + namespaces are often used to define modules in C++, there is a natural + correlation between the likely contents of a SWIG module and the + contents of a namespace. For instance, it would not be unreasonable to + assume that a programmer might make a separate extension module for + each C++ namespace. In this case, it would be redundant to prepend + everything with an additional namespace prefix when the module itself + already serves as a namespace in the target language. Or put another + way, if you want SWIG to keep namespaces separate, simply wrap each + namespace with its own SWIG interface.

      +

      Because namespaces are flattened, it is possible for symbols defined + in different namespaces to generate a name conflict in the target + language. For example:

      +
      +
      +namespace A {
+   void foo(int);
+}
+namespace B {
+   void foo(double);
+}
+
      +
      +

      When this conflict occurs, you will get an error message that + resembles this:

      +
      +
      +example.i:26. Error. 'foo' is multiply defined in the generated module.
+example.i:23. Previous declaration of 'foo'
+
      +
      +

      To resolve this error, simply use %rename to disambiguate + the declarations. For example:

      +
      +
      +%rename(B_foo) B::foo;
+...
+namespace A {
+   void foo(int);
+}
+namespace B {
+   void foo(double);     // Gets renamed to B_foo
+}
+
      +
      +

      Similarly, %ignore can be used to ignore declarations.

      +

      using declarations do not have any effect on the generated + wrapper code. They are ignored by SWIG language modules and they do not + result in any code. However, these declarations are used by + the internal type system to track type-names. Therefore, if you have + code like this:

      +
      +
      +namespace A {
+   typedef int Integer;
+}
+using namespace A;
+void foo(Integer x);
+
      +
      +

      SWIG knows that Integer is the same as A::Integer + which is the same as int.

      +

      Namespaces may be combined with templates. If necessary, the +%template directive can be used to expand a template defined in a + different namespace. For example:

      +
      +
      +namespace foo {
+    template<typename T> T max(T a, T b) { return a > b ? a : b; }
+}
+
+using foo::max;
+
+%template(maxint)   max<int>;           // Okay.
+%template(maxfloat) foo::max<float>;    // Okay (qualified name).
+
+namespace bar {
+    using namespace foo;
+    %template(maxdouble)  max<double>;    // Okay.
+}
+
      +
      +

      The combination of namespaces and other SWIG directives may + introduce subtle scope-related problems. The key thing to keep in mind + is that all SWIG generated wrappers are produced in the global + namespace. Symbols from other namespaces are always accessed using + fully qualified names---names are never imported into the global space + unless the interface happens to do so with a using + declaration. In almost all cases, SWIG adjusts typenames and symbols to + be fully qualified. However, this is not done in code fragments such as + function bodies, typemaps, exception handlers, and so forth. For + example, consider the following:

      +
      +
      +namespace foo {
+    typedef int Integer;
+    class bar {
+    public:
+       ...
+    };
+}
+
+%extend foo::bar {
+   Integer add(Integer x, Integer y) {
+       Integer r = x + y;        // Error. Integer not defined in this scope
+       return r;
+   }
+};
+
      +
      +

      In this case, SWIG correctly resolves the added method parameters + and return type to foo::Integer. However, since function + bodies aren't parsed and such code is emitted in the global namespace, + this code produces a compiler error about Integer. To fix the + problem, make sure you use fully qualified names. For example:

      +
      +
      +%extend foo::bar {
+   Integer add(Integer x, Integer y) {
+       foo::Integer r = x + y;        // Ok.
+       return r;
+   }
+};
+
      +
      +

      Note: SWIG does not propagate using + declarations to the resulting wrapper code. If these declarations + appear in an interface, they should also appear in any header + files that might have been included in a %{ ... %} section. In + other words, don't insert extra using declarations into a SWIG + interface unless they also appear in the underlying C++ code.

      +

      Note: Code inclusion directives such as %{ ... %} or + %inline %{ ... %} should not be placed inside a namespace + declaration. The code emitted by these directives will not be enclosed + in a namespace and you may get very strange results. If you need to use + namespaces with these directives, consider the following:

      +
      +
      +// Good version
+%inline %{
+namespace foo {
+     void bar(int) { ... }
+     ...
+}
+%}
+
+// Bad version.  Emitted code not placed in namespace.
+namespace foo {
+%inline %{
+     void bar(int) { ... }   /* I'm bad */
+     ...
+%}
+}
+
      +
      +

      Note: When the %extend directive is used inside a + namespace, the namespace name is included in the generated functions. + For example, if you have code like this,

      +
      +
      +namespace foo {
+   class bar {
+   public:
+        %extend {
+           int blah(int x);
+        };
+   };
+}
+
      +
      +

      the added method blah() is mapped to a function int + foo_bar_blah(foo::bar *self, int x). This function resides in the + global namespace.

      +

      Note: Although namespaces are flattened in the target + language, the SWIG generated wrapper code observes the same namespace + conventions as used in the input file. Thus, if there are no symbol + conflicts in the input, there will be no conflicts in the generated + code.

      +

      Note: In the same way that no resolution is performed on + parameters, a conversion operator name must match exactly to how it is + defined. Do not change the qualification of the operator. For example, + suppose you had an interface like this:

      +
      +
      +namespace foo {
+   class bar;
+   class spam {
+   public:
+        ...
+        operator bar();      // Conversion of spam -> bar
+        ...
+   };
+}
+
      +
      +

      The following is how the feature is expected to be written for a + successful match:

      +
      +
      +%rename(tofoo) foo::spam::operator bar();
+
      +
      +

      The following does not work as no namespace resolution is performed + in the matching of conversion operator names:

      +
      +
      +%rename(tofoo) foo::spam::operator foo::bar();
+
      +
      +

      Note, however, that if the operator is defined using a qualifier in + its name, then the feature must use it too...

      +
      +
      +%rename(tofoo) foo::spam::operator bar();      // will not match
+%rename(tofoo) foo::spam::operator foo::bar(); // will match
+namespace foo {
+   class bar;
+   class spam {
+   public:
+        ...
+        operator foo::bar();
+        ...
+   };
+}
+
      +
      +

      Compatibility Note: Versions of SWIG prior to 1.3.32 were + inconsistent in this approach. A fully qualified name was usually + required, but would not work in some situations.

      +

      Note: The flattening of namespaces is only intended to serve + as a basic namespace implementation. None of the target language + modules are currently programmed with any namespace awareness. In the + future, language modules may or may not provide more advanced namespace + support.

      +

      6.20 + Renaming templated types in namespaces

      +

      As has been mentioned, when %rename includes parameters, the + parameter types must match exactly (no typedef or namespace resolution + is performed). SWIG treats templated types slightly differently and has + an additional matching rule so unlike non-templated types, an exact + match is not always required. If the fully qualified templated type is + specified, it will have a higher precedence over the generic template + type. In the example below, the generic template type is used to rename + to bbb and the fully qualified type is used to rename to +ccc.

      +
      +
      +%rename(bbb) Space::ABC::aaa(T t);                       // will match but with lower precedence than ccc
+%rename(ccc) Space::ABC<Space::XYZ>::aaa(Space::XYZ t);  // will match but with higher precedence than bbb
+
+namespace Space {
+  class XYZ {};
+  template<typename T> struct ABC {
+    void aaa(T t) {}
+  };
+}
+%template(ABCXYZ) Space::ABC<Space::XYZ>;
+
      +
      +

      It should now be apparent that there are many ways to achieve a + renaming with %rename. This is demonstrated by the following two + examples, which are effectively the same as the above example. Below + shows how %rename can be placed inside a namespace.

      +
      +
      +namespace Space {
+  %rename(bbb) ABC::aaa(T t);                       // will match but with lower precedence than ccc
+  %rename(ccc) ABC<Space::XYZ>::aaa(Space::XYZ t);  // will match but with higher precedence than bbb
+  %rename(ddd) ABC<Space::XYZ>::aaa(XYZ t);         // will not match
+}
+
+namespace Space {
+  class XYZ {};
+  template<typename T> struct ABC {
+    void aaa(T t) {}
+  };
+}
+%template(ABCXYZ) Space::ABC<Space::XYZ>;
+
      +
      +

      Note that ddd does not match as there is no namespace + resolution for parameter types and the fully qualified type must be + specified for template type expansion. The following example shows how + %rename can be placed within %extend.

      +
      +
      +namespace Space {
+  %extend ABC {
+    %rename(bbb) aaa(T t);           // will match but with lower precedence than ccc
+  }
+  %extend ABC<Space::XYZ> {
+    %rename(ccc) aaa(Space::XYZ t);  // will match but with higher precedence than bbb
+    %rename(ddd) aaa(XYZ t);         // will not match
+  }
+}
+
+namespace Space {
+  class XYZ {};
+  template<typename T> struct ABC {
+    void aaa(T t) {}
+  };
+}
+%template(ABCXYZ) Space::ABC<Space::XYZ>;
+
      +
      +

      6.21 Exception + specifications

      +

      When C++ programs utilize exceptions, exceptional behavior is + sometimes specified as part of a function or method declaration. For + example:

      +
      +
      +class Error { };
+
+class Foo {
+public:
+    ...
+    void blah() throw(Error);
+    ...
+};
+
      +
      +

      If an exception specification is used, SWIG automatically generates + wrapper code for catching the indicated exception and, when possible, + rethrowing it into the target language, or converting it into an error + in the target language otherwise. For example, in Python, you can write + code like this:

      +
      +
      +f = Foo()
+try:
+    f.blah()
+except Error,e:
+     # e is a wrapped instance of "Error"
+
      +
      +

      Details of how to tailor code for handling the caught C++ exception + and converting it into the target language's exception/error handling + mechanism is outlined in the "throws" typemap + section.

      +

      Since exception specifications are sometimes only used sparingly, + this alone may not be enough to properly handle C++ exceptions. To do + that, a different set of special SWIG directives are used. Consult the + "Exception handling with %exception" section + for details. The next section details a way of simulating an exception + specification or replacing an existing one.

      +

      6.22 Exception handling with %catches

      +

      Exceptions are automatically handled for methods with an exception + specification. Similar handling can be achieved for methods without + exception specifications through the %catches feature. It is + also possible to replace any declared exception specification using the + %catches feature. In fact, %catches uses the same +"throws" typemaps that SWIG uses for exception specifications in + handling exceptions. The %catches feature must contain a list + of possible types that can be thrown. For each type that is in the + list, SWIG will generate a catch handler, in the same way that it would + for types declared in the exception specification. Note that the list + can also include the catch all specification "...". For example,

      +
      +
      +struct EBase { virtual ~EBase(); };
+struct Error1 : EBase { };
+struct Error2 : EBase { };
+struct Error3 : EBase { };
+struct Error4 : EBase { };
+
+%catches(Error1,Error2,...) Foo::bar();
+%catches(EBase) Foo::blah();
+
+class Foo {
+public:
+    ...
+    void bar();
+    void blah() throw(Error1,Error2,Error3,Error4);
+    ...
+};
+
      +
      +

      For the Foo::bar() method, which can throw anything, SWIG + will generate catch handlers for Error1, Error2 as + well as a catch all handler (...). Each catch handler will convert the + caught exception and convert it into a target language error/exception. + The catch all handler will convert the caught exception into an unknown + error/exception.

      +

      Without the %catches feature being attached to +Foo::blah(), SWIG will generate catch handlers for all of the types + in the exception specification, that is, Error1, Error2, Error3, + Error4. However, with the %catches feature above, just a + single catch handler for the base class, EBase will be + generated to convert the C++ exception into a target language + error/exception.

      +

      6.23 Pointers to Members

      +

      Starting with SWIG-1.3.7, there is limited parsing support for + pointers to C++ class members. For example:

      +
      +
      +double do_op(Object *o, double (Object::*callback)(double,double));
+extern double (Object::*fooptr)(double,double);
+%constant double (Object::*FOO)(double,double) = &Object::foo;
+
      +
      +

      Although these kinds of pointers can be parsed and represented by + the SWIG type system, few language modules know how to handle them due + to implementation differences from standard C pointers. Readers are + strongly advised to consult an advanced text such as the "The + Annotated C++ Manual" for specific details.

      +

      When pointers to members are supported, the pointer value might + appear as a special string like this:

      +
      +
      +>>> print example.FOO
+_ff0d54a800000000_m_Object__f_double_double__double
+>>>
+
      +
      +

      In this case, the hexadecimal digits represent the entire value of + the pointer which is usually the contents of a small C++ structure on + most machines.

      +

      SWIG's type-checking mechanism is also more limited when working + with member pointers. Normally SWIG tries to keep track of inheritance + when checking types. However, no such support is currently provided for + member pointers.

      +

      6.24 Smart pointers and operator->()

      +

      In some C++ programs, objects are often encapsulated by + smart-pointers or proxy classes. This is sometimes done to implement + automatic memory management (reference counting) or persistence. + Typically a smart-pointer is defined by a template class where the +-> operator has been overloaded. This class is then wrapped around + some other class. For example:

      +
      +
      +// Smart-pointer class
+template<class T> class SmartPtr {
+    T *pointee;
+public:
+    ...
+    T *operator->() {
+        return pointee;
+    }
+    ...
+};
+
+// Ordinary class
+class Foo_Impl {
+public:
+    int x;
+    virtual void bar();
+    ...
+};
+
+// Smart-pointer wrapper
+typedef SmartPtr<Foo_Impl> Foo;
+
+// Create smart pointer Foo
+Foo make_Foo() {
+    return SmartPtr(new Foo_Impl());
+}
+
+// Do something with smart pointer Foo
+void do_something(Foo f) {
+    printf("x = %d\n", f->x);
+    f->bar();
+}
+
      +
      +

      A key feature of this approach is that by defining operator-> + the methods and attributes of the object wrapped by a smart pointer are + transparently accessible. For example, expressions such as these (from + the previous example),

      +
      +
      +f->x
+f->bar()
+
      +
      +

      are transparently mapped to the following

      +
      +
      +(f.operator->())->x;
+(f.operator->())->bar();
+
      +
      +

      When generating wrappers, SWIG tries to emulate this functionality + to the extent that it is possible. To do this, whenever +operator->() is encountered in a class, SWIG looks at its returned + type and uses it to generate wrappers for accessing attributes of the + underlying object. For example, wrapping the above code produces + wrappers like this:

      +
      +
      +int Foo_x_get(Foo *f) {
+   return (*f)->x;
+}
+void Foo_x_set(Foo *f, int value) {
+   (*f)->x = value;
+}
+void Foo_bar(Foo *f) {
+   (*f)->bar();
+}
+
      +
      +

      These wrappers take a smart-pointer instance as an argument, but + dereference it in a way to gain access to the object returned by +operator->(). You should carefully compare these wrappers to those + in the first part of this chapter (they are slightly different).

      +

      The end result is that access looks very similar to C++. For + example, you could do this in Python:

      +
      +
      +>>> f = make_Foo()
+>>> print f.x
+0
+>>> f.bar()
+>>>
+
      +
      +

      When generating wrappers through a smart-pointer, SWIG tries to + generate wrappers for all methods and attributes that might be + accessible through operator->(). This includes any methods + that might be accessible through inheritance. However, there are a + number of restrictions:

      +
        +
      • Member variables and methods are wrapped through a smart pointer. + Enumerations, constructors, and destructors are not wrapped.
        • +
      • +

        If the smart-pointer class and the underlying object both define a + method or variable of the same name, then the smart-pointer version has + precedence. For example, if you have this code

        +
        +
        +class Foo {
+public:
+    int x;
+};
+
+class Bar {
+public:
+    int x;       
+    Foo *operator->();
+};
+
        +
        +

        then the wrapper for Bar::x accesses the x defined + in Bar, and not the x defined in Foo.

        +
        • +
      +

      If your intent is to only expose the smart-pointer class in the + interface, it is not necessary to wrap both the smart-pointer class and + the class for the underlying object. However, you must still tell SWIG + about both classes if you want the technique described in this section + to work. To only generate wrappers for the smart-pointer class, you can + use the %ignore directive. For example:

      +
      +
      +%ignore Foo;
+class Foo {       // Ignored
+};
+
+class Bar {
+public:
+   Foo *operator->();
+   ...
+};
+
      +
      +

      Alternatively, you can import the definition of Foo from a + separate file using %import.

      +

      Note: When a class defines operator->(), the + operator itself is wrapped as a method __deref__(). For + example:

      +
      +
      +f = Foo()               # Smart-pointer
+p = f.__deref__()       # Raw pointer from operator->
+
      +
      +

      Note: To disable the smart-pointer behavior, use %ignore + to ignore operator->(). For example:

      +
      +
      +%ignore Bar::operator->;
+
      +
      +

      Note: Smart pointer support was first added in SWIG-1.3.14.

      +

      6.25 Using declarations and inheritance

      +

      using declarations are sometimes used to adjust access to + members of base classes. For example:

      +
      +
      +class Foo {
+public:
+      int  blah(int x);
+};
+
+class Bar {
+public:
+      double blah(double x);
+};
+
+class FooBar : public Foo, public Bar {
+public:
+      using Foo::blah;  
+      using Bar::blah;
+      char *blah(const char *x);
+};
+
      +
      +

      In this example, the using declarations make different + versions of the overloaded blah() method accessible from the + derived class. For example:

      +
      +
      +FooBar *f;
+f->blah(3);         // Ok. Invokes Foo::blah(int)
+f->blah(3.5);       // Ok. Invokes Bar::blah(double)
+f->blah("hello");   // Ok. Invokes FooBar::blah(const char *);
+
      +
      +

      SWIG emulates the same functionality when creating wrappers. For + example, if you wrap this code in Python, the module works just like + you would expect:

      +
      +
      +>>> import example
+>>> f = example.FooBar()
+>>> f.blah(3)
+>>> f.blah(3.5)
+>>> f.blah("hello")
+
      +
      +

      using declarations can also be used to change access when + applicable. For example:

      +
      +
      +class Foo {
+protected:
+    int x;
+    int blah(int x);
+};
+
+class Bar : public Foo {
+public:
+    using Foo::x;       // Make x public
+    using Foo::blah;    // Make blah public
+};
+
      +
      +

      This also works in SWIG---the exposed declarations will be wrapped + normally.

      +

      When using declarations are used as shown in these + examples, declarations from the base classes are copied into the + derived class and wrapped normally. When copied, the declarations + retain any properties that might have been attached using %rename +, %ignore, or %feature. Thus, if a method is ignored + in a base class, it will also be ignored by a using + declaration.

      +

      Because a using declaration does not provide fine-grained + control over the declarations that get imported, it may be difficult to + manage such declarations in applications that make heavy use of SWIG + customization features. If you can't get using to work + correctly, you can always change the interface to the following:

      +
      +
      +
+class FooBar : public Foo, public Bar {
+public:
+#ifndef SWIG
+      using Foo::blah;  
+      using Bar::blah;
+#else
+      int blah(int x);         // explicitly tell SWIG about other declarations
+      double blah(double x);
+#endif
+
+      char *blah(const char *x);
+};
+
      +
      +

      Notes:

      +
        +
      • +

        If a derived class redefines a method defined in a base class, then a + using declaration won't cause a conflict. For example:

        +
        +
        +class Foo {
+public:
+       int blah(int );
+       double blah(double);
+};
+
+class Bar : public Foo {
+public:
+       using Foo::blah;    // Only imports blah(double);
+       int blah(int);
+};
+
        +
        • +
      • +

        Resolving ambiguity in overloading may prevent declarations from + being imported by using. For example:

        +
        +
        +%rename(blah_long) Foo::blah(long);
+class Foo {
+public:
+     int blah(int);
+     long blah(long);  // Renamed to blah_long
+};
+
+class Bar : public Foo {
+public:
+     using Foo::blah;     // Only imports blah(int)
+     double blah(double x);
+};
+
        +
        • +
      +

      6.26 Nested classes

      +

      There is limited support for nested structs and unions when wrapping + C code, see Nested structures for + further details. However, there is no nested class/struct/union support + when wrapping C++ code (using the -c++ commandline option). This may be + added at a future date, however, until then some of the following + workarounds can be applied.

      +

      It might be possible to use partial class information. Since SWIG + does not need the entire class specification to work, conditional + compilation can be used to comment out the problematic nested class + definition, you might do this:

      +
      +
      +class Foo {
+public:
+#ifndef SWIG
+   class Bar {
+   public:
+     ...
+   };
+#endif
+   Foo();
+  ~Foo();
+   ...
+};
+
      +
      +

      The next workaround assumes you cannot modify the source code as was + done above and it provides a solution for methods that use nested class + types. Imagine we are wrapping the Outer class which contains + a nested class Inner:

      +
      +
      +// File outer.h
+class Outer {
+public:
+  class Inner {
+    public:
+      int var;
+      Inner(int v = 0) : var(v) {}
+  };
+  void method(Inner inner);
+};
+
      +
      +

      The following interface file works around SWIG nested class + limitations by redefining the nested class as a global class. A typedef + for the compiler is also required in order for the generated wrappers + to compile.

      +
      +
      +// File : example.i
+%module example
+
+// Suppress SWIG warning
+#pragma SWIG nowarn=SWIGWARN_PARSE_NESTED_CLASS
+
+// Redefine nested class in global scope in order for SWIG to generate
+// a proxy class. Only SWIG parses this definition.
+class Inner {
+  public:
+    int var;
+    Inner(int v = 0) : var(v) {}
+};
+
+%{
+#include "outer.h"
+%}
+%include "outer.h"
+
+%{
+// SWIG thinks that Inner is a global class, so we need to trick the C++
+// compiler into understanding this so called global type.
+typedef Outer::Inner Inner;
+%}
+
+
      +
      +

      The downside to this approach is having to maintain two definitions + of Inner, the real one and the one in the interface file that + SWIG parses.

      +

      6.27 A brief rant about + const-correctness

      +

      A common issue when working with C++ programs is dealing with all + possible ways in which the const qualifier (or lack thereof) + will break your program, all programs linked against your program, and + all programs linked against those programs.

      +

      Although SWIG knows how to correctly deal with const in its + internal type system and it knows how to generate wrappers that are + free of const-related warnings, SWIG does not make any attempt to + preserve const-correctness in the target language. Thus, it is possible + to pass const qualified objects to non-const methods and + functions. For example, consider the following code in C++:

      +
      +
      +const Object * foo();
+void bar(Object *);
+
+...
+// C++ code
+void blah() {
+   bar(foo());         // Error: bar discards const
+};
+
      +
      +

      Now, consider the behavior when wrapped into a Python module:

      +
      +
      +>>> bar(foo())         # Okay
+>>> 
+
      +
      +

      Although this is clearly a violation of the C++ type-system, fixing + the problem doesn't seem to be worth the added implementation + complexity that would be required to support it in the SWIG run-time + type system. There are no plans to change this in future releases + (although we'll never rule anything out entirely).

      +

      The bottom line is that this particular issue does not appear to be + a problem for most SWIG projects. Of course, you might want to consider + using another tool if maintaining constness is the most important part + of your project.

      +

      6.28 Where to go for more information

      +

      If you're wrapping serious C++ code, you might want to pick up a + copy of "The Annotated C++ Reference Manual" by Ellis and Stroustrup. + This is the reference document we use to guide a lot of SWIG's C++ + support.

      + + + + + + +
      +

      7 Preprocessing

      + + +
      + +
      + +

      SWIG includes its own enhanced version of the C preprocessor. The + preprocessor supports the standard preprocessor directives and macro + expansion rules. However, a number of modifications and enhancements + have been made. This chapter describes some of these modifications.

      +

      7.1 File inclusion

      +

      To include another file into a SWIG interface, use the %include + directive like this:

      +
      +
      +%include "pointer.i"
+
      +
      +

      Unlike, #include, %include includes each file once + (and will not reload the file on subsequent %include + declarations). Therefore, it is not necessary to use include-guards in + SWIG interfaces.

      +

      By default, the #include is ignored unless you run SWIG + with the -includeall option. The reason for ignoring + traditional includes is that you often don't want SWIG to try and wrap + everything included in standard header system headers and auxiliary + files.

      +

      7.2 File imports

      +

      SWIG provides another file inclusion directive with the %import + directive. For example:

      +
      +
      +%import "foo.i"
+
      +
      +

      The purpose of %import is to collect certain information + from another SWIG interface file or a header file without actually + generating any wrapper code. Such information generally includes type + declarations (e.g., typedef) as well as C++ classes that might + be used as base-classes for class declarations in the interface. The + use of %import is also important when SWIG is used to generate + extensions as a collection of related modules. This is an advanced + topic and is described in later in the Working + with Modules chapter.

      +

      The -importall directive tells SWIG to follow all +#include statements as imports. This might be useful if you want to + extract type definitions from system header files without generating + any wrappers.

      +

      7.3 Conditional + Compilation

      +

      SWIG fully supports the use of #if, #ifdef, +#ifndef, #else, #endif to conditionally include + parts of an interface. The following symbols are predefined by SWIG + when it is parsing the interface:

      +
      +
      +SWIG                            Always defined when SWIG is processing a file
+SWIGIMPORTED                    Defined when SWIG is importing a file with %import
+SWIGMAC                         Defined when running SWIG on the Macintosh
+SWIGWIN                         Defined when running SWIG under Windows
+SWIG_VERSION                    Hexadecimal number containing SWIG version,
+                                such as 0x010311 (corresponding to SWIG-1.3.11).
+
+SWIGALLEGROCL                   Defined when using Allegro CL
+SWIGCFFI                        Defined when using CFFI
+SWIGCHICKEN                     Defined when using CHICKEN
+SWIGCLISP                       Defined when using CLISP
+SWIGCSHARP                      Defined when using C#
+SWIGGUILE                       Defined when using Guile
+SWIGJAVA                        Defined when using Java
+SWIGLUA                         Defined when using Lua
+SWIGMODULA3                     Defined when using Modula-3
+SWIGMZSCHEME                    Defined when using Mzscheme        
+SWIGOCAML                       Defined when using Ocaml
+SWIGOCTAVE                      Defined when using Octave
+SWIGPERL                        Defined when using Perl
+SWIGPHP                         Defined when using PHP
+SWIGPIKE                        Defined when using Pike
+SWIGPYTHON                      Defined when using Python
+SWIGR                           Defined when using R
+SWIGRUBY                        Defined when using Ruby
+SWIGSEXP                        Defined when using S-expressions
+SWIGTCL                         Defined when using Tcl
+SWIGXML                         Defined when using XML
+
      +
      +

      In addition, SWIG defines the following set of standard C/C++ + macros:

      +
      +
      +__LINE__                        Current line number
+__FILE__                        Current file name
+__STDC__                        Defined to indicate ANSI C
+__cplusplus                     Defined when -c++ option used
+
      +
      +

      Interface files can look at these symbols as necessary to change the + way in which an interface is generated or to mix SWIG directives with C + code. These symbols are also defined within the C code generated by + SWIG (except for the symbol `SWIG' which is only defined + within the SWIG compiler).

      +

      7.4 Macro Expansion

      +

      Traditional preprocessor macros can be used in SWIG interfaces. Be + aware that the #define statement is also used to try and + detect constants. Therefore, if you have something like this in your + file,

      +
      +
      +#ifndef _FOO_H 1
+#define _FOO_H 1
+...
+#endif
+
      +
      +

      you may get some extra constants such as _FOO_H showing up + in the scripting interface.

      +

      More complex macros can be defined in the standard way. For example:

      +
      +
      +#define EXTERN extern
+#ifdef __STDC__
+#define _ANSI(args)   (args)
+#else
+#define _ANSI(args) ()
+#endif
+
      +
      +

      The following operators can appear in macro definitions:

      +
        +
      • #x +
        Converts macro argument x to a string surrounded by double + quotes ("x").
        • +
      • x ## y +
        Concatenates x and y together to form xy.
        • +
      • `x` +
        If x is a string surrounded by double quotes, do nothing. + Otherwise, turn into a string like #x. This is a non-standard + SWIG extension.
        • +
      +

      7.5 SWIG Macros

      +

      SWIG provides an enhanced macro capability with the %define + and %enddef directives. For example:

      +
      +
      +%define ARRAYHELPER(type,name)
+%inline %{
+type *new_ ## name (int nitems) {
+   return (type *) malloc(sizeof(type)*nitems);
+}
+void delete_ ## name(type *t) {
+   free(t);
+}
+type name ## _get(type *t, int index) {
+   return t[index];
+}
+void name ## _set(type *t, int index, type val) {
+   t[index] = val;
+}
+%}
+%enddef
+
+ARRAYHELPER(int, IntArray)
+ARRAYHELPER(double, DoubleArray)
+
      +
      +

      The primary purpose of %define is to define large macros of + code. Unlike normal C preprocessor macros, it is not necessary to + terminate each line with a continuation character (\)--the macro + definition extends to the first occurrence of %enddef. + Furthermore, when such macros are expanded, they are reparsed through + the C preprocessor. Thus, SWIG macros can contain all other + preprocessor directives except for nested %define statements.

      +

      The SWIG macro capability is a very quick and easy way to generate + large amounts of code. In fact, many of SWIG's advanced features and + libraries are built using this mechanism (such as C++ template + support).

      +

      7.6 C99 and GNU Extensions

      +

      SWIG-1.3.12 and newer releases support variadic preprocessor macros. + For example:

      +
      +
      +#define DEBUGF(fmt,...)   fprintf(stderr,fmt,__VA_ARGS__)
+
      +
      +

      When used, any extra arguments to ... are placed into the + special variable __VA_ARGS__. This also works with special + SWIG macros defined using %define.

      +

      SWIG allows a variable number of arguments to be empty. However, + this often results in an extra comma (,) and syntax error in the + resulting expansion. For example:

      +
      +
      +DEBUGF("hello");   --> fprintf(stderr,"hello",);
+
      +
      +

      To get rid of the extra comma, use ## like this:

      +
      +
      +#define DEBUGF(fmt,...)   fprintf(stderr,fmt, ##__VA_ARGS__)
+
      +
      +

      SWIG also supports GNU-style variadic macros. For example:

      +
      +
      +#define DEBUGF(fmt, args...)  fprintf(stdout,fmt,args)
+
      +
      +

      Comment: It's not entirely clear how variadic macros might be + useful to interface building. However, they are used internally to + implement a number of SWIG directives and are provided to make SWIG + more compatible with C99 code.

      +

      7.7 Preprocessing and %{ ... %} & " + ... " delimiters

      +

      The SWIG preprocessor does not process any text enclosed in a code + block %{ ... %}. Therefore, if you write code like this,

      +
      +
      +%{
+#ifdef NEED_BLAH
+int blah() {
+   ...
+}
+#endif
+%}
+
      +
      +

      the contents of the %{ ... %} block are copied without + modification to the output (including all preprocessor directives).

      +

      7.8 Preprocessing and { ... } + delimiters

      +

      SWIG always runs the preprocessor on text appearing inside { ... + }. However, sometimes it is desirable to make a preprocessor + directive pass through to the output file. For example:

      +
      +
      +%extend Foo {
+   void bar() {
+      #ifdef DEBUG
+       printf("I'm in bar\n");
+      #endif
+   }
+}
+
      +
      +

      By default, SWIG will interpret the #ifdef DEBUG statement. + However, if you really wanted that code to actually go into the wrapper + file, prefix the preprocessor directives with % like this:

      +
      +
      +%extend Foo {
+   void bar() {
+      %#ifdef DEBUG
+       printf("I'm in bar\n");
+      %#endif
+   }
+}
+
      +
      +

      SWIG will strip the extra % and leave the preprocessor + directive in the code.

      +

      7.9 Preprocessor and + Typemaps

      +

      Typemaps support a special attribute + called noblock where the { ... } delimiters can be used, but + the delimiters are not actually generated into the code. The effect is + then similar to using "" or %{ %} delimiters but the code is run + through the preprocessor. For example:

      +
      +
      +#define SWIG_macro(CAST) (CAST)$input
+%typemap(in) Int {$1= SWIG_macro(int);}
+
      +
      +

      might generate

      +
      +
      +  {
+    arg1=(int)jarg1;
+  }
+
      +
      +

      whereas

      +
      +
      +#define SWIG_macro(CAST) (CAST)$input
+%typemap(in,noblock=1) Int {$1= SWIG_macro(int);}
+
      +
      +

      might generate

      +
      +
      +  arg1=(int)jarg1;
+
      +
      +

      and

      +
      +
      +#define SWIG_macro(CAST) (CAST)$input
+%typemap(in) Int %{$1=SWIG_macro(int);%}
+
      +
      +

      would generate

      +
      +
      +  arg1=SWIG_macro(int);
+
      +
      +

      7.10 Viewing preprocessor output

      +

      Like many compilers, SWIG supports a -E command line option + to display the output from the preprocessor. When the -E + switch is used, SWIG will not generate any wrappers. Instead the + results after the preprocessor has run are displayed. This might be + useful as an aid to debugging and viewing the results of macro + expansions.

      +

      7.11 The #error and + #warning directives

      +

      SWIG supports the commonly used #warning and #error + preprocessor directives. The #warning directive will cause + SWIG to issue a warning then continue processing. The #error + directive will cause SWIG to exit with a fatal error. Example usage:

      +
      +
      +#error "This is a fatal error message"
+#warning "This is a warning message"
+
      +
      +

      The #error behaviour can be made to work like #warning + if the -cpperraswarn commandline option is used. + Alternatively, the #pragma directive can be used to the same + effect, for example:

      +
      +
      +  /* Modified behaviour: #error does not cause SWIG to exit with error */
+  #pragma SWIG cpperraswarn=1
+  /* Normal behaviour: #error does cause SWIG to exit with error */
+  #pragma SWIG cpperraswarn=0
+
      +
      +

      8 SWIG library

      + + +
      + +
      + +

      To help build extension modules, SWIG is packaged with a library of + support files that you can include in your own interfaces. These files + often define new SWIG directives or provide utility functions that can + be used to access parts of the standard C and C++ libraries. This + chapter provides a reference to the current set of supported library + files.

      +

      Compatibility note: Older versions of SWIG included a number + of library files for manipulating pointers, arrays, and other + structures. Most these files are now deprecated and have been removed + from the distribution. Alternative libraries provide similar + functionality. Please read this chapter carefully if you used the old + libraries.

      +

      8.1 The %include directive and library + search path

      +

      Library files are included using the %include directive. + When searching for files, directories are searched in the following + order:

      +
        +
      • The current directory
        • +
      • Directories specified with the -I command line option
        • +
      • ./swig_lib
        • +
      • SWIG library install location as reported by swig -swiglib, + for example /usr/local/share/swig/1.3.30
        • +
      • On Windows, a directory Lib relative to the location of +swig.exe is also searched.
        • +
      +

      Within each directory, SWIG first looks for a subdirectory + corresponding to a target language (e.g., python, tcl +, etc.). If found, SWIG will search the language specific directory + first. This allows for language-specific implementations of library + files.

      +

      You can ignore the installed SWIG library by setting the +SWIG_LIB environment variable. Set the environment variable to hold + an alternative library directory.

      +

      The directories that are searched are displayed when using +-verbose commandline option.

      +

      8.2 C Arrays and Pointers

      +

      This section describes library modules for manipulating low-level C + arrays and pointers. The primary use of these modules is in supporting + C declarations that manipulate bare pointers such as int *, +double *, or void *. The modules can be used to allocate + memory, manufacture pointers, dereference memory, and wrap pointers as + class-like objects. Since these functions provide direct access to + memory, their use is potentially unsafe and you should exercise + caution.

      +

      8.2.1 cpointer.i

      +

      The cpointer.i module defines macros that can be used to + used to generate wrappers around simple C pointers. The primary use of + this module is in generating pointers to primitive datatypes such as +int and double.

      +

      %pointer_functions(type,name)

      +
      +

      Generates a collection of four functions for manipulating a pointer +type *:

      +

      type *new_name()

      +
      +

      Creates a new object of type type and returns a pointer to + it. In C, the object is created using calloc(). In C++, +new is used.

      +
      +

      type *copy_name(type value)

      +
      +

      Creates a new object of type type and returns a pointer to + it. An initial value is set by copying it from value. In C, + the object is created using calloc(). In C++, new is + used.

      +
      +

      type *delete_name(type *obj)

      +
      +

      Deletes an object type type.

      +
      +

      void name_assign(type *obj, type value)

      +
      +

      Assigns *obj = value.

      +
      +

      type name_value(type *obj)

      +
      +

      Returns the value of *obj.

      +
      +

      When using this macro, type may be any type and name + must be a legal identifier in the target language. name should + not correspond to any other name used in the interface file.

      +

      Here is a simple example of using %pointer_functions():

      +
      +
      +%module example
+%include "cpointer.i"
+
+/* Create some functions for working with "int *" */
+%pointer_functions(int, intp);
+
+/* A function that uses an "int *" */
+void add(int x, int y, int *result);
+
      +
      +

      Now, in Python:

      +
      +
      +>>> import example
+>>> c = example.new_intp()     # Create an "int" for storing result
+>>> example.add(3,4,c)         # Call function
+>>> example.intp_value(c)      # Dereference
+7
+>>> example.delete_intp(c)     # Delete
+
      +
      +

      %pointer_class(type,name)

      +
      +

      Wraps a pointer of type * inside a class-based interface. + This interface is as follows:

      +
      +
      +struct name {
+   name();                            // Create pointer object
+  ~name();                            // Delete pointer object
+   void assign(type value);           // Assign value
+   type value();                      // Get value
+   type *cast();                      // Cast the pointer to original type
+   static name *frompointer(type *);  // Create class wrapper from existing
+                                      // pointer
+};
+
      +
      +

      When using this macro, type is restricted to a simple type + name like int, float, or Foo. Pointers and + other complicated types are not allowed. name must be a valid + identifier not already in use. When a pointer is wrapped as a class, + the "class" may be transparently passed to any function that expects + the pointer.

      +

      If the target language does not support proxy classes, the use of + this macro will produce the example same functions as +%pointer_functions() macro.

      +

      It should be noted that the class interface does introduce a new + object or wrap a pointer inside a special structure. Instead, the raw + pointer is used directly.

      +

      Here is the same example using a class instead:

      +
      +
      +%module example
+%include "cpointer.i"
+
+/* Wrap a class interface around an "int *" */
+%pointer_class(int, intp);
+
+/* A function that uses an "int *" */
+void add(int x, int y, int *result);
+
      +
      +

      Now, in Python (using proxy classes)

      +
      +
      +>>> import example
+>>> c = example.intp()         # Create an "int" for storing result
+>>> example.add(3,4,c)         # Call function
+>>> c.value()                  # Dereference
+7
+
      +
      +

      Of the two macros, %pointer_class is probably the most + convenient when working with simple pointers. This is because the + pointers are access like objects and they can be easily garbage + collected (destruction of the pointer object destroys the underlying + object).

      +
      +

      %pointer_cast(type1, type2, name)

      +
      +

      Creates a casting function that converts type1 to type2 +. The name of the function is name. For example:

      +
      +
      +%pointer_cast(int *, unsigned int *, int_to_uint);
+
      +
      +

      In this example, the function int_to_uint() would be used + to cast types in the target language.

      +
      +

      Note: None of these macros can be used to safely work with + strings (char * or char **).

      +

      Note: When working with simple pointers, typemaps can often + be used to provide more seamless operation.

      +

      8.2.2 carrays.i

      +

      This module defines macros that assist in wrapping ordinary C + pointers as arrays. The module does not provide any safety or an extra + layer of wrapping--it merely provides functionality for creating, + destroying, and modifying the contents of raw C array data.

      +

      %array_functions(type,name)

      +
      +

      Creates four functions.

      +

      type *new_name(int nelements)

      +
      +

      Creates a new array of objects of type type. In C, the + array is allocated using calloc(). In C++, new [] is + used.

      +
      +

      type *delete_name(type *ary)

      +
      +

      Deletes an array. In C, free() is used. In C++, delete + [] is used.

      +
      +

      type name_getitem(type *ary, int index)

      +
      +

      Returns the value ary[index].

      +
      +

      void name_setitem(type *ary, int index, type value)

      +
      +

      Assigns ary[index] = value.

      +
      +

      When using this macro, type may be any type and name + must be a legal identifier in the target language. name should + not correspond to any other name used in the interface file.

      +

      Here is an example of %array_functions(). Suppose you had a + function like this:

      +
      +
      +void print_array(double x[10]) {
+   int i;
+   for (i = 0; i < 10; i++) {
+      printf("[%d] = %g\n", i, x[i]);
+   }
+}
+
      +
      +

      To wrap it, you might write this:

      +
      +
      +%module example
+
+%include "carrays.i"
+%array_functions(double, doubleArray);
+
+void print_array(double x[10]);
+
      +
      +

      Now, in a scripting language, you might write this:

      +
      +
      +a = new_doubleArray(10)           # Create an array
+for i in range(0,10):
+    doubleArray_setitem(a,i,2*i)  # Set a value
+print_array(a)                    # Pass to C
+delete_doubleArray(a)             # Destroy array
+
      +
      +

      %array_class(type,name)

      +
      +

      Wraps a pointer of type * inside a class-based interface. + This interface is as follows:

      +
      +
      +struct name {
+   name(int nelements);                  // Create an array
+  ~name();                               // Delete array
+   type getitem(int index);              // Return item
+   void setitem(int index, type value);  // Set item
+   type *cast();                         // Cast to original type
+   static name *frompointer(type *);     // Create class wrapper from
+                                         // existing pointer
+};
+
      +
      +

      When using this macro, type is restricted to a simple type + name like int or float. Pointers and other + complicated types are not allowed. name must be a valid + identifier not already in use. When a pointer is wrapped as a class, it + can be transparently passed to any function that expects the pointer.

      +

      When combined with proxy classes, the %array_class() macro + can be especially useful. For example:

      +
      +
      +%module example
+%include "carrays.i"
+%array_class(double, doubleArray);
+
+void print_array(double x[10]);
+
      +
      +

      Allows you to do this:

      +
      +
      +import example
+c = example.doubleArray(10)  # Create double[10]
+for i in range(0,10):
+    c[i] = 2*i               # Assign values
+example.print_array(c)       # Pass to C
+
      +
      +

      Note: These macros do not encapsulate C arrays inside a + special data structure or proxy. There is no bounds checking or safety + of any kind. If you want this, you should consider using a special + array object rather than a bare pointer.

      +

      Note: %array_functions() and %array_class() + should not be used with types of char or char *.

      +

      8.2.3 cmalloc.i

      +

      This module defines macros for wrapping the low-level C memory + allocation functions malloc(), calloc(), +realloc(), and free().

      +

      %malloc(type [,name=type])

      +
      +

      Creates a wrapper around malloc() with the following + prototype:

      +
      +
      +type *malloc_name(int nbytes = sizeof(type));
+
      +
      +

      If type is void, then the size parameter +nbytes is required. The name parameter only needs to be + specified when wrapping a type that is not a valid identifier (e.g., " +int *", "double **", etc.).

      +
      +

      %calloc(type [,name=type])

      +
      +

      Creates a wrapper around calloc() with the following + prototype:

      +
      +
      +type *calloc_name(int nobj =1, int sz = sizeof(type));
+
      +
      +

      If type is void, then the size parameter sz + is required.

      +
      +

      %realloc(type [,name=type])

      +
      +

      Creates a wrapper around realloc() with the following + prototype:

      +
      +
      +type *realloc_name(type *ptr, int nitems);
+
      +
      +

      Note: unlike the C realloc(), the wrapper generated by this + macro implicitly includes the size of the corresponding type. For + example, realloc_int(p, 100) reallocates p so that it + holds 100 integers.

      +
      +

      %free(type [,name=type])

      +
      +

      Creates a wrapper around free() with the following + prototype:

      +
      +
      +void free_name(type *ptr);
+
      +
      +

      %sizeof(type [,name=type])

      +
      +

      Creates the constant:

      +
      +
      +%constant int sizeof_name = sizeof(type);
+
      +
      +

      %allocators(type [,name=type])

      +
      +

      Generates wrappers for all five of the above operations.

      +
      +

      Here is a simple example that illustrates the use of these macros:

      +
      +
      +// SWIG interface
+%module example
+%include "cmalloc.i"
+
+%malloc(int);
+%free(int);
+
+%malloc(int *, intp);
+%free(int *, intp);
+
+%allocators(double);
+
      +
      +

      Now, in a script:

      +
      +
      +>>> from example import *
+>>> a = malloc_int()
+>>> a
+'_000efa70_p_int'
+>>> free_int(a)
+>>> b = malloc_intp()
+>>> b
+'_000efb20_p_p_int'
+>>> free_intp(b)
+>>> c = calloc_double(50)
+>>> c
+'_000fab98_p_double'
+>>> c = realloc_double(100000)
+>>> free_double(c)
+>>> print sizeof_double
+8
+>>>
+
      +
      +

      8.2.4 cdata.i

      +

      The cdata.i module defines functions for converting raw C + data to and from strings in the target language. The primary + applications of this module would be packing/unpacking of binary data + structures---for instance, if you needed to extract data from a buffer. + The target language must support strings with embedded binary data in + order for this to work.

      +

      char *cdata(void *ptr, int nbytes)

      +
      +

      Converts nbytes of data at ptr into a string. +ptr can be any pointer.

      +
      +

      void memmove(void *ptr, char *s)

      +
      +

      Copies all of the string data in s into the memory pointed + to by ptr. The string may contain embedded NULL bytes. The + length of the string is implicitly determined in the underlying wrapper + code.

      +
      +

      One use of these functions is packing and unpacking data from + memory. Here is a short example:

      +
      +
      +// SWIG interface
+%module example
+%include "carrays.i"
+%include "cdata.i"
+
+%array_class(int, intArray);
+
      +
      +

      Python example:

      +
      +
      +>>> a = intArray(10)
+>>> for i in range(0,10):
+...    a[i] = i
+>>> b = cdata(a,40)
+>>> b
+'\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x02\x00\x00\x00\x03\x00\x00\x00\x04
+\x00\x00\x00\x05\x00\x00\x00\x06\x00\x00\x00\x07\x00\x00\x00\x08\x00\x00\x00\t'
+>>> c = intArray(10)
+>>> memmove(c,b)
+>>> print c[4]
+4
+>>>
+
      +
      +

      Since the size of data is not always known, the following macro is + also defined:

      +

      %cdata(type [,name=type])

      +
      +

      Generates the following function for extracting C data for a given + type.

      +
      +
      +char *cdata_name(type* ptr, int nitems)
+
      +
      +

      nitems is the number of items of the given type to extract.

      +
      +

      Note: These functions provide direct access to memory and can + be used to overwrite data. Clearly they are unsafe.

      +

      8.3 C String Handling

      +

      A common problem when working with C programs is dealing with + functions that manipulate raw character data using char *. In + part, problems arise because there are different interpretations of +char *---it could be a NULL-terminated string or it could point to + binary data. Moreover, functions that manipulate raw strings may mutate + data, perform implicit memory allocations, or utilize fixed-sized + buffers.

      +

      The problems (and perils) of using char * are well-known. + However, SWIG is not in the business of enforcing morality. The modules + in this section provide basic functionality for manipulating raw C + strings.

      +

      8.3.1 Default string handling

      +

      Suppose you have a C function with this prototype:

      +
      +
      +char *foo(char *s);
+
      +
      +

      The default wrapping behavior for this function is to set s + to a raw char * that refers to the internal string data in the + target language. In other words, if you were using a language like Tcl, + and you wrote this,

      +
      +
      +% foo Hello
+
      +
      +

      then s would point to the representation of "Hello" inside + the Tcl interpreter. When returning a char *, SWIG assumes + that it is a NULL-terminated string and makes a copy of it. This gives + the target language its own copy of the result.

      +

      There are obvious problems with the default behavior. First, since a + char * argument points to data inside the target language, it + is NOT safe for a function to modify this data (doing so may + corrupt the interpreter and lead to a crash). Furthermore, the default + behavior does not work well with binary data. Instead, strings are + assumed to be NULL-terminated.

      +

      8.3.2 Passing binary data

      +

      If you have a function that expects binary data,

      +
      +
      +int parity(char *str, int len, int initial);
+
      +
      +

      you can wrap the parameters (char *str, int len) as a + single argument using a typemap. Just do this:

      +
      +
      +%apply (char *STRING, int LENGTH) { (char *str, int len) };
+...
+int parity(char *str, int len, int initial);
+
      +
      +

      Now, in the target language, you can use binary string data like + this:

      +
      +
      +>>> s = "H\x00\x15eg\x09\x20"
+>>> parity(s,0)
+
      +
      +

      In the wrapper function, the passed string will be expanded to a + pointer and length parameter.

      +

      8.3.3 Using %newobject to release memory

      +

      If you have a function that allocates memory like this,

      +
      +
      +char *foo() {
+   char *result = (char *) malloc(...);
+   ...
+   return result;
+}
+
      +
      +

      then the SWIG generated wrappers will have a memory leak--the + returned data will be copied into a string object and the old contents + ignored.

      +

      To fix the memory leak, use the %newobject directive.

      +
      +
      +%newobject foo;
+...
+char *foo();
+
      +
      +

      This will release the result.

      +

      8.3.4 cstring.i

      +

      The cstring.i library file provides a collection of macros + for dealing with functions that either mutate string arguments or which + try to output string data through their arguments. An example of such a + function might be this rather questionable implementation:

      +
      +
      +void get_path(char *s) {
+    // Potential buffer overflow---uh, oh.
+    sprintf(s,"%s/%s", base_directory, sub_directory);
+}
+...
+// Somewhere else in the C program
+{
+    char path[1024];
+    ...
+    get_path(path);
+    ...
+}
+
      +
      +

      (Off topic rant: If your program really has functions like this, you + would be well-advised to replace them with safer alternatives involving + bounds checking).

      +

      The macros defined in this module all expand to various combinations + of typemaps. Therefore, the same pattern matching rules and ideas + apply.

      +

      %cstring_bounded_output(parm, maxsize)

      +
      +

      Turns parameter parm into an output value. The + output string is assumed to be NULL-terminated and smaller than +maxsize characters. Here is an example:

      +
      +
      +%cstring_bounded_output(char *path, 1024);
+...
+void get_path(char *path);
+
      +
      +

      In the target language:

      +
      +
      +>>> get_path()
+/home/beazley/packages/Foo/Bar
+>>>
+
      +
      +

      Internally, the wrapper function allocates a small buffer (on the + stack) of the requested size and passes it as the pointer value. Data + stored in the buffer is then returned as a function return value. If + the function already returns a value, then the return value and the + output string are returned together (multiple return values). If + more than maxsize bytes are written, your program + will crash with a buffer overflow!

      +
      +

      %cstring_chunk_output(parm, chunksize)

      +
      +

      Turns parameter parm into an output value. The + output string is always chunksize and may contain + binary data. Here is an example:

      +
      +
      +%cstring_chunk_output(char *packet, PACKETSIZE);
+...
+void get_packet(char *packet);
+
      +
      +

      In the target language:

      +
      +
      +>>> get_packet()
+'\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f\xd3\x99\x14V\xec\x06\xea\xa2\x88'
+>>>
+
      +
      +

      This macro is essentially identical to %cstring_bounded_output +. The only difference is that the result is always chunksize + characters. Furthermore, the result can contain binary data. If + more than maxsize bytes are written, your program + will crash with a buffer overflow!

      +
      +

      %cstring_bounded_mutable(parm, maxsize)

      +
      +

      Turns parameter parm into a mutable string + argument. The input string is assumed to be NULL-terminated and smaller + than maxsize characters. The output string is also + assumed to be NULL-terminated and less than maxsize + characters.

      +
      +
      +%cstring_bounded_mutable(char *ustr, 1024);
+...
+void make_upper(char *ustr);
+
      +
      +

      In the target language:

      +
      +
      +>>> make_upper("hello world")
+'HELLO WORLD'
+>>>
+
      +
      +

      Internally, this macro is almost exactly the same as +%cstring_bounded_output. The only difference is that the parameter + accepts an input value that is used to initialize the internal buffer. + It is important to emphasize that this function does not mutate the + string value passed---instead it makes a copy of the input value, + mutates it, and returns it as a result. If more than maxsize + bytes are written, your program will crash with a buffer overflow! +

      +
      +

      %cstring_mutable(parm [, expansion])

      +
      +

      Turns parameter parm into a mutable string + argument. The input string is assumed to be NULL-terminated. An + optional parameter expansion specifies the number of + extra characters by which the string might grow when it is modified. + The output string is assumed to be NULL-terminated and less than the + size of the input string plus any expansion characters.

      +
      +
      +%cstring_mutable(char *ustr);
+...
+void make_upper(char *ustr);
+
+%cstring_mutable(char *hstr, HEADER_SIZE);
+...
+void attach_header(char *hstr);
+
      +
      +

      In the target language:

      +
      +
      +>>> make_upper("hello world")
+'HELLO WORLD'
+>>> attach_header("Hello world")
+'header: Hello world'
+>>>
+
      +
      +

      This macro differs from %cstring_bounded_mutable() in that + a buffer is dynamically allocated (on the heap using malloc/new +). This buffer is always large enough to store a copy of the input value + plus any expansion bytes that might have been requested. It is + important to emphasize that this function does not directly mutate the + string value passed---instead it makes a copy of the input value, + mutates it, and returns it as a result. If the function expands the + result by more than expansion extra bytes, then the + program will crash with a buffer overflow!

      +
      +

      %cstring_output_maxsize(parm, maxparm)

      +
      +

      This macro is used to handle bounded character output functions + where both a char * and a maximum length parameter are + provided. As input, a user simply supplies the maximum length. The + return value is assumed to be a NULL-terminated string.

      +
      +
      +%cstring_output_maxsize(char *path, int maxpath);
+...
+void get_path(char *path, int maxpath);
+
      +
      +

      In the target language:

      +
      +
      +>>> get_path(1024)
+'/home/beazley/Packages/Foo/Bar'
+>>>
+
      +
      +

      This macro provides a safer alternative for functions that need to + write string data into a buffer. User supplied buffer size is used to + dynamically allocate memory on heap. Results are placed into that + buffer and returned as a string object.

      +
      +

      %cstring_output_withsize(parm, maxparm)

      +
      +

      This macro is used to handle bounded character output functions + where both a char * and a pointer int * are passed. + Initially, the int * parameter points to a value containing + the maximum size. On return, this value is assumed to contain the + actual number of bytes. As input, a user simply supplies the maximum + length. The output value is a string that may contain binary data.

      +
      +
      +%cstring_output_withsize(char *data, int *maxdata);
+...
+void get_data(char *data, int *maxdata);
+
      +
      +

      In the target language:

      +
      +
      +>>> get_data(1024)
+'x627388912'
+>>> get_data(1024)
+'xyzzy'
+>>>
+
      +
      +

      This macro is a somewhat more powerful version of +%cstring_output_chunk(). Memory is dynamically allocated and can be + arbitrary large. Furthermore, a function can control how much data is + actually returned by changing the value of the maxparm + argument.

      +
      +

      %cstring_output_allocate(parm, release)

      +
      +

      This macro is used to return strings that are allocated within the + program and returned in a parameter of type char **. For + example:

      +
      +
      +void foo(char **s) {
+    *s = (char *) malloc(64);
+    sprintf(*s, "Hello world\n");
+}
+
      +
      +

      The returned string is assumed to be NULL-terminated. +release specifies how the allocated memory is to be released + (if applicable). Here is an example:

      +
      +
      +%cstring_output_allocate(char **s, free(*$1));
+...
+void foo(char **s);
+
      +
      +

      In the target language:

      +
      +
      +>>> foo()
+'Hello world\n'
+>>>
+
      +
      +

      %cstring_output_allocate_size(parm, szparm, release)

      +
      +

      This macro is used to return strings that are allocated within the + program and returned in two parameters of type char ** and +int *. For example:

      +
      +
      +void foo(char **s, int *sz) {
+    *s = (char *) malloc(64);
+    *sz = 64;
+    // Write some binary data
+    ...
+}
+
      +
      +

      The returned string may contain binary data. release + specifies how the allocated memory is to be released (if applicable). + Here is an example:

      +
      +
      +%cstring_output_allocate_size(char **s, int *slen, free(*$1));
+...
+void foo(char **s, int *slen);
+
      +
      +

      In the target language:

      +
      +
      +>>> foo()
+'\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f\xd3\x99\x14V\xec\x06\xea\xa2\x88'
+>>>
+
      +
      +

      This is the safest and most reliable way to return binary string + data in SWIG. If you have functions that conform to another prototype, + you might consider wrapping them with a helper function. For example, + if you had this:

      +
      +
      +char  *get_data(int *len);
+
      +
      +

      You could wrap it with a function like this:

      +
      +
      +void my_get_data(char **result, int *len) {
+   *result = get_data(len);
+}
+
      +
      +

      Comments:

      +
        +
      • Support for the cstring.i module depends on the target + language. Not all SWIG modules currently support this library.
        • +
      • Reliable handling of raw C strings is a delicate topic. There are + many ways to accomplish this in SWIG. This library provides support for + a few common techniques.
        • +
      • If used in C++, this library uses new and delete [] + for memory allocation. If using ANSI C, the library uses malloc() + and free().
        • +
      • Rather than manipulating char * directly, you might + consider using a special string structure or class instead.
        • +
      +

      8.4 STL/C++ Library

      +

      The library modules in this section provide access to parts of the + standard C++ library including the STL. SWIG support for the STL is an + ongoing effort. Support is quite comprehensive for some language + modules but some of the lesser used modules do not have quite as much + library code written.

      +

      The following table shows which C++ classes are supported and the + equivalent SWIG interface library file for the C++ library.

      + + + + + + + + + +
      C++ classC++ Library file +SWIG Interface library file
      std::dequedequestd_deque.i
      std::listliststd_list.i
      std::mapmapstd_map.i
      std::pairutilitystd_pair.i
      std::setsetstd_set.i
      std::stringstringstd_string.i
      std::vectorvectorstd_vector.i
      +

      The list is by no means complete; some language modules support a + subset of the above and some support additional STL classes. Please + look for the library files in the appropriate language library + directory.

      +

      8.4.1 std_string.i

      +

      The std_string.i library provides typemaps for converting + C++ std::string objects to and from strings in the target + scripting language. For example:

      +
      +
      +%module example
+%include "std_string.i"
+
+std::string foo();
+void        bar(const std::string &x);
+
      +
      +

      In the target language:

      +
      +
      +x = foo();                # Returns a string object
+bar("Hello World");       # Pass string as std::string
+
      +
      +

      A common problem that people encounter is that of classes/structures + containing a std::string. This can be overcome by defining a + typemap. For example:

      +
      +
      +%module example
+%include "std_string.i"
+
+%apply const std::string& {std::string* foo};
+
+struct my_struct
+{
+  std::string foo;
+};
+
      +
      +

      In the target language:

      +
      +
      +x = my_struct();
+x.foo="Hello World";      # assign with string
+print x.foo;              # print as string
+
      +
      +

      This module only supports types std::string and const + std::string &. Pointers and non-const references are left + unmodified and returned as SWIG pointers.

      +

      This library file is fully aware of C++ namespaces. If you export +std::string or rename it with a typedef, make sure you include + those declarations in your interface. For example:

      +
      +
      +%module example
+%include "std_string.i"
+
+using namespace std;
+typedef std::string String;
+...
+void foo(string s, const String &t);     // std_string typemaps still applied
+
      +
      +

      Note: The std_string library is incompatible with + Perl on some platforms. We're looking into it.

      +

      8.4.2 std_vector.i

      +

      The std_vector.i library provides support for the C++ +vector class in the STL. Using this library involves the use of the + %template directive. All you need to do is to instantiate + different versions of vector for the types that you want to + use. For example:

      +
      +
      +%module example
+%include "std_vector.i"
+
+namespace std {
+   %template(vectori) vector<int>;
+   %template(vectord) vector<double>;
+};
+
      +
      +

      When a template vector<X> is instantiated a number of + things happen:

      +
        +
      • A class that exposes the C++ API is created in the target language . + This can be used to create objects, invoke methods, etc. This class is + currently a subset of the real STL vector class.
        • +
      • Input typemaps are defined for vector<X>, const + vector<X> &, and const vector<X> *. For each of these, a + pointer vector<X> * may be passed or a native list object in + the target language.
        • +
      • An output typemap is defined for vector<X>. In this case, + the values in the vector are expanded into a list object in the target + language.
        • +
      • For all other variations of the type, the wrappers expect to receive + a vector<X> * object in the usual manner.
        • +
      • An exception handler for std::out_of_range is defined.
        • +
      • Optionally, special methods for indexing, item retrieval, slicing, + and element assignment may be defined. This depends on the target + language.
        • +
      +

      To illustrate the use of this library, consider the following + functions:

      +
      +
      +/* File : example.h */
+
+#include <vector>
+#include <algorithm>
+#include <functional>
+#include <numeric>
+
+double average(std::vector<int> v) {
+    return std::accumulate(v.begin(),v.end(),0.0)/v.size();
+}
+
+std::vector<double> half(const std::vector<double>& v) {
+    std::vector<double> w(v);
+    for (unsigned int i=0; i<w.size(); i++)
+        w[i] /= 2.0;
+    return w;
+}
+
+void halve_in_place(std::vector<double>& v) {
+    std::transform(v.begin(),v.end(),v.begin(),
+                   std::bind2nd(std::divides<double>(),2.0));
+}
+
      +
      +

      To wrap with SWIG, you might write the following:

      +
      +
      +%module example
+%{
+#include "example.h"
+%}
+
+%include "std_vector.i"
+// Instantiate templates used by example
+namespace std {
+   %template(IntVector) vector<int>;
+   %template(DoubleVector) vector<double>;
+}
+
+// Include the header file with above prototypes
+%include "example.h"
+
      +
      +

      Now, to illustrate the behavior in the scripting interpreter, + consider this Python example:

      +
      +
      +>>> from example import *
+>>> iv = IntVector(4)         # Create an vector<int>
+>>> for i in range(0,4):
+...      iv[i] = i
+>>> average(iv)               # Call method
+1.5
+>>> average([0,1,2,3])        # Call with list
+1.5
+>>> half([1,2,3])             # Half a list
+(0.5,1.0,1.5)
+>>> halve_in_place([1,2,3])   # Oops
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+TypeError: Type error. Expected _p_std__vectorTdouble_t
+>>> dv = DoubleVector(4)
+>>> for i in range(0,4):
+...       dv[i] = i
+>>> halve_in_place(dv)       # Ok
+>>> for i in dv:
+...       print i
+...
+0.0
+0.5
+1.0
+1.5
+>>> dv[20] = 4.5
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+  File "example.py", line 81, in __setitem__
+    def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
+IndexError: vector index out of range
+>>>
+
      +
      +

      This library module is fully aware of C++ namespaces. If you use + vectors with other names, make sure you include the appropriate +using or typedef directives. For example:

      +
      +
      +%include "std_vector.i"
+
+namespace std {
+    %template(IntVector) vector<int>;
+}
+
+using namespace std;
+typedef std::vector Vector;
+
+void foo(vector<int> *x, const Vector &x);
+
      +
      +

      Note: This module makes use of several advanced SWIG features + including templatized typemaps and template partial specialization. If + you are trying to wrap other C++ code with templates, you might look at + the code contained in std_vector.i. Alternatively, you can + show them the code if you want to make their head explode.

      +

      Note: This module is defined for all SWIG target languages. + However argument conversion details and the public API exposed to the + interpreter vary.

      +

      Note: std_vector.i was written by Luigi "The + Amazing" Ballabio.

      +

      8.4.3 STL exceptions

      +

      Many of the STL wrapper functions add parameter checking and will + throw a language dependent error/exception should the values not be + valid. The classic example is array bounds checking. The library + wrappers are written to throw a C++ exception in the case of error. The + C++ exception in turn gets converted into an appropriate + error/exception for the target language. By and large this handling + should not need customising, however, customisation can easily be + achieved by supplying appropriate "throws" typemaps. For example:

      +
      +
      +%module example
+%include "std_vector.i"
+%typemap(throws) std::out_of_range {
+  // custom exception handler
+}
+%template(VectInt) std::vector<int>;
+
      +
      +

      The custom exception handler might, for example, log the exception + then convert it into a specific error/exception for the target + language.

      +

      When using the STL it is advisable to add in an exception handler to + catch all STL exceptions. The %exception directive can be used + by placing the following code before any other methods or libraries to + be wrapped:

      +
      +
      +%include "exception.i"
+
+%exception {
+  try {
+    $action
+  } catch (const std::exception& e) {
+    SWIG_exception(SWIG_RuntimeError, e.what());
+  }
+}
+
      +
      +

      Any thrown STL exceptions will then be gracefully handled instead of + causing a crash.

      +

      8.5 Utility Libraries

      +

      8.5.1 exception.i

      +

      The exception.i library provides a language-independent + function for raising a run-time exception in the target language. This + library is largely used by the SWIG library writers. If possible, use + the error handling scheme available to your target language as there is + greater flexibility in what errors/exceptions can be thrown.

      +

      SWIG_exception(int code, const char *message)

      +
      +

      Raises an exception in the target language. code is one of + the following symbolic constants:

      +
      +
      +SWIG_MemoryError
+SWIG_IOError
+SWIG_RuntimeError
+SWIG_IndexError
+SWIG_TypeError
+SWIG_DivisionByZero
+SWIG_OverflowError
+SWIG_SyntaxError
+SWIG_ValueError
+SWIG_SystemError
+
      +
      +

      message is a string indicating more information about the + problem.

      +
      +

      The primary use of this module is in writing language-independent + exception handlers. For example:

      +
      +
      +%include "exception.i"
+%exception std::vector::getitem {
+    try {
+        $action
+    } catch (std::out_of_range& e) {
+        SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
+    }
+}
+
      +
      +

      9 Argument Handling

      + + +
      + +
      + +

      In Chapter 3, SWIG's treatment of basic datatypes and pointers was + described. In particular, primitive types such as int and +double are mapped to corresponding types in the target language. + For everything else, pointers are used to refer to structures, classes, + arrays, and other user-defined datatypes. However, in certain + applications it is desirable to change SWIG's handling of a specific + datatype. For example, you might want to return multiple values through + the arguments of a function. This chapter describes some of the + techniques for doing this.

      +

      9.1 The typemaps.i library

      +

      This section describes the typemaps.i library + file--commonly used to change certain properties of argument + conversion.

      +

      9.1.1 Introduction

      +

      Suppose you had a C function like this:

      +
      +
      +void add(double a, double b, double *result) {
+	*result = a + b;
+}
+
      +
      +

      From reading the source code, it is clear that the function is + storing a value in the double *result parameter. However, + since SWIG does not examine function bodies, it has no way to know that + this is the underlying behavior.

      +

      One way to deal with this is to use the typemaps.i library + file and write interface code like this:

      +
      +
      +// Simple example using typemaps
+%module example
+%include "typemaps.i"
+
+%apply double *OUTPUT { double *result };
+%inlne %{
+extern void add(double a, double b, double *result);
+%}
+
      +
      +

      The %apply directive tells SWIG that you are going to apply + a special type handling rule to a type. The "double *OUTPUT" + specification is the name of a rule that defines how to return an + output value from an argument of type double *. This rule gets + applied to all of the datatypes listed in curly braces-- in this case " +double *result".

      +

      When the resulting module is created, you can now use the function + like this (shown for Python):

      +
      +
      +>>> a = add(3,4)
+>>> print a
+7
+>>>
+
      +
      +

      In this case, you can see how the output value normally returned in + the third argument has magically been transformed into a function + return value. Clearly this makes the function much easier to use since + it is no longer necessary to manufacture a special double * + object and pass it to the function somehow.

      +

      Once a typemap has been applied to a type, it stays in effect for + all future occurrences of the type and name. For example, you could + write the following:

      +
      +
      +%module example
+%include "typemaps.i"
+
+%apply double *OUTPUT { double *result };
+
+%inline %{
+extern void add(double a, double b, double *result);
+extern void sub(double a, double b, double *result);
+extern void mul(double a, double b, double *result);
+extern void div(double a, double b, double *result);
+%}
+...
+
      +
      +

      In this case, the double *OUTPUT rule is applied to all of + the functions that follow.

      +

      Typemap transformations can even be extended to multiple return + values. For example, consider this code:

      +
      +
      +%include "typemaps.i"
+%apply int *OUTPUT { int *width, int *height };
+
+// Returns a pair (width,height)
+void getwinsize(int winid, int *width, int *height);
+
      +
      +

      In this case, the function returns multiple values, allowing it to + be used like this:

      +
      +
      +>>> w,h = genwinsize(wid)
+>>> print w
+400
+>>> print h
+300
+>>>
+
      +
      +

      It should also be noted that although the %apply directive + is used to associate typemap rules to datatypes, you can also use the + rule names directly in arguments. For example, you could write this:

      +
      +
      +// Simple example using typemaps
+%module example
+%include "typemaps.i"
+
+%{
+extern void add(double a, double b, double *OUTPUT);
+%}
+extern void add(double a, double b, double *OUTPUT);
+
      +
      +

      Typemaps stay in effect until they are explicitly deleted or + redefined to something else. To clear a typemap, the %clear + directive should be used. For example:

      +
      +
      +%clear double *result;      // Remove all typemaps for double *result
+
      +
      +

      9.1.2 Input parameters

      +

      The following typemaps instruct SWIG that a pointer really only + holds a single input value:

      +
      +
      +int *INPUT		
+short *INPUT
+long *INPUT
+unsigned int *INPUT
+unsigned short *INPUT
+unsigned long *INPUT
+double *INPUT
+float *INPUT
+
      +
      +

      When used, it allows values to be passed instead of pointers. For + example, consider this function:

      +
      +
      +double add(double *a, double *b) {
+	return *a+*b;
+}
+
      +
      +

      Now, consider this SWIG interface:

      +
      +
      +%module example
+%include "typemaps.i"
+...
+%{
+extern double add(double *, double *);
+%}
+extern double add(double *INPUT, double *INPUT);
+
+
      +
      +

      When the function is used in the scripting language interpreter, it + will work like this:

      +
      +
      +result = add(3,4)
+
      +
      +

      9.1.3 Output parameters

      +

      The following typemap rules tell SWIG that pointer is the output + value of a function. When used, you do not need to supply the argument + when calling the function. Instead, one or more output values are + returned.

      +
      +
      +int *OUTPUT
+short *OUTPUT
+long *OUTPUT
+unsigned int *OUTPUT
+unsigned short *OUTPUT
+unsigned long *OUTPUT
+double *OUTPUT
+float *OUTPUT
+
+
      +
      +

      These methods can be used as shown in an earlier example. For + example, if you have this C function :

      +
      +
      +void add(double a, double b, double *c) {
+	*c = a+b;
+}
+
      +
      +

      A SWIG interface file might look like this :

      +
      +
      +%module example
+%include "typemaps.i"
+...
+%inline %{
+extern void add(double a, double b, double *OUTPUT);
+%}
+
+
      +
      +

      In this case, only a single output value is returned, but this is + not a restriction. An arbitrary number of output values can be returned + by applying the output rules to more than one argument (as shown + previously).

      +

      If the function also returns a value, it is returned along with the + argument. For example, if you had this:

      +
      +
      +extern int foo(double a, double b, double *OUTPUT);
+
      +
      +

      The function will return two values like this:

      +
      +
      +iresult, dresult = foo(3.5, 2)
+
      +
      +

      9.1.4 Input/Output parameters

      +

      When a pointer serves as both an input and output value you can use + the following typemaps :

      +
      +
      +int *INOUT
+short *INOUT
+long *INOUT
+unsigned int *INOUT
+unsigned short *INOUT
+unsigned long *INOUT
+double *INOUT
+float *INOUT
+
+
      +
      +

      A C function that uses this might be something like this:

      +
      +
      +void negate(double *x) {
+	*x = -(*x);
+}
+
+
      +
      +

      To make x function as both and input and output value, declare the + function like this in an interface file :

      +
      +
      +%module example
+%include "typemaps.i"
+...
+%{
+extern void negate(double *);
+%}
+extern void negate(double *INOUT);
+
+
      +
      +

      Now within a script, you can simply call the function normally :

      +
      +
      +a = negate(3);         # a = -3 after calling this
+
      +
      +

      One subtle point of the INOUT rule is that many scripting + languages enforce mutability constraints on primitive objects (meaning + that simple objects like integers and strings aren't supposed to + change). Because of this, you can't just modify the object's value in + place as the underlying C function does in this example. Therefore, the + INOUT rule returns the modified value as a new object rather + than directly overwriting the value of the original input object.

      +

      Compatibility note : The INOUT rule used to be known + as BOTH in earlier versions of SWIG. Backwards compatibility + is preserved, but deprecated.

      +

      9.1.5 Using different names

      +

      As previously shown, the %apply directive can be used to + apply the INPUT, OUTPUT, and INOUT typemaps + to different argument names. For example:

      +
      +
      +// Make double *result an output value
+%apply double *OUTPUT { double *result };
+
+// Make Int32 *in an input value
+%apply int *INPUT { Int32 *in };
+
+// Make long *x inout
+%apply long *INOUT {long *x};
+
+
      +
      +

      To clear a rule, the %clear directive is used:

      +
      +
      +%clear double *result;
+%clear Int32 *in, long *x;
+
      +
      +

      Typemap declarations are lexically scoped so a typemap takes effect + from the point of definition to the end of the file or a matching +%clear declaration.

      +

      9.2 Applying constraints to input values

      +

      In addition to changing the handling of various input values, it is + also possible to use typemaps to apply constraints. For example, maybe + you want to insure that a value is positive, or that a pointer is + non-NULL. This can be accomplished including the constraints.i + library file.

      +

      9.2.1 Simple constraint example

      +

      The constraints library is best illustrated by the following + interface file :

      +
      +
      +// Interface file with constraints
+%module example
+%include "constraints.i"
+
+double exp(double x);
+double log(double POSITIVE);         // Allow only positive values
+double sqrt(double NONNEGATIVE);     // Non-negative values only
+double inv(double NONZERO);          // Non-zero values
+void   free(void *NONNULL);          // Non-NULL pointers only
+
+
      +
      +

      The behavior of this file is exactly as you would expect. If any of + the arguments violate the constraint condition, a scripting language + exception will be raised. As a result, it is possible to catch bad + values, prevent mysterious program crashes and so on.

      +

      9.2.2 Constraint methods

      +

      The following constraints are currently available

      +
      +
      +POSITIVE                     Any number > 0 (not zero)
+NEGATIVE                     Any number < 0 (not zero)
+NONNEGATIVE                  Any number >= 0
+NONPOSITIVE                  Any number <= 0
+NONZERO                      Nonzero number
+NONNULL                      Non-NULL pointer (pointers only).
+
+
      +
      +

      9.2.3 Applying constraints to new + datatypes

      +

      The constraints library only supports the primitive C datatypes, but + it is easy to apply it to new datatypes using %apply. For + example :

      +
      +
      +// Apply a constraint to a Real variable
+%apply Number POSITIVE { Real in };
+
+// Apply a constraint to a pointer type
+%apply Pointer NONNULL { Vector * };
+
+
      +
      +

      The special types of "Number" and "Pointer" can be applied to any + numeric and pointer variable type respectively. To later remove a + constraint, the %clear directive can be used :

      +
      +
      +%clear Real in;
+%clear Vector *;
+
      +
      +

      10 Typemaps

      + + +
      + +
      + +

      10.1 Introduction

      +

      Chances are, you are reading this chapter for one of two reasons; + you either want to customize SWIG's behavior or you overheard someone + mumbling some incomprehensible drivel about "typemaps" and you asked + yourself "typemaps, what are those?" That said, let's start with a + short disclaimer that "typemaps" are an advanced customization feature + that provide direct access to SWIG's low-level code generator. Not only + that, they are an integral part of the SWIG C++ type system (a + non-trivial topic of its own). Typemaps are generally not a + required part of using SWIG. Therefore, you might want to re-read the + earlier chapters if you have found your way to this chapter with only a + vague idea of what SWIG already does by default.

      +

      10.1.1 Type conversion

      +

      One of the most important problems in wrapper code generation is the + conversion of datatypes between programming languages. Specifically, + for every C/C++ declaration, SWIG must somehow generate wrapper code + that allows values to be passed back and forth between languages. Since + every programming language represents data differently, this is not a + simple of matter of simply linking code together with the C linker. + Instead, SWIG has to know something about how data is represented in + each language and how it can be manipulated.

      +

      To illustrate, suppose you had a simple C function like this:

      +
      +
      +int factorial(int n);
+
      +
      +

      To access this function from Python, a pair of Python API functions + are used to convert integer values. For example:

      +
      +
      +long PyInt_AsLong(PyObject *obj);      /* Python --> C */
+PyObject *PyInt_FromLong(long x);      /* C --> Python */
+
      +
      +

      The first function is used to convert the input argument from a + Python integer object to C long. The second function is used + to convert a value from C back into a Python integer object.

      +

      Inside the wrapper function, you might see these functions used like + this:

      +
      +
      +PyObject *wrap_factorial(PyObject *self, PyObject *args) {
+    int       arg1;
+    int       result;
+    PyObject *obj1;
+    PyObject *resultobj;
+
+    if (!PyArg_ParseTuple("O:factorial", &obj1)) return NULL;
+    arg1 = PyInt_AsLong(obj1);
+    result = factorial(arg1);
+    resultobj = PyInt_FromLong(result);
+    return resultobj;
+}
+
      +
      +

      Every target language supported by SWIG has functions that work in a + similar manner. For example, in Perl, the following functions are used:

      +
      +
      +IV SvIV(SV *sv);                     /* Perl --> C */
+void sv_setiv(SV *sv, IV val);       /* C --> Perl */
+
      +
      +

      In Tcl:

      +
      +
      +int Tcl_GetLongFromObj(Tcl_Interp *interp, Tcl_Obj *obj, long *value);
+Tcl_Obj *Tcl_NewIntObj(long value);
+
      +
      +

      The precise details are not so important. What is important is that + all of the underlying type conversion is handled by collections of + utility functions and short bits of C code like this---you simply have + to read the extension documentation for your favorite language to know + how it works (an exercise left to the reader).

      +

      10.1.2 Typemaps

      +

      Since type handling is so central to wrapper code generation, SWIG + allows it to be completely defined (or redefined) by the user. To do + this, a special %typemap directive is used. For example:

      +
      +
      +/* Convert from Python --> C */
+%typemap(in) int {
+    $1 = PyInt_AsLong($input);
+}
+
+/* Convert from C --> Python */
+%typemap(out) int {
+    $result = PyInt_FromLong($1);
+}
+
      +
      +

      At first glance, this code will look a little confusing. However, + there is really not much to it. The first typemap (the "in" typemap) is + used to convert a value from the target language to C. The second + typemap (the "out" typemap) is used to convert in the other direction. + The content of each typemap is a small fragment of code that is + inserted directly into the SWIG generated wrapper functions. The code + is usually C or C++ code which will be generated into the C/C++ wrapper + functions. Note that this isn't always the case as some target language + modules allow target language code within the typemaps which gets + generated into target language specific files. Within this code, a + number of special variables prefixed with a $ are expanded. These are + really just placeholders for C/C++ variables that are generated in the + course of creating the wrapper function. In this case, $input + refers to an input object that needs to be converted to C/C++ and +$result refers to an object that is going to be returned by a + wrapper function. $1 refers to a C/C++ variable that has the + same type as specified in the typemap declaration (an int in + this example).

      +

      A short example might make this a little more clear. If you were + wrapping a function like this:

      +
      +
      +int gcd(int x, int y);
+
      +
      +

      A wrapper function would look approximately like this:

      +
      +
      +PyObject *wrap_gcd(PyObject *self, PyObject *args) {
+   int arg1;
+   int arg2;
+   int result;
+   PyObject *obj1;
+   PyObject *obj2;
+   PyObject *resultobj;
+
+   if (!PyArg_ParseTuple("OO:gcd", &obj1, &obj2)) return NULL;
+
+   /* "in" typemap, argument 1 */   
+   {
+      arg1 = PyInt_AsLong(obj1);
+   }
+
+   /* "in" typemap, argument 2 */
+   {
+      arg2 = PyInt_AsLong(obj2);
+   }
+
+   result = gcd(arg1,arg2);
+
+   /* "out" typemap, return value */
+   {
+      resultobj = PyInt_FromLong(result);
+   }
+
+   return resultobj;
+}
+
      +
      +

      In this code, you can see how the typemap code has been inserted + into the function. You can also see how the special $ variables have + been expanded to match certain variable names inside the wrapper + function. This is really the whole idea behind typemaps--they simply + let you insert arbitrary code into different parts of the generated + wrapper functions. Because arbitrary code can be inserted, it possible + to completely change the way in which values are converted.

      +

      10.1.3 Pattern matching

      +

      As the name implies, the purpose of a typemap is to "map" C + datatypes to types in the target language. Once a typemap is defined + for a C datatype, it is applied to all future occurrences of that type + in the input file. For example:

      +
      +
      +/* Convert from Perl --> C */
+%typemap(in) int {
+   $1 = SvIV($input);
+}
+
+...
+int factorial(int n);
+int gcd(int x, int y);
+int count(char *s, char *t, int max);
+
      +
      +

      The matching of typemaps to C datatypes is more than a simple + textual match. In fact, typemaps are fully built into the underlying + type system. Therefore, typemaps are unaffected by typedef, + namespaces, and other declarations that might hide the underlying type. + For example, you could have code like this:

      +
      +
      +/* Convert from Ruby--> C */
+%typemap(in) int {
+   $1 = NUM2INT($input);
+}
+...
+typedef int Integer;
+namespace foo {
+    typedef Integer Number;
+};
+
+int foo(int x);
+int bar(Integer y);
+int spam(foo::Number a, foo::Number b);
+
      +
      +

      In this case, the typemap is still applied to the proper arguments + even though typenames don't always match the text "int". This ability + to track types is a critical part of SWIG--in fact, all of the target + language modules work merely define a set of typemaps for the basic + types. Yet, it is never necessary to write new typemaps for typenames + introduced by typedef.

      +

      In addition to tracking typenames, typemaps may also be specialized + to match against a specific argument name. For example, you could write + a typemap like this:

      +
      +
      +%typemap(in) double nonnegative {
+   $1 = PyFloat_AsDouble($input);
+   if ($1 < 0) {
+        PyErr_SetString(PyExc_ValueError,"argument must be nonnegative.");
+        return NULL;
+   }
+}
+
+...
+double sin(double x);
+double cos(double x);
+double sqrt(double nonnegative);
+
+typedef double Real;
+double log(Real nonnegative);
+...
+
      +
      +

      For certain tasks such as input argument conversion, typemaps can be + defined for sequences of consecutive arguments. For example:

      +
      +
      +%typemap(in) (char *str, int len) {
+    $1 = PyString_AsString($input);   /* char *str */
+    $2 = PyString_Size($input);       /* int len   */
+}
+...
+int count(char *str, int len, char c);
+
      +
      +

      In this case, a single input object is expanded into a pair of C + arguments. This example also provides a hint to the unusual variable + naming scheme involving $1, $2, and so forth.

      +

      10.1.4 Reusing typemaps

      +

      Typemaps are normally defined for specific type and argument name + patterns. However, typemaps can also be copied and reused. One way to + do this is to use assignment like this:

      +
      +
      +%typemap(in) Integer = int;   
+%typemap(in) (char *buffer, int size) = (char *str, int len);
+
      +
      +

      A more general form of copying is found in the %apply + directive like this:

      +
      +
      +%typemap(in) int {
+   /* Convert an integer argument */
+   ...
+}
+%typemap(out) int {
+   /* Return an integer value */
+   ...
+}
+
+/* Apply all of the integer typemaps to size_t */
+%apply int { size_t };    
+
      +
      +

      %apply merely takes all of the typemaps that are + defined for one type and applies them to other types. Note: you can + include a comma separated set of types in the { ... } part of +%apply.

      +

      It should be noted that it is not necessary to copy typemaps for + types that are related by typedef. For example, if you have + this,

      +
      +
      +typedef int size_t;
+
      +
      +

      then SWIG already knows that the int typemaps apply. You + don't have to do anything.

      +

      10.1.5 What can be done with typemaps?

      +

      The primary use of typemaps is for defining wrapper generation + behavior at the level of individual C/C++ datatypes. There are + currently six general categories of problems that typemaps address:

      +

      Argument handling

      +
      +
      +int foo(int x, double y, char *s);
+
      +
      +
        +
      • Input argument conversion ("in" typemap).
        • +
      • Input argument type checking ("typecheck" typemap).
        • +
      • Output argument handling ("argout" typemap).
        • +
      • Input argument value checking ("check" typemap).
        • +
      • Input argument initialization ("arginit" typemap).
        • +
      • Default arguments ("default" typemap).
        • +
      • Input argument resource management ("freearg" typemap).
        • +
      +

      Return value handling

      +
      +
      +int foo(int x, double y, char *s);
+
      +
      +
        +
      • Function return value conversion ("out" typemap).
        • +
      • Return value resource management ("ret" typemap).
        • +
      • Resource management for newly allocated objects ("newfree" typemap).
        • +
      +

      Exception handling

      +
      +
      +int foo(int x, double y, char *s) throw(MemoryError, IndexError);
+
      +
      +
        +
      • Handling of C++ exception specifications. ("throw" typemap).
        • +
      +

      Global variables

      +
      +
      +int foo;
+
      +
      +
        +
      • Assignment of a global variable. ("varin" typemap).
        • +
      • Reading a global variable. ("varout" typemap).
        • +
      +

      Member variables

      +
      +
      +struct Foo {
+    int x[20];
+};
+
      +
      +
        +
      • Assignment of data to a class/structure member. ("memberin" + typemap).
        • +
      +

      Constant creation

      +
      +
      +#define FOO 3
+%constant int BAR = 42;
+enum { ALE, LAGER, STOUT };
+
      +
      +
        +
      • Creation of constant values. ("consttab" or "constcode" typemap).
        • +
      +

      Details of each of these typemaps will be covered shortly. Also, + certain language modules may define additional typemaps that expand + upon this list. For example, the Java module defines a variety of + typemaps for controlling additional aspects of the Java bindings. + Consult language specific documentation for further details.

      +

      10.1.6 What can't be done with typemaps?

      +

      Typemaps can't be used to define properties that apply to C/C++ + declarations as a whole. For example, suppose you had a declaration + like this,

      +
      +
      +Foo *make_Foo();
+
      +
      +

      and you wanted to tell SWIG that make_Foo() returned a + newly allocated object (for the purposes of providing better memory + management). Clearly, this property of make_Foo() is not + a property that would be associated with the datatype Foo * by + itself. Therefore, a completely different SWIG customization mechanism + (%feature) is used for this purpose. Consult the +Customization Features chapter for more information about that.

      +

      Typemaps also can't be used to rearrange or transform the order of + arguments. For example, if you had a function like this:

      +
      +
      +void foo(int, char *);
+
      +
      +

      you can't use typemaps to interchange the arguments, allowing you to + call the function like this:

      +
      +
      +foo("hello",3)          # Reversed arguments
+
      +
      +

      If you want to change the calling conventions of a function, write a + helper function instead. For example:

      +
      +
      +%rename(foo) wrap_foo;
+%inline %{
+void wrap_foo(char *s, int x) {
+   foo(x,s);
+}
+%}
+
      +
      +

      10.1.7 The rest of this chapter

      +

      The rest of this chapter provides detailed information for people + who want to write new typemaps. This information is of particular + importance to anyone who intends to write a new SWIG target language + module. Power users can also use this information to write application + specific type conversion rules.

      +

      Since typemaps are strongly tied to the underlying C++ type system, + subsequent sections assume that you are reasonably familiar with the + basic details of values, pointers, references, arrays, type qualifiers + (e.g., const), structures, namespaces, templates, and memory + management in C/C++. If not, you would be well-advised to consult a + copy of "The C Programming Language" by Kernighan and Ritchie or "The + C++ Programming Language" by Stroustrup before going any further.

      +

      10.2 Typemap specifications

      +

      This section describes the behavior of the %typemap + directive itself.

      +

      10.2.1 Defining a typemap

      +

      New typemaps are defined using the %typemap declaration. + The general form of this declaration is as follows (parts enclosed in [ + ... ] are optional):

      +
      +
      +%typemap(method [, modifiers]) typelist code ;
+
      +
      +

      method is a simply a name that specifies what kind of + typemap is being defined. It is usually a name like "in", +"out", or "argout". The purpose of these methods is + described later.

      +

      modifiers is an optional comma separated list of +name="value" values. These are sometimes to attach extra + information to a typemap and is often target-language dependent.

      +

      typelist is a list of the C++ type patterns that the + typemap will match. The general form of this list is as follows:

      +
      +
      +typelist    :  typepattern [, typepattern, typepattern, ... ] ;
+
+typepattern :  type [ (parms) ]
+            |  type name [ (parms) ]
+            |  ( typelist ) [ (parms) ]
+
+
      +
      +

      Each type pattern is either a simple type, a simple type and + argument name, or a list of types in the case of multi-argument + typemaps. In addition, each type pattern can be parameterized with a + list of temporary variables (parms). The purpose of these variables + will be explained shortly.

      +

      code specifies the code used in the typemap. Usually this is + C/C++ code, but in the statically typed target languages, such as Java + and C#, this can contain target language code for certain typemaps. It + can take any one of the following forms:

      +
      +
      +code       : { ... }
+           | " ... "
+           | %{ ... %}
+
      +
      +

      Note that the preprocessor will expand code within the {} + delimiters, but not in the last two styles of delimiters, see +Preprocessor and Typemaps. Here are some examples of valid typemap + specifications:

      +
      +
      +/* Simple typemap declarations */
+%typemap(in) int {
+   $1 = PyInt_AsLong($input);
+}
+%typemap(in) int "$1 = PyInt_AsLong($input);";
+%typemap(in) int %{ 
+   $1 = PyInt_AsLong($input);
+%}
+
+/* Typemap with extra argument name */
+%typemap(in) int nonnegative {
+   ...
+}
+
+/* Multiple types in one typemap */
+%typemap(in) int, short, long { 
+   $1 = SvIV($input);
+}
+
+/* Typemap with modifiers */
+%typemap(in,doc="integer") int "$1 = gh_scm2int($input);";
+
+/* Typemap applied to patterns of multiple arguments */
+%typemap(in) (char *str, int len),
+             (char *buffer, int size)
+{
+   $1 = PyString_AsString($input);
+   $2 = PyString_Size($input);
+}
+
+/* Typemap with extra pattern parameters */
+%typemap(in, numinputs=0) int *output (int temp),
+                          long *output (long temp)
+{
+   $1 = &temp;
+}
+
      +
      +

      Admittedly, it's not the most readable syntax at first glance. + However, the purpose of the individual pieces will become clear.

      +

      10.2.2 Typemap scope

      +

      Once defined, a typemap remains in effect for all of the + declarations that follow. A typemap may be redefined for different + sections of an input file. For example:

      +
      +
      +// typemap1
+%typemap(in) int {
+...
+}
+
+int fact(int);                    // typemap1
+int gcd(int x, int y);            // typemap1
+
+// typemap2
+%typemap(in) int {
+...
+}
+
+int isprime(int);                 // typemap2
+
      +
      +

      One exception to the typemap scoping rules pertains to the +%extend declaration. %extend is used to attach new + declarations to a class or structure definition. Because of this, all + of the declarations in an %extend block are subject to the + typemap rules that are in effect at the point where the class itself is + defined. For example:

      +
      +
      +class Foo {
+   ...
+};
+
+%typemap(in) int {
+ ...
+}
+
+%extend Foo {
+   int blah(int x);    // typemap has no effect.  Declaration is attached to Foo which 
+                       // appears before the %typemap declaration.
+};
+
      +
      +

      10.2.3 Copying a typemap

      +

      A typemap is copied by using assignment. For example:

      +
      +
      +%typemap(in) Integer = int;
+
      +
      +

      or this:

      +
      +
      +%typemap(in) Integer, Number, int32_t = int;
+
      +
      +

      Types are often managed by a collection of different typemaps. For + example:

      +
      +
      +%typemap(in)     int { ... }
+%typemap(out)    int { ... }
+%typemap(varin)  int { ... }
+%typemap(varout) int { ... }
+
      +
      +

      To copy all of these typemaps to a new type, use %apply. + For example:

      +
      +
      +%apply int { Integer };            // Copy all int typemaps to Integer
+%apply int { Integer, Number };    // Copy all int typemaps to both Integer and Number
+
      +
      +

      The patterns for %apply follow the same rules as for +%typemap. For example:

      +
      +
      +%apply int *output { Integer *output };                    // Typemap with name
+%apply (char *buf, int len) { (char *buffer, int size) };  // Multiple arguments
+
      +
      +

      10.2.4 Deleting a typemap

      +

      A typemap can be deleted by simply defining no code. For example:

      +
      +
      +%typemap(in) int;               // Clears typemap for int
+%typemap(in) int, long, short;  // Clears typemap for int, long, short
+%typemap(in) int *output;       
+
      +
      +

      The %clear directive clears all typemaps for a given type. + For example:

      +
      +
      +%clear int;                     // Removes all types for int
+%clear int *output, long *output;
+
      +
      +

      Note: Since SWIG's default behavior is defined by typemaps, + clearing a fundamental type like int will make that type + unusable unless you also define a new set of typemaps immediately after + the clear operation.

      +

      10.2.5 Placement of typemaps

      +

      Typemap declarations can be declared in the global scope, within a + C++ namespace, and within a C++ class. For example:

      +
      +
      +%typemap(in) int {
+   ...
+}
+
+namespace std {
+    class string;
+    %typemap(in) string {
+        ...
+    }
+}
+
+class Bar {
+public:
+    typedef const int & const_reference;
+    %typemap(out) const_reference {
+         ...
+    }
+};
+
      +
      +

      When a typemap appears inside a namespace or class, it stays in + effect until the end of the SWIG input (just like before). However, the + typemap takes the local scope into account. Therefore, this code

      +
      +
      +namespace std {
+    class string;
+    %typemap(in) string {
+       ...
+    }
+}
+
      +
      +

      is really defining a typemap for the type std::string. You + could have code like this:

      +
      +
      +namespace std {
+    class string;
+    %typemap(in) string {          /* std::string */
+       ...
+    }
+}
+
+namespace Foo {
+    class string;
+    %typemap(in) string {          /* Foo::string */
+       ...
+    }
+}
+
      +
      +

      In this case, there are two completely distinct typemaps that apply + to two completely different types (std::string and +Foo::string).

      +

      It should be noted that for scoping to work, SWIG has to know that +string is a typename defined within a particular namespace. In this + example, this is done using the class declaration class string +.

      +

      10.3 Pattern matching rules

      +

      The section describes the pattern matching rules by which C + datatypes are associated with typemaps.

      +

      10.3.1 Basic matching rules

      +

      Typemaps are matched using both a type and a name (typically the + name of a argument). For a given TYPE NAME pair, the following + rules are applied, in order, to find a match. The first typemap found + is used.

      +
        +
      • Typemaps that exactly match TYPE and NAME.
        • +
      • Typemaps that exactly match TYPE only.
        • +
      +

      If TYPE includes qualifiers (const, volatile, etc.), they + are stripped and the following checks are made:

      +
        +
      • Typemaps that match the stripped TYPE and NAME.
        • +
      • Typemaps that match the stripped TYPE only.
        • +
      +

      If TYPE is an array. The following transformation is made:

      +
        +
      • Replace all dimensions to [ANY] and look for a generic + array typemap.
        • +
      +

      To illustrate, suppose that you had a function like this:

      +
      +
      +int foo(const char *s);
+
      +
      +

      To find a typemap for the argument const char *s, SWIG will + search for the following typemaps:

      +
      +
      +const char *s           Exact type and name match
+const char *            Exact type match
+char *s                 Type and name match (stripped qualifiers)
+char *                  Type match (stripped qualifiers)
+
      +
      +

      When more than one typemap rule might be defined, only the first + match found is actually used. Here is an example that shows how some of + the basic rules are applied:

      +
      +
      +%typemap(in) int *x {
+   ... typemap 1
+}
+
+%typemap(in) int * {
+   ... typemap 2
+}
+
+%typemap(in) const int *z {
+   ... typemap 3
+}
+
+%typemap(in) int [4] {
+   ... typemap 4
+}
+
+%typemap(in) int [ANY] {
+   ... typemap 5
+}
+
+void A(int *x);        // int *x rule    (typemap 1)
+void B(int *y);        // int * rule     (typemap 2)
+void C(const int *x);  // int *x rule    (typemap 1)
+void D(const int *z);  // int * rule     (typemap 3)
+void E(int x[4]);      // int [4] rule   (typemap 4)
+void F(int x[1000]);   // int [ANY] rule (typemap 5)
+
      +
      +

      10.3.2 Typedef reductions

      +

      If no match is found using the rules in the previous section, SWIG + applies a typedef reduction to the type and repeats the typemap search + for the reduced type. To illustrate, suppose you had code like this:

      +
      +
      +%typemap(in) int {
+   ... typemap 1
+}
+
+typedef int Integer;
+void blah(Integer x);
+
      +
      +

      To find the typemap for Integer x, SWIG will first search + for the following typemaps:

      +
      +
      +Integer x
+Integer
+
      +
      +

      Finding no match, it then applies a reduction Integer -> int + to the type and repeats the search.

      +
      +
      +int x
+int      --> match: typemap 1
+
      +
      +

      Even though two types might be the same via typedef, SWIG allows + typemaps to be defined for each typename independently. This allows for + interesting customization possibilities based solely on the typename + itself. For example, you could write code like this:

      +
      +
      +typedef double  pdouble;     // Positive double
+
+// typemap 1
+%typemap(in) double {
+   ... get a double ...
+}
+// typemap 2
+%typemap(in) pdouble {
+   ... get a positive double ...
+}
+double sin(double x);           // typemap 1
+pdouble sqrt(pdouble x);        // typemap 2
+
      +
      +

      When reducing the type, only one typedef reduction is applied at a + time. The search process continues to apply reductions until a match is + found or until no more reductions can be made.

      +

      For complicated types, the reduction process can generate a long + list of patterns. Consider the following:

      +
      +
      +typedef int Integer;
+typedef Integer Row4[4];
+void foo(Row4 rows[10]);
+
      +
      +

      To find a match for the Row4 rows[10] argument, SWIG would + check the following patterns, stopping only when it found a match:

      +
      +
      +Row4 rows[10]
+Row4 [10]
+Row4 rows[ANY]
+Row4 [ANY]
+
+# Reduce Row4 --> Integer[4]
+Integer rows[10][4]
+Integer [10][4]
+Integer rows[ANY][ANY]
+Integer [ANY][ANY]
+
+# Reduce Integer --> int
+int rows[10][4]
+int [10][4]
+int rows[ANY][ANY]
+int [ANY][ANY]
+
      +
      +

      For parameterized types like templates, the situation is even more + complicated. Suppose you had some declarations like this:

      +
      +
      +typedef int Integer;
+typedef foo<Integer,Integer> fooii;
+void blah(fooii *x);
+
      +
      +

      In this case, the following typemap patterns are searched for the + argument fooii *x:

      +
      +
      +fooii *x
+fooii *
+
+# Reduce fooii --> foo<Integer,Integer>
+foo<Integer,Integer> *x
+foo<Integer,Integer> *
+
+# Reduce Integer -> int
+foo<int, Integer> *x
+foo<int, Integer> *
+
+# Reduce Integer -> int
+foo<int, int> *x
+foo<int, int> *
+
      +
      +

      Typemap reductions are always applied to the left-most type that + appears. Only when no reductions can be made to the left-most type are + reductions made to other parts of the type. This behavior means that + you could define a typemap for foo<int,Integer>, but a typemap + for foo<Integer,int> would never be matched. Admittedly, this + is rather esoteric--there's little practical reason to write a typemap + quite like that. Of course, you could rely on this to confuse your + coworkers even more.

      +

      10.3.3 Default typemaps

      +

      Most SWIG language modules use typemaps to define the default + behavior of the C primitive types. This is entirely straightforward. + For example, a set of typemaps are written like this:

      +
      +
      +%typemap(in) int   "convert an int";
+%typemap(in) short "convert a short";
+%typemap(in) float "convert a float";
+...
+
      +
      +

      Since typemap matching follows all typedef declarations, + any sort of type that is mapped to a primitive type through typedef + will be picked up by one of these primitive typemaps.

      +

      The default behavior for pointers, arrays, references, and other + kinds of types are handled by specifying rules for variations of the + reserved SWIGTYPE type. For example:

      +
      +
      +%typemap(in) SWIGTYPE *            { ... default pointer handling ...         }
+%typemap(in) SWIGTYPE &            { ... default reference handling ...       }
+%typemap(in) SWIGTYPE []           { ... default array handling ...           }
+%typemap(in) enum SWIGTYPE         { ... default handling for enum values ... }
+%typemap(in) SWIGTYPE (CLASS::*)   { ... default pointer member handling ...  } 
+
      +
      +

      These rules match any kind of pointer, reference, or array--even + when multiple levels of indirection or multiple array dimensions are + used. Therefore, if you wanted to change SWIG's default handling for + all types of pointers, you would simply redefine the rule for +SWIGTYPE *.

      +

      Finally, the following typemap rule is used to match against simple + types that don't match any other rules:

      +
      +
      +%typemap(in) SWIGTYPE   { ... handle an unknown type ... }
+
      +
      +

      This typemap is important because it is the rule that gets triggered + when call or return by value is used. For instance, if you have a + declaration like this:

      +
      +
      +double dot_product(Vector a, Vector b);
+
      +
      +

      The Vector type will usually just get matched against +SWIGTYPE. The default implementation of SWIGTYPE is to + convert the value into pointers (as described in chapter 3).

      +

      By redefining SWIGTYPE it may be possible to implement + other behavior. For example, if you cleared all typemaps for +SWIGTYPE, SWIG simply won't wrap any unknown datatype (which might + be useful for debugging). Alternatively, you might modify SWIGTYPE to + marshal objects into strings instead of converting them to pointers.

      +

      The best way to explore the default typemaps is to look at the ones + already defined for a particular language module. Typemaps definitions + are usually found in the SWIG library in a file such as python.swg +, tcl8.swg, etc.

      +

      10.3.4 Mixed default typemaps

      +

      The default typemaps described above can be mixed with const + and with each other. For example the SWIGTYPE * typemap is for + default pointer handling, but if a const SWIGTYPE * typemap is + defined it will be used instead for constant pointers. Some further + examples follow:

      +
      +
      +%typemap(in) enum SWIGTYPE &        { ... enum references ...                       }
+%typemap(in) const enum SWIGTYPE &  { ... const enum references ...                 }
+%typemap(in) SWIGTYPE *&            { ... pointers passed by reference ...          }
+%typemap(in) SWIGTYPE * const &     { ... constant pointers passed by reference ... }
+%typemap(in) SWIGTYPE[ANY][ANY]     { ... 2D arrays ...                             }
+
      +
      +

      Note that the the typedef reduction described earlier is also used + with these mixed default typemaps. For example, say the following + typemaps are defined and SWIG is looking for the best match for the + enum shown below:

      +
      +
      +%typemap(in) const Hello &          { ... }
+%typemap(in) const enum SWIGTYPE &  { ... }
+%typemap(in) enum SWIGTYPE &        { ... }
+%typemap(in) SWIGTYPE &             { ... }
+%typemap(in) SWIGTYPE               { ... }
+
+enum Hello {};
+const Hello &hi;
+
      +
      +

      The typemap at the top of the list will be chosen, not because it is + defined first, but because it is the closest match for the type being + wrapped. If any of the typemaps in the above list were not defined, + then the next one on the list would have precedence. In other words the + typemap chosen is the closest explicit match.

      +

      Compatibility note: The mixed default typemaps were + introduced in SWIG-1.3.23, but were not used much in this version. + Expect to see them being used more and more within the various + libraries in later versions of SWIG.

      +

      10.3.5 Multi-arguments typemaps

      +

      When multi-argument typemaps are specified, they take precedence + over any typemaps specified for a single type. For example:

      +
      +
      +%typemap(in) (char *buffer, int len) {
+   // typemap 1
+}
+
+%typemap(in) char *buffer {
+   // typemap 2
+}
+
+void foo(char *buffer, int len, int count); // (char *buffer, int len)
+void bar(char *buffer, int blah);           // char *buffer
+
      +
      +

      Multi-argument typemaps are also more restrictive in the way that + they are matched. Currently, the first argument follows the matching + rules described in the previous section, but all subsequent arguments + must match exactly.

      +

      10.4 Code generation rules

      +

      This section describes rules by which typemap code is inserted into + the generated wrapper code.

      +

      10.4.1 Scope

      +

      When a typemap is defined like this:

      +
      +
      +%typemap(in) int {
+   $1 = PyInt_AsLong($input);
+}
+
      +
      +

      the typemap code is inserted into the wrapper function using a new + block scope. In other words, the wrapper code will look like this:

      +
      +
      +wrap_whatever() {
+    ...
+    // Typemap code
+    {                    
+       arg1 = PyInt_AsLong(obj1);
+    }
+    ...
+}
+
      +
      +

      Because the typemap code is enclosed in its own block, it is legal + to declare temporary variables for use during typemap execution. For + example:

      +
      +
      +%typemap(in) short {
+   long temp;          /* Temporary value */
+   if (Tcl_GetLongFromObj(interp, $input, &temp) != TCL_OK) {
+      return TCL_ERROR;
+   }
+   $1 = (short) temp;
+}
+
      +
      +

      Of course, any variables that you declare inside a typemap are + destroyed as soon as the typemap code has executed (they are not + visible to other parts of the wrapper function or other typemaps that + might use the same variable names).

      +

      Occasionally, typemap code will be specified using a few alternative + forms. For example:

      +
      +
      +%typemap(in) int "$1 = PyInt_AsLong($input);";
+%typemap(in) int %{
+$1 = PyInt_AsLong($input);
+%}
+
      +
      +

      These two forms are mainly used for cosmetics--the specified code is + not enclosed inside a block scope when it is emitted. This sometimes + results in a less complicated looking wrapper function.

      +

      10.4.2 Declaring new local variables

      +

      Sometimes it is useful to declare a new local variable that exists + within the scope of the entire wrapper function. A good example of this + might be an application in which you wanted to marshal strings. Suppose + you had a C++ function like this

      +
      +
      +int foo(std::string *s);
+
      +
      +

      and you wanted to pass a native string in the target language as an + argument. For instance, in Perl, you wanted the function to work like + this:

      +
      +
      +$x = foo("Hello World");
+
      +
      +

      To do this, you can't just pass a raw Perl string as the +std::string * argument. Instead, you have to create a temporary +std::string object, copy the Perl string data into it, and then + pass a pointer to the object. To do this, simply specify the typemap + with an extra parameter like this:

      +
      +
      +%typemap(in) std::string * (std::string temp) {
+    unsigned int len;
+    char        *s;
+    s = SvPV($input,len);         /* Extract string data */
+    temp.assign(s,len);           /* Assign to temp */
+    $1 = &temp;                   /* Set argument to point to temp */
+}
+
      +
      +

      In this case, temp becomes a local variable in the scope of + the entire wrapper function. For example:

      +
      +
      +wrap_foo() {
+   std::string temp;    <--- Declaration of temp goes here
+   ...
+
+   /* Typemap code */
+   {
+      ...
+      temp.assign(s,len);
+      ...
+   } 
+   ...
+}
+
      +
      +

      When you set temp to a value, it persists for the duration + of the wrapper function and gets cleaned up automatically on exit.

      +

      It is perfectly safe to use more than one typemap involving local + variables in the same declaration. For example, you could declare a + function as :

      +
      +
      +void foo(std::string *x, std::string *y, std::string *z);
+
      +
      +

      This is safely handled because SWIG actually renames all local + variable references by appending an argument number suffix. Therefore, + the generated code would actually look like this:

      +
      +
      +wrap_foo() {
+   int *arg1;    /* Actual arguments */
+   int *arg2;
+   int *arg3;
+   std::string temp1;    /* Locals declared in the typemap */
+   std::string temp2;
+   std::string temp3;
+   ...
+   {
+       char *s;
+       unsigned int len;
+       ...
+       temp1.assign(s,len);
+       arg1 = *temp1;
+   }
+   {
+       char *s;
+       unsigned int len;
+       ...
+       temp2.assign(s,len);
+       arg2 = &temp2;
+   }
+   {
+       char *s;
+       unsigned int len;
+       ...
+       temp3.assign(s,len);
+       arg3 = &temp3;
+   }
+   ...
+}
+
      +
      +

      Some typemaps do not recognize local variables (or they may simply + not apply). At this time, only typemaps that apply to argument + conversion support this.

      +

      Note:

      +

      When declaring a typemap for multiple types, each type must have its + own local variable declaration.

      +
      +
      +%typemap(in) const std::string *, std::string * (std::string temp) // NO!
+// only std::string * has a local variable
+// const std::string * does not (oops)
+....
+
+%typemap(in) const std::string * (std::string temp), std::string * (std::string temp) // Correct
+....
+
      +
      +

      10.4.3 Special variables

      +

      Within all typemaps, the following special variables are expanded. + This is by no means a complete list as some target languages have + additional special variables which are documented in the language + specific chapters.

      +
      + + + + + + + + + + + + + + + + + + + + +
      VariableMeaning
      $n A C local variable corresponding to type + n in the typemap pattern.
      $argnumArgument number. Only available in typemaps + related to argument conversion
      $n_nameArgument name
      $n_typeReal C datatype of type n.
      $n_ltypeltype of type n
      $n_mangleMangled form of type n. For + example _p_Foo
      $n_descriptorType descriptor structure for + type n. For example SWIGTYPE_p_Foo. This is primarily + used when interacting with the run-time type checker (described later).
      $*n_typeReal C datatype of type n + with one pointer removed.
      $*n_ltypeltype of type n with one + pointer removed.
      $*n_mangleMangled form of type n with + one pointer removed.
      $*n_descriptorType descriptor structure for + type n with one pointer removed.
      $&n_typeReal C datatype of type n + with one pointer added.
      $&n_ltypeltype of type n with one + pointer added.
      $&n_mangleMangled form of type n with + one pointer added.
      $&n_descriptorType descriptor structure for + type n with one pointer added.
      $n_basetypeBase typename with all pointers and + qualifiers stripped.
      +
      +

      Within the table, $n refers to a specific type within the + typemap specification. For example, if you write this

      +
      +
      +%typemap(in) int *INPUT {
+
+}
+
      +
      +

      then $1 refers to int *INPUT. If you have a typemap like + this,

      +
      +
      +%typemap(in) (int argc, char *argv[]) {
+  ...
+}
+
      +
      +

      then $1 refers to int argc and $2 refers to char + *argv[].

      +

      Substitutions related to types and names always fill in values from + the actual code that was matched. This is useful when a typemap might + match multiple C datatype. For example:

      +
      +
      +%typemap(in)  int, short, long {
+   $1 = ($1_ltype) PyInt_AsLong($input);
+}
+
      +
      +

      In this case, $1_ltype is replaced with the datatype that + is actually matched.

      +

      When typemap code is emitted, the C/C++ datatype of the special + variables $1 and $2 is always an "ltype." An "ltype" + is simply a type that can legally appear on the left-hand side of a C + assignment operation. Here are a few examples of types and ltypes:

      +
      +
      +type              ltype
+------            ----------------
+int               int
+const int         int
+const int *       int *
+int [4]           int *
+int [4][5]        int (*)[5]
+
      +
      +

      In most cases a ltype is simply the C datatype with qualifiers + stripped off. In addition, arrays are converted into pointers.

      +

      Variables such as $&1_type and $*1_type are used + to safely modify the type by removing or adding pointers. Although not + needed in most typemaps, these substitutions are sometimes needed to + properly work with typemaps that convert values between pointers and + values.

      +

      If necessary, type related substitutions can also be used when + declaring locals. For example:

      +
      +
      +%typemap(in) int * ($*1_type temp) {
+    temp = PyInt_AsLong($input);
+    $1 = &temp;
+}
+
      +
      +

      There is one word of caution about declaring local variables in this + manner. If you declare a local variable using a type substitution such + as $1_ltype temp, it won't work like you expect for arrays and + certain kinds of pointers. For example, if you wrote this,

      +
      +
      +%typemap(in) int [10][20] {
+   $1_ltype temp;
+}
+
      +
      +

      then the declaration of temp will be expanded as

      +
      +
      +int (*)[20] temp;
+
      +
      +

      This is illegal C syntax and won't compile. There is currently no + straightforward way to work around this problem in SWIG due to the way + that typemap code is expanded and processed. However, one possible + workaround is to simply pick an alternative type such as void * + and use casts to get the correct type when needed. For example:

      +
      +
      +%typemap(in) int [10][20] {
+   void *temp;
+   ...
+   (($1_ltype) temp)[i][j] = x;    /* set a value */
+   ...
+}
+
      +
      +

      Another approach, which only works for arrays is to use the +$1_basetype substitution. For example:

      +
      +
      +%typemap(in) int [10][20] {
+   $1_basetype temp[10][20];
+   ...
+   temp[i][j] = x;    /* set a value */
+   ...
+}
+
      +
      +

      10.4.4 Special + variable macros

      +

      Special variable macros are like macro functions in that they take + one or more input arguments which are used for the macro expansion. + They look like macro/function calls but use the special variable $ + prefix to the macro name. Note that unlike normal macros, the expansion + is not done by the preprocessor, it is done during the SWIG + parsing/compilation stages. The following special variable macros are + available across all language modules.

      +

      10.4.4.1 + $descriptor(type)

      +

      This macro expands into the type descriptor structure for any C/C++ + type specified in type. It behaves like the $1_descriptor + special variable described above except that the type to expand is + taken from the macro argument rather than inferred from the typemap + type. For example, $descriptor(std::vector<int> *) will expand + into SWIGTYPE_p_std__vectorT_int_t. This macro is mostly used + in the scripting target languages and is demonstrated later in the +Run-time type checker usage section.

      +

      10.4.4.2 + $typemap(method, typepattern)

      +

      This macro uses the pattern + matching rules described earlier to lookup and then substitute the + special variable macro with the code in the matched typemap. The + typemap to search for is specified by the arguments, where method + is the typemap method name and typepattern is a type pattern + as per the %typemap specification in the +Defining a typemap section.

      +

      The special variables within the matched typemap are expanded into + those for the matched typemap type, not the typemap within which the + macro is called. In practice, there is little use for this macro in the + scripting target languages. It is mostly used in the target languages + that are statically typed as a way to obtain the target language type + given the C/C++ type and more commonly only when the C++ type is a + template parameter.

      +

      The example below is for C# only and uses some typemap method names + documented in the C# chapter, but it shows some of the possible syntax + variations.

      +
      +
      +%typemap(cstype) unsigned long    "uint"
+%typemap(cstype) unsigned long bb "bool"
+%typemap(cscode) BarClass %{
+  void foo($typemap(cstype, unsigned long aa) var1,
+           $typemap(cstype, unsigned long bb) var2,
+           $typemap(cstype, (unsigned long bb)) var3,
+           $typemap(cstype, unsigned long) var4)
+  {
+    // do something
+  }
+%}
+
      +
      +

      The result is the following expansion

      +
      +
      +%typemap(cstype) unsigned long    "uint"
+%typemap(cstype) unsigned long bb "bool"
+%typemap(cscode) BarClass %{
+  void foo(uint var1,
+           bool var2,
+           bool var3,
+           uint var4)
+  {
+    // do something
+  }
+%}
+
      +
      +

      10.5 Common typemap methods

      +

      The set of typemaps recognized by a language module may vary. + However, the following typemap methods are nearly universal:

      +

      10.5.1 "in" typemap

      +

      The "in" typemap is used to convert function arguments from the + target language to C. For example:

      +
      +
      +%typemap(in) int {
+   $1 = PyInt_AsLong($input);
+}
+
      +
      +

      The following special variables are available:

      +
      +
      +$input            - Input object holding value to be converted.
+$symname          - Name of function/method being wrapped
+
      +
      +

      This is probably the most commonly redefined typemap because it can + be used to implement customized conversions.

      +

      In addition, the "in" typemap allows the number of converted + arguments to be specified. The numinputs attributes + facilitates this. For example:

      +
      +
      +// Ignored argument.
+%typemap(in, numinputs=0) int *out (int temp) {
+    $1 = &temp;
+}
+
      +
      +

      At this time, only zero or one arguments may be converted. When +numinputs is set to 0, the argument is effectively ignored and + cannot be supplied from the target language. The argument is still + required when making the C/C++ call and the above typemap shows the + value used is instead obtained from a locally declared variable called +temp. Usually numinputs is not specified, whereupon the + default value is 1, that is, there is a one to one mapping of the + number of arguments when used from the target language to the C/C++ + call. Multi-argument + typemaps provide a similar concept where the number of arguments + mapped from the target language to C/C++ can be changed for more tha + multiple adjacent C/C++ arguments.

      +

      Compatibility note: Specifying numinputs=0 is the + same as the old "ignore" typemap.

      +

      10.5.2 "typecheck" typemap

      +

      The "typecheck" typemap is used to support overloaded functions and + methods. It merely checks an argument to see whether or not it matches + a specific type. For example:

      +
      +
      +%typemap(typecheck,precedence=SWIG_TYPECHECK_INTEGER) int {
+   $1 = PyInt_Check($input) ? 1 : 0;
+}
+
      +
      +

      For typechecking, the $1 variable is always a simple integer that is + set to 1 or 0 depending on whether or not the input argument is the + correct type.

      +

      If you define new "in" typemaps and your program uses + overloaded methods, you should also define a collection of "typecheck" + typemaps. More details about this follow in a later section on + "Typemaps and Overloading."

      +

      10.5.3 "out" typemap

      +

      The "out" typemap is used to convert function/method return values + from C into the target language. For example:

      +
      +
      +%typemap(out) int {
+   $result = PyInt_FromLong($1);
+}
+
      +
      +

      The following special variables are available.

      +
      +
      +$result           - Result object returned to target language.
+$symname          - Name of function/method being wrapped
+
      +
      +

      The "out" typemap supports an optional attribute flag called + "optimal". This is for code optimisation and is detailed in the +Optimal code generation when returning by value section.

      +

      10.5.4 "arginit" typemap

      +

      The "arginit" typemap is used to set the initial value of a function + argument--before any conversion has occurred. This is not normally + necessary, but might be useful in highly specialized applications. For + example:

      +
      +
      +// Set argument to NULL before any conversion occurs
+%typemap(arginit) int *data {
+   $1 = NULL;
+}
+
      +
      +

      10.5.5 "default" typemap

      +

      The "default" typemap is used to turn an argument into a default + argument. For example:

      +
      +
      +%typemap(default) int flags {
+   $1 = DEFAULT_FLAGS;
+}
+...
+int foo(int x, int y, int flags);
+
      +
      +

      The primary use of this typemap is to either change the wrapping of + default arguments or specify a default argument in a language where + they aren't supported (like C). Target languages that do not support + optional arguments, such as Java and C#, effectively ignore the value + specified by this typemap as all arguments must be given.

      +

      Once a default typemap has been applied to an argument, all + arguments that follow must have default values. See the +Default/optional arguments section for further information on + default argument wrapping.

      +

      10.5.6 "check" typemap

      +

      The "check" typemap is used to supply value checking code during + argument conversion. The typemap is applied after arguments + have been converted. For example:

      +
      +
      +%typemap(check) int positive {
+   if ($1 <= 0) {
+       SWIG_exception(SWIG_ValueError,"Expected positive value.");
+   }
+}
+
      +
      +

      10.5.7 "argout" typemap

      +

      The "argout" typemap is used to return values from arguments. This + is most commonly used to write wrappers for C/C++ functions that need + to return multiple values. The "argout" typemap is almost always + combined with an "in" typemap---possibly to ignore the input value. For + example:

      +
      +
      +/* Set the input argument to point to a temporary variable */
+%typemap(in, numinputs=0) int *out (int temp) {
+   $1 = &temp;
+}
+
+%typemap(argout) int *out {
+   // Append output value $1 to $result
+   ...
+}
+
      +
      +

      The following special variables are available.

      +
      +
      +$result           - Result object returned to target language.
+$input            - The original input object passed.
+$symname          - Name of function/method being wrapped
+
      +
      +

      The code supplied to the "argout" typemap is always placed after the + "out" typemap. If multiple return values are used, the extra return + values are often appended to return value of the function.

      +

      See the typemaps.i library for examples.

      +

      10.5.8 "freearg" typemap

      +

      The "freearg" typemap is used to cleanup argument data. It is only + used when an argument might have allocated resources that need to be + cleaned up when the wrapper function exits. The "freearg" typemap + usually cleans up argument resources allocated by the "in" typemap. For + example:

      +
      +
      +// Get a list of integers
+%typemap(in) int *items {
+   int nitems = Length($input);    
+   $1 = (int *) malloc(sizeof(int)*nitems);
+}
+// Free the list 
+%typemap(freearg) int *items {
+   free($1);
+}
+
      +
      +

      The "freearg" typemap inserted at the end of the wrapper function, + just before control is returned back to the target language. This code + is also placed into a special variable $cleanup that may be + used in other typemaps whenever a wrapper function needs to abort + prematurely.

      +

      10.5.9 "newfree" typemap

      +

      The "newfree" typemap is used in conjunction with the %newobject + directive and is used to deallocate memory used by the return result of + a function. For example:

      +
      +
      +%typemap(newfree) string * {
+   delete $1;
+}
+%typemap(out) string * {
+   $result = PyString_FromString($1->c_str());
+}
+...
+
+%newobject foo;
+...
+string *foo();
+
      +
      +

      See Object ownership and %newobject for + further details.

      +

      10.5.10 "memberin" typemap

      +

      The "memberin" typemap is used to copy data from an already + converted input value into a structure member. It is typically + used to handle array members and other special cases. For example:

      +
      +
      +%typemap(memberin) int [4] {
+   memmove($1, $input, 4*sizeof(int));
+}
+
      +
      +

      It is rarely necessary to write "memberin" typemaps---SWIG already + provides a default implementation for arrays, strings, and other + objects.

      +

      10.5.11 "varin" typemap

      +

      The "varin" typemap is used to convert objects in the target + language to C for the purposes of assigning to a C/C++ global variable. + This is implementation specific.

      +

      10.5.12 "varout" typemap

      +

      The "varout" typemap is used to convert a C/C++ object to an object + in the target language when reading a C/C++ global variable. This is + implementation specific.

      +

      10.5.13 "throws" typemap

      +

      The "throws" typemap is only used when SWIG parses a C++ method with + an exception specification or has the %catches feature + attached to the method. It provides a default mechanism for handling + C++ methods that have declared the exceptions they will throw. The + purpose of this typemap is to convert a C++ exception into an error or + exception in the target language. It is slightly different to the other + typemaps as it is based around the exception type rather than the type + of a parameter or variable. For example:

      +
      +
      +%typemap(throws) const char * %{
+  PyErr_SetString(PyExc_RuntimeError, $1);
+  SWIG_fail;
+%}
+void bar() throw (const char *);
+
      +
      +

      As can be seen from the generated code below, SWIG generates an + exception handler with the catch block comprising the "throws" typemap + content.

      +
      +
      +...
+try {
+    bar();
+}
+catch(char const *_e) {
+    PyErr_SetString(PyExc_RuntimeError, _e);
+    SWIG_fail;
+    
+}
+...
+
      +
      +

      Note that if your methods do not have an exception specification yet + they do throw exceptions, SWIG cannot know how to deal with them. For a + neat way to handle these, see the Exception + handling with %exception section.

      +

      10.6 Some typemap examples

      +

      This section contains a few examples. Consult language module + documentation for more examples.

      +

      10.6.1 Typemaps for arrays

      +

      A common use of typemaps is to provide support for C arrays + appearing both as arguments to functions and as structure members.

      +

      For example, suppose you had a function like this:

      +
      +
      +void set_vector(int type, float value[4]);
+
      +
      +

      If you wanted to handle float value[4] as a list of floats, + you might write a typemap similar to this:

      +
      +
      +
+%typemap(in) float value[4] (float temp[4]) {
+  int i;
+  if (!PySequence_Check($input)) {
+    PyErr_SetString(PyExc_ValueError,"Expected a sequence");
+    return NULL;
+  }
+  if (PySequence_Length($input) != 4) {
+    PyErr_SetString(PyExc_ValueError,"Size mismatch. Expected 4 elements");
+    return NULL;
+  }
+  for (i = 0; i < 4; i++) {
+    PyObject *o = PySequence_GetItem($input,i);
+    if (PyNumber_Check(o)) {
+      temp[i] = (float) PyFloat_AsDouble(o);
+    } else {
+      PyErr_SetString(PyExc_ValueError,"Sequence elements must be numbers");      
+      return NULL;
+    }
+  }
+  $1 = temp;
+}
+
      +
      +

      In this example, the variable temp allocates a small array + on the C stack. The typemap then populates this array and passes it to + the underlying C function.

      +

      When used from Python, the typemap allows the following type of + function call:

      +
      +
      +>>> set_vector(type, [ 1, 2.5, 5, 20 ])
+
      +
      +

      If you wanted to generalize the typemap to apply to arrays of all + dimensions you might write this:

      +
      +
      +%typemap(in) float value[ANY] (float temp[$1_dim0]) {
+  int i;
+  if (!PySequence_Check($input)) {
+    PyErr_SetString(PyExc_ValueError,"Expected a sequence");
+    return NULL;
+  }
+  if (PySequence_Length($input) != $1_dim0) {
+    PyErr_SetString(PyExc_ValueError,"Size mismatch. Expected $1_dim0 elements");
+    return NULL;
+  }
+  for (i = 0; i < $1_dim0; i++) {
+    PyObject *o = PySequence_GetItem($input,i);
+    if (PyNumber_Check(o)) {
+      temp[i] = (float) PyFloat_AsDouble(o);
+    } else {
+      PyErr_SetString(PyExc_ValueError,"Sequence elements must be numbers");      
+      return NULL;
+    }
+  }
+  $1 = temp;
+}
+
      +
      +

      In this example, the special variable $1_dim0 is expanded + with the actual array dimensions. Multidimensional arrays can be + matched in a similar manner. For example:

      +
      +
      +%typemap(in) float matrix[ANY][ANY] (float temp[$1_dim0][$1_dim1]) {
+   ... convert a 2d array ...
+}
+
      +
      +

      For large arrays, it may be impractical to allocate storage on the + stack using a temporary variable as shown. To work with heap allocated + data, the following technique can be used.

      +
      +
      +%typemap(in) float value[ANY] {
+  int i;
+  if (!PySequence_Check($input)) {
+    PyErr_SetString(PyExc_ValueError,"Expected a sequence");
+    return NULL;
+  }
+  if (PySequence_Length($input) != $1_dim0) {
+    PyErr_SetString(PyExc_ValueError,"Size mismatch. Expected $1_dim0 elements");
+    return NULL;
+  }
+  $1 = (float *) malloc($1_dim0*sizeof(float));
+  for (i = 0; i < $1_dim0; i++) {
+    PyObject *o = PySequence_GetItem($input,i);
+    if (PyNumber_Check(o)) {
+      $1[i] = (float) PyFloat_AsDouble(o);
+    } else {
+      PyErr_SetString(PyExc_ValueError,"Sequence elements must be numbers");      
+      free($1);
+      return NULL;
+    }
+  }
+}
+%typemap(freearg) float value[ANY] {
+   if ($1) free($1);
+}
+
      +
      +

      In this case, an array is allocated using malloc. The +freearg typemap is then used to release the argument after the + function has been called.

      +

      Another common use of array typemaps is to provide support for array + structure members. Due to subtle differences between pointers and + arrays in C, you can't just "assign" to a array structure member. + Instead, you have to explicitly copy elements into the array. For + example, suppose you had a structure like this:

      +
      +
      +struct SomeObject {
+	float  value[4];
+        ...
+};
+
      +
      +

      When SWIG runs, it won't produce any code to set the vec + member. You may even get a warning message like this:

      +
      +
      +swig -python  example.i
+Generating wrappers for Python
+example.i:10.  Warning. Array member value will be read-only.
+
      +
      +

      These warning messages indicate that SWIG does not know how you want + to set the vec field.

      +

      To fix this, you can supply a special "memberin" typemap like this:

      +
      +
      +%typemap(memberin) float [ANY] {
+  int i;
+  for (i = 0; i < $1_dim0; i++) {
+      $1[i] = $input[i];
+  }
+}
+
      +
      +

      The memberin typemap is used to set a structure member from data + that has already been converted from the target language to C. In this + case, $input is the local variable in which converted input + data is stored. This typemap then copies this data into the structure.

      +

      When combined with the earlier typemaps for arrays, the combination + of the "in" and "memberin" typemap allows the following usage:

      +
      +
      +>>> s = SomeObject()
+>>> s.x = [1, 2.5, 5, 10]
+
      +
      +

      Related to structure member input, it may be desirable to return + structure members as a new kind of object. For example, in this + example, you will get very odd program behavior where the structure + member can be set nicely, but reading the member simply returns a + pointer:

      +
      +
      +>>> s = SomeObject()
+>>> s.x = [1, 2.5, 5, 10]
+>>> print s.x
+_1008fea8_p_float
+>>> 
+
      +
      +

      To fix this, you can write an "out" typemap. For example:

      +
      +
      +%typemap(out) float [ANY] {
+  int i;
+  $result = PyList_New($1_dim0);
+  for (i = 0; i < $1_dim0; i++) {
+    PyObject *o = PyFloat_FromDouble((double) $1[i]);
+    PyList_SetItem($result,i,o);
+  }
+}
+
      +
      +

      Now, you will find that member access is quite nice:

      +
      +
      +>>> s = SomeObject()
+>>> s.x = [1, 2.5, 5, 10]
+>>> print s.x
+[ 1, 2.5, 5, 10]
+
      +
      +

      Compatibility Note: SWIG1.1 used to provide a special + "memberout" typemap. However, it was mostly useless and has since been + eliminated. To return structure members, simply use the "out" typemap.

      +

      10.6.2 Implementing constraints with + typemaps

      +

      One particularly interesting application of typemaps is the + implementation of argument constraints. This can be done with the + "check" typemap. When used, this allows you to provide code for + checking the values of function arguments. For example :

      +
      +
      +%module math
+
+%typemap(check) double posdouble {
+	if ($1 < 0) {
+		croak("Expecting a positive number");
+	}
+}
+
+...
+double sqrt(double posdouble);
+
+
      +
      +

      This provides a sanity check to your wrapper function. If a negative + number is passed to this function, a Perl exception will be raised and + your program terminated with an error message.

      +

      This kind of checking can be particularly useful when working with + pointers. For example :

      +
      +
      +%typemap(check) Vector * {
+    if ($1 == 0) {
+        PyErr_SetString(PyExc_TypeError,"NULL Pointer not allowed");
+        return NULL;
+   }
+}
+
+
      +
      +

      will prevent any function involving a Vector * from + accepting a NULL pointer. As a result, SWIG can often prevent a + potential segmentation faults or other run-time problems by raising an + exception rather than blindly passing values to the underlying C/C++ + program.

      +

      Note: A more advanced constraint checking system is in development. + Stay tuned.

      +

      10.7 Typemaps for multiple languages

      +

      The code within typemaps is usually language dependent, however, + many languages support the same typemaps. In order to distinguish + typemaps across different languages, the preprocessor should be used. + For example, the "in" typemap for Perl and Ruby could be written as:

      +
      +
      +#if defined(SWIGPERL)
+  %typemap(in) int "$1 = ($1_ltype) SvIV($input);"
+#elif defined(SWIGRUBY)
+  %typemap(in) int "$1 = NUM2INT($input);"
+#else
+  #warning no "in" typemap defined
+#endif
+
      +
      +

      The full set of language specific macros is defined in the +Conditional Compilation section. The example above also shows a + common approach of issuing a warning for an as yet unsupported + language.

      +

      Compatibility note: In SWIG-1.1 different languages could be + distinguished with the language name being put within the %typemap + directive, for example, +
      %typemap(ruby,in) int "$1 = NUM2INT($input);".

      +

      10.8 Optimal code generation when + returning by value

      +

      The "out" typemap is the main typemap for return types. This typemap + supports an optional attribute flag called "optimal", which is for + reducing temporary variables and the amount of generated code, thereby + giving the compiler the opportunity to use return value optimization + for generating faster executing code. It only really makes a difference + when returning objects by value and has some limitations on usage, as + explained later on.

      +

      When a function returns an object by value, SWIG generates code that + instantiates the default type on the stack then assigns the value + returned by the function call to it. A copy of this object is then made + on the heap and this is what is ultimately stored and used from the + target language. This will be clearer considering an example. Consider + running the following code through SWIG:

      +
      +
      +%typemap(out) SWIGTYPE %{
+  $result = new $1_ltype((const $1_ltype &)$1);
+%}
+
+%inline %{
+#include <iostream>
+using namespace std;
+
+struct XX {
+  XX() { cout << "XX()" << endl; }
+  XX(int i) { cout << "XX(" << i << ")" << endl; }
+  XX(const XX &other) { cout << "XX(const XX &)" << endl; }
+  XX & operator =(const XX &other) { cout << "operator=(const XX &)" << endl; return *this; }
+  ~XX() { cout << "~XX()" << endl; }
+  static XX create() { 
+    return XX(0);
+  }
+};
+%}
+
      +
      +

      The "out" typemap shown is the default typemap for C# when returning + by objects by value. When making a call to XX::create() from + C#, the output is as follows:

      +
      +
      +XX()
+XX(0)
+operator=(const XX &)
+~XX()
+XX(const XX &)
+~XX()
+~XX()
+
      +
      +

      Note that three objects are being created as well as an assignment. + Wouldn't it be great if the XX::create() method was the only + time a constructor was called? As the method returns by value, this is + asking a lot and the code that SWIG generates by default makes it + impossible for the compiler to use return value optimisation (RVO) +. However, this is where the "optimal" attribute in the "out" typemap + can help out. If the typemap code is kept the same and just the + "optimal" attribute specified like this:

      +
      +
      +%typemap(out, optimal="1") SWIGTYPE %{
+  $result = new $1_ltype((const $1_ltype &)$1);
+%}
+
      +
      +

      then when the code is run again, the output is simply:

      +
      +
      +XX(0)
+~XX()
+
      +
      +

      How the "optimal" attribute works is best explained using the + generated code. Without "optimal", the generated code is:

      +
      +
      +SWIGEXPORT void * SWIGSTDCALL CSharp_XX_create() {
+  void * jresult ;
+  XX result;
+  result = XX::create();
+  jresult = new XX((const XX &)result);
+  return jresult;
+}
+
+
      +
      +

      With the "optimal" attribute, the code is:

      +
      +
      +SWIGEXPORT void * SWIGSTDCALL CSharp_XX_create() {
+  void * jresult ;
+  jresult = new XX((const XX &)XX::create());
+  return jresult;
+}
+
      +
      +

      The major difference is the result temporary variable + holding the value returned from XX::create() is no longer + generated and instead the copy constructor call is made directly from + the value returned by XX::create(). With modern compilers + implementing RVO, the copy is not actually done, in fact the object is + never created on the stack in XX::create() at all, it is + simply created directly on the heap. In the first instance, the $1 + special variable in the typemap is expanded into result. In + the second instance, $1 is expanded into XX::create() + and this is essentially what the "optimal" attribute is telling SWIG to + do.

      +

      The "optimal" attribute optimisation is not turned on by default as + it has a number of restrictions. Firstly, some code cannot be condensed + into a simple call for passing into the copy constructor. One common + occurrence is when %exception is used. + Consider adding the following %exception to the example:

      +
      +
      +%exception XX::create() %{
+try {
+  $action
+} catch(const std::exception &e) {
+  cout << e.what() << endl;
+}
+%}
+
      +
      +

      SWIG can detect when the "optimal" attribute cannot be used and will + ignore it and in this case will issue the following warning:

      +
      +
      +example.i:28: Warning(474): Method XX::create() usage of the optimal attribute in the out 
+typemap at example.i:14 ignored as the following cannot be used to generate optimal code: 
+try {
+  result = XX::create();
+} catch(const std::exception &e) {
+  cout << e.what() << endl;
+}
+
      +
      +

      It should be clear that the above code cannot be used as the + argument to the copy constructor call, ie for the $1 + substitution.

      +

      Secondly, if the typemaps uses $1 more than once, then + multiple calls to the wrapped function will be made. Obviously that is + not very optimal. In fact SWIG attempts to detect this and will issue a + warning something like:

      +
      +
      +example.i:21: Warning(475): Multiple calls to XX::create() might be generated due to 
+optimal attribute usage in the out typemap at example.i:7.
+
      +
      +

      However, it doesn't always get it right, for example when $1 + is within some commented out code.

      +

      10.9 Multi-argument + typemaps

      +

      So far, the typemaps presented have focused on the problem of + dealing with single values. For example, converting a single input + object to a single argument in a function call. However, certain + conversion problems are difficult to handle in this manner. As an + example, consider the example at the very beginning of this chapter:

      +
      +
      +int foo(int argc, char *argv[]);
+
      +
      +

      Suppose that you wanted to wrap this function so that it accepted a + single list of strings like this:

      +
      +
      +>>> foo(["ale","lager","stout"])
+
      +
      +

      To do this, you not only need to map a list of strings to char + *argv[], but the value of int argc is implicitly + determined by the length of the list. Using only simple typemaps, this + type of conversion is possible, but extremely painful. Therefore, + SWIG1.3 introduces the notion of multi-argument typemaps.

      +

      A multi-argument typemap is a conversion rule that specifies how to + convert a single object in the target language to set of + consecutive function arguments in C/C++. For example, the following + multi-argument maps perform the conversion described for the above + example:

      +
      +
      +%typemap(in) (int argc, char *argv[]) {
+  int i;
+  if (!PyList_Check($input)) {
+    PyErr_SetString(PyExc_ValueError, "Expecting a list");
+    return NULL;
+  }
+  $1 = PyList_Size($input);
+  $2 = (char **) malloc(($1+1)*sizeof(char *));
+  for (i = 0; i < $1; i++) {
+    PyObject *s = PyList_GetItem($input,i);
+    if (!PyString_Check(s)) {
+        free($2);
+        PyErr_SetString(PyExc_ValueError, "List items must be strings");
+        return NULL;
+    }
+    $2[i] = PyString_AsString(s);
+  }
+  $2[i] = 0;
+}
+
+%typemap(freearg) (int argc, char *argv[]) {
+   if ($2) free($2);
+}
+
      +
      +

      A multi-argument map is always specified by surrounding the + arguments with parentheses as shown. For example:

      +
      +
      +%typemap(in) (int argc, char *argv[]) { ... }
+
      +
      +

      Within the typemap code, the variables $1, $2, and + so forth refer to each type in the map. All of the usual substitutions + apply--just use the appropriate $1 or $2 prefix on + the variable name (e.g., $2_type, $1_ltype, etc.)

      +

      Multi-argument typemaps always have precedence over simple typemaps + and SWIG always performs longest-match searching. Therefore, you will + get the following behavior:

      +
      +
      +%typemap(in) int argc                              { ... typemap 1 ... }
+%typemap(in) (int argc, char *argv[])              { ... typemap 2 ... }
+%typemap(in) (int argc, char *argv[], char *env[]) { ... typemap 3 ... }
+
+int foo(int argc, char *argv[]);                   // Uses typemap 2
+int bar(int argc, int x);                          // Uses typemap 1
+int spam(int argc, char *argv[], char *env[]);     // Uses typemap 3
+
      +
      +

      It should be stressed that multi-argument typemaps can appear + anywhere in a function declaration and can appear more than once. For + example, you could write this:

      +
      +
      +%typemap(in) (int scount, char *swords[]) { ... }
+%typemap(in) (int wcount, char *words[]) { ... }
+
+void search_words(int scount, char *swords[], int wcount, char *words[], int maxcount);
+
      +
      +

      Other directives such as %apply and %clear also + work with multi-argument maps. For example:

      +
      +
      +%apply (int argc, char *argv[]) {
+    (int scount, char *swords[]),
+    (int wcount, char *words[])
+};
+...
+%clear (int scount, char *swords[]), (int wcount, char *words[]);
+...
+
      +
      +

      Although multi-argument typemaps may seem like an exotic, little + used feature, there are several situations where they make sense. + First, suppose you wanted to wrap functions similar to the low-level +read() and write() system calls. For example:

      +
      +
      +typedef unsigned int size_t;
+
+int read(int fd, void *rbuffer, size_t len);
+int write(int fd, void *wbuffer, size_t len);
+
      +
      +

      As is, the only way to use the functions would be to allocate memory + and pass some kind of pointer as the second argument---a process that + might require the use of a helper function. However, using + multi-argument maps, the functions can be transformed into something + more natural. For example, you might write typemaps like this:

      +
      +
      +// typemap for an outgoing buffer
+%typemap(in) (void *wbuffer, size_t len) {
+   if (!PyString_Check($input)) {
+       PyErr_SetString(PyExc_ValueError, "Expecting a string");
+       return NULL;
+   }
+   $1 = (void *) PyString_AsString($input);
+   $2 = PyString_Size($input);
+}
+
+// typemap for an incoming buffer
+%typemap(in) (void *rbuffer, size_t len) {
+   if (!PyInt_Check($input)) {
+       PyErr_SetString(PyExc_ValueError, "Expecting an integer");
+       return NULL;
+   }
+   $2 = PyInt_AsLong($input);
+   if ($2 < 0) {
+       PyErr_SetString(PyExc_ValueError, "Positive integer expected");
+       return NULL;
+   }
+   $1 = (void *) malloc($2);
+}
+
+// Return the buffer.  Discarding any previous return result
+%typemap(argout) (void *rbuffer, size_t len) {
+   Py_XDECREF($result);   /* Blow away any previous result */
+   if (result < 0) {      /* Check for I/O error */
+       free($1);
+       PyErr_SetFromErrno(PyExc_IOError);
+       return NULL;
+   }
+   $result = PyString_FromStringAndSize($1,result);
+   free($1);
+}
+
      +
      +

      (note: In the above example, $result and result + are two different variables. result is the real C datatype + that was returned by the function. $result is the scripting + language object being returned to the interpreter.).

      +

      Now, in a script, you can write code that simply passes buffers as + strings like this:

      +
      +
      +>>> f = example.open("Makefile")
+>>> example.read(f,40)
+'TOP        = ../..\nSWIG       = $(TOP)/.'
+>>> example.read(f,40)
+'./swig\nSRCS       = example.c\nTARGET    '
+>>> example.close(f)
+0
+>>> g = example.open("foo", example.O_WRONLY | example.O_CREAT, 0644)
+>>> example.write(g,"Hello world\n")
+12
+>>> example.write(g,"This is a test\n")
+15
+>>> example.close(g)
+0
+>>>
+
      +
      +

      A number of multi-argument typemap problems also arise in libraries + that perform matrix-calculations--especially if they are mapped onto + low-level Fortran or C code. For example, you might have a function + like this:

      +
      +
      +int is_symmetric(double *mat, int rows, int columns);
+
      +
      +

      In this case, you might want to pass some kind of higher-level + object as an matrix. To do this, you could write a multi-argument + typemap like this:

      +
      +
      +%typemap(in) (double *mat, int rows, int columns) {
+    MatrixObject *a;
+    a = GetMatrixFromObject($input);     /* Get matrix somehow */
+
+    /* Get matrix properties */
+    $1 = GetPointer(a);
+    $2 = GetRows(a);
+    $3 = GetColumns(a);
+}
+
      +
      +

      This kind of technique can be used to hook into scripting-language + matrix packages such as Numeric Python. However, it should also be + stressed that some care is in order. For example, when crossing + languages you may need to worry about issues such as row-major vs. + column-major ordering (and perform conversions if needed).

      +

      10.10 The run-time type checker

      +

      Most scripting languages need type information at run-time. This + type information can include how to construct types, how to garbage + collect types, and the inheritance relationships between types. If the + language interface does not provide its own type information storage, + the generated SWIG code needs to provide it.

      +

      Requirements for the type system:

      +
        +
      • Store inheritance and type equivalence information and be able to + correctly re-create the type pointer.
        • +
      • Share type information between modules.
        • +
      • Modules can be loaded in any order, irregardless of actual type + dependency.
        • +
      • Avoid the use of dynamically allocated memory, and library/system + calls in general.
        • +
      • Provide a reasonably fast implementation, minimizing the lookup time + for all language modules.
        • +
      • Custom, language specific information can be attached to types.
        • +
      • Modules can be unloaded from the type system.
        • +
      +

      10.10.1 Implementation

      +

      The run-time type checker is used by many, but not all, of SWIG's + supported target languages. The run-time type checker features are not + required and are thus not used for strongly typed languages such as + Java and C#. The scripting and scheme based languages rely on it and it + forms a critical part of SWIG's operation for these languages.

      +

      When pointers, arrays, and objects are wrapped by SWIG, they are + normally converted into typed pointer objects. For example, an instance + of Foo * might be a string encoded like this:

      +
      +
      +_108e688_p_Foo
+
      +
      +

      At a basic level, the type checker simply restores some type-safety + to extension modules. However, the type checker is also responsible for + making sure that wrapped C++ classes are handled correctly---especially + when inheritance is used. This is especially important when an + extension module makes use of multiple inheritance. For example:

      +
      +
      +class Foo {
+   int x;
+};
+
+class Bar {
+   int y;
+};
+
+class FooBar : public Foo, public Bar {
+   int z;
+};
+
      +
      +

      When the class FooBar is organized in memory, it contains + the contents of the classes Foo and Bar as well as + its own data members. For example:

      +
      +
      +FooBar --> | -----------|  <-- Foo
+           |   int x    |
+           |------------|  <-- Bar
+           |   int y    |
+           |------------|
+           |   int z    |
+           |------------|
+
      +
      +

      Because of the way that base class data is stacked together, the + casting of a Foobar * to either of the base classes may change + the actual value of the pointer. This means that it is generally not + safe to represent pointers using a simple integer or a bare void * +---type tags are needed to implement correct handling of pointer values + (and to make adjustments when needed).

      +

      In the wrapper code generated for each language, pointers are + handled through the use of special type descriptors and conversion + functions. For example, if you look at the wrapper code for Python, you + will see code like this:

      +
      +
      +if ((SWIG_ConvertPtr(obj0,(void **) &arg1, SWIGTYPE_p_Foo,1)) == -1) return NULL;
+
      +
      +

      In this code, SWIGTYPE_p_Foo is the type descriptor that + describes Foo *. The type descriptor is actually a pointer to + a structure that contains information about the type name to use in the + target language, a list of equivalent typenames (via typedef or + inheritance), and pointer value handling information (if applicable). + The SWIG_ConvertPtr() function is simply a utility function + that takes a pointer object in the target language and a + type-descriptor objects and uses this information to generate a C++ + pointer. However, the exact name and calling conventions of the + conversion function depends on the target language (see language + specific chapters for details).

      +

      The actual type code is in swigrun.swg, and gets inserted near the + top of the generated swig wrapper file. The phrase "a type X that can + cast into a type Y" means that given a type X, it can be converted into + a type Y. In other words, X is a derived class of Y or X is a typedef + of Y. The structure to store type information looks like this:

      +
      +
      +/* Structure to store information on one type */
+typedef struct swig_type_info {
+  const char *name;             /* mangled name of this type */
+  const char *str;              /* human readable name for this type */
+  swig_dycast_func dcast;       /* dynamic cast function down a hierarchy */
+  struct swig_cast_info *cast;  /* Linked list of types that can cast into this type */
+  void *clientdata;             /* Language specific type data */
+} swig_type_info;
+
+/* Structure to store a type and conversion function used for casting */
+typedef struct swig_cast_info {
+  swig_type_info *type;          /* pointer to type that is equivalent to this type */
+  swig_converter_func converter; /* function to cast the void pointers */
+  struct swig_cast_info *next;   /* pointer to next cast in linked list */
+  struct swig_cast_info *prev;   /* pointer to the previous cast */
+} swig_cast_info;
+
      +
      +

      Each swig_type_info stores a linked list of types that it + is equivalent to. Each entry in this doubly linked list stores a + pointer back to another swig_type_info structure, along with a pointer + to a conversion function. This conversion function is used to solve the + above problem of the FooBar class, correctly returning a pointer to the + type we want.

      +

      The basic problem we need to solve is verifying and building + arguments passed to functions. So going back to the +SWIG_ConvertPtr() function example from above, we are expecting a +Foo * and need to check if obj0 is in fact a Foo * +. From before, SWIGTYPE_p_Foo is just a pointer to the +swig_type_info structure describing Foo *. So we loop + through the linked list of swig_cast_info structures attached + to SWIGTYPE_p_Foo. If we see that the type of obj0 is + in the linked list, we pass the object through the associated + conversion function and then return a positive. If we reach the end of + the linked list without a match, then obj0 can not be + converted to a Foo * and an error is generated.

      +

      Another issue needing to be addressed is sharing type information + between multiple modules. More explicitly, we need to have ONE +swig_type_info for each type. If two modules both use the type, the + second module loaded must lookup and use the swig_type_info structure + from the module already loaded. Because no dynamic memory is used and + the circular dependencies of the casting information, loading the type + information is somewhat tricky, and not explained here. A complete + description is in the Lib/swiginit.swg file (and near the top + of any generated file).

      +

      Each module has one swig_module_info structure which looks like + this:

      +
      +
      +/* Structure used to store module information
+ * Each module generates one structure like this, and the runtime collects
+ * all of these structures and stores them in a circularly linked list.*/
+typedef struct swig_module_info {
+  swig_type_info **types;         /* Array of pointers to swig_type_info structs in this module */
+  int size;                       /* Number of types in this module */
+  struct swig_module_info *next;  /* Pointer to next element in circularly linked list */
+  swig_type_info **type_initial;  /* Array of initially generated type structures */
+  swig_cast_info **cast_initial;  /* Array of initially generated casting structures */
+  void *clientdata;               /* Language specific module data */
+} swig_module_info;
+
      +
      +

      Each module stores an array of pointers to swig_type_info + structures and the number of types in this module. So when a second + module is loaded, it finds the swig_module_info structure for + the first module and searches the array of types. If any of its own + types are in the first module and have already been loaded, it uses + those swig_type_info structures rather than creating new ones. + These swig_module_info structures are chained together in a + circularly linked list.

      +

      10.10.2 Usage

      +

      This section covers how to use these functions from typemaps. To + learn how to call these functions from external files (not the + generated _wrap.c file), see the External + access to the run-time system section.

      +

      When pointers are converted in a typemap, the typemap code often + looks similar to this:

      +
      +
      +%typemap(in) Foo * {
+  if ((SWIG_ConvertPtr($input, (void **) &$1, $1_descriptor)) == -1) return NULL;
+}
+
      +
      +

      The most critical part is the typemap is the use of the +$1_descriptor special variable. When placed in a typemap, this is + expanded into the SWIGTYPE_* type descriptor object above. As + a general rule, you should always use $1_descriptor instead of + trying to hard-code the type descriptor name directly.

      +

      There is another reason why you should always use the +$1_descriptor variable. When this special variable is expanded, + SWIG marks the corresponding type as "in use." When type-tables and + type information is emitted in the wrapper file, descriptor information + is only generated for those datatypes that were actually used in the + interface. This greatly reduces the size of the type tables and + improves efficiency.

      +

      Occasionally, you might need to write a typemap that needs to + convert pointers of other types. To handle this, the special variable + macro $descriptor(type) covered earlier can be used to + generate the SWIG type descriptor name for any C datatype. For example:

      +
      +
      +%typemap(in) Foo * {
+  if ((SWIG_ConvertPtr($input, (void **) &$1, $1_descriptor)) == -1) {
+     Bar *temp;
+     if ((SWIG_ConvertPtr($input, (void **) &temp, $descriptor(Bar *)) == -1) {
+         return NULL;
+     }
+     $1 = (Foo *) temp;
+  }
+}
+
      +
      +

      The primary use of $descriptor(type) is when writing + typemaps for container objects and other complex data structures. There + are some restrictions on the argument---namely it must be a fully + defined C datatype. It can not be any of the special typemap variables.

      +

      In certain cases, SWIG may not generate type-descriptors like you + expect. For example, if you are converting pointers in some + non-standard way or working with an unusual combination of interface + files and modules, you may find that SWIG omits information for a + specific type descriptor. To fix this, you may need to use the +%types directive. For example:

      +
      +
      +%types(int *, short *, long *, float *, double *);
+
      +
      +

      When %types is used, SWIG generates type-descriptor + information even if those datatypes never appear elsewhere in the + interface file.

      +

      Further details about the run-time type checking can be found in the + documentation for individual language modules. Reading the source code + may also help. The file Lib/swigrun.swg in the SWIG library + contains all of the source code for type-checking. This code is also + included in every generated wrapped file so you probably just look at + the output of SWIG to get a better sense for how types are managed.

      +

      10.11 Typemaps and overloading

      +

      In many target languages, SWIG fully supports C++ overloaded methods + and functions. For example, if you have a collection of functions like + this:

      +
      +
      +int foo(int x);
+int foo(double x);
+int foo(char *s, int y);
+
      +
      +

      You can access the functions in a normal way from the scripting + interpreter:

      +
      +
      +# Python
+foo(3)           # foo(int)
+foo(3.5)         # foo(double)
+foo("hello",5)   # foo(char *, int)
+
+# Tcl
+foo 3            # foo(int)
+foo 3.5          # foo(double)
+foo hello 5      # foo(char *, int)
+
      +
      +

      To implement overloading, SWIG generates a separate wrapper function + for each overloaded method. For example, the above functions would + produce something roughly like this:

      +
      +
      +// wrapper pseudocode
+_wrap_foo_0(argc, args[]) {       // foo(int)
+   int arg1;
+   int result;
+   ...
+   arg1 = FromInteger(args[0]);
+   result = foo(arg1);
+   return ToInteger(result);
+}
+
+_wrap_foo_1(argc, args[]) {       // foo(double)
+   double arg1;
+   int result;
+   ...
+   arg1 = FromDouble(args[0]);
+   result = foo(arg1);
+   return ToInteger(result);
+}
+
+_wrap_foo_2(argc, args[]) {       // foo(char *, int)
+   char *arg1;
+   int   arg2;
+   int result;
+   ...
+   arg1 = FromString(args[0]);
+   arg2 = FromInteger(args[1]);
+   result = foo(arg1,arg2);
+   return ToInteger(result);
+}
+
+
      +
      +

      Next, a dynamic dispatch function is generated:

      +
      +
      +_wrap_foo(argc, args[]) {
+   if (argc == 1) {
+       if (IsInteger(args[0])) {
+           return _wrap_foo_0(argc,args);
+       } 
+       if (IsDouble(args[0])) {
+           return _wrap_foo_1(argc,args);
+       }
+   }
+   if (argc == 2) {
+       if (IsString(args[0]) && IsInteger(args[1])) {
+          return _wrap_foo_2(argc,args);
+       }
+   }
+   error("No matching function!\n");
+}
+
      +
      +

      The purpose of the dynamic dispatch function is to select the + appropriate C++ function based on argument types---a task that must be + performed at runtime in most of SWIG's target languages.

      +

      The generation of the dynamic dispatch function is a relatively + tricky affair. Not only must input typemaps be taken into account + (these typemaps can radically change the types of arguments accepted), + but overloaded methods must also be sorted and checked in a very + specific order to resolve potential ambiguity. A high-level overview of + this ranking process is found in the "SWIG and C++ +" chapter. What isn't mentioned in that chapter is the mechanism by + which it is implemented---as a collection of typemaps.

      +

      To support dynamic dispatch, SWIG first defines a general purpose + type hierarchy as follows:

      +
      +
      +Symbolic Name                   Precedence Value
+------------------------------  ------------------
+SWIG_TYPECHECK_POINTER           0  
+SWIG_TYPECHECK_VOIDPTR           10 
+SWIG_TYPECHECK_BOOL              15 
+SWIG_TYPECHECK_UINT8             20 
+SWIG_TYPECHECK_INT8              25 
+SWIG_TYPECHECK_UINT16            30 
+SWIG_TYPECHECK_INT16             35 
+SWIG_TYPECHECK_UINT32            40 
+SWIG_TYPECHECK_INT32             45 
+SWIG_TYPECHECK_UINT64            50 
+SWIG_TYPECHECK_INT64             55 
+SWIG_TYPECHECK_UINT128           60 
+SWIG_TYPECHECK_INT128            65 
+SWIG_TYPECHECK_INTEGER           70 
+SWIG_TYPECHECK_FLOAT             80 
+SWIG_TYPECHECK_DOUBLE            90 
+SWIG_TYPECHECK_COMPLEX           100 
+SWIG_TYPECHECK_UNICHAR           110 
+SWIG_TYPECHECK_UNISTRING         120 
+SWIG_TYPECHECK_CHAR              130 
+SWIG_TYPECHECK_STRING            140 
+SWIG_TYPECHECK_BOOL_ARRAY        1015 
+SWIG_TYPECHECK_INT8_ARRAY        1025 
+SWIG_TYPECHECK_INT16_ARRAY       1035 
+SWIG_TYPECHECK_INT32_ARRAY       1045 
+SWIG_TYPECHECK_INT64_ARRAY       1055 
+SWIG_TYPECHECK_INT128_ARRAY      1065 
+SWIG_TYPECHECK_FLOAT_ARRAY       1080 
+SWIG_TYPECHECK_DOUBLE_ARRAY      1090 
+SWIG_TYPECHECK_CHAR_ARRAY        1130 
+SWIG_TYPECHECK_STRING_ARRAY      1140 
+
      +
      +

      (These precedence levels are defined in swig.swg, a library + file that's included by all target language modules.)

      +

      In this table, the precedence-level determines the order in which + types are going to be checked. Low values are always checked before + higher values. For example, integers are checked before floats, single + values are checked before arrays, and so forth.

      +

      Using the above table as a guide, each target language defines a + collection of "typecheck" typemaps. The follow excerpt from the Python + module illustrates this:

      +
      +
      +/* Python type checking rules */
+/* Note:  %typecheck(X) is a macro for %typemap(typecheck,precedence=X) */
+
+%typecheck(SWIG_TYPECHECK_INTEGER)
+	 int, short, long,
+ 	 unsigned int, unsigned short, unsigned long,
+	 signed char, unsigned char,
+	 long long, unsigned long long,
+	 const int &, const short &, const long &,
+ 	 const unsigned int &, const unsigned short &, const unsigned long &,
+	 const long long &, const unsigned long long &,
+	 enum SWIGTYPE,
+         bool, const bool & 
+{
+  $1 = (PyInt_Check($input) || PyLong_Check($input)) ? 1 : 0;
+}
+
+%typecheck(SWIG_TYPECHECK_DOUBLE)
+	float, double,
+	const float &, const double &
+{
+  $1 = (PyFloat_Check($input) || PyInt_Check($input) || PyLong_Check($input)) ? 1 : 0;
+}
+
+%typecheck(SWIG_TYPECHECK_CHAR) char {
+  $1 = (PyString_Check($input) && (PyString_Size($input) == 1)) ? 1 : 0;
+}
+
+%typecheck(SWIG_TYPECHECK_STRING) char * {
+  $1 = PyString_Check($input) ? 1 : 0;
+}
+
+%typecheck(SWIG_TYPECHECK_POINTER) SWIGTYPE *, SWIGTYPE &, SWIGTYPE [] {
+  void *ptr;
+  if (SWIG_ConvertPtr($input, (void **) &ptr, $1_descriptor, 0) == -1) {
+    $1 = 0;
+    PyErr_Clear();
+  } else {
+    $1 = 1;
+  }
+}
+
+%typecheck(SWIG_TYPECHECK_POINTER) SWIGTYPE {
+  void *ptr;
+  if (SWIG_ConvertPtr($input, (void **) &ptr, $&1_descriptor, 0) == -1) {
+    $1 = 0;
+    PyErr_Clear();
+  } else {
+    $1 = 1;
+  }
+}
+
+%typecheck(SWIG_TYPECHECK_VOIDPTR) void * {
+  void *ptr;
+  if (SWIG_ConvertPtr($input, (void **) &ptr, 0, 0) == -1) {
+    $1 = 0;
+    PyErr_Clear();
+  } else {
+    $1 = 1;
+  }
+}
+
+%typecheck(SWIG_TYPECHECK_POINTER) PyObject *
+{
+  $1 = ($input != 0);
+}
+
      +
      +

      It might take a bit of contemplation, but this code has merely + organized all of the basic C++ types, provided some simple + type-checking code, and assigned each type a precedence value.

      +

      Finally, to generate the dynamic dispatch function, SWIG uses the + following algorithm:

      +
        +
      • Overloaded methods are first sorted by the number of required + arguments.
        • +
      • Methods with the same number of arguments are then sorted by + precedence values of argument types.
        • +
      • Typecheck typemaps are then emitted to produce a dispatch function + that checks arguments in the correct order.
        • +
      +

      If you haven't written any typemaps of your own, it is unnecessary + to worry about the typechecking rules. However, if you have written new + input typemaps, you might have to supply a typechecking rule as well. + An easy way to do this is to simply copy one of the existing + typechecking rules. Here is an example,

      +
      +
      +// Typemap for a C++ string
+%typemap(in) std::string {
+    if (PyString_Check($input)) {
+         $1 = std::string(PyString_AsString($input));
+     } else {
+         SWIG_exception(SWIG_TypeError, "string expected");
+     }
+}
+// Copy the typecheck code for "char *".  
+%typemap(typecheck) std::string = char *;
+
      +
      +

      The bottom line: If you are writing new typemaps and you are using + overloaded methods, you will probably have to write typecheck code or + copy existing code. Since this is a relatively new SWIG feature, there + are few examples to work with. However, you might look at some of the + existing library files likes 'typemaps.i' for a guide.

      +

      Notes:

      +
        +
      • Typecheck typemaps are not used for non-overloaded methods. Because + of this, it is still always necessary to check types in any "in" + typemaps.
        • +
      • The dynamic dispatch process is only meant to be a heuristic. There + are many corner cases where SWIG simply can't disambiguate types to the + same degree as C++. The only way to resolve this ambiguity is to use + the %rename directive to rename one of the overloaded methods + (effectively eliminating overloading).
        • +
      • Typechecking may be partial. For example, if working with arrays, + the typecheck code might simply check the type of the first array + element and use that to dispatch to the correct function. Subsequent + "in" typemaps would then perform more extensive type-checking.
        • +
      • Make sure you read the section on overloading in the " +SWIG and C++" chapter.
        • +
      +

      10.12 More about %apply and +%clear

      +

      In order to implement certain kinds of program behavior, it is + sometimes necessary to write sets of typemaps. For example, to support + output arguments, one often writes a set of typemaps like this:

      +
      +
      +%typemap(in,numinputs=0) int *OUTPUT (int temp) {
+   $1 = &temp;
+}
+%typemap(argout) int *OUTPUT {
+   // return value somehow
+}
+
      +
      +

      To make it easier to apply the typemap to different argument types + and names, the %apply directive performs a copy of all + typemaps from one type to another. For example, if you specify this,

      +
      +
      +%apply int *OUTPUT { int *retvalue, int32 *output };
+
      +
      +

      then all of the int *OUTPUT typemaps are copied to int + *retvalue and int32 *output.

      +

      However, there is a subtle aspect of %apply that needs more + description. Namely, %apply does not overwrite a typemap rule + if it is already defined for the target datatype. This behavior allows + you to do two things:

      +
        +
      • You can specialize parts of a complex typemap rule by first defining + a few typemaps and then using %apply to incorporate the + remaining pieces.
        • +
      • Sets of different typemaps can be applied to the same datatype using + repeated %apply directives.
        • +
      +

      For example:

      +
      +
      +%typemap(in) int *INPUT (int temp) {
+   temp = ... get value from $input ...;
+   $1 = &temp;
+}
+
+%typemap(check) int *POSITIVE {
+   if (*$1 <= 0) {
+      SWIG_exception(SWIG_ValueError,"Expected a positive number!\n");
+      return NULL;
+   }
+}
+
+...
+%apply int *INPUT     { int *invalue };
+%apply int *POSITIVE  { int *invalue };
+
      +
      +

      Since %apply does not overwrite or replace any existing + rules, the only way to reset behavior is to use the %clear + directive. %clear removes all typemap rules defined for a + specific datatype. For example:

      +
      +
      +%clear int *invalue;
+
      +
      +

      10.13 Reducing wrapper code size

      +

      Since the code supplied to a typemap is inlined directly into + wrapper functions, typemaps can result in a tremendous amount of code + bloat. For example, consider this typemap for an array:

      +
      +
      +%typemap(in) float [ANY] {
+  int i;
+  if (!PySequence_Check($input)) {
+    PyErr_SetString(PyExc_ValueError,"Expected a sequence");
+    return NULL;
+  }
+  if (PySequence_Length($input) != $1_dim0) {
+    PyErr_SetString(PyExc_ValueError,"Size mismatch. Expected $1_dim0 elements");
+    return NULL;
+  }
+  $1 = (float) malloc($1_dim0*sizeof(float));
+  for (i = 0; i < $1_dim0; i++) {
+    PyObject *o = PySequence_GetItem($input,i);
+    if (PyNumber_Check(o)) {
+      $1[i] = (float) PyFloat_AsDouble(o);
+    } else {
+      PyErr_SetString(PyExc_ValueError,"Sequence elements must be numbers");      
+      free(result);
+      return NULL;
+    }
+  }
+}
+
      +
      +

      If you had a large interface with hundreds of functions all + accepting array parameters, this typemap would be replicated + repeatedly--generating a huge amount of code. A better approach might + be to consolidate some of the typemap into a function. For example:

      +
      +
      +%{
+/* Define a helper function */
+static float *
+convert_float_array(PyObject *input, int size) {
+  int i;
+  float *result;
+  if (!PySequence_Check(input)) {
+    PyErr_SetString(PyExc_ValueError,"Expected a sequence");
+    return NULL;
+  }
+  if (PySequence_Length(input) != size) {
+    PyErr_SetString(PyExc_ValueError,"Size mismatch. ");
+    return NULL;
+  }
+  result = (float) malloc(size*sizeof(float));
+  for (i = 0; i < size; i++) {
+    PyObject *o = PySequence_GetItem(input,i);
+    if (PyNumber_Check(o)) {
+      result[i] = (float) PyFloat_AsDouble(o);
+    } else {
+      PyErr_SetString(PyExc_ValueError,"Sequence elements must be numbers");
+      free(result);       
+      return NULL;
+    }
+  }
+  return result;
+}
+%}
+
+%typemap(in) float [ANY] {
+    $1 = convert_float_array($input, $1_dim0);
+    if (!$1) return NULL;
+}
+%}
+
      +
      +

      10.14 Passing data between typemaps

      +

      It is also important to note that the primary use of local variables + is to create stack-allocated objects for temporary use inside a wrapper + function (this is faster and less-prone to error than allocating data + on the heap). In general, the variables are not intended to pass + information between different types of typemaps. However, this can be + done if you realize that local names have the argument number appended + to them. For example, you could do this:

      +
      +
      +%typemap(in) int *(int temp) {
+   temp = (int) PyInt_AsLong($input);
+   $1 = &temp;
+}
+
+%typemap(argout) int * {
+   PyObject *o = PyInt_FromLong(temp$argnum);
+   ...
+}
+
      +
      +

      In this case, the $argnum variable is expanded into the + argument number. Therefore, the code will reference the appropriate + local such as temp1 and temp2. It should be noted + that there are plenty of opportunities to break the universe here and + that accessing locals in this manner should probably be avoided. At the + very least, you should make sure that the typemaps sharing information + have exactly the same types and names.

      +

      10.15 C++ "this" pointer

      +

      All the rules discussed for Typemaps apply to C++ as well as C. + However in addition C++ passes an extra parameter into every non-static + class method -- the this pointer. Occasionally it can be + useful to apply a typemap to this pointer (for example to check and + make sure this is non-null before deferencing). Actually, C + also has an the equivalent of the this pointer which is used + when accessing variables in a C struct.

      +

      In order to customise the this pointer handling, target a + variable named self in your typemaps. self is the + name SWIG uses to refer to the extra parameter in wrapped functions.

      +

      For example, if wrapping for Java generation:

      +
      +
      +%typemap(check) SWIGTYPE *self %{
+if (!$1) {
+  SWIG_JavaThrowException(jenv, SWIG_JavaNullPointerException, "swigCPtr null");
+  return $null;
+}
+%}
+
      +
      +

      In the above case, the $1 variable is expanded into the + argument name that SWIG is using as the this pointer. SWIG + will then insert the check code before the actual C++ class method is + called, and will raise an exception rather than crash the Java virtual + machine. The generated code will look something like:

      +
      +
      +  if (!arg1) {
+    SWIG_JavaThrowException(jenv, SWIG_JavaNullPointerException,
+      "invalid native object; delete() likely already called");
+    return ;
+  }
+  (arg1)->wrappedFunction(...);
+
      +
      +

      Note that if you have a parameter named self then it will + also match the typemap. One work around is to create an interface file + that wraps the method, but give the argument a name other than self +.

      +

      10.16 Where to go for more information?

      +

      The best place to find out more information about writing typemaps + is to look in the SWIG library. Most language modules define all of + their default behavior using typemaps. These are found in files such as + python.swg, perl5.swg, tcl8.swg and so + forth. The typemaps.i file in the library also contains + numerous examples. You should look at these files to get a feel for how + to define typemaps of your own. Some of the language modules support + additional typemaps and further information is available in the + individual chapters for each target language. There you may also find + more hands-on practical examples.

      +
      +

      11 Customization Features

      + + +
      + +
      + +

      In many cases, it is desirable to change the default wrapping of + particular declarations in an interface. For example, you might want to + provide hooks for catching C++ exceptions, add assertions, or provide + hints to the underlying code generator. This chapter describes some of + these customization techniques. First, a discussion of exception + handling is presented. Then, a more general-purpose customization + mechanism known as "features" is described.

      +

      11.1 Exception handling with %exception

      +

      The %exception directive allows you to define a general + purpose exception handler. For example, you can specify the following:

      +
      +
      +%exception {
+    try {
+        $action
+    }
+    catch (RangeError) {
+        PyErr_SetString(PyExc_IndexError,"index out-of-bounds");
+        return NULL;
+    }
+}
+
      +
      +

      When defined, the code enclosed in braces is inserted directly into + the low-level wrapper functions. The special variable $action + is one of a few +%exception special variable supported and gets replaced with the + actual operation to be performed (a function call, method invocation, + attribute access, etc.). An exception handler remains in effect until + it is explicitly deleted. This is done by using either %exception + or %noexception with no code. For example:

      +
      +
      +%exception;   // Deletes any previously defined handler
+
      +
      +

      Compatibility note: Previous versions of SWIG used a special + directive %except for exception handling. That directive is + deprecated--%exception provides the same functionality, but is + substantially more flexible.

      +

      11.1.1 Handling exceptions in C code

      +

      C has no formal exception handling mechanism so there are several + approaches that might be used. A somewhat common technique is to simply + set a special error code. For example:

      +
      +
      +/* File : except.c */
+
+static char error_message[256];
+static int error_status = 0;
+
+void throw_exception(char *msg) {
+	strncpy(error_message,msg,256);
+	error_status = 1;
+}
+
+void clear_exception() {
+	error_status = 0;
+}
+char *check_exception() {
+	if (error_status) return error_message;
+	else return NULL;
+}
+
+
      +
      +

      To use these functions, functions simply call throw_exception() + to indicate an error occurred. For example :

      +
      +
      +double inv(double x) {
+	if (x != 0) return 1.0/x;
+	else {
+		throw_exception("Division by zero");
+		return 0;
+	}
+}
+
+
      +
      +

      To catch the exception, you can write a simple exception handler + such as the following (shown for Perl5) :

      +
      +
      +%exception {
+    char *err;
+    clear_exception();
+    $action
+    if ((err = check_exception())) {
+       croak(err);
+    }
+}
+
      +
      +

      In this case, when an error occurs, it is translated into a Perl + error. Each target language has its own approach to creating a runtime + error/exception in and for Perl it is the croak method shown + above.

      +

      11.1.2 Exception handling with + longjmp()

      +

      Exception handling can also be added to C code using the +<setjmp.h> library. Here is a minimalistic implementation that + relies on the C preprocessor :

      +
      +
      +/* File : except.c
+   Just the declaration of a few global variables we're going to use */
+
+#include <setjmp.h>
+jmp_buf exception_buffer;
+int exception_status;
+
+/* File : except.h */
+#include <setjmp.h>
+extern jmp_buf exception_buffer;
+extern int exception_status;
+
+#define try if ((exception_status = setjmp(exception_buffer)) == 0)
+#define catch(val) else if (exception_status == val)
+#define throw(val) longjmp(exception_buffer,val)
+#define finally else
+
+/* Exception codes */
+
+#define RangeError     1
+#define DivisionByZero 2
+#define OutOfMemory    3
+
+
      +
      +

      Now, within a C program, you can do the following :

      +
      +
      +double inv(double x) {
+	if (x) return 1.0/x;
+	else throw(DivisionByZero);
+}
+
+
      +
      +

      Finally, to create a SWIG exception handler, write the following :

      +
      +
      +%{
+#include "except.h"
+%}
+
+%exception {
+	try {
+		$action
+	} catch(RangeError) {
+		croak("Range Error");
+	} catch(DivisionByZero) {
+		croak("Division by zero");
+	} catch(OutOfMemory) {
+		croak("Out of memory");
+	} finally {
+		croak("Unknown exception");
+	}
+}
+
      +
      +

      Note: This implementation is only intended to illustrate the general + idea. To make it work better, you'll need to modify it to handle nested + try declarations.

      +

      11.1.3 Handling C++ exceptions

      +

      Handling C++ exceptions is also straightforward. For example:

      +
      +
      +%exception {
+	try {
+		$action
+	} catch(RangeError) {
+		croak("Range Error");
+	} catch(DivisionByZero) {
+		croak("Division by zero");
+	} catch(OutOfMemory) {
+		croak("Out of memory");
+	} catch(...) {
+		croak("Unknown exception");
+	}
+}
+
+
      +
      +

      The exception types need to be declared as classes elsewhere, + possibly in a header file :

      +
      +
      +class RangeError {};
+class DivisionByZero {};
+class OutOfMemory {};
+
      +
      +

      11.1.4 Exception handlers + for variables

      +

      By default all variables will ignore %exception, so it is + effectively turned off for all variables wrappers. This applies to + global variables, member variables and static member variables. The + approach is certainly a logical one when wrapping variables in C. + However, in C++, it is quite possible for an exception to be thrown + while the variable is being assigned. To ensure %exception is + used when wrapping variables, it needs to be 'turned on' using the +%allowexception feature. Note that %allowexception is just + a macro for %feature("allowexcept"), that is, it is a feature + called "allowexcept". Any variable which has this feature attached to + it, will then use the %exception feature, but of course, only + if there is a %exception attached to the variable in the first + place. The %allowexception feature works like any other + feature and so can be used globally or for selective variables.

      +
      +
      +%allowexception;                // turn on globally
+%allowexception Klass::MyVar;   // turn on for a specific variable
+
+%noallowexception Klass::MyVar; // turn off for a specific variable
+%noallowexception;              // turn off globally
+
      +
      +

      11.1.5 Defining different exception + handlers

      +

      By default, the %exception directive creates an exception + handler that is used for all wrapper functions that follow it. Unless + there is a well-defined (and simple) error handling mechanism in place, + defining one universal exception handler may be unwieldy and result in + excessive code bloat since the handler is inlined into each wrapper + function.

      +

      To fix this, you can be more selective about how you use the +%exception directive. One approach is to only place it around + critical pieces of code. For example:

      +
      +
      +%exception {
+	... your exception handler ...
+}
+/* Define critical operations that can throw exceptions here */
+
+%exception;
+
+/* Define non-critical operations that don't throw exceptions */
+
      +
      +

      More precise control over exception handling can be obtained by + attaching an exception handler to specific declaration name. For + example:

      +
      +
      +%exception allocate {
+    try {
+        $action
+    } 
+    catch (MemoryError) {
+        croak("Out of memory");
+    }
+}
+
      +
      +

      In this case, the exception handler is only attached to declarations + named "allocate". This would include both global and member functions. + The names supplied to %exception follow the same rules as for +%rename described in the section on +Ambiguity resolution and renaming. For example, if you wanted to + define an exception handler for a specific class, you might write this:

      +
      +
      +%exception Object::allocate {
+    try {
+        $action
+    } 
+    catch (MemoryError) {
+        croak("Out of memory");
+    }
+}
+
      +
      +

      When a class prefix is supplied, the exception handler is applied to + the corresponding declaration in the specified class as well as for + identically named functions appearing in derived classes.

      +

      %exception can even be used to pinpoint a precise + declaration when overloading is used. For example:

      +
      +
      +%exception Object::allocate(int) {
+    try {
+        $action
+    } 
+    catch (MemoryError) {
+        croak("Out of memory");
+    }
+}
+
      +
      +

      Attaching exceptions to specific declarations is a good way to + reduce code bloat. It can also be a useful way to attach exceptions to + specific parts of a header file. For example:

      +
      +
      +%module example
+%{
+#include "someheader.h"
+%}
+
+// Define a few exception handlers for specific declarations
+%exception Object::allocate(int) {
+    try {
+        $action
+    } 
+    catch (MemoryError) {
+        croak("Out of memory");
+    }
+}
+
+%exception Object::getitem {
+    try {
+       $action
+    }
+    catch (RangeError) {
+       croak("Index out of range");
+    }
+}
+...
+// Read a raw header file
+%include "someheader.h"
+
      +
      +

      Compatibility note: The %exception directive + replaces the functionality provided by the deprecated "except" typemap. + The typemap would allow exceptions to be thrown in the target language + based on the return type of a function and was intended to be a + mechanism for pinpointing specific declarations. However, it never + really worked that well and the new %exception directive is much + better.

      +

      11.1.6 + Special variables for %exception

      +

      The %exception directive supports a few special variables which are + placeholders for code substitution. The following table shows the + available special variables and details what the special variables are + replaced with.

      + + + + + + + +
      $actionThe actual operation to be performed (a function + call, method invocation, variable access, etc.)
      $symnameThe symbol name used internally by SWIG
      $overnameThe extra mangling used in the symbol name for + overloaded method. Expands to nothing if the wrapped method is not + overloaded.
      $wrapnameThe language specific wrapper name (usually a + C function name exported from the shared object/dll)
      $declThe fully qualified C/C++ declaration of the + method being wrapped without the return type
      $fulldeclThe fully qualified C/C++ declaration of the + method being wrapped including the return type
      +

      The special variables are often used in situations where method + calls are logged. Exactly which form of the method call needs logging + is up to individual requirements, but the example code below shows all + the possible expansions, plus how an exception message could be + tailored to show the C++ method declaration:

      +
      +
      +%exception Special::something {
+  log("symname: $symname");
+  log("overname: $overname");
+  log("wrapname: $wrapname");
+  log("decl: $decl");
+  log("fulldecl: $fulldecl");
+  try {
+    $action
+  } 
+  catch (MemoryError) {
+      croak("Out of memory in $decl");
+  }
+}
+void log(const char *message);
+struct Special {
+  void something(const char *c);
+  void something(int i);
+};
+
      +
      +

      Below shows the expansions for the 1st of the overloaded +something wrapper methods for Perl:

      +
      +
      +  log("symname: Special_something");
+  log("overname: __SWIG_0");
+  log("wrapname: _wrap_Special_something__SWIG_0");
+  log("decl: Special::something(char const *)");
+  log("fulldecl: void Special::something(char const *)");
+  try {
+    (arg1)->something((char const *)arg2);
+  } 
+  catch (MemoryError) {
+    croak("Out of memory in Special::something(char const *)");
+  }
+
      +
      +

      11.1.7 Using The SWIG exception + library

      +

      The exception.i library file provides support for creating + language independent exceptions in your interfaces. To use it, simply + put an "%include exception.i" in your interface file. This + creates a function SWIG_exception() that can be used to raise + common scripting language exceptions in a portable manner. For example + :

      +
      +
      +// Language independent exception handler
+%include exception.i       
+
+%exception {
+    try {
+        $action
+    } catch(RangeError) {
+        SWIG_exception(SWIG_ValueError, "Range Error");
+    } catch(DivisionByZero) {
+        SWIG_exception(SWIG_DivisionByZero, "Division by zero");
+    } catch(OutOfMemory) {
+        SWIG_exception(SWIG_MemoryError, "Out of memory");
+    } catch(...) {
+        SWIG_exception(SWIG_RuntimeError,"Unknown exception");
+    }
+}
+
+
      +
      +

      As arguments, SWIG_exception() takes an error type code (an + integer) and an error message string. The currently supported error + types are :

      +
      +
      +SWIG_UnknownError
+SWIG_IOError
+SWIG_RuntimeError
+SWIG_IndexError
+SWIG_TypeError
+SWIG_DivisionByZero
+SWIG_OverflowError
+SWIG_SyntaxError
+SWIG_ValueError
+SWIG_SystemError
+SWIG_AttributeError
+SWIG_MemoryError
+SWIG_NullReferenceError
+
      +
      +

      Since the SWIG_exception() function is defined at the + C-level it can be used elsewhere in SWIG. This includes typemaps and + helper functions.

      +

      11.2 Object ownership and %newobject

      +

      A common problem in some applications is managing proper ownership + of objects. For example, consider a function like this:

      +
      +
      +Foo *blah() {
+   Foo *f = new Foo();
+   return f;
+}
+
      +
      +

      If you wrap the function blah(), SWIG has no idea that the + return value is a newly allocated object. As a result, the resulting + extension module may produce a memory leak (SWIG is conservative and + will never delete objects unless it knows for certain that the returned + object was newly created).

      +

      To fix this, you can provide an extra hint to the code generator + using the %newobject directive. For example:

      +
      +
      +%newobject blah;
+Foo *blah();
+
      +
      +

      %newobject works exactly like %rename and +%exception. In other words, you can attach it to class members and + parameterized declarations as before. For example:

      +
      +
      +%newobject ::blah();                   // Only applies to global blah
+%newobject Object::blah(int,double);   // Only blah(int,double) in Object
+%newobject *::copy;                    // Copy method in all classes
+...
+
      +
      +

      When %newobject is supplied, many language modules will + arrange to take ownership of the return value. This allows the value to + be automatically garbage-collected when it is no longer in use. + However, this depends entirely on the target language (a language + module may also choose to ignore the %newobject directive).

      +

      Closely related to %newobject is a special typemap. The + "newfree" typemap can be used to deallocate a newly allocated return + value. It is only available on methods for which %newobject + has been applied and is commonly used to clean-up string results. For + example:

      +
      +
      +%typemap(newfree) char * "free($1);";
+...
+%newobject strdup;
+...
+char *strdup(const char *s);
+
      +
      +

      In this case, the result of the function is a string in the target + language. Since this string is a copy of the original result, the data + returned by strdup() is no longer needed. The "newfree" + typemap in the example simply releases this memory.

      +

      As a complement to the %newobject, from SWIG 1.3.28, you + can use the %delobject directive. For example, if you have two + methods, one to create objects and one to destroy them, you can use:

      +
      +
      +%newobject create_foo;
+%delobject destroy_foo;
+...
+Foo *create_foo();
+void destroy_foo(Foo *foo);
+
      +
      +

      or in a member method as:

      +
      +
      +%delobject Foo::destroy;
+
+class Foo {
+public:
+  void destroy() { delete this;}
+
+private:
+  ~Foo();
+};
+
      +
      +

      %delobject instructs SWIG that the first argument passed to + the method will be destroyed, and therefore, the target language should + not attempt to deallocate it twice. This is similar to use the DISOWN + typemap in the first method argument, and in fact, it also depends on + the target language on implementing the 'disown' mechanism properly.

      +

      Compatibility note: Previous versions of SWIG had a special +%new directive. However, unlike %newobject, it only + applied to the next declaration. For example:

      +
      +
      +%new char *strdup(const char *s);
+
      +
      +

      For now this is still supported but is deprecated.

      +

      How to shoot yourself in the foot: The %newobject + directive is not a declaration modifier like the old %new + directive. Don't write code like this:

      +
      +
      +%newobject
+char *strdup(const char *s);
+
      +
      +

      The results might not be what you expect.

      +

      11.3 Features and the %feature directive

      +

      Both %exception and %newobject are examples of a + more general purpose customization mechanism known as "features." A + feature is simply a user-definable property that is attached to + specific declarations. Features are attached using the %feature + directive. For example:

      +
      +
      +%feature("except") Object::allocate {
+    try {
+        $action
+    } 
+    catch (MemoryError) {
+        croak("Out of memory");
+    }
+}
+
+%feature("new","1") *::copy;
+
      +
      +

      In fact, the %exception and %newobject directives + are really nothing more than macros involving %feature:

      +
      +
      +#define %exception %feature("except")
+#define %newobject %feature("new","1")
+
      +
      +

      The name matching rules outlined in the +Ambiguity resolution and renaming section applies to all +%feature directives. In fact the the %rename directive is + just a special form of %feature. The matching rules mean that + features are very flexible and can be applied with pinpoint accuracy to + specific declarations if needed. Additionally, if no declaration name + is given, a global feature is said to be defined. This feature is then + attached to every declaration that follows. This is how global + exception handlers are defined. For example:

      +
      +
      +/* Define a global exception handler */
+%feature("except") {
+   try {
+     $action
+   }
+   ...
+}
+
+... bunch of declarations ...
+
      +
      +

      The %feature directive can be used with different syntax. + The following are all equivalent:

      +
      +
      +%feature("except") Object::method { $action };
+%feature("except") Object::method %{ $action %};
+%feature("except") Object::method " $action ";
+%feature("except","$action") Object::method;
+
      +
      +

      The syntax in the first variation will generate the { } + delimiters used whereas the other variations will not.

      +

      11.3.1 Feature + attributes

      +

      The %feature directive also accepts XML style attributes in + the same way that typemaps do. Any number of attributes can be + specified. The following is the generic syntax for features:

      +
      +
      +%feature("name","value", attribute1="AttributeValue1") symbol;
+%feature("name", attribute1="AttributeValue1") symbol {value};
+%feature("name", attribute1="AttributeValue1") symbol %{value%};
+%feature("name", attribute1="AttributeValue1") symbol "value";
+
      +
      +

      More than one attribute can be specified using a comma separated + list. The Java module is an example that uses attributes in +%feature("except"). The throws attribute specifies the + name of a Java class to add to a proxy method's throws clause. In the + following example, MyExceptionClass is the name of the Java + class for adding to the throws clause.

      +
      +
      +%feature("except", throws="MyExceptionClass") Object::method { 
+   try {
+     $action
+   } catch (...) {
+     ... code to throw a MyExceptionClass Java exception ...
+   }
+};
+
      +
      +

      Further details can be obtained from the +Java exception handling section.

      +

      11.3.2 Feature flags

      +

      Feature flags are used to enable or disable a particular feature. + Feature flags are a common but simple usage of %feature and + the feature value should be either 1 to enable or 0 + to disable the feature.

      +
      +
      +%feature("featurename")          // enables feature
+%feature("featurename", "1")     // enables feature
+%feature("featurename", "x")     // enables feature
+%feature("featurename", "0")     // disables feature
+%feature("featurename", "")      // clears feature
+
      +
      +

      Actually any value other than zero will enable the feature. Note + that if the value is omitted completely, the default value becomes +1, thereby enabling the feature. A feature is cleared by specifying + no value, see Clearing + features. The %immutable directive described in the +Creating read-only variables section, is just a macro for +%feature("immutable"), and can be used to demonstrates feature + flags:

      +
      +
      +                                // features are disabled by default
+int red;                        // mutable
+
+%feature("immutable");          // global enable
+int orange;                     // immutable
+
+%feature("immutable","0");      // global disable
+int yellow;                     // mutable
+
+%feature("immutable","1");      // another form of global enable
+int green;                      // immutable
+
+%feature("immutable","");       // clears the global feature
+int blue;                       // mutable
+
      +
      +

      Note that features are disabled by default and must be explicitly + enabled either globally or by specifying a targeted declaration. The + above intersperses SWIG directives with C code. Of course you can + target features explicitly, so the above could also be rewritten as:

      +
      +
      +%feature("immutable","1") orange;
+%feature("immutable","1") green;
+int red;                        // mutable
+int orange;                     // immutable
+int yellow;                     // mutable
+int green;                      // immutable
+int blue;                       // mutable
+
      +
      +

      The above approach allows for the C declarations to be separated + from the SWIG directives for when the C declarations are parsed from a + C header file. The logic above can of course be inverted and rewritten + as:

      +
      +
      +%feature("immutable","1");
+%feature("immutable","0") red;
+%feature("immutable","0") yellow;
+%feature("immutable","0") blue;
+int red;                        // mutable
+int orange;                     // immutable
+int yellow;                     // mutable
+int green;                      // immutable
+int blue;                       // mutable
+
      +
      +

      As hinted above for %immutable, most feature flags can also + be specified via alternative syntax. The alternative syntax is just a + macro in the swig.swg Library file. The following shows the + alternative syntax for the imaginary featurename feature:

      +
      +
      +%featurename       // equivalent to %feature("featurename", "1") ie enables feature
+%nofeaturename     // equivalent to %feature("featurename", "0") ie disables feature
+%clearfeaturename  // equivalent to %feature("featurename", "")  ie clears feature
+
      +
      +

      The concept of clearing features is discussed next.

      +

      11.3.3 Clearing + features

      +

      A feature stays in effect until it is explicitly cleared. A feature + is cleared by supplying a %feature directive with no value. + For example %feature("name",""). A cleared feature means that + any feature exactly matching any previously defined feature is no + longer used in the name matching rules. So if a feature is cleared, it + might mean that another name matching rule will apply. To clarify, + let's consider the except feature again (%exception):

      +
      +
      +// Define global exception handler
+%feature("except") {
+    try {
+        $action
+    } catch (...) {
+        croak("Unknown C++ exception");
+    }
+}
+
+// Define exception handler for all clone methods to log the method calls
+%feature("except") *::clone() {
+    try {
+        logger.info("$action");
+        $action
+    } catch (...) {
+        croak("Unknown C++ exception");
+    }
+}
+
+... initial set of class declarations with clone methods ...
+
+// clear the previously defined feature
+%feature("except","") *::clone();
+
+... final set of class declarations with clone methods ...
+
      +
      +

      In the above scenario, the initial set of clone methods will log all + method invocations from the target language. This specific feature is + cleared for the final set of clone methods. However, these clone + methods will still have an exception handler (without logging) as the + next best feature match for them is the global exception handler.

      +

      Note that clearing a feature is not always the same as disabling it. + Clearing the feature above with %feature("except","") *::clone() + is not the same as specifying %feature("except","0") *::clone() +. The former will disable the feature for clone methods - the feature is + still a better match than the global feature. If on the other hand, no + global exception handler had been defined at all, then clearing the + feature would be the same as disabling it as no other feature would + have matched.

      +

      Note that the feature must match exactly for it to be cleared by any + previously defined feature. For example the following attempt to clear + the initial feature will not work:

      +
      +
      +%feature("except") clone() { logger.info("$action"); $action }
+%feature("except","") *::clone();
+
      +
      +

      but this will:

      +
      +
      +%feature("except") clone() { logger.info("$action"); $action }
+%feature("except","") clone();
+
      +
      +

      SWIG provides macros for disabling and clearing features. Many of + these can be found in the swig.swg library file. The typical + pattern is to define three macros; one to define the feature itself, + one to disable the feature and one to clear the feature. The three + macros below show this for the "except" feature:

      +
      +
      +#define %exception      %feature("except")
+#define %noexception    %feature("except","0")
+#define %clearexception %feature("except","")
+
      +
      +

      11.3.4 Features + and default arguments

      +

      SWIG treats methods with default arguments as separate overloaded + methods as detailed in the default + arguments section. Any %feature targeting a method with + default arguments will apply to all the extra overloaded methods that + SWIG generates if the default arguments are specified in the feature. + If the default arguments are not specified in the feature, then the + feature will match that exact wrapper method only and not the extra + overloaded methods that SWIG generates. For example:

      +
      +
      +%feature("except") void hello(int i=0, double d=0.0) { ... }
+void hello(int i=0, double d=0.0);
+
      +
      +

      will apply the feature to all three wrapper methods, that is:

      +
      +
      +void hello(int i, double d);
+void hello(int i);
+void hello();
+
      +
      +

      If the default arguments are not specified in the feature:

      +
      +
      +%feature("except") void hello(int i, double d) { ... }
+void hello(int i=0, double d=0.0);
+
      +
      +

      then the feature will only apply to this wrapper method:

      +
      +
      +void hello(int i, double d);
+
      +
      +

      and not these wrapper methods:

      +
      +
      +void hello(int i);
+void hello();
+
      +
      +

      If compactdefaultargs are being + used, then the difference between specifying or not specifying default + arguments in a feature is not applicable as just one wrapper is + generated.

      +

      Compatibility note: The different behaviour of features + specified with or without default arguments was introduced in + SWIG-1.3.23 when the approach to wrapping methods with default + arguments was changed.

      +

      11.3.5 Feature example

      +

      As has been shown earlier, the intended use for the %feature + directive is as a highly flexible customization mechanism that can be + used to annotate declarations with additional information for use by + specific target language modules. Another example is in the Python + module. You might use %feature to rewrite proxy/shadow class + code as follows:

      +
      +
      +%module example
+%rename(bar_id) bar(int,double);
+
+// Rewrite bar() to allow some nice overloading
+
+%feature("shadow") Foo::bar(int) %{
+def bar(*args):
+    if len(args) == 3:
+         return apply(examplec.Foo_bar_id,args)
+    return apply(examplec.Foo_bar,args)
+%}
+    
+class Foo {
+public:
+    int bar(int x);
+    int bar(int x, double y);
+}
+
      +
      +

      Further details of %feature usage is described in the + documentation for specific language modules.

      +
      +

      12 Contracts

      + + +
      + +
      + +

      A common problem that arises when wrapping C libraries is that of + maintaining reliability and checking for errors. The fact of the matter + is that many C programs are notorious for not providing error checks. + Not only that, when you expose the internals of an application as a + library, it often becomes possible to crash it simply by providing bad + inputs or using it in a way that wasn't intended.

      +

      This chapter describes SWIG's support for software contracts. In the + context of SWIG, a contract can be viewed as a runtime constraint that + is attached to a declaration. For example, you can easily attach + argument checking rules, check the output values of a function and + more. When one of the rules is violated by a script, a runtime + exception is generated rather than having the program continue to + execute.

      +

      12.1 The %contract directive

      +

      Contracts are added to a declaration using the %contract directive. + Here is a simple example:

      +
      +
      +%contract sqrt(double x) {
+require:
+    x >= 0;
+ensure:
+    sqrt >= 0;
+}
+
+...
+double sqrt(double);
+
      +
      +

      In this case, a contract is being added to the sqrt() + function. The %contract directive must always appear before + the declaration in question. Within the contract there are two + sections, both of which are optional. The require: section + specifies conditions that must hold before the function is called. + Typically, this is used to check argument values. The ensure: + section specifies conditions that must hold after the function is + called. This is often used to check return values or the state of the + program. In both cases, the conditions that must hold must be specified + as boolean expressions.

      +

      In the above example, we're simply making sure that sqrt() returns a + non-negative number (if it didn't, then it would be broken in some + way).

      +

      Once a contract has been specified, it modifies the behavior of the + resulting module. For example:

      +
      +
      +>>> example.sqrt(2)
+1.4142135623730951
+>>> example.sqrt(-2)
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+RuntimeError: Contract violation: require: (arg1>=0)
+>>>
+
      +
      +

      12.2 %contract and classes

      +

      The %contract directive can also be applied to class + methods and constructors. For example:

      +
      +
      +%contract Foo::bar(int x, int y) {
+require:
+   x > 0;
+ensure:
+   bar > 0;
+}
+
+%contract Foo::Foo(int a) {
+require:
+   a > 0;
+}
+
+class Foo {
+public:
+    Foo(int);
+    int bar(int, int);
+};
+
      +
      +

      The way in which %contract is applied is exactly the same + as the %feature directive. Thus, any contract that you + specified for a base class will also be attached to inherited methods. + For example:

      +
      +
      +class Spam : public Foo {
+public:
+   int bar(int,int);    // Gets contract defined for Foo::bar(int,int)
+};
+
      +
      +

      In addition to this, separate contracts can be applied to both the + base class and a derived class. For example:

      +
      +
      +%contract Foo::bar(int x, int) {
+require:
+    x > 0;
+}
+
+%contract Spam::bar(int, int y) {
+require:
+    y > 0;
+}
+
+class Foo {
+public:
+    int bar(int,int);   // Gets Foo::bar contract.
+};
+
+class Spam : public Foo {
+public:
+     int bar(int,int);   // Gets Foo::bar and Spam::bar contract
+};
+
      +
      +

      When more than one contract is applied, the conditions specified in + a "require:" section are combined together using a logical-AND + operation. In other words conditions specified for the base class and + conditions specified for the derived class all must hold. In the above + example, this means that both the arguments to Spam::bar must + be positive.

      +

      12.3 Constant aggregation and + %aggregate_check

      +

      Consider an interface file that contains the following code:

      +
      +
      +#define  UP     1
+#define  DOWN   2
+#define  RIGHT  3
+#define  LEFT   4
+
+void move(SomeObject *, int direction, int distance);
+
      +
      +

      One thing you might want to do is impose a constraint on the + direction parameter to make sure it's one of a few accepted values. To + do that, SWIG provides an easy to use macro %aggregate_check() that + works like this:

      +
      +
      +%aggregate_check(int, check_direction, UP, DOWN, LEFT, RIGHT);
+
      +
      +

      This merely defines a utility function of the form

      +
      +
      +int check_direction(int x);
+
      +
      +

      That checks the argument x to see if it is one of the values listed. + This utility function can be used in contracts. For example:

      +
      +
      +%aggregate_check(int, check_direction, UP, DOWN, RIGHT, LEFT);
+
+%contract move(SomeObject *, int direction, in) {
+require:
+     check_direction(direction);
+}
+
+#define  UP     1
+#define  DOWN   2
+#define  RIGHT  3
+#define  LEFT   4
+
+void move(SomeObject *, int direction, int distance);
+
      +
      +

      Alternatively, it can be used in typemaps and other directives. For + example:

      +
      +
      +%aggregate_check(int, check_direction, UP, DOWN, RIGHT, LEFT);
+
+%typemap(check) int direction {
+    if (!check_direction($1)) SWIG_exception(SWIG_ValueError, "Bad direction");
+}
+
+#define  UP     1
+#define  DOWN   2
+#define  RIGHT  3
+#define  LEFT   4
+
+void move(SomeObject *, int direction, int distance);
+
      +
      +

      Regrettably, there is no automatic way to perform similar checks + with enums values. Maybe in a future release.

      +

      12.4 Notes

      +

      Contract support was implemented by Songyan (Tiger) Feng and first + appeared in SWIG-1.3.20.

      +
      +

      13 Variable Length Arguments

      + + +
      + +
      + +

      (a.k.a, "The horror. The horror.")

      +

      This chapter describes the problem of wrapping functions that take a + variable number of arguments. For instance, generating wrappers for the + C printf() family of functions.

      +

      This topic is sufficiently advanced to merit its own chapter. In + fact, support for varargs is an often requested feature that was first + added in SWIG-1.3.12. Most other wrapper generation tools have wisely + chosen to avoid this issue.

      +

      13.1 Introduction

      +

      Some C and C++ programs may include functions that accept a variable + number of arguments. For example, most programmers are familiar with + functions from the C library such as the following:

      +
      +
      +int printf(const char *fmt, ...)
+int fprintf(FILE *, const char *fmt, ...);
+int sprintf(char *s, const char *fmt, ...);
+
      +
      +

      Although there is probably little practical purpose in wrapping + these specific C library functions in a scripting language (what would + be the point?), a library may include its own set of special functions + based on a similar API. For example:

      +
      +
      +int  traceprintf(const char *fmt, ...);
+
      +
      +

      In this case, you may want to have some kind of access from the + target language.

      +

      Before describing the SWIG implementation, it is important to + discuss the common uses of varargs that you are likely to encounter in + real programs. Obviously, there are the printf() style output + functions as shown. Closely related to this would be scanf() + style input functions that accept a format string and a list of + pointers into which return values are placed. However, variable length + arguments are also sometimes used to write functions that accept a + NULL-terminated list of pointers. A good example of this would be a + function like this:

      +
      +
      +int execlp(const char *path, const char *arg1, ...);
+...
+
+/* Example */
+execlp("ls","ls","-l",NULL);
+
      +
      +

      In addition, varargs is sometimes used to fake default arguments in + older C libraries. For instance, the low level open() system + call is often declared as a varargs function so that it will accept two + or three arguments:

      +
      +
      +int open(const char *path, int oflag, ...);
+...
+
+/* Examples */
+f = open("foo", O_RDONLY);
+g = open("bar", O_WRONLY | O_CREAT, 0644);
+
      +
      +

      Finally, to implement a varargs function, recall that you have to + use the C library functions defined in <stdarg.h>. For + example:

      +
      +
      +List make_list(const char *s, ...) {
+    va_list ap;
+    List    x;
+    ...
+    va_start(ap, s);
+    while (s) {
+       x.append(s);
+       s = va_arg(ap, const char *);
+    }
+    va_end(ap);
+    return x;
+}
+
      +
      +

      13.2 The Problem

      +

      Generating wrappers for a variable length argument function presents + a number of special challenges. Although C provides support for + implementing functions that receive variable length arguments, there + are no functions that can go in the other direction. Specifically, you + can't write a function that dynamically creates a list of arguments and + which invokes a varargs function on your behalf.

      +

      Although it is possible to write functions that accept the special + type va_list, this is something entirely different. You can't + take a va_list structure and pass it in place of the variable + length arguments to another varargs function. It just doesn't work.

      +

      The reason this doesn't work has to do with the way that function + calls get compiled. For example, suppose that your program has a + function call like this:

      +
      +
      +printf("Hello %s. Your number is %d\n", name, num);
+
      +
      +

      When the compiler looks at this, it knows that you are calling +printf() with exactly three arguments. Furthermore, it knows that + the number of arguments as well are their types and sizes is never + going to change during program execution. Therefore, this gets turned + to machine code that sets up a three-argument stack frame followed by a + call to printf().

      +

      In contrast, suppose you attempted to make some kind of wrapper + around printf() using code like this:

      +
      +
      +int wrap_printf(const char *fmt, ...) {
+   va_list ap;
+   va_start(ap,fmt);
+   ...
+   printf(fmt,ap);
+   ...
+   va_end(ap);
+};
+
      +
      +

      Although this code might compile, it won't do what you expect. This + is because the call to printf() is compiled as a procedure + call involving only two arguments. However, clearly a two-argument + configuration of the call stack is completely wrong if your intent is + to pass an arbitrary number of arguments to the real printf(). + Needless to say, it won't work.

      +

      Unfortunately, the situation just described is exactly the problem + faced by wrapper generation tools. In general, the number of passed + arguments will not be known until run-time. To make matters even worse, + you won't know the types and sizes of arguments until run-time as well. + Needless to say, there is no obvious way to make the C compiler + generate code for a function call involving an unknown number of + arguments of unknown types.

      +

      In theory, it is possible to write a wrapper that does the + right thing. However, this involves knowing the underlying ABI for the + target platform and language as well as writing special purpose code + that manually constructed the call stack before making a procedure + call. Unfortunately, both of these tasks require the use of inline + assembly code. Clearly, that's the kind of solution you would much + rather avoid.

      +

      With this nastiness in mind, SWIG provides a number of solutions to + the varargs wrapping problem. Most of these solutions are compromises + that provide limited varargs support without having to resort to + assembly language. However, SWIG can also support real varargs wrapping + (with stack-frame manipulation) if you are willing to get hands dirty. + Keep reading.

      +

      13.3 Default varargs support

      +

      When variable length arguments appear in an interface, the default + behavior is to drop the variable argument list entirely, replacing them + with a single NULL pointer. For example, if you had this function,

      +
      +
      +void traceprintf(const char *fmt, ...);
+
      +
      +

      it would be wrapped as if it had been declared as follows:

      +
      +
      +void traceprintf(const char *fmt);
+
      +
      +

      When the function is called inside the wrappers, it is called as + follows:

      +
      +
      +traceprintf(arg1, NULL);
+
      +
      +

      Arguably, this approach seems to defeat the whole point of variable + length arguments. However, this actually provides enough support for + many simple kinds of varargs functions to still be useful. For + instance, you could make function calls like this (in Python):

      +
      +
      +>>> traceprintf("Hello World")
+>>> traceprintf("Hello %s. Your number is %d\n" % (name, num))
+
      +
      +

      Notice how string formatting is being done in Python instead of C.

      +

      13.4 Argument replacement using %varargs

      +

      Instead of dropping the variable length arguments, an alternative + approach is to replace (...) with a set of suitable arguments. + SWIG provides a special %varargs directive that can be used to + do this. For example,

      +
      +
      +%varargs(int mode = 0) open;
+...
+int open(const char *path, int oflags, ...);
+
      +
      +

      is equivalent to this:

      +
      +
      +int open(const char *path, int oflags, int mode = 0);
+
      +
      +

      In this case, %varargs is simply providing more specific + information about the extra arguments that might be passed to a + function. If the parameters to a varargs function are of uniform type, +%varargs can also accept a numerical argument count as follows:

      +
      +
      +%varargs(10,char *arg = NULL) execlp;
+...
+int execlp(const char *path, const char *arg1, ...);
+
      +
      +

      This would wrap execlp() as a function that accepted up to + 10 optional arguments. Depending on the application, this may be more + than enough for practical purposes.

      +

      Argument replacement is most appropriate in cases where the types of + the extra arguments is uniform and the maximum number of arguments is + known. When replicated argument replacement is used, at least one extra + argument is added to the end of the arguments when making the function + call. This argument serves as a sentinel to make sure the list is + properly terminated. It has the same value as that supplied to the +%varargs directive.

      +

      Argument replacement is not as useful when working with functions + that accept mixed argument types such as printf(). Providing + general purpose wrappers to such functions presents special problems + (covered shortly).

      +

      13.5 Varargs and typemaps

      +

      Variable length arguments may be used in typemap specifications. For + example:

      +
      +
      +%typemap(in) (...) {
+    // Get variable length arguments (somehow)
+    ...
+}
+
+%typemap(in) (const char *fmt, ...) {
+    // Multi-argument typemap
+}
+
      +
      +

      However, this immediately raises the question of what "type" is + actually used to represent (...). For lack of a better + alternative, the type of (...) is set to void *. + Since there is no way to dynamically pass arguments to a varargs + function (as previously described), the void * argument value + is intended to serve as a place holder for storing some kind of + information about the extra arguments (if any). In addition, the + default behavior of SWIG is to pass the void * value as an + argument to the function. Therefore, you could use the pointer to hold + a valid argument value if you wanted.

      +

      To illustrate, here is a safer version of wrapping printf() + in Python:

      +
      +
      +%typemap(in) (const char *fmt, ...) {
+    $1 = "%s";                                /* Fix format string to %s */
+    $2 = (void *) PyString_AsString($input);  /* Get string argument */
+};
+...
+int printf(const char *fmt, ...);
+
      +
      +

      In this example, the format string is implicitly set to "%s" +. This prevents a program from passing a bogus format string to the + extension. Then, the passed input object is decoded and placed in the +void * argument defined for the (...) argument. When the + actual function call is made, the underlying wrapper code will look + roughly like this:

      +
      +
      +wrap_printf() {
+   char *arg1;
+   void *arg2;
+   int   result;
+
+   arg1 = "%s";
+   arg2 = (void *) PyString_AsString(arg2obj);
+   ...
+   result = printf(arg1,arg2);
+   ...
+}
+
      +
      +

      Notice how both arguments are passed to the function and it does + what you would expect.

      +

      The next example illustrates a more advanced kind of varargs + typemap. Disclaimer: this requires special support in the target + language module and is not guaranteed to work with all SWIG modules at + this time. It also starts to illustrate some of the more fundamental + problems with supporting varargs in more generality.

      +

      If a typemap is defined for any form of (...), many SWIG + modules will generate wrappers that accept a variable number of + arguments as input and will make these arguments available in some + form. The precise details of this depends on the language module being + used (consult the appropriate chapter for more details). However, + suppose that you wanted to create a Python wrapper for the execlp() + function shown earlier. To do this using a typemap instead of using +%varargs, you might first write a typemap like this:

      +
      +
      +%typemap(in) (...)(char *args[10]) {
+    int i;
+    int argc;
+    for (i = 0; i < 10; i++) args[i] = 0;
+    argc = PyTuple_Size(varargs);
+    if (argc > 10) {
+       PyErr_SetString(PyExc_ValueError,"Too many arguments");
+       return NULL;
+    }
+    for (i = 0; i < argc; i++) {
+       PyObject *o = PyTuple_GetItem(varargs,i);
+       if (!PyString_Check(o)) {
+           PyErr_SetString(PyExc_ValueError,"Expected a string");
+           return NULL;
+       }
+       args[i] = PyString_AsString(o);
+    }
+    $1 = (void *) args;
+}
+
      +
      +

      In this typemap, the special variable varargs is a tuple + holding all of the extra arguments passed (this is specific to the + Python module). The typemap then pulls this apart and sticks the values + into the array of strings args. Then, the array is assigned to + $1 (recall that this is the void * variable + corresponding to (...)). However, this assignment is only half + of the picture----clearly this alone is not enough to make the function + work. To patch everything up, you have to rewrite the underlying action + code using the %feature directive like this:

      +
      +
      +%feature("action") execlp {
+   char *args = (char **) arg3;
+   result = execlp(arg1, arg2, args[0], args[1], args[2], args[3], args[4],
+                   args[5],args[6],args[7],args[8],args[9], NULL);
+}
+
+int execlp(const char *path, const char *arg, ...);
+
      +
      +

      This patches everything up and creates a function that more or less + works. However, don't try explaining this to your coworkers unless you + know for certain that they've had several cups of coffee. If you really + want to elevate your guru status and increase your job security, + continue to the next section.

      +

      13.6 Varargs wrapping with libffi

      +

      All of the previous examples have relied on features of SWIG that + are portable and which don't rely upon any low-level machine-level + details. In many ways, they have all dodged the real issue of variable + length arguments by recasting a varargs function into some weaker + variation with a fixed number of arguments of known types. In many + cases, this works perfectly fine. However, if you want more generality + than this, you need to bring out some bigger guns.

      +

      One way to do this is to use a special purpose library such as + libffi ( +http://sources.redhat.com/libffi). libffi is a library that allows + you to dynamically construct call-stacks and invoke procedures in a + relatively platform independent manner. Details about the library can + be found in the libffi distribution and are not repeated here.

      +

      To illustrate the use of libffi, suppose that you really + wanted to create a wrapper for execlp() that accepted any + number of arguments. To do this, you might make a few adjustments to + the previous example. For example:

      +
      +
      +/* Take an arbitrary number of extra arguments and place into an array
+   of strings */
+
+%typemap(in) (...) {
+   char **argv;
+   int    argc;
+   int    i;
+
+   argc = PyTuple_Size(varargs);
+   argv = (char **) malloc(sizeof(char *)*(argc+1));
+   for (i = 0; i < argc; i++) {
+      PyObject *o = PyTuple_GetItem(varargs,i);
+      if (!PyString_Check(o)) {
+          PyErr_SetString(PyExc_ValueError,"Expected a string");
+	  free(argv);
+          return NULL;
+      }
+      argv[i] = PyString_AsString(o);
+   }
+   argv[i] = NULL;
+   $1 = (void *) argv;
+}
+
+/* Rewrite the function call, using libffi */    
+
+%feature("action") execlp {
+  int       i, vc;
+  ffi_cif   cif;
+  ffi_type  **types;
+  void      **values;
+  char      **args;
+
+  vc = PyTuple_Size(varargs);
+  types  = (ffi_type **) malloc((vc+3)*sizeof(ffi_type *));
+  values = (void **) malloc((vc+3)*sizeof(void *));
+  args   = (char **) arg3;
+
+  /* Set up path parameter */
+  types[0] = &ffi_type_pointer;
+  values[0] = &arg1;
+  
+  /* Set up first argument */
+  types[1] = &ffi_type_pointer;
+  values[1] = &arg2;
+
+  /* Set up rest of parameters */
+  for (i = 0; i <= vc; i++) {
+    types[2+i] = &ffi_type_pointer;
+    values[2+i] = &args[i];
+  }
+  if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, vc+3,
+                   &ffi_type_uint, types) == FFI_OK) {
+    ffi_call(&cif, (void (*)()) execlp, &result, values);
+  } else {
+    PyErr_SetString(PyExc_RuntimeError, "Whoa!!!!!");
+    free(types);
+    free(values);
+    free(arg3);
+    return NULL;
+  }
+  free(types);
+  free(values);
+  free(arg3);
+}
+
+/* Declare the function. Whew! */
+int execlp(const char *path, const char *arg1, ...);
+
      +
      +

      Looking at this example, you may start to wonder if SWIG is making + life any easier. Given the amount of code involved, you might also + wonder why you didn't just write a hand-crafted wrapper! Either that or + you're wondering "why in the hell am I trying to wrap this varargs + function in the first place?!?" Obviously, those are questions you'll + have to answer for yourself.

      +

      As a more extreme example of libffi, here is some code that attempts + to wrap printf(),

      +
      +
      +/* A wrapper for printf() using libffi */
+
+%{
+/* Structure for holding passed arguments after conversion */
+  typedef struct {
+    int type;
+    union {
+      int    ivalue;
+      double dvalue;
+      void   *pvalue;
+    } val;
+  } vtype;
+  enum { VT_INT, VT_DOUBLE, VT_POINTER };
+%}
+
+%typemap(in) (const char *fmt, ...) {
+  vtype *argv;
+  int    argc;
+  int    i;
+
+  /* Format string */
+  $1 = PyString_AsString($input);
+
+  /* Variable length arguments */
+  argc = PyTuple_Size(varargs);
+  argv = (vtype *) malloc(argc*sizeof(vtype));
+  for (i = 0; i < argc; i++) {
+    PyObject *o = PyTuple_GetItem(varargs,i);
+    if (PyInt_Check(o)) {
+      argv[i].type = VT_INT;
+      argv[i].val.ivalue = PyInt_AsLong(o);
+    } else if (PyFloat_Check(o)) {
+      argv[i].type = VT_DOUBLE;
+      argv[i].val.dvalue = PyFloat_AsDouble(o);
+    } else if (PyString_Check(o)) {
+      argv[i].type = VT_POINTER;
+      argv[i].val.pvalue = (void *) PyString_AsString(o);
+    } else {
+      PyErr_SetString(PyExc_ValueError,"Unsupported argument type");
+      free(argv);
+      return NULL;
+    }
+  }
+  $2 = (void *) argv;
+}
+
+/* Rewrite the function call using libffi */    
+%feature("action") printf {
+  int       i, vc;
+  ffi_cif   cif;
+  ffi_type  **types;
+  void      **values;
+  vtype     *args;
+
+  vc = PyTuple_Size(varargs);
+  types  = (ffi_type **) malloc((vc+1)*sizeof(ffi_type *));
+  values = (void **) malloc((vc+1)*sizeof(void *));
+  args   = (vtype *) arg2;
+
+  /* Set up fmt parameter */
+  types[0] = &ffi_type_pointer;
+  values[0] = &arg1;
+
+  /* Set up rest of parameters */
+  for (i = 0; i < vc; i++) {
+    switch(args[i].type) {
+    case VT_INT:
+      types[1+i] = &ffi_type_uint;
+      values[1+i] = &args[i].val.ivalue;
+      break;
+    case VT_DOUBLE:
+      types[1+i] = &ffi_type_double;
+      values[1+i] = &args[i].val.dvalue;
+      break;
+    case VT_POINTER:
+      types[1+i] = &ffi_type_pointer;
+      values[1+i] = &args[i].val.pvalue;
+      break;
+    default:
+      abort();    /* Whoa! We're seriously hosed */
+      break;   
+    }
+  }
+  if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, vc+1,
+                   &ffi_type_uint, types) == FFI_OK) {
+    ffi_call(&cif, (void (*)()) printf, &result, values);
+  } else {
+    PyErr_SetString(PyExc_RuntimeError, "Whoa!!!!!");
+    free(types);
+    free(values);
+    free(args);
+    return NULL;
+  }
+  free(types);
+  free(values);
+  free(args);
+}
+
+/* The function */
+int printf(const char *fmt, ...);
+
      +
      +

      Much to your amazement, it even seems to work if you try it:

      +
      +
      +>>> import example
+>>> example.printf("Grade: %s   %d/60 = %0.2f%%\n", "Dave", 47, 47.0*100/60)
+Grade: Dave   47/60 = 78.33%
+>>>
+
      +
      +

      Of course, there are still some limitations to consider:

      +
      +
      +>>> example.printf("la de da de da %s", 42)
+Segmentation fault (core dumped)
+
      +
      +

      And, on this note, we leave further exploration of libffi to the + reader as an exercise. Although Python has been used as an example, + most of the techniques in this section can be extrapolated to other + language modules with a bit of work. The only details you need to know + is how the extra arguments are accessed in each target language. For + example, in the Python module, we used the special varargs + variable to get these arguments. Modules such as Tcl8 and Perl5 simply + provide an argument number for the first extra argument. This can be + used to index into an array of passed arguments to get values. Please + consult the chapter on each language module for more details.

      +

      13.7 Wrapping of va_list

      +

      Closely related to variable length argument wrapping, you may + encounter functions that accept a parameter of type va_list. + For example:

      +
      +
      +int vfprintf(FILE *f, const char *fmt, va_list ap);
+
      +
      +

      As far as we know, there is no obvious way to wrap these functions + with SWIG. This is because there is no documented way to assemble the + proper va_list structure (there are no C library functions to do it and + the contents of va_list are opaque). Not only that, the contents of a +va_list structure are closely tied to the underlying call-stack. + It's not clear that exporting a va_list would have any use or + that it would work at all.

      +

      13.8 C++ Issues

      +

      Wrapping of C++ member functions that accept a variable number of + arguments presents a number of challenges. By far, the easiest way to + handle this is to use the %varargs directive. This is portable + and it fully supports classes much like the %rename directive. + For example:

      +
      +
      +%varargs (10, char * = NULL) Foo::bar;
+
+class Foo {
+public:
+     virtual void bar(char *arg, ...);   // gets varargs above
+};
+
+class Spam: public Foo {
+public:
+     virtual void bar(char *arg, ...);   // gets varargs above
+};
+
      +
      +

      %varargs also works with constructors, operators, and any + other C++ programming construct that accepts variable arguments.

      +

      Doing anything more advanced than this is likely to involve a + serious world of pain. In order to use a library like libffi, you will + need to know the underlying calling conventions and details of the C++ + ABI. For instance, the details of how this is passed to member + functions as well as any hidden arguments that might be used to pass + additional information. These details are implementation specific and + may differ between compilers and even different versions of the same + compiler. Also, be aware that invoking a member function is further + complicated if it is a virtual method. In this case, invocation might + require a table lookup to obtain the proper function address (although + you might be able to obtain an address by casting a bound pointer to a + pointer to function as described in the C++ ARM section 18.3.4).

      +

      If you do decide to change the underlying action code, be aware that + SWIG always places the this pointer in arg1. Other + arguments are placed in arg2, arg3, and so forth. For + example:

      +
      +
      +%feature("action") Foo::bar {
+   ...
+   result = arg1->bar(arg2, arg3, etc.);
+   ...
+}
+
      +
      +

      Given the potential to shoot yourself in the foot, it is probably + easier to reconsider your design or to provide an alternative interface + using a helper function than it is to create a fully general wrapper to + a varargs C++ member function.

      +

      13.9 Discussion

      +

      This chapter has provided a number of techniques that can be used to + address the problem of variable length argument wrapping. If you care + about portability and ease of use, the %varargs directive is + probably the easiest way to tackle the problem. However, using + typemaps, it is possible to do some very advanced kinds of wrapping.

      +

      One point of discussion concerns the structure of the libffi + examples in the previous section. Looking at that code, it is not at + all clear that this is the easiest way to solve the problem. However, + there are a number of subtle aspects of the solution to + consider--mostly concerning the way in which the problem has been + decomposed. First, the example is structured in a way that tries to + maintain separation between wrapper-specific information and the + declaration of the function itself. The idea here is that you might + structure your interface like this:

      +
      +
      +%typemap(const char *fmt, ...) {
+   ...
+}
+%feature("action") traceprintf {
+   ...
+}
+
+/* Include some header file with traceprintf in it */
+%include "someheader.h"
+
      +
      +

      Second, careful scrutiny will reveal that the typemaps involving +(...) have nothing whatsoever to do with the libffi library. In + fact, they are generic with respect to the way in which the function is + actually called. This decoupling means that it will be much easier to + consider other library alternatives for making the function call. For + instance, if libffi wasn't supported on a certain platform, you might + be able to use something else instead. You could use conditional + compilation to control this:

      +
      +
      +#ifdef USE_LIBFFI
+%feature("action") printf {
+   ...
+}
+#endif
+#ifdef USE_OTHERFFI
+%feature("action") printf {
+...
+}
+#endif
+
      +
      +

      Finally, even though you might be inclined to just write a + hand-written wrapper for varargs functions, the techniques used in the + previous section have the advantage of being compatible with all other + features of SWIG such as exception handling.

      +

      As a final word, some C programmers seem to have the assumption that + the wrapping of variable length argument functions is an easily solved + problem. However, this section has hopefully dispelled some of these + myths. All things being equal, you are better off avoiding variable + length arguments if you can. If you can't avoid them, please consider + some of the simple solutions first. If you can't live with a simple + solution, proceed with caution. At the very least, make sure you + carefully read the section "A7.3.2 Function Calls" in Kernighan and + Ritchie and make sure you fully understand the parameter passing + conventions used for varargs. Also, be aware of the platform + dependencies and reliability issues that this will introduce. Good + luck.

      +
      +

      14 Warning Messages

      + + +
      + +
      + +

      14.1 Introduction

      +

      During compilation, SWIG may generate a variety of warning messages. + For example:

      +
      +
      +example.i:16: Warning(501): Overloaded declaration ignored.  bar(double)
+example.i:15: Warning(501): Previous declaration is bar(int)
+
      +
      +

      Typically, warning messages indicate non-fatal problems with the + input where the generated wrapper code will probably compile, but it + may not work like you expect.

      +

      14.2 Warning message suppression

      +

      All warning messages have a numeric code that is shown in the + warning message itself. To suppress the printing of a warning message, + a number of techniques can be used. First, you can run SWIG with the +-w command line option. For example:

      +
      +
      +% swig -python -w501 example.i
+% swig -python -w501,505,401 example.i
+
      +
      +

      Alternatively, warnings can be suppressed by inserting a special + preprocessor pragma into the input file:

      +
      +
      +%module example
+#pragma SWIG nowarn=501
+#pragma SWIG nowarn=501,505,401
+
      +
      +

      Finally, code-generation warnings can be disabled on a declaration + by declaration basis using the %warnfilter directive. For + example:

      +
      +
      +%module example
+%warnfilter(501) foo;
+...
+int foo(int);
+int foo(double);              // Silently ignored.
+
      +
      +

      The %warnfilter directive has the same semantics as other + declaration modifiers like %rename, %ignore and +%feature, see the %feature directive + section. For example, if you wanted to suppress a warning for a method + in a class hierarchy, you could do this:

      +
      +
      +%warnfilter(501) Object::foo;
+class Object {
+public:
+   int foo(int);
+   int foo(double);      // Silently ignored
+   ...
+};
+
+class Derived : public Object {
+public:
+   int foo(int);
+   int foo(double);      // Silently ignored
+   ...
+};
+
      +
      +

      Warnings can be suppressed for an entire class by supplying a class + name. For example:

      +
      +
      +%warnfilter(501) Object;
+
+class Object {
+public:
+   ...                      // All 501 warnings ignored in class
+};
+
      +
      +

      There is no option to suppress all SWIG warning messages. The + warning messages are there for a reason---to tell you that something + may be broken in your interface. Ignore the warning messages + at your own peril.

      +

      14.3 Enabling extra warnings

      +

      Some warning messages are disabled by default and are generated only + to provide additional diagnostics. These warnings can be turned on + using the -Wextra option. For example:

      +
      +
      +% swig -Wextra -python example.i
+
      +
      +

      To selectively turn on extra warning messages, you can use the + directives and options in the previous section--simply add a "+" to all + warning numbers. For example:

      +
      +
      +% swig -w+309,+452 example.i
+
      +
      +

      or in your interface file use either

      +
      +
      +#pragma SWIG nowarn=+309,+452
+
      +
      +

      or

      +
      +
      +%warnfilter(+309,+452) foo;
+
      +
      +

      Note: selective enabling of warnings with %warnfilter + overrides any global settings you might have made using -w or +#pragma.

      +

      You can of course also enable all warnings and suppress a select + few, for example:

      +
      +
      +% swig -Wextra -w309,452 example.i
+
      +
      +

      The warnings on the right take precedence over the warnings on the + left, so in the above example -Wextra adds numerous warnings + including 452, but then -w309,452 overrides this and so 452 is + suppressesed.

      +

      If you would like all warnings to appear, regardless of the warning + filters used, then use the -Wall option. The -Wall + option also turns on the extra warnings that -Wextra adds, + however, it is subtely different. When -Wall is used, it also + disables all other warning filters, that is, any warnings suppressed or + added in %warnfilter, #pragma SWIG nowarn or the +-w option.

      +

      14.4 Issuing a warning message

      +

      Warning messages can be issued from an interface file using a number + of directives. The %warn directive is the most simple:

      +
      +
      +%warn "900:This is your last warning!"
+
      +
      +

      All warning messages are optionally prefixed by the warning number + to use. If you are generating your own warnings, make sure you don't + use numbers defined in the table at the end of this section.

      +

      The %ignorewarn directive is the same as %ignore + except that it issues a warning message whenever a matching declaration + is found. For example:

      +
      +
      +%ignorewarn("362:operator= ignored") operator=;
+
      +
      +

      Warning messages can be associated with typemaps using the +warning attribute of a typemap declaration. For example:

      +
      +
      +%typemap(in, warning="901:You are really going to regret this") blah * {
+   ...
+}
+
      +
      +

      In this case, the warning message will be printed whenever the + typemap is actually used.

      +

      14.5 Symbolic symbols

      +

      The swigwarn.swg file that is installed with SWIG contains + symbol constants that could also be used in %warnfilter and +#pragma SWIG nowarn. For example this file contains the following + line:

      +
      +
      +%define SWIGWARN_TYPE_UNDEFINED_CLASS 401 %enddef
+
      +
      +

      so SWIGWARN_TYPE_UNDEFINED_CLASS could be used instead of + 401, for example:

      +
      +
      +#pragma SWIG nowarn=SWIGWARN_TYPE_UNDEFINED_CLASS
+
      +
      +

      or

      +
      +
      +%warnfilter(SWIGWARN_TYPE_UNDEFINED_CLASS) Foo;
+
      +
      +

      14.6 Commentary

      +

      The ability to suppress warning messages is really only provided for + advanced users and is not recommended in normal use. You are advised to + modify your interface to fix the problems highlighted by the warnings + wherever possible instead of suppressing warnings.

      +

      Certain types of SWIG problems are errors. These usually arise due + to parsing errors (bad syntax) or semantic problems for which there is + no obvious recovery. There is no mechanism for suppressing error + messages.

      +

      14.7 Warnings as errors

      +

      Warnings can be handled as errors by using the -Werror + command line option. This will cause SWIG to exit with a non successful + exit code if a warning is encountered.

      +

      14.8 Message output format

      +

      The output format for both warnings and errors can be selected for + integration with your favourite IDE/editor. Editors and IDEs can + usually parse error messages and if in the appropriate format will + easily take you directly to the source of the error. The standard + format is used by default except on Windows where the Microsoft format + is used by default. These can be overridden using command line options, + for example:

      +
      +
      +$ swig -python -Fstandard example.i
+example.i:4: Syntax error in input.
+$ swig -python -Fmicrosoft example.i
+example.i(4): Syntax error in input.
+
      +
      +

      14.9 Warning number reference

      +

      14.9.1 Deprecated features (100-199)

      +
        +
      • 101. Deprecated %extern directive.
        • +
      • 102. Deprecated %val directive.
        • +
      • 103. Deprecated %out directive.
        • +
      • 104. Deprecated %disabledoc directive.
        • +
      • 105. Deprecated %enabledoc directive.
        • +
      • 106. Deprecated %doconly directive.
        • +
      • 107. Deprecated %style directive.
        • +
      • 108. Deprecated %localstyle directive.
        • +
      • 109. Deprecated %title directive.
        • +
      • 110. Deprecated %section directive.
        • +
      • 111. Deprecated %subsection directive.
        • +
      • 112. Deprecated %subsubsection directive.
        • +
      • 113. Deprecated %addmethods directive.
        • +
      • 114. Deprecated %readonly directive.
        • +
      • 115. Deprecated %readwrite directive.
        • +
      • 116. Deprecated %except directive.
        • +
      • 117. Deprecated %new directive.
        • +
      • 118. Deprecated %typemap(except).
        • +
      • 119. Deprecated %typemap(ignore).
        • +
      • 120. Deprecated command line option (-runtime, -noruntime).
        • +
      • 121. Deprecated %name directive.
        • +
      +

      14.9.2 Preprocessor (200-299)

      +
        +
      • 201. Unable to find 'filename'.
        • +
      • 202. Could not evaluate 'expr'.
        • +
      +

      14.9.3 C/C++ Parser (300-399)

      +
        +
      • 301. class keyword used, but not in C++ mode.
        • +
      • 302. Identifier 'name' redefined (ignored).
        • +
      • 303. %extend defined for an undeclared class 'name +'.
        • +
      • 304. Unsupported constant value (ignored).
        • +
      • 305. Bad constant value (ignored).
        • +
      • 306. 'identifier' is private in this context.
        • +
      • 307. Can't set default argument value (ignored)
        • +
      • 308. Namespace alias 'name' not allowed here. Assuming ' +name'
        • +
      • 309. [private | protected] inheritance ignored.
        • +
      • 310. Template 'name' was already wrapped as 'name' + (ignored)
        • +
      • 311. Template partial specialization not supported.
        • +
      • 312. Nested classes not currently supported (ignored).
        • +
      • 313. Unrecognized extern type "name" (ignored).
        • +
      • 314. 'identifier' is a lang keyword.
        • +
      • 315. Nothing known about 'identifier'.
        • +
      • 316. Repeated %module directive.
        • +
      • 317. Specialization of non-template 'name'.
        • +
      • 318. Instantiation of template name is ambiguous. Using + templ at file:line
        • +
      • 319. No access specifier given for base class name + (ignored).
        • +
      • 320. Explicit template instantiation ignored.
        • +
      • 321. identifier conflicts with a built-in name.
        • +
      • 322. Redundant redeclaration of 'name'.
        • +
      • 350. operator new ignored.
        • +
      • 351. operator delete ignored.
        • +
      • 352. operator+ ignored.
        • +
      • 353. operator- ignored.
        • +
      • 354. operator* ignored.
        • +
      • 355. operator/ ignored.
        • +
      • 356. operator% ignored.
        • +
      • 357. operator^ ignored.
        • +
      • 358. operator& ignored.
        • +
      • 359. operator| ignored.
        • +
      • 360. operator~ ignored.
        • +
      • 361. operator! ignored.
        • +
      • 362. operator= ignored.
        • +
      • 363. operator< ignored.
        • +
      • 364. operator> ignored.
        • +
      • 365. operator+= ignored.
        • +
      • 366. operator-= ignored.
        • +
      • 367. operator*= ignored.
        • +
      • 368. operator/= ignored.
        • +
      • 369. operator%= ignored.
        • +
      • 370. operator^= ignored.
        • +
      • 371. operator&= ignored.
        • +
      • 372. operator|= ignored.
        • +
      • 373. operator<< ignored.
        • +
      • 374. operator>>ignored.
        • +
      • 375. operator<<= ignored.
        • +
      • 376. operator>>= ignored.
        • +
      • 377. operator== ignored.
        • +
      • 378. operator!= ignored.
        • +
      • 379. operator<= ignored.
        • +
      • 380. operator>= ignored.
        • +
      • 381. operator&& ignored.
        • +
      • 382. operator|| ignored.
        • +
      • 383. operator++ ignored.
        • +
      • 384. operator-- ignored.
        • +
      • 385. operator, ignored.
        • +
      • 386. operator-<* ignored.
        • +
      • 387. operator-< ignored.
        • +
      • 388. operator() ignored.
        • +
      • 389. operator[] ignored.
        • +
      • 390. operator+ ignored (unary).
        • +
      • 391. operator- ignored (unary).
        • +
      • 392. operator* ignored (unary).
        • +
      • 393. operator& ignored (unary).
        • +
      • 394. operator new[] ignored.
        • +
      • 395. operator delete[] ignored.
        • +
      +

      14.9.4 Types and typemaps (400-499)

      +
        +
      • 401. Nothing known about class 'name'. Ignored.
        • +
      • 402. Base class 'name' is incomplete.
        • +
      • 403. Class 'name' might be abstract.
        • +
      • 450. Deprecated typemap feature ($source/$target).
        • +
      • 451. Setting const char * variable may leak memory.
        • +
      • 452. Reserved
        • +
      • 453. Can't apply (pattern). No typemaps are defined.
        • +
      • 460. Unable to use type type as a function argument.
        • +
      • 461. Unable to use return type type in function name +.
        • +
      • 462. Unable to set variable of type type.
        • +
      • 463. Unable to read variable of type type.
        • +
      • 464. Unsupported constant value.
        • +
      • 465. Unable to handle type type.
        • +
      • 466. Unsupported variable type type.
        • +
      • 467. Overloaded declaration not supported (no type checking + rule for 'type')
        • +
      • 468. No 'throw' typemap defined for exception type type
        • +
      • 469. No or improper directorin typemap defined for type
        • +
      • 470. Thread/reentrant unsafe wrapping, consider returning by value + instead.
        • +
      • 471. Unable to use return type type in director method
        • +
      • 474. Method method usage of the optimal attribute in the + out typemap at file:line ignored as the following + cannot be used to generate optimal code: code
        • +
      • 475. Multiple calls to method might be generated due to + optimal attribute usage in the out typemap at file:line +.
        • +
      +

      14.9.5 Code generation (500-599)

      +
        +
      • 501. Overloaded declaration ignored. decl
        • +
      • 502. Overloaded constructor ignored. decl
        • +
      • 503. Can't wrap 'identifier' unless renamed to a valid + identifier.
        • +
      • 504. Function name must have a return type.
        • +
      • 505. Variable length arguments discarded.
        • +
      • 506. Can't wrap varargs with keyword arguments enabled.
        • +
      • 507. Adding native function name not supported (ignored).
        • +
      • 508. Declaration of 'name' shadows declaration accessible + via operator->() at file:line.
        • +
      • 509. Overloaded declaration is shadowed by declaration + at file:line.
        • +
      • 510. Friend function 'name' ignored.
        • +
      • 511. Can't use keyword arguments with overloaded functions.
        • +
      • 512. Overloaded declaration const ignored. Non-const method + at file:line used.
        • +
      • 513. Can't generate wrappers for unnamed struct/class.
        • +
      • 514.
        • +
      • 515.
        • +
      • 516. Overloaded method declaration ignored. Method + declaration at file:line used.
        • +
      • 517.
        • +
      • 518. Portability warning: File file1 will be overwritten by + file2 on case insensitive filesystems such as Windows' FAT32 and + NTFS unless the class/module name is renamed.
        • +
      • 519. %template() contains no name. Template method ignored: + declaration
        • +
      +

      14.9.6 Language module specific + (800-899)

      +
        +
      • 801. Wrong name (corrected to 'name'). (Ruby).
        • +
      +
        +
      • 810. No jni typemap defined for type (Java).
        • +
      • 811. No jtype typemap defined for type (Java).
        • +
      • 812. No jstype typemap defined for type (Java).
        • +
      • 813. Warning for classname: Base baseclass + ignored. Multiple inheritance is not supported in Java. (Java).
        • +
      • 814.
        • +
      • 815. No javafinalize typemap defined for type (Java).
        • +
      • 816. No javabody typemap defined for type (Java).
        • +
      • 817. No javaout typemap defined for type (Java).
        • +
      • 818. No javain typemap defined for type (Java).
        • +
      • 819. No javadirectorin typemap defined for type (Java).
        • +
      • 820. No javadirectorout typemap defined for type (Java).
        • +
      • 821.
        • +
      • 822. Covariant return types not supported in Java. Proxy method will + return basetype (Java).
        • +
      • 823. No javaconstruct typemap defined for type (Java).
        • +
      • 824. Missing JNI descriptor in directorin typemap defined for + type (Java).
        • +
      +
        +
      • 830. No ctype typemap defined for type (C#).
        • +
      • 831. No cstype typemap defined for type (C#).
        • +
      • 832. No cswtype typemap defined for type (C#).
        • +
      • 833. Warning for classname: Base baseclass + ignored. Multiple inheritance is not supported in C#. (C#).
        • +
      • 834.
        • +
      • 835. No csfinalize typemap defined for type (C#).
        • +
      • 836. No csbody typemap defined for type (C#).
        • +
      • 837. No csout typemap defined for type (C#).
        • +
      • 838. No csin typemap defined for type (C#).
        • +
      • 839.
        • +
      • 840.
        • +
      • 841.
        • +
      • 842. Covariant return types not supported in C#. Proxy method will + return basetype (C#).
        • +
      • 843. No csconstruct typemap defined for type (C#).
        • +
      • 844. C# exception may not be thrown - no $excode or excode attribute + in typemap typemap. (C#).
        • +
      • 845. Unmanaged code contains a call to a + SWIG_CSharpSetPendingException method and C# code does not handle + pending exceptions via the canthrow attribute. (C#).
        • +
      +
        +
      • 870. Warning for classname: Base baseclass + ignored. Multiple inheritance is not supported in PHP.
        • +
      • 871. Unrecognized pragma pragma. (Php).
        • +
      +

      14.9.7 User defined (900-999)

      +

      These numbers can be used by your own application.

      +

      14.10 History

      +

      The ability to control warning messages was first added to + SWIG-1.3.12.

      +
      +

      15 Working with Modules

      + + +
      + +
      + +

      15.1 Modules Introduction

      +

      Each invocation of SWIG requires a module name to be specified. The + module name is used to name the resulting target language extension + module. Exactly what this means and and what the name is used for + depends on the target language, for example the name can define a + target language namespace or merely be a useful name for naming files + or helper classes. Essentially, a module comprises target language + wrappers for a chosen collection of global variables/functions, + structs/classes and other C/C++ types.

      +

      The module name can be supplied in one of two ways. The first is to + specify it with the special %module directive. This directive + must appear at the beginning of the interface file. The general form of + this directive is:

      +
      +
      +%module(option1="value1",option2="value2",...) modulename
+
      +
      +

      where the modulename is mandatory and the options add one or more + optional additional features. Typically no options are specified, for + example:

      +
      +
      +%module mymodule
+
      +
      +

      The second way to specify the module name is with the -module + command line option, for example -module mymodule. If the + module name is supplied on the command line, it overrides the name + specified by the %module directive.

      +

      When first working with SWIG, users commonly start by creating a + single module. That is, you might define a single SWIG interface that + wraps some set of C/C++ code. You then compile all of the generated + wrapper code together and use it. For large applications, however, this + approach is problematic---the size of the generated wrapper code can be + rather large. Moreover, it is probably easier to manage the target + language interface when it is broken up into smaller pieces.

      +

      This chapter describes the problem of using SWIG in programs where + you want to create a collection of modules. Each module in the + collection is created via separate invocations of SWIG.

      +

      15.2 Basics

      +

      The basic usage case with multiple modules is when modules do not + have cross-references (ie. when wrapping multiple independent C APIs). + In that case, swig input files should just work out of the box - you + simply create multiple wrapper .cxx files, link them into your + application, and insert/load each in the scripting language runtime as + you would do for the single module case.

      +

      A bit more complex is the case in which modules need to share + information. For example, when one module extends the class of another + by deriving from it:

      +
      +
      +// File: base.h
+class base {
+public:
+  int foo();
+};
+
      +
       
      +
      +// File: base_module.i
+%module base_module
+
+%{
+#include "base.h"
+%}
+%include "base.h"
+
      +
       
      +
      +// File: derived_module.i
+%module derived_module
+
+%import "base_module.i"
+
+%inline %{
+class derived : public base {
+public:
+  int bar();
+};
+%}
+
      +
      +

      To create the wrapper properly, module derived_module needs + to know about the base class and that its interface is covered + in another module. The line %import "base_module.i" lets SWIG + know exactly that. Oftentimes the .h file is passed to +%import instead of the .i, which unfortunately doesn't + work for all language modules. For example, Python requires the name of + module that the base class exists in so that the proxy classes can + fully inherit the base class's methods. Typically you will get a + warning when the module name is missing, eg:

      +
      +
      +derived_module.i:8: Warning(401): Base class 'base' ignored - unknown module name for base. Either import 
+the appropriate module interface file or specify the name of the module in the %import directive.
+
      +
      +

      It is sometimes desirable to import the header file rather than the + interface file and overcome the above warning. For example in the case + of the imported interface being quite large, it may be desirable to + simplify matters and just import a small header file of dependent + types. This can be done by specifying the optional module + attribute in the %import directive. The derived_module.i + file shown above could be replaced with the following:

      +
      +// File: derived_module.i
+%module derived_module
+
+%import(module="base_module") "base.h"
+
+%inline %{
+class derived : public base {
+public:
+  int bar();
+};
+
      +

      +

      Note that "base_module" is the module name and is the same as that + specified in %module in base_module.i as well as the +%import in derived_module.i.

      +

      Another issue to beware of is that multiple dependent wrappers + should not be linked/loaded in parallel from multiple threads as SWIG + provides no locking - for more on that issue, read on.

      +

      15.3 The SWIG runtime code

      +

      Many of SWIG's target languages generate a set of functions commonly + known as the "SWIG runtime." These functions are primarily related to + the runtime type system which checks pointer types and performs other + tasks such as proper casting of pointer values in C++. As a general + rule, the statically typed target languages, such as Java, use the + language's built in static type checking and have no need for a SWIG + runtime. All the dynamically typed / interpreted languages rely on the + SWIG runtime.

      +

      The runtime functions are private to each SWIG-generated module. + That is, the runtime functions are declared with "static" linkage and + are visible only to the wrapper functions defined in that module. The + only problem with this approach is that when more than one SWIG module + is used in the same application, those modules often need to share type + information. This is especially true for C++ programs where SWIG must + collect and share information about inheritance relationships that + cross module boundaries.

      +

      To solve the problem of sharing information across modules, a + pointer to the type information is stored in a global variable in the + target language namespace. During module initialization, type + information is loaded into the global data structure of type + information from all modules.

      +

      There are a few trade offs with this approach. This type information + is global across all SWIG modules loaded, and can cause type conflicts + between modules that were not designed to work together. To solve this + approach, the SWIG runtime code uses a define SWIG_TYPE_TABLE to + provide a unique type table. This behavior can be enabled when + compiling the generated _wrap.cxx or _wrap.c file by adding + -DSWIG_TYPE_TABLE=myprojectname to the command line argument.

      +

      Then, only modules compiled with SWIG_TYPE_TABLE set to + myprojectname will share type information. So if your project has three + modules, all three should be compiled with + -DSWIG_TYPE_TABLE=myprojectname, and then these three modules will + share type information. But any other project's types will not + interfere or clash with the types in your module.

      +

      Another issue relating to the global type table is thread safety. If + two modules try and load at the same time, the type information can + become corrupt. SWIG currently does not provide any locking, and if you + use threads, you must make sure that modules are loaded serially. Be + careful if you use threads and the automatic module loading that some + scripting languages provide. One solution is to load all modules before + spawning any threads, or use SWIG_TYPE_TABLE to separate type tables so + they do not clash with each other.

      +

      Lastly, SWIG uses a #define SWIG_RUNTIME_VERSION, located in + Lib/swigrun.swg and near the top of every generated module. This number + gets incremented when the data structures change, so that SWIG modules + generated with different versions can peacefully coexist. So the type + structures are separated by the (SWIG_TYPE_TABLE, SWIG_RUNTIME_VERSION) + pair, where by default SWIG_TYPE_TABLE is empty. Only modules compiled + with the same pair will share type information.

      +

      15.4 External access to the runtime

      +

      As described in The run-time type + checker, the functions SWIG_TypeQuery, +SWIG_NewPointerObj, and others sometimes need to be called. Calling + these functions from a typemap is supported, since the typemap code is + embedded into the _wrap.c file, which has those declarations + available. If you need to call the SWIG run-time functions from another + C file, there is one header you need to include. To generate the header + that needs to be included, run the following command:

      +
      +$ swig -python -external-runtime <filename>
+
      +

      +

      The filename argument is optional and if it is not passed, then the + default filename will be something like swigpyrun.h, depending + on the language. This header file should be treated like any of the + other _wrap.c output files, and should be regenerated when the _wrap + files are. After including this header, your code will be able to call +SWIG_TypeQuery, SWIG_NewPointerObj, SWIG_ConvertPtr + and others. The exact argument parameters for these functions might + differ between language modules; please check the language module + chapters for more information.

      +

      Inside this header the functions are declared static and are included + inline into the file, and thus the file does not need to be linked + against any SWIG libraries or code (you might still need to link + against the language libraries like libpython-2.3). Data is shared + between this file and the _wrap.c files through a global variable in + the scripting language. It is also possible to copy this header file + along with the generated wrapper files into your own package, so that + you can distribute a package that can be compiled without SWIG + installed (this works because the header file is self-contained, and + does not need to link with anything).

      +

      This header will also use the -DSWIG_TYPE_TABLE described above, so + when compiling any code which includes the generated header file should + define the SWIG_TYPE_TABLE to be the same as the module whose types you + are trying to access.

      +

      15.5 A word of caution about static + libraries

      +

      When working with multiple SWIG modules, you should take care not to + use static libraries. For example, if you have a static library +libfoo.a and you link a collection of SWIG modules with that + library, each module will get its own private copy of the library code + inserted into it. This is very often NOT what you want and it + can lead to unexpected or bizarre program behavior. When working with + dynamically loadable modules, you should try to work exclusively with + shared libraries.

      +

      15.6 References

      +

      Due to the complexity of working with shared libraries and multiple + modules, it might be a good idea to consult an outside reference. John + Levine's "Linkers and Loaders" is highly recommended.

      +

      15.7 Reducing the wrapper file size

      +

      Using multiple modules with the %import directive is the + most common approach to modularising large projects. In this way a + number of different wrapper files can be generated, thereby avoiding + the generation of a single large wrapper file. There are a couple of + alternative solutions for reducing the size of a wrapper file through + the use of command line options and features.

      +

      -fcompact +
      This command line option will compact the size of the wrapper file + without changing the code generated into the wrapper file. It simply + removes blank lines and joins lines of code together. This is useful + for compilers that have a maximum file size that can be handled.

      +

      -fvirtual +
      This command line option will remove the generation of superfluous + virtual method wrappers. Consider the following inheritance hierarchy:

      +
      +
      +struct Base {
+  virtual void method();
+  ...
+};
+
+struct Derived : Base {
+  virtual void method();
+  ...
+};
+
      +
      +

      Normally wrappers are generated for both methods, whereas this + command line option will suppress the generation of a wrapper for +Derived::method. Normal polymorphic behaviour remains as +Derived::method will still be called should you have a Derived + instance and call the wrapper for Base::method.

      +

      %feature("compactdefaultargs") +
      This feature can reduce the number of wrapper methods when wrapping + methods with default arguments. The section on +default arguments discusses the feature and its limitations.

      +
      +

      16 Using SWIG with ccache - ccache-swig(1) + manpage

      + + +
      + +
      + +

      +

      16.1 NAME

      +

      ccache-swig - a fast compiler cache

      +

      +

      16.2 SYNOPSIS

      +

      ccache-swig [OPTION]

      +

      ccache-swig <compiler> [COMPILER OPTIONS]

      +

      <compiler> [COMPILER OPTIONS]

      +

      +

      16.3 DESCRIPTION

      +

      ccache-swig is a compiler cache. It speeds up re-compilation of + C/C++/SWIG code by caching previous compiles and detecting when the + same compile is being done again. ccache-swig is ccache plus support + for SWIG. ccache and ccache-swig are used interchangeably in this + document.

      +

      +

      16.4 OPTIONS SUMMARY

      +

      Here is a summary of the options to ccache-swig.

      +

      +
      +
+-s                      show statistics summary
+-z                      zero statistics
+-c                      run a cache cleanup
+-C                      clear the cache completely
+-F <n>                  set maximum files in cache
+-M <n>                  set maximum size of cache (use G, M or K)
+-h                      this help page
+-V                      print version number
+
+
      +

      +

      16.5 OPTIONS

      +

      These options only apply when you invoke ccache as "ccache-swig". + When invoked as a compiler none of these options apply. In that case + your normal compiler options apply and you should refer to your + compilers documentation.

      +

      +
      +

      +

      -h
      +
      Print a options summary page +

      +

      +
      +
      -s
      +
      Print the current statistics summary for the cache. The statistics + are stored spread across the subdirectories of the cache. Using + "ccache-swig -s" adds up the statistics across all subdirectories and + prints the totals. +

      +

      +
      +
      -z
      +
      Zero the cache statistics. +

      +

      +
      +
      -V
      +
      Print the ccache version number +

      +

      +
      +
      -c
      +
      Clean the cache and re-calculate the cache file count and size + totals. Normally the -c option should not be necessary as ccache keeps + the cache below the specified limits at runtime and keeps statistics up + to date on each compile. This option is mostly useful if you manually + modify the cache contents or believe that the cache size statistics may + be inaccurate. +

      +

      +
      +
      -C
      +
      Clear the entire cache, removing all cached files. +

      +

      +
      +
      -F <maxfiles>
      +
      This sets the maximum number of files allowed in the cache. The + value is stored inside the cache directory and applies to all future + compiles. Due to the way the value is stored the actual value used is + always rounded down to the nearest multiple of 16. +

      +

      +
      +
      -M <maxsize>
      +
      This sets the maximum cache size. You can specify a value in + gigabytes, megabytes or kilobytes by appending a G, M or K to the + value. The default is gigabytes. The actual value stored is rounded + down to the nearest multiple of 16 kilobytes. +

      +
      +

      +
      +

      +

      16.6 INSTALLATION

      +

      There are two ways to use ccache. You can either prefix your compile + commands with "ccache-swig" or you can create a symbolic link between + ccache-swig and the names of your compilers. The first method is most + convenient if you just want to try out ccache or wish to use it for + some specific projects. The second method is most useful for when you + wish to use ccache for all your compiles.

      +

      To install for usage by the first method just copy ccache-swig to + somewhere in your path.

      +

      To install for the second method do something like this:

      +
      +
+  cp ccache-swig /usr/local/bin/
+  ln -s /usr/local/bin/ccache-swig /usr/local/bin/gcc
+  ln -s /usr/local/bin/ccache-swig /usr/local/bin/g++
+  ln -s /usr/local/bin/ccache-swig /usr/local/bin/cc
+  ln -s /usr/local/bin/ccache-swig /usr/local/bin/swig
+
+
      + This will work as long as /usr/local/bin comes before the path to gcc + (which is usually in /usr/bin). After installing you may wish to run + "which gcc" to make sure that the correct link is being used. +

      Note! Do not use a hard link, use a symbolic link. A hardlink will + cause "interesting" problems.

      +

      +

      16.7 EXTRA OPTIONS

      +

      When run as a compiler front end ccache usually just takes the same + command line options as the compiler you are using. The only exception + to this is the option '--ccache-skip'. That option can be used to tell + ccache that the next option is definitely not a input filename, and + should be passed along to the compiler as-is.

      +

      The reason this can be important is that ccache does need to parse + the command line and determine what is an input filename and what is a + compiler option, as it needs the input filename to determine the name + of the resulting object file (among other things). The heuristic ccache + uses in this parse is that any string on the command line that exists + as a file is treated as an input file name (usually a C file). By using + --ccache-skip you can force an option to not be treated as an input + file name and instead be passed along to the compiler as a command line + option.

      +

      +

      16.8 ENVIRONMENT VARIABLES

      +

      ccache uses a number of environment variables to control operation. + In most cases you won't need any of these as the defaults will be fine.

      +

      +
      +

      +

      +

      CCACHE_DIR
      +
      the CCACHE_DIR environment variable specifies where ccache will + keep its cached compiler output. The default is "$HOME/.ccache". +

      +

      +
      +
      CCACHE_TEMPDIR
      +
      the CCACHE_TEMPDIR environment variable specifies where ccache will + put temporary files. The default is the same as CCACHE_DIR. Note that + the CCACHE_TEMPDIR path must be on the same filesystem as the + CCACHE_DIR path, so that renames of files between the two directories + can work. +

      +

      +
      +
      CCACHE_LOGFILE
      +
      If you set the CCACHE_LOGFILE environment variable then ccache will + write some log information on cache hits and misses in that file. This + is useful for tracking down problems. +

      +

      +
      +
      CCACHE_VERBOSE
      +
      If you set the CCACHE_VERBOSE environment variable then ccache will + display on stdout all the compiler invocations that it makes. This can + useful for debugging unexpected problems. +

      +

      +
      +
      CCACHE_PATH
      +
      You can optionally set CCACHE_PATH to a colon separated path where + ccache will look for the real compilers. If you don't do this then + ccache will look for the first executable matching the compiler name in + the normal PATH that isn't a symbolic link to ccache itself. +

      +

      +
      +
      CCACHE_CC
      +
      You can optionally set CCACHE_CC to force the name of the compiler + to use. If you don't do this then ccache works it out from the command + line. +

      +

      +
      +
      CCACHE_PREFIX
      +
      This option adds a prefix to the command line that ccache runs when + invoking the compiler. Also see the section below on using ccache with + distcc. +

      +

      +
      +
      CCACHE_DISABLE
      +
      If you set the environment variable CCACHE_DISABLE then ccache will + just call the real compiler, bypassing the cache completely. +

      +

      +
      +
      CCACHE_READONLY
      +
      the CCACHE_READONLY environment variable tells ccache to attempt to + use existing cached object files, but not to try to add anything new to + the cache. If you are using this because your CCACHE_DIR is read-only, + then you may find that you also need to set CCACHE_TEMPDIR as otherwise + ccache will fail to create the temporary files. +

      +

      +
      +
      CCACHE_CPP2
      +
      If you set the environment variable CCACHE_CPP2 then ccache will + not use the optimisation of avoiding the 2nd call to the pre-processor + by compiling the pre-processed output that was used for finding the + hash in the case of a cache miss. This is primarily a debugging option, + although it is possible that some unusual compilers will have problems + with the intermediate filename extensions used in this optimisation, in + which case this option could allow ccache to be used. +

      +

      +
      +
      CCACHE_NOCOMPRESS
      +
      If you set the environment variable CCACHE_NOCOMPRESS then there is + no compression used on files that go into the cache. However, this + setting has no effect on how files are retrieved from the cache, + compressed results will still be usable. +

      +

      +
      +
      CCACHE_NOSTATS
      +
      If you set the environment variable CCACHE_NOSTATS then ccache will + not update the statistics files on each compile. +

      +

      +
      +
      CCACHE_NLEVELS
      +
      The environment variable CCACHE_NLEVELS allows you to choose the + number of levels of hash in the cache directory. The default is 2. The + minimum is 1 and the maximum is 8. +

      +

      +
      +
      CCACHE_HARDLINK
      +
      If you set the environment variable CCACHE_HARDLINK then ccache + will attempt to use hard links from the cache directory when creating + the compiler output rather than using a file copy. Using hard links is + faster, but can confuse programs like 'make' that rely on modification + times. Hard links are never made for compressed cache files. +

      +

      +
      +
      CCACHE_RECACHE
      +
      This forces ccache to not use any cached results, even if it finds + them. New results are still cached, but existing cache entries are + ignored. +

      +

      +
      +
      CCACHE_UMASK
      +
      This sets the umask for ccache and all child processes (such as the + compiler). This is mostly useful when you wish to share your cache with + other users. Note that this also affects the file permissions set on + the object files created from your compilations. +

      +

      +
      +
      CCACHE_HASHDIR
      +
      This tells ccache to hash the current working directory when + calculating the hash that is used to distinguish two compiles. This + prevents a problem with the storage of the current working directory in + the debug info of a object file, which can lead ccache to give a cached + object file that has the working directory in the debug info set + incorrectly. This option is off by default as the incorrect setting of + this debug info rarely causes problems. If you strike problems with gdb + not using the correct directory then enable this option. +

      +

      +
      +
      CCACHE_UNIFY
      +
      If you set the environment variable CCACHE_UNIFY then ccache will + use the C/C++ unifier when hashing the pre-processor output if -g is + not used in the compile. The unifier is slower than a normal hash, so + setting this environment variable loses a little bit of speed, but it + means that ccache can take advantage of not recompiling when the + changes to the source code consist of reformatting only. Note that + using CCACHE_UNIFY changes the hash, so cached compiles with + CCACHE_UNIFY set cannot be used when CCACHE_UNIFY is not set and vice + versa. The reason the unifier is off by default is that it can give + incorrect line number information in compiler warning messages. +

      +

      +
      +
      CCACHE_EXTENSION
      +
      Normally ccache tries to automatically determine the extension to + use for intermediate C pre-processor files based on the type of file + being compiled. Unfortunately this sometimes doesn't work, for example + when using the aCC compiler on HP-UX. On systems like this you can use + the CCACHE_EXTENSION option to override the default. On HP-UX set this + environment variable to "i" if you use the aCC compiler. +

      +

      +
      +
      CCACHE_STRIPC
      +
      If you set the environment variable CCACHE_STRIPC then ccache will + strip the -c option when invoking the preprocessor. This option is + primarily for the Sun Workshop C++ compiler as without this option an + unwarranted warning is displayed: CC: Warning: "-E" redefines product + from "object" to "source (stdout)" when -E and -c is used together. +

      +

      +
      +
      CCACHE_SWIG
      +
      When using SWIG as the compiler and it does not have 'swig' in the + executable name, then the CCACHE_SWIG environment variable needs to be + set in order for ccache to work correctly with SWIG. The use of + CCACHE_CPP2 is also recommended for SWIG due to some preprocessor + quirks, however, use of CCACHE_CPP2 can often be skipped -- check your + generated code with and without this option set. Known problems are + using preprocessor directives within %inline blocks and the use of + '#pragma SWIG'. +

      +
      +

      +
      +

      +

      16.9 CACHE SIZE MANAGEMENT

      +

      By default ccache has a one gigabyte limit on the cache size and no + maximum number of files. You can set a different limit using the + "ccache -M" and "ccache -F" options, which set the size and number of + files limits.

      +

      When these limits are reached ccache will reduce the cache to 20% + below the numbers you specified in order to avoid doing the cache clean + operation too often.

      +

      +

      16.10 CACHE COMPRESSION

      +

      By default on most platforms ccache will compress all files it puts + into the cache using the zlib compression. While this involves a + negligible performance slowdown, it significantly increases the number + of files that fit in the cache. You can turn off compression setting + the CCACHE_NOCOMPRESS environment variable.

      +

      +

      16.11 HOW IT WORKS

      +

      The basic idea is to detect when you are compiling exactly the same + code a 2nd time and use the previously compiled output. You detect that + it is the same code by forming a hash of:

      +

      +
        +
      • the pre-processor output from running the compiler with -E
        • +
      • the command line options
        • +
      • the real compilers size and modification time
        • +
      • any stderr output generated by the compiler
        • +
      +

      These are hashed using md4 (a strong hash) and a cache file is + formed based on that hash result. When the same compilation is done a + second time ccache is able to supply the correct compiler output + (including all warnings etc) from the cache.

      +

      ccache has been carefully written to always produce exactly the same + compiler output that you would get without the cache. If you ever + discover a case where ccache changes the output of your compiler then + please let me know.

      +

      +

      16.12 USING CCACHE WITH DISTCC

      +

      distcc is a very useful program for distributing compilation across + a range of compiler servers. It is often useful to combine distcc with + ccache, so that compiles that are done are sped up by distcc, but that + ccache avoids the compile completely where possible.

      +

      To use distcc with ccache I recommend using the CCACHE_PREFIX + option. You just need to set the environment variable CCACHE_PREFIX to + 'distcc' and ccache will prefix the command line used with the compiler + with the command 'distcc'.

      +

      +

      16.13 SHARING A CACHE

      +

      A group of developers can increase the cache hit rate by sharing a + cache directory. The hard links however cause unwanted side effects, as + all links to a cached file share the file's modification timestamp. + This results in false dependencies to be triggered by timestamp-based + build systems whenever another user links to an existing file. + Typically, users will see that their libraries and binaries are + relinked without reason. To share a cache without side effects, the + following conditions need to be met:

      +

      +
        +
      • Use the same CCACHE_DIR environment variable + setting
        • +
      • Unset the CCACHE_HARDLINK environment variable
        • +
      • Make sure everyone sets the CCACHE_UMASK environment variable to + 002, this ensures that cached files are accessible to everyone in the + group.
        • +
      • Make sure that all users have write permission in the entire cache + directory (and that you trust all users of the shared cache).
        • +
      • Make sure that the setgid bit is set on all directories in the + cache. This tells the filesystem to inherit group ownership for new + directories. The command "chmod g+s `find $CCACHE_DIR -type d`" might + be useful for this.
        • +
      • Set CCACHE_NOCOMPRESS for all users, if there are + users with versions of ccache that do not support compression.
        • +
      +

      +

      16.14 HISTORY

      +

      ccache was inspired by the compilercache shell script script written + by Erik Thiele and I would like to thank him for an excellent piece of + work. See +http://www.erikyyy.de/compilercache/ for the Erik's scripts. + ccache-swig is a port of the original ccache with support added for use + with SWIG.

      +

      I wrote ccache because I wanted to get a bit more speed out of a + compiler cache and I wanted to remove some of the limitations of the + shell-script version.

      +

      +

      16.15 DIFFERENCES FROM COMPILERCACHE

      +

      The biggest differences between Erik's compilercache script and + ccache are:

      +
        +
      • ccache is written in C, which makes it a bit faster (calling out to + external programs is mostly what slowed down the scripts).
        • +
      • ccache can automatically find the real compiler
        • +
      • ccache keeps statistics on hits/misses
        • +
      • ccache can do automatic cache management
        • +
      • ccache can cache compiler output that includes warnings. In many + cases this gives ccache a much higher cache hit rate.
        • +
      • ccache can handle a much wider ranger of compiler options
        • +
      • ccache avoids a double call to cpp on a cache miss
        • +
      +

      +

      16.16 CREDITS

      +

      Thanks to the following people for their contributions to ccache

      +
        +
      • Erik Thiele for the original compilercache script
        • +
      • Luciano Rocha for the idea of compiling the pre-processor output to + avoid a 2nd cpp pass
        • +
      • Paul Russell for many suggestions and the debian packaging
        • +
      +

      +

      16.17 AUTHOR

      +

      ccache was written by Andrew Tridgell +http://samba.org/~tridge/. ccache was adapted to create ccache-swig + for use with SWIG by William Fulton.

      +

      If you wish to report a problem or make a suggestion then please + email the SWIG developers on the swig-devel mailing list, see +http://www.swig.org/mail.html

      +

      ccache is released under the GNU General Public License version 2 or + later. Please see the file COPYING for license details.

      +

      +
      + + +

      17 SWIG and Allegro Common Lisp

      + + +
      + +
      + +

      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.

      +

      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.

      +

      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.

      +

      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 (UFFI or 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.

      +

      17.1 Basics

      +

      17.1.1 Running Swig

      +

      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.

      +

      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 .i extension--containing any foreign declarations of + identifiers you wish to use. The most common approach is to use a 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.

      +

      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.

      +

      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.

      +
      example.i +
      +%module example
+
+%include "header.h"
+
+int fact(int n);
+
      +
      +

      The contents of header.h are very simple:

      +
      header.h +
      +int fact(char *statement);   // pass it a fact, and it will rate it.
+
      +
      +

      The contents of example.cl will look like this:

      +
      example.cl +
      +(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)))
+
      +
      +

      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 erroneous. Function + overloading is not supported in C, and this code will not compile even + though SWIG did not complain.

      +

      In order to generate a C interface to Allegro CL using this code run + swig using the -allegrocl option, as below:

      +
      +
      +% swig -allegrocl example.i
+
      +
      +

      When building an interface to C++ code, include the -c++ + option:

      +
      +
      +% swig -allegrocl -c++ example.i
+
      +
      +

      As a result of running one of the above commands, a file named +example.cl will be generated containing the lisp side of the + interface. As well, a file example_wrap.cxx 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.

      +

      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.

      +

      The generated wrapper file is below. It contains very simple + wrappers by default, that simply pass the arguments to the actual + function.

      +
      example_wrap.i +
      +   ... 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;
+    }
+}
+
      +
      +

      And again, the generated lisp code. Note that it differs from what + is generated when parsing C code:

      +
      +
      +   ...
+
+(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)))
+
      +
      +

      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 Function overloading/Parameter + defaulting.

      +

      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.

      +

      17.1.2 Command Line Options

      +

      There are three Allegro CL specific command-line option:

      +
      +
      +swig -allegrocl [ options ] filename
+
+   -identifier-converter [name] - Binds the variable swig:*swig-identifier-convert* 
+                                  in the generated .cl file to name.
+				  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 swig.<module-name> rather than
+	      swig. 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.
+
      +
      +

      See Section 17.5 Identifier converter + functions for more details.

      +

      17.1.3 Inserting user code into + generated files

      +

      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 #include "header.h" directive. This can be done using the + SWIG %insert(section) %{ ...code... %} directive:

      +
      +
      +%module example
+
+%{
+#include "header.h"
+%}
+
+%include "header.h"
+
+int fact(int n);
+
      +
      +

      Additional sections have been added for inserting into the generated + lisp interface file

      +
        +
      • lisphead - inserts before type declarations
        • +
      • lisp - inserts after type declarations according to where + it appears in the .i file
        • +
      +

      Note that the block %{ ... %} is effectively a shortcut for + %insert("header") %{ ... %}.

      +

      17.2 Wrapping Overview

      +

      New users to SWIG are encouraged to read SWIG Basics +, and SWIG and C++, for those interested in + generating an interface to C++.

      +

      17.2.1 Function Wrapping

      +

      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.

      +

      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:

      +
      +
      +        ______________
+       |              |  (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
+
      +
      +

      17.2.2 Foreign Wrappers

      +

      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.

      +

      17.2.3 FFI Wrappers

      +

      These are the generated ff:def-foreign-call forms. No typemaps are + applicable to this layer, but the %ffargs directive is + available for use in .i files, to specify which keyword arguments + should be specified for a given function.

      +
      ffargs.i: +
      +%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();
+
      +
      +

      Generates:

      +
      ffargs.cl: +
      +(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))
+
      +
      +
      %ffargs(strings_convert="t");
      +
      +

      Is the only default value specified in allegrocl.swg to + force the muffling of warnings about automatic string conversion when + defining ff:def-foreign-call's.

      +

      17.2.4 Non-overloaded Defuns

      +

      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 lin 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 lout typemap.

      +

      17.2.5 Overloaded Defuns

      +

      In the case of overloaded functions, mulitple 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 lispclass 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 lout typemap.

      +

      17.2.6 What about constant and variable + access?

      +

      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, defconstant and +ff:def-foreign-variable forms will be generated for accessing + constants and global variables. These, along with the defuns + listed above are the intended API for calling into the foreign module.

      +

      17.2.7 Object Wrapping

      +

      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.

      +

      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.

      +

      17.3 Wrapping Details

      +

      In this section is described how particular C/C++ constructs are + translated into lisp.

      +

      17.3.1 Namespaces

      +

      C++ namespaces are translated into Lisp packages by SWIG. The Global + namespace is mapped to a package named by the %module + directive or the -module command-line argument. Further + namespaces are generated by the swig-defpackage utility + function and given names based on Allegro CLs nested namespace + convention. For example:

      +
      foo.i: +
      +%module foo
+
+%{
+#include "foo.h"
+%}
+
+%include "foo.h"
+
+namespace car {
+   ...
+   namespace tires {
+      int do_something(int n);
+   }
+}
+
      +
      +

      Generates the following code.

      +
      foo.cl +
      +(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)))
+
      +
      +

      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(*).

      +

      (*) Except for the package named by the module, all namespace + names are passed to the identifier-converter-function as strings with a + :type of :namespace. It is the job of this function + to generate the desired symbol, accounting for case preferences, + additional naming cues, etc.

      +

      Note that packages created by swig-defpackage do not use + the COMMON-LISP or EXCL package. This reduces possible conflicts when + defining foreign types via the SWIG interface in all but the + toplevel modules package. This may lead to confusion if, for + example, the current package is foo.car.tires and you attempt + to use a common-lisp function such as (car '(1 2 3).

      +

      17.3.2 Constants

      +

      Constants, as declared by the preprocessor #define macro or SWIG +%constant directive, are included in SWIGs 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).

      +

      Here are examples of simple preprocessor constants when using + -nocwrap.

      +
      +
      +#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
+
      +
      +

      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.

      +

      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.

      +
      +
      +#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
+
      +
      +

      Users are cautioned to get to know their constants before use, or + not use the -nocwrap command-line option.

      +

      17.3.3 Variables

      +

      For C wrapping, a def-foreign-variable call is generated for access + to global variables.

      +

      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.

      +
      vars.h +
      +namespace nnn {
+  int const global_var = 2;
+  float glob_float = 2.0;
+}
+
      +
      +

      Generated code:

      +
      vars.cl +
      +(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))
+
      +
      +

      Note also, that where applicable, setter wrappers are implemented as + setf methods on the getter function, providing a lispy interface to the + foreign code.

      +
      +
      +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
+
      +
      +

      17.3.4 Enumerations

      +

      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 it's 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 typemaps +.

      +

      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 it's value + into lisp.

      +

      For example, the following header file

      enum.h: +
      +enum COL { RED, GREEN, BLUE };	
+enum FOO { FOO1 = 10, FOO2, FOO3 };
+
      +

      +

      In -nocwrap mode, generates

      +
      enum.cl: +
      +(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))
+
      +
      +

      And when generating a .cxx wrapper

      enum_wrap.cxx: +
      +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;
+
      +

      +

      and

      +
      enum.cl: +
      +(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)
+
+
      +
      +

      17.3.5 Arrays

      +

      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.

      +

      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.

      +
      array.h +
      +#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];
+}
+
      +
      +

      Generates:

      +
      array.cl +
      +(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)))
+
      +
      +

      17.3.6 Classes and Structs and Unions + (oh my!)

      +

      17.3.6.1 CLOS wrapping of

      +

      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 X, the wrapping defun (or + defmethod) on the Lisp side will automatically wrap the pointer + returned in an instance of the apropriate class. This makes it much + easier to write and debug code than if pointers were passed around as a + jumble of integer values.

      +

      17.3.6.2 CLOS Inheritance

      +

      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. It's 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.

      +

      17.3.6.3 Member fields and functions

      +

      All public fields will have accessor getter/setter functions + generated for them, as appropriate. All public member functions will + have wrapper functions generated.

      +

      We currently ignore anything that isn't public (i.e. +private or protected), because the C++ compiler won't + allow the wrapper functions to access such fields. Likewise, the + interface does nothing for friend directives,

      +

      17.3.6.4 Why not directly access C++ + classes using foreign types?

      +

      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.

      +

      17.3.7 Templates

      +

      17.3.7.1 Generating wrapper code for + templates

      +

      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 +%template directive.

      +

      17.3.7.2 Implicit Template + instantiation

      +

      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.

      +

      17.3.8 Typedef, Templates, and Synonym + Types

      +

      In C/C++ it is possible, via typedef, to have many names refer to + the same type. In general, this is not a problem, though it + can lead to confusion. Assume the below C++ header file:

      +
      synonyms.h +
      +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 */
+
      +
      +

      The function zzz 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 A. Assuming a + simple implementation, a call to xxx(1) will return a pointer + to an A object, which will be wrapped in a CLOS instance of class A +, and a call to yyy(1) will result in a CLOS instance of type +Foo being returned. Without establishing a clear type relationship + between Foo and A, an attempt to call zzz(yyy(1)) + will result in an error.

      +

      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, intead of generating a distinct CLOS class definition, we + generate a form that expands to:

      +
      (setf (find-class <synonym>) <primary>) +
      +

      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.

      +

      Given the above header file, synonym.h, a Lisp session would appear + as follows:

      +
      +
      +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> 
+
      +
      +

      17.3.8.1 Choosing a primary type

      +

      The choice of a primary type is selected by the following criteria + from a set of synonym types.

      +
        +
      • If a synonym type has a class definition, it is the primary type.
        • +
      • If a synonym type is a class template and has been explicitly + instantiated via %template, it is the primary type.
        • +
      • For all other sets of synonymous types, the synonym which is parsed + first becomes the primary type.
        • +
      +

      17.3.9 Function overloading/Parameter + defaulting

      +

      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.

      +

      Example:

      +
      overload.h: +
      +
+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 */
+
      +
      +

      Creates the following three wrappers, for each of the possible + argument combinations

      +
      overload_wrap.cxx +
      +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;
+    }
+}
+
      +
      +

      And the following foreign-function-call and method definitions on + the lisp side:

      +
      overload.cl +
      +(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)))
+
      +
      +

      And their usage in a sample lisp session:

      +
      +
      +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> 
+
      +
      +

      17.3.10 Operator wrapping and Operator + overloading

      +

      Wrappers to defined C++ Operators are automatically renamed, using +%rename, to the following defaults:

      +
      +
      +/* 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[];
+
      +
      +

      Name mangling occurs on all such renamed identifiers, so that + wrapper name generated by B::operator= will be B___eq__ +, i.e. <class-or-namespace>_ has been added. Users may modify + these default names by adding %rename directives in their own + .i files.

      +

      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 %extend + directive is used to add an overload method on Operator==.

      +
      opoverload.h +
      +class B {
+ public:
+  int x;
+  int y;
+  bool operator==(B const& other) const;
+};
+
      +
      +

      and

      +
      opoverload.i +
      +%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;
+};
+
      +
      +

      Either operator can be called via a single call to the dispatch + function:

      +
      +
      +opoverload> (B___eq__ x1 x2)
+nil
+opoverload> (B___eq__ x1 3)
+nil
+opoverload> 
+
      +
      +

      17.3.11 Varargs

      +

      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 %vararg 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 printf(). It's + declaration would appear as follows:

      +

      See the following section on Variable Length + arguments provides examples on how %vararg can be used, + along with other ways such functions can be wrapped.

      +

      17.3.12 C++ Exceptions

      +

      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.

      +

      17.3.13 Pass by value, pass by + reference

      +

      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 typemaps, and should + not require any fine tuning by the user, even for newly defined types.

      +

      17.4 Typemaps

      +

      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 +Typemaps for more information.

      +

      17.4.1 Code Generation in the C++ + Wrapper

      +

      Every C++ wrapper generated by SWIG takes the following form:

      +
      +
      +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;
+   }
+
      +
      +

      17.4.1.1 IN Typemap

      +

      the in 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 +<binding locals to parameters> 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.

      +

      These are the default specifications for the IN typemap. Here, +$input refers to the parameter code is being generated for, and +$1 is the local variable to which it is being assigned. The default + settings of this typemap are as follows:

      +
      +
      +%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;";
+
      +
      +

      17.4.1.2 OUT Typemap

      +

      The out 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. It's default mapping is as follows:

      +
      +
      +%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);";
+
      +
      +

      17.4.1.3 CTYPE Typemap

      +

      This typemap is not used for code generation, but purely for the + transformation of types in the parameter list of the wrapper function. + It's primary use is to handle by-value to by-reference conversion in + the wrappers parameter list. Its default settings are:

      +
      +
      +%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";
+
      +
      +

      These three typemaps are specifically employed by the 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 common typemaps here.

      +

      17.4.2 Code generation in Lisp wrappers

      +

      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.

      +

      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 16.3.1 + Namespaces for details.

      +

      17.4.2.1 LIN Typemap

      +

      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.

      +

      The LIN typemap accepts the following $variable references.

      +
        +
      • $in - expands to the name of the parameter being applied to + this typemap
        • +
      • $out - expands to the name of the local variable assigned + to this typemap
        • +
      • $in_fftype - the foreign function type of the C type.
        • +
      • $*in_fftype - 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.
        • +
      • $body - very important. Instructs SWIG where subsequent + code generation steps should be inserted into the current typemap. + Leaving out a $body reference will result in lisp wrappers + that do very little by way of calling into foreign code. Not + recommended.
        • +
      +
      +
      +%typemap(lin)	SWIGTYPE 	"(cl:let (($out $in))\n  $body)";
+
      +
      +

      17.4.2.2 LOUT Typemap

      +

      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.

      +

      The LOUT typemap uses the following $variable

      +
        +
      • $lclass - Expands to the CLOS class that represents + foreign-objects of the return type matching this typemap.
        • +
      • $body - Same as for the LIN map. Place this variable where + you want the foreign-function call to occur.
        • +
      • $ldestructor - 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).
        • +
      +
      +
      +%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)";
+
      +
      +

      17.4.2.3 FFITYPE Typemap

      +

      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:

      +
      +
      +%typemap(ffitype) bool ":unsigned-char";
+
      +
      +

      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:

      +
      +
      +%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)";
+
      +
      +

      17.4.2.4 LISPTYPE Typemap

      +

      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:

      +
      +
      +%typemap(lisptype) bool "cl:boolean";
+%typemap(lisptype) char "cl:character";
+%typemap(lisptype) unsigned char "cl:integer";
+%typemap(lisptype) signed char "cl:integer";
+
      +
      +

      17.4.2.5 LISPCLASS Typemap

      +

      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:

      +
      +
      +%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";
+
      +
      +

      17.4.3 Modifying SWIG behavior using + typemaps

      +

      The following example shows how we made use of the above typemaps to + add support for the wchar_t type.

      +
      +
      +%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";
+
      +
      +

      17.5 Identifier Converter functions

      +

      17.5.1 Creating symbols in the lisp + environment

      +

      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.

      +

      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.

      +

      17.5.2 Existing identifier-converter + functions

      +

      Two basic identifier routines have been defined.

      +

      17.5.2.1 identifier-convert-null

      +

      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.

      +

      17.5.2.2 identifier-convert-lispify

      +

      All underscores in the identifier string are converted to hyphens. + Otherwise, identifier-convert-lispify performs the same symbol + transformations.

      +

      17.5.2.3 Default identifier to symbol + conversions

      +

      Check the definitions of the above two default identifier-converters + in Lib/allegrocl/allegrocl.swg for default naming conventions.

      +

      17.5.3 Defining your own + identifier-converter

      +

      A user-defined identifier-converter function should conform to the + following specification:

      +
      +
      +(defun identifier-convert-fn (id &key type class arity) ...body...)
+result ==> symbol or (setf symbol)
+
      +
      +

      The ID argument is a string representing an identifier in + the foreign environment.

      +

      The :type keyword argument provides more information on the type of + identifier. It's 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.

      +
        +
      • :class - names a CLOS class.
        • +
      • :constant - names a defconstant
        • +
      • :constructor - names a function for creating a foreign object
        • +
      • :destructor - names a function for freeing a foreign object
        • +
      • :function - names a CLOS wrapping defmethod or defun.
        • +
      • :ff-operator - names a foreign call defined via ff:def-foreign-call
        • +
      • :getter - getter function
        • +
      • :namespace - names a C++ namespace
        • +
      • :setter - names a setter function. May return a (setf symbol) + reference
        • +
      • :operator - names a C++ operator, such as Operator=, Operator*.
        • +
      • :slot - names a slot in a struct/class/union declaration.
        • +
      • :type - names a foreign-type defined via ff:def-foreign-type.
        • +
      • :variable - names a variable defined via ff:def-foreign-variable.
        • +
      +

      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.

      +

      The :arity keyword argument only appears in swig:swig-defmethod + forms generated for overloaded functions. It's value is an integer + indicating the number of arguments passed to the routine indicated by + this identifier.

      +

      17.5.4 Instructing SWIG to use a + particular identifier-converter

      +

      By default, SWIG will use identifier-converter-null. To specify + another convert function, use the -identifier-converter + command-line argument. The value should be a string naming the function + you wish the interface to use instead, when generating symbols. ex:

      +
      +
      +% swig -allegrocl -c++ -module mymodule -identifier-converter my-identifier-converter
+
      +
      +

      18 SWIG and C#

      + + +
      + +
      + +

      18.1 Introduction

      +

      The purpose of the C# module is to offer an automated way of + accessing existing C/C++ code from .NET languages. The wrapper code + implementation uses C# and the Platform Invoke (PInvoke) interface to + access natively compiled C/C++ code. The PInvoke interface has been + chosen over Microsoft's Managed C++ interface as it is portable to both + Microsoft Windows and non-Microsoft platforms. PInvoke is part of the + ECMA/ISO C# specification. It is also better suited for robust + production environments due to the Managed C++ flaw called the +Mixed DLL Loading Problem. Swig C# works equally well on + non-Microsoft operating systems such as Linux, Solaris and Apple Mac + using Mono and +Portable.NET.

      +

      To get the most out of this chapter an understanding of interop is + required. The Microsoft Developer + Network (MSDN) has a good reference guide in a section titled + "Interop Marshaling". Monodoc, available from the Mono project, has a + very useful section titled +Interop with native libraries.

      +

      18.2 Differences to the Java + module

      +

      The C# module is very similar to the Java module, so until some more + complete documentation has been written, please use the +Java documentation as a guide to using SWIG with C#. The C# module + has the same major SWIG features as the Java module. The rest of this + section should be read in conjunction with the Java documentation as it + lists the main differences. The most notable differences to Java are + the following:

      +
        +
      • When invoking SWIG use the -csharp command line option + instead of -java.
        • +
      • The -nopgcpp command line option does not exist.
        • +
      • The -package command line option does not exist.
        • +
      • The -namespace <name> commandline option will generate all + code into the namespace specified by <name>. C# supports + nested namespaces that are not lexically nested, so nested namespaces + will of course also work. For example: -namespace com.bloggs.widget +, will generate code into C# namespaces:
        +
        +namespace com.bloggs.widget {
+  ...
+}
+
        +
        Note that by default, the generated C# classes have no namespace + and the module name is unrelated to namespaces. The module name is just + like in Java and is merely used to name some of the generated classes.
        • +
      • The -dllimport <name> commandline option specifies the + name of the DLL for the DllImport attribute for every PInvoke + method. If this commandline option is not given, the DllImport + DLL name is the same as the module name. This option is useful for when + one wants to invoke SWIG multiple times on different modules, yet + compile all the resulting code into a single DLL.
        • +
      • C/C++ variables are wrapped with C# properties and not JavaBean + style getters and setters.
        • +
      • Global constants are generated into the module class. There is no + constants interface.
        • +
      • There is no implementation for type unsafe enums - not deemed + necessary.
        • +
      • The default enum wrapping approach is proper C# enums, not typesafe + enums. +
        Note that %csconst(0) will be ignored when wrapping C/C++ enums + with proper C# enums. This is because C# enum items must be initialised + from a compile time constant. If an enum item has an initialiser and + the initialiser doesn't compile as C# code, then the %csconstvalue + directive must be used as %csconst(0) will have no effect. If it was + used, it would generate an illegal runtime initialisation via a PInvoke + call.
        • +
      • C# doesn't support the notion of throws clauses. Therefore there is + no 'throws' typemap attribute support for adding exception classes to a + throws clause. Likewise there is no need for an equivalent to +%javaexception. In fact, throwing C# exceptions works quite + differently, see C# Exceptions below.
        • +
      • The majority of the typemaps are in csharp.swg, not java.swg.
        • +
      • +

        Typemap equivalent names:

        +
        +
        +jni                         -> ctype
+jtype                       -> imtype
+jstype                      -> cstype
+javain                      -> csin
+javaout                     -> csout
+javadirectorin              -> csdirectorin
+javadirectorout             -> csdirectorout
+javainterfaces              -> csinterfaces and csinterfaces_derived
+javabase                    -> csbase
+javaclassmodifiers          -> csclassmodifiers
+javacode                    -> cscode
+javaimports                 -> csimports
+javabody                    -> csbody
+javafinalize                -> csfinalize
+javadestruct                -> csdestruct
+javadestruct_derived        -> csdestruct_derived
+
        +
        • +
      • +

        Additional typemaps:

        +
        +
        +csvarin                     C# code property set typemap
+csvarout                    C# code property get typemap
+csattributes                C# attributes for attaching to proxy classes/enums
+
        +
        • +
      • +

        Feature equivalent names:

        +
        +
        +%javaconst                  -> %csconst
+%javaconstvalue             -> %csconstvalue
+%javamethodmodifiers        -> %csmethodmodifiers
+
        +
        • +
      • +

        Pragma equivalent names:

        +
        +
        +%pragma(java)               -> %pragma(csharp)
+jniclassbase                -> imclassbase
+jniclassclassmodifiers      -> imclassclassmodifiers
+jniclasscode                -> imclasscode
+jniclassimports             -> imclassimports
+jniclassinterfaces          -> imclassinterfaces
+
        +
        • +
      • +

        Special variable equivalent names:

        +
        +
        +$javaclassname              -> $csclassname
+$&javaclassname             -> $&csclassname
+$*javaclassname             -> $*csclassname
+$javainput                  -> $csinput
+$jnicall                    -> $imcall
+
        +
        • +
      • +

        Unlike the "javain" typemap, the "csin" typemap does not support the + 'pgcpp' attribute as the C# module does not have a premature garbage + collection prevention parameter. The "csin" typemap supports additional + optional attributes called 'cshin' and 'terminator'. The 'cshin' + attribute should contain the parameter type and name whenever a +constructor helper function is generated due to the 'pre' or 'post' + attributes. The 'terminator' attribute normally just contains a closing + brace for when the 'pre' attribute contains an opening brace, such as + when a C# using or fixed block is started. Note that + 'pre', 'post', 'terminator' and 'cshin' attributes are not used for + marshalling the property set. Please see the +Date marshalling example and Date + marshalling of properties example for further understanding of + these "csin" applicable attributes.

        +
        • +
      • +

        Support for asymmetric type marshalling. The 'ctype', 'imtype' and + 'cstype' typemaps support an optional out attribute which is + used for output types. If this typemap attribute is specified, then the + type specified in the attribute is used for output types and the type + specified in the typemap itself is used for the input type. If this + typemap attribute is not specified, then the type used for both input + and output is the type specified in the typemap. An example shows that +char * could be marshalled in different ways,

        +
        +
        +%typemap(imtype, out="IntPtr") char * "string"
+char * function(char *);
+
        +
        +

        The output type is thus IntPtr and the input type is string. The + resulting intermediary C# code is:

        +
        +
        +public static extern IntPtr function(string jarg1);
+
        +
        • +
      • +

        Support for type attributes. The 'imtype' and 'cstype' typemaps can + have an optional inattributes and outattributes + typemap attribute. There are C# attributes and typemap attributes, + don't get confused!! The C# attributes specified in these typemap + attributes are generated wherever the type is used in the C# wrappers. + These can be used to specify any C# attribute associated with a C/C++ + type, but are more typically used for the C# MarshalAs + attribute. For example:

        +
        +
        +%typemap(imtype,
+         inattributes="[MarshalAs(UnmanagedType.LPStr)]",
+         outattributes="[return: MarshalAs(UnmanagedType.LPStr)]") const char * "String"
+
+const char * GetMsg() {}
+void SetMsg(const char *msg) {}
+
        +
        +

        The intermediary class will then have the marshalling as specified + by everything in the 'imtype' typemap:

        +
        +
        +class examplePINVOKE {
+  ...
+  [DllImport("example", EntryPoint="CSharp_GetMsg")]
+  [return: MarshalAs(UnmanagedType.LPStr)]
+  public static extern String GetMsg();
+
+  [DllImport("example", EntryPoint="CSharp_SetMsg")]
+  public static extern void SetMsg([MarshalAs(UnmanagedType.LPStr)]String jarg1);
+}
+
        +
        +

        Note that the DllImport attribute is always generated, + irrespective of any additional attributes specified.

        +

        These attributes are associated with the C/C++ parameter type or + return type, which is subtly different to the attribute features and + typemaps covered next. Note that all these different C# attributes can + be combined so that a method has more than one attribute.

        +
        • +
      • +

        Support for attaching C# attributes to wrapped methods and + variables. This is done using the %csattributes feature, see %feature directives. Note that C# attributes are + attached to proxy classes and enums using the csattributes + typemap. For example, imagine we have a custom attribute class, +ThreadSafeAttribute, for labelling thread safety. The following + SWIG code shows how to attach this C# attribute to some methods and the + class declaration itself:

        +
        +
        +%typemap(csattributes) AClass          "[ThreadSafe]"
+%csattributes AClass::AClass(double d) "[ThreadSafe(false)]"
+%csattributes AClass::AMethod()        "[ThreadSafe(true)]"
+
+%inline %{
+class AClass {
+public:
+  AClass(double a) {}
+  void AMethod() {}
+};
+%}
+
        +
        +

        will generate a C# proxy class:

        +
        +
        +[ThreadSafe]
+public class AClass : IDisposable {
+  ...
+  [ThreadSafe(false)]
+  public AClass(double a) ...
+
+  [ThreadSafe(true)]
+  public void AMethod() ...
+}
+
        +
        +

        If C# attributes need adding to the set or get + part of C# properties, when wrapping C/C++ variables, they can be added + using the 'csvarin' and 'csvarout' typemaps respectively. Note that the + type used for the property is specified in the 'cstype' typemap. If the + 'out' attribute exists in this typemap, then the type used is from the + 'out' attribute.

        +
        • +
      • +

        The intermediary classname has PINVOKE appended after the + module name instead of JNI, for example modulenamePINVOKE +.

        +
        • +
      • +

        The %csmethodmodifiers feature can also be applied to + variables as well as methods. In addition to the default public + modifier that SWIG generates when %csmethodmodifiers is not + specified, the feature will also replace the virtual/new +/override modifiers that SWIG thinks is appropriate. This + feature is useful for some obscure cases where SWIG might get the +virtual/new/override modifiers incorrect, for + example with multiple inheritance.

        +
        • +
      • +

        The name of the intermediary class can be changed from its default, + that is, the module name with PINVOKE appended after it. The module + directive attribute imclassname is used to achieve this:

        +
        +
        +%module (imclassname="name") modulename
+
        +
        +

        If name is the same as modulename then the module + class name gets changed from modulename to +modulenameModule.

        +
        • +
      • There is no additional 'premature garbage collection prevention + parameter' as the marshalling of the HandleRef object takes + care of ensuring a reference to the proxy class is held until the + unmanaged call completed.
        • +
      +

      $dllimport +
      This is a C# only special variable that can be used in typemaps, + pragmas, features etc. The special variable will get translated into + the value specified by the -dllimport commandline option if + specified, otherwise it is equivalent to the $module special + variable.

      +

      $imclassname +
      This special variable expands to the intermediary class name. For + C# this is usually the same as '$modulePINVOKE' ('$moduleJNI' for + Java), unless the imclassname attribute is specified in the +%module directive.

      +

      The directory Examples/csharp has a number of simple + examples. Visual Studio .NET 2003 solution and project files are + available for compiling with the Microsoft .NET C# compiler on Windows. + If your SWIG installation went well on a Unix environment and your C# + compiler was detected, you should be able to type make in each + example directory, then ilrun runme.exe (Portable.NET C# + compiler) or mono runme.exe (Mono C# compiler) to run the + examples. Windows users can also get the examples working using a +Cygwin or MinGW environment for + automatic configuration of the example makefiles. Any one of the three + C# compilers (Portable.NET, Mono or Microsoft) can be detected from + within a Cygwin or Mingw environment if installed in your path.

      +

      18.3 C# Arrays

      +

      There are various ways to pass arrays from C# to C/C++. The default + wrapping treats arrays as pointers and as such simple type wrapper + classes are generated, eg SWIGTYPE_p_int when wrapping the C + type int [] or int *. This gives a rather restricted + use of the underlying unmanaged code and the most practical way to use + arrays is to enhance or customise with one of the following three + approaches; namely the SWIG C arrays library, P/Invoke default array + marshalling or pinned arrays.

      +

      18.3.1 The SWIG C arrays + library

      +

      The C arrays library keeps all the array memory in the unmanaged + layer. The library is available to all language modules and is + documented in the carrays.i library + section. Please refer to this section for details, but for convenience, + the C# usage for the two examples outlined there is shown below.

      +

      For the %array_functions example, the equivalent usage + would be:

      +
      +
      +SWIGTYPE_p_double a = example.new_doubleArray(10);  // Create an array
+for (int i=0; i<10; i++)
+  example.doubleArray_setitem(a,i,2*i);             // Set a value
+example.print_array(a);                             // Pass to C
+example.delete_doubleArray(a);                      // Destroy array
+
      +
      +

      and for the %array_class example, the equivalent usage + would be:

      +
      +
      +doubleArray c = new doubleArray(10);    // Create double[10]
+for (int i=0; i<10; i++)
+  c.setitem(i, 2*i);                    // Assign values
+example.print_array(c.cast());          // Pass to C
+
      +
      +

      18.3.2 + Managed arrays using P/Invoke default array marshalling

      +

      In the P/Invoke default marshalling scheme, one needs to designate + whether the invoked function will treat a managed array parameter as + input, output, or both. When the function is invoked, the CLR allocates + a separate chunk of memory as big as the given managed array, which is + automatically released at the end of the function call. If the array + parameter is marked as being input, the content of the managed array is + copied into this buffer when the call is made. Correspondingly, if the + array parameter is marked as being output, the contents of the reserved + buffer are copied back into the managed array after the call returns. A + pointer to to this buffer is passed to the native function.

      +

      The reason for allocating a separate buffer is to leave the CLR free + to relocate the managed array object during garbage collection. If the + overhead caused by the copying is causing a significant performance + penalty, consider pinning the managed array and passing a direct + reference as described in the next section.

      +

      For more information on the subject, see the +Default Marshaling for Arrays article on MSDN.

      +

      The P/Invoke default marshalling is supported by the +arrays_csharp.i library via the INPUT, OUTPUT and INOUT typemaps. + Let's look at some example usage. Consider the following C function:

      +
      +
      +void myArrayCopy(int *sourceArray, int *targetArray, int nitems);
+
      +
      +

      We can now instruct SWIG to use the default marshalling typemaps by

      +
      +
      +%include "arrays_csharp.i"
+
+%apply int INPUT[]  {int *sourceArray}
+%apply int OUTPUT[] {int *targetArray}
+
      +
      +

      As a result, we get the following method in the module class:

      +
      +
      +public static void myArrayCopy(int[] sourceArray, int[] targetArray, int nitems) {
+    examplePINVOKE.myArrayCopy(sourceArray, targetArray, nitems);
+}
+
      +
      +

      If we look beneath the surface at the corresponding intermediary + class code, we see that SWIG has generated code that uses attributes + (from the System.Runtime.InteropServices namespace) to tell the CLR to + use default marshalling for the arrays:

      +
      +
      +[DllImport("example", EntryPoint="CSharp_myArrayCopy")]
+public static extern void myArrayCopy([In, MarshalAs(UnmanagedType.LPArray)]int[] jarg1, 
+                                      [Out, MarshalAs(UnmanagedType.LPArray)]int[] jarg2, int jarg3);
+
      +
      +

      As an example of passing an inout array (i.e. the target function + will both read from and write to the array), consider this C function + that swaps a given number of elements in the given arrays:

      +
      +
      +void myArraySwap(int *array1, int *array2, int nitems);
+
      +
      +

      Now, we can instruct SWIG to wrap this by

      +
      +
      +%include "arrays_csharp.i"
+
+%apply int INOUT[] {int *array1}
+%apply int INOUT[] {int *array2}
+
      +
      +

      This results in the module class method

      +
      +
      +  public static void myArraySwap(int[] array1, int[] array2, int nitems) {
+    examplePINVOKE.myArraySwap(array1, array2, nitems);
+  }
+
      +
      +

      and intermediate class method

      +
      +
      +  [DllImport("example", EntryPoint="CSharp_myArraySwap")]
+  public static extern void myArraySwap([In, Out, MarshalAs(UnmanagedType.LPArray)]int[] jarg1, 
+                                        [In, Out, MarshalAs(UnmanagedType.LPArray)]int[] jarg2, int jarg3);
+
      +
      +

      18.3.3 Managed arrays using + pinning

      +

      It is also possible to pin a given array in memory (i.e. fix its + location in memory), obtain a direct pointer to it, and then pass this + pointer to the wrapped C/C++ function. This approach involves no + copying, but it makes the work of the garbage collector harder as the + managed array object can not be relocated before the fix on the array + is released. You should avoid fixing arrays in memory in cases where + the control may re-enter the managed side via a callback and/or another + thread may produce enough garbage to trigger garbage collection.

      +

      For more information, see the +fixed statement in the C# language reference.

      +

      Now let's look at an example using pinning, thus avoiding the CLR + making copies of the arrays passed as parameters. The +arrays_csharp.i library file again provides the required support + via the FIXED typemaps. Let's use the same function from the + previous section:

      +
      +
      +void myArrayCopy(int *sourceArray, int *targetArray, int nitems);
+
      +
      +

      We now need to declare the module class method unsafe, as we are + using pointers:

      +
      +
      +%csmethodmodifiers myArrayCopy "public unsafe";
+
      +
      +

      Apply the appropriate typemaps to the array parameters:

      +
      +
      +%include "arrays_csharp.i"
+
+%apply int FIXED[] {int *sourceArray}
+%apply int FIXED[] {int *targetArray}
+
      +
      +

      Notice that there is no need for separate in, out or inout typemaps + as is the case when using P/Invoke default marshalling.

      +

      As a result, we get the following method in the module class:

      +
      +
      +  public unsafe static void myArrayCopy(int[] sourceArray, int[] targetArray, int nitems) {
+    fixed ( int *swig_ptrTo_sourceArray = sourceArray ) {
+    fixed ( int *swig_ptrTo_targetArray = targetArray ) {
+    {
+      examplePINVOKE.myArrayCopy((IntPtr)swig_ptrTo_sourceArray, (IntPtr)swig_ptrTo_targetArray, nitems);
+    }
+    }
+    }
+  }
+
      +
      +

      On the method signature level the only difference to the version + using P/Invoke default marshalling is the "unsafe" quantifier, which is + required because we are handling pointers.

      +

      Also the intermediate class method looks a little different from the + default marshalling example - the method is expecting an IntPtr as the + parameter type.

      +
      +
      +[DllImport("example", EntryPoint="CSharp_myArrayCopy")]
+public static extern void myArrayCopy(IntPtr jarg1, IntPtr jarg2, int jarg3);
+
      +
      +

      18.4 C# Exceptions

      +

      It is possible to throw a C# Exception from C/C++ code. SWIG already + provides the framework for throwing C# exceptions if it is able to + detect that a C++ exception could be thrown. Automatically detecting + that a C++ exception could be thrown is only possible when a C++ + exception specification is used, see +Exception specifications. The Exception + handling with %exception section details the %exception + feature. Customised code for handling exceptions with or without a C++ + exception specification is possible and the details follow. However + anyone wishing to do this should be familiar with the contents of the + sections referred to above.

      +

      Unfortunately a C# exception cannot simply be thrown from unmanaged + code for a variety of reasons. Most notably being that throwing a C# + exception results in exceptions being thrown across the C PInvoke + interface and C does not understand exceptions. The design revolves + around a C# exception being constructed and stored as a pending + exception, to be thrown only when the unmanaged code has completed. + Implementing this is a tad involved and there are thus some unusual + typemap constructs. Some practical examples follow and they should be + read in conjunction with the rest of this section.

      +

      First some details about the design that must be followed. Each + typemap or feature that generates unmanaged code supports an + attribute called canthrow. This is simply a flag which when + set indicates that the code in the typemap/feature has code which might + want to throw a C# exception. The code in the typemap/feature can then + raise a C# exception by calling one of the C functions, +SWIG_CSharpSetPendingException() or +SWIG_CSharpSetPendingExceptionArgument(). When called, the function + makes a callback into the managed world via a delegate. The callback + creates and stores an exception ready for throwing when the unmanaged + code has finished. The typemap/feature unmanaged code is then expected + to force an immediate return from the unmanaged wrapper function, so + that the pending managed exception can then be thrown. The support code + has been carefully designed to be efficient as well as thread-safe. + However to achieve the goal of efficiency requires some optional code + generation in the managed code typemaps. Code to check for + pending exceptions is generated if and only if the unmanaged code has + code to set a pending exception, that is if the canthrow + attribute is set. The optional managed code is generated using the +excode typemap attribute and $excode special variable in + the relevant managed code typemaps. Simply, if any relevant unmanaged + code has the canthrow attribute set, then any occurrences of +$excode is replaced with the code in the excode attribute. + If the canthrow attribute is not set, then any occurrences of +$excode are replaced with nothing.

      +

      The prototypes for the SWIG_CSharpSetPendingException() and + SWIG_CSharpSetPendingExceptionArgument() functions are

      +
      +
      +static void SWIG_CSharpSetPendingException(SWIG_CSharpExceptionCodes code,
+                                           const char *msg);
+
+static void SWIG_CSharpSetPendingExceptionArgument(SWIG_CSharpExceptionArgumentCodes code,
+                                                   const char *msg,
+                                                   const char *param_name);
+
      +
      +

      The first parameter defines which .NET exceptions can be thrown:

      +
      +
      +typedef enum {
+  SWIG_CSharpApplicationException,
+  SWIG_CSharpArithmeticException,
+  SWIG_CSharpDivideByZeroException,
+  SWIG_CSharpIndexOutOfRangeException,
+  SWIG_CSharpInvalidCastException,
+  SWIG_CSharpInvalidOperationException,
+  SWIG_CSharpIOException,
+  SWIG_CSharpNullReferenceException,
+  SWIG_CSharpOutOfMemoryException,
+  SWIG_CSharpOverflowException,
+  SWIG_CSharpSystemException
+} SWIG_CSharpExceptionCodes;
+
+typedef enum {
+  SWIG_CSharpArgumentException,
+  SWIG_CSharpArgumentNullException,
+  SWIG_CSharpArgumentOutOfRangeException,
+} SWIG_CSharpExceptionArgumentCodes;
+
      +
      +

      where, for example, SWIG_CSharpApplicationException + corresponds to the .NET exception, ApplicationException. The +msg and param_name parameters contain the C# exception + message and parameter name associated with the exception.

      +

      The %exception feature in C# has the canthrow + attribute set. The %csnothrowexception feature is like +%exception, but it does not have the canthrow attribute + set so should only be used when a C# exception is not created.

      +

      18.4.1 C# + exception example using "check" typemap

      +

      Lets say we have the following simple C++ method:

      +
      +
      +void positivesonly(int number);
+
      +
      +

      and we want to check that the input number is always + positive and if not throw a C# ArgumentOutOfRangeException. + The "check" typemap is designed for checking input parameters. Below + you will see the canthrow attribute is set because the code + contains a call to SWIG_CSharpSetPendingExceptionArgument(). + The full example follows:

      +
      +
      +%module example
+
+%typemap(check, canthrow=1) int number %{
+if ($1 < 0) {
+  SWIG_CSharpSetPendingExceptionArgument(SWIG_CSharpArgumentOutOfRangeException,
+                                         "only positive numbers accepted", "number");
+  return $null;
+}
+// SWIGEXCODE is a macro used by many other csout typemaps
+%define SWIGEXCODE
+ "\n    if ($modulePINVOKE.SWIGPendingException.Pending)"
+ "\n      throw $modulePINVOKE.SWIGPendingException.Retrieve();"
+%enddef
+%typemap(csout, excode=SWIGEXCODE) void {
+    $imcall;$excode
+  }
+%}
+
+%inline %{
+
+void positivesonly(int number) {
+}
+
+%}
+
      +
      +

      When the following C# code is executed:

      +
      +
      +public class runme {
+    static void Main() {
+      example.positivesonly(-1);
+    }
+}
+
      +
      +

      The exception is thrown:

      +
      +
      +Unhandled Exception: System.ArgumentOutOfRangeException: only positive numbers accepted
+Parameter name: number
+in <0x00034> example:positivesonly (int)
+in <0x0000c> runme:Main ()
+
      +
      +

      Now let's analyse the generated code to gain a fuller understanding + of the typemaps. The generated unmanaged C++ code is:

      +
      +
      +SWIGEXPORT void SWIGSTDCALL CSharp_positivesonly(int jarg1) {
+    int arg1 ;
+    
+    arg1 = (int)jarg1; 
+    
+    if (arg1 < 0) {
+        SWIG_CSharpSetPendingExceptionArgument(SWIG_CSharpArgumentOutOfRangeException,
+                                               "only positive numbers accepted", "number");
+        return ;
+    }
+    
+    positivesonly(arg1);
+    
+}
+
      +
      +

      This largely comes from the "check" typemap. The managed code in the + module class is:

      +
      +
      +public class example {
+  public static void positivesonly(int number) {
+    examplePINVOKE.positivesonly(number);
+    if (examplePINVOKE.SWIGPendingException.Pending)
+      throw examplePINVOKE.SWIGPendingException.Retrieve();
+  }
+
+}
+
      +
      +

      This comes largely from the "csout" typemap.

      +

      The "csout" typemap is the same as the default void "csout" typemap + so is not strictly necessary for the example. However, it is shown to + demonstrate what managed output code typemaps should contain, that is, + a $excode special variable and an excode attribute. + Also note that $excode is expanded into the code held in the +excode attribute. The $imcall as always expands into +examplePINVOKE.positivesonly(number). The exception support code in + the intermediary class, examplePINVOKE, is not shown, but is + contained within the inner classes, SWIGPendingException and +SWIGExceptionHelper and is always generated. These classes can be + seen in any of the generated wrappers. However, all that is required of + a user is as demonstrated in the "csin" typemap above. That is, is to + check SWIGPendingException.Pending and to throw the exception + returned by SWIGPendingException.Retrieve().

      +

      If the "check" typemap did not exist, then the following module + class would instead be generated:

      +
      +
      +public class example {
+  public static void positivesonly(int number) {
+    examplePINVOKE.positivesonly(number);
+  }
+
+}
+
      +
      +

      Here we see the pending exception checking code is omitted. In fact, + the code above would be generated if the canthrow attribute + was not in the "check" typemap, such as:

      +
      +
      +%typemap(check) int number %{
+if ($1 < 0) {
+  SWIG_CSharpSetPendingExceptionArgument(SWIG_CSharpArgumentOutOfRangeException,
+                                         "only positive numbers accepted", "number");
+  return $null;
+}
+%}
+
      +
      +

      Note that if SWIG detects you have used +SWIG_CSharpSetPendingException() or +SWIG_CSharpSetPendingExceptionArgument() without setting the +canthrow attribute you will get a warning message similar to

      +
      +
      +example.i:21: Warning(845): Unmanaged code contains a call to a SWIG_CSharpSetPendingException
+method and C# code does not handle pending exceptions via the canthrow attribute.
+
      +
      +

      Actually it will issue this warning for any function beginning with +SWIG_CSharpSetPendingException.

      +

      18.4.2 C# + exception example using %exception

      +

      Let's consider a similar, but more common example that throws a C++ + exception from within a wrapped function. We can use %exception + as mentioned in Exception handling with %exception +.

      +
      +
      +%exception negativesonly(int value) %{
+try {
+  $action
+} catch (std::out_of_range e) {
+  SWIG_CSharpSetPendingException(SWIG_CSharpApplicationException, e.what());
+}
+%}
+
+%inline %{
+#include <stdexcept>
+void negativesonly(int value) {
+  if (value >= 0)
+    throw std::out_of_range("number should be negative");
+}
+%}
+
      +
      +

      The generated unmanaged code this time catches the C++ exception and + converts it into a C# ApplicationException.

      +
      +
      +SWIGEXPORT void SWIGSTDCALL CSharp_negativesonly(int jarg1) {
+    int arg1 ;
+    
+    arg1 = (int)jarg1; 
+    
+    try {
+        negativesonly(arg1);
+        
+    } catch (std::out_of_range e) {
+        SWIG_CSharpSetPendingException(SWIG_CSharpApplicationException, e.what());
+        return ;
+    }
+    
+}
+
      +
      +

      The managed code generated does check for the pending exception as + mentioned earlier as the C# version of %exception has the +canthrow attribute set by default:

      +
      +
      +  public static void negativesonly(int value) {
+    examplePINVOKE.negativesonly(value);
+    if (examplePINVOKE.SWIGPendingException.Pending)
+      throw examplePINVOKE.SWIGPendingException.Retrieve();
+  }
+
      +
      +

      +18.4.3 C# exception example using exception specifications

      +

      When C++ exception specifications are used, SWIG is able to detect + that the method might throw an exception. By default SWIG will + automatically generate code to catch the exception and convert it into + a managed ApplicationException, as defined by the default + "throws" typemaps. The following example has a user supplied "throws" + typemap which is used whenever an exception specification contains a +std::out_of_range, such as the evensonly method below.

      +
      +
      +%typemap(throws, canthrow=1) std::out_of_range {
+  SWIG_CSharpSetPendingExceptionArgument(SWIG_CSharpArgumentException, $1.what(), NULL);
+  return $null;
+}
+
+%inline %{
+#include <stdexcept>
+void evensonly(int input) throw (std::out_of_range) {
+  if (input%2 != 0)
+    throw std::out_of_range("number is not even");
+}
+%}
+
      +
      +

      Note that the type for the throws typemap is the type in the + exception specification. SWIG generates a try catch block with the + throws typemap code in the catch handler.

      +
      +
      +SWIGEXPORT void SWIGSTDCALL CSharp_evensonly(int jarg1) {
+    int arg1 ;
+    
+    arg1 = (int)jarg1; 
+    try {
+        evensonly(arg1);
+    }
+    catch(std::out_of_range &_e) {
+      {
+          SWIG_CSharpSetPendingExceptionArgument(SWIG_CSharpArgumentException, (&_e)->what(), NULL);
+          return ;
+      }
+    }
+    
+}
+
      +
      +

      Multiple catch handlers are generated should there be more than one + exception specifications declared.

      +

      18.4.4 Custom C# + ApplicationException example

      +

      This example involves a user defined exception. The conventional + .NET exception handling approach is to create a custom +ApplicationException and throw it in your application. The goal in + this example is to convert the STL std::out_of_range exception + into one of these custom .NET exceptions.

      +

      The default exception handling is quite easy to use as the +SWIG_CSharpSetPendingException() and +SWIG_CSharpSetPendingExceptionArgument() methods are provided by + SWIG. However, for a custom C# exception, the boiler plate code that + supports these functions needs replicating. In essence this consists of + some C/C++ code and C# code. The C/C++ code can be generated into the + wrapper file using the %insert(runtime) directive and the C# + code can be generated into the intermediary class using the +imclasscode pragma as follows:

      +
      +
      +%insert(runtime) %{
+  // Code to handle throwing of C# CustomApplicationException from C/C++ code.
+  // The equivalent delegate to the callback, CSharpExceptionCallback_t, is CustomExceptionDelegate
+  // and the equivalent customExceptionCallback instance is customDelegate
+  typedef void (SWIGSTDCALL* CSharpExceptionCallback_t)(const char *);
+  CSharpExceptionCallback_t customExceptionCallback = NULL;
+
+  extern "C" SWIGEXPORT
+  void SWIGSTDCALL CustomExceptionRegisterCallback(CSharpExceptionCallback_t customCallback) {
+    customExceptionCallback = customCallback;
+  }
+
+  // Note that SWIG detects any method calls named starting with
+  // SWIG_CSharpSetPendingException for warning 845
+  static void SWIG_CSharpSetPendingExceptionCustom(const char *msg) {
+    customExceptionCallback(msg);
+  }
+%}
+
+%pragma(csharp) imclasscode=%{
+  class CustomExceptionHelper {
+    // C# delegate for the C/C++ customExceptionCallback
+    public delegate void CustomExceptionDelegate(string message);
+    static CustomExceptionDelegate customDelegate =
+                                   new CustomExceptionDelegate(SetPendingCustomException);
+
+    [DllImport("$dllimport", EntryPoint="CustomExceptionRegisterCallback")]
+    public static extern
+           void CustomExceptionRegisterCallback(CustomExceptionDelegate customCallback);
+
+    static void SetPendingCustomException(string message) {
+      SWIGPendingException.Set(new CustomApplicationException(message));
+    }
+
+    static CustomExceptionHelper() {
+      CustomExceptionRegisterCallback(customDelegate);
+    }
+  }
+  static CustomExceptionHelper exceptionHelper = new CustomExceptionHelper();
+%}
+
      +
      +

      The method stored in the C# delegate instance, customDelegate + is what gets called by the C/C++ callback. However, the equivalent to + the C# delegate, that is the C/C++ callback, needs to be assigned + before any unmanaged code is executed. This is achieved by putting the + initialisation code in the intermediary class. Recall that the + intermediary class contains all the PInvoke methods, so the static + variables in the intermediary class will be initialised before any of + the PInvoke methods in this class are called. The exceptionHelper + static variable ensures the C/C++ callback is initialised with the + value in customDelegate by calling the +CustomExceptionRegisterCallback method in the +CustomExceptionHelper static constructor. Once this has been done, + unmanaged code can make callbacks into the managed world as +customExceptionCallback will be initialised with a valid + callback/delegate. Any calls to +SWIG_CSharpSetPendingExceptionCustom() will make the callback to + create the pending exception in the same way that +SWIG_CSharpSetPendingException() and +SWIG_CSharpSetPendingExceptionArgument() does. In fact the method + has been similarly named so that SWIG can issue the warning about + missing canthrow attributes as discussed earlier. It is an + invaluable warning as it is easy to forget the canthrow + attribute when writing typemaps/features.

      +

      The SWIGPendingException helper class is not shown, but is + generated as an inner class into the intermediary class. It stores the + pending exception in Thread Local Storage so that the exception + handling mechanism is thread safe.

      +

      The boiler plate code above must be used in addition to a + handcrafted CustomApplicationException:

      +
      +
      +// Custom C# Exception
+class CustomApplicationException : System.ApplicationException {
+  public CustomApplicationException(string message) 
+    : base(message) {
+  }
+}
+
      +
      +

      and the SWIG interface code:

      +
      +
      +%typemap(throws, canthrow=1) std::out_of_range {
+  SWIG_CSharpSetPendingExceptionCustom($1.what());
+  return $null;
+}
+
+%inline %{
+void oddsonly(int input) throw (std::out_of_range) {
+  if (input%2 != 1)
+    throw std::out_of_range("number is not odd");
+}
+%}
+
      +
      +

      The "throws" typemap now simply calls our new +SWIG_CSharpSetPendingExceptionCustom() function so that the + exception can be caught, as such:

      +
      +
      +try {
+  example.oddsonly(2);
+} catch (CustomApplicationException e) {
+  ...
+}
+
      +
      +

      18.5 C# Directors

      +

      The SWIG directors feature adds extra code to the generated C# proxy + classes that enable these classes to be used in cross-language + polymorphism. Essentially, it enables unmanaged C++ code to call back + into managed code for virtual methods so that a C# class can derive + from a wrapped C++ class.

      +

      The following sections provide information on the C# director + implementation and contain most of the information required to use the + C# directors. However, the Java directors + section should also be read in order to gain more insight into + directors.

      +

      18.5.1 Directors example

      +

      Imagine we are wrapping a C++ base class, Base, from which + we would like to inherit in C#. Such a class is shown below as well as + another class, Caller, which calls the virtual method +UIntMethod from pure unmanaged C++ code.

      +
      +
      +// file: example.h
+class Base {
+public:
+  virtual ~Base() {}
+
+  virtual unsigned int UIntMethod(unsigned int x) {
+    std::cout << "Base - UIntMethod(" << x << ")" << std::endl;
+    return x;
+  }
+  virtual void BaseBoolMethod(const Base &b, bool flag) {}
+};
+
+class Caller {
+public:
+  Caller(): m_base(0) {}
+  ~Caller() { delBase(); }
+  void set(Base *b) { delBase(); m_base = b; }
+  void reset() { m_base = 0; }
+  unsigned int UIntMethodCall(unsigned int x) { return m_base->UIntMethod(x); }
+
+private:
+  Base *m_base;
+  void delBase() { delete m_base; m_base = 0; }
+};
+
      +
      +

      The director feature is turned off by default and the following + simple interface file shows how directors are enabled for the class +Base.

      +
      +
      +/* File : example.i */
+%module(directors="1") example
+%{
+#include "example.h"
+%}
+
+%feature("director") Base;
+
+%include "example.h"
+
      +
      +

      The following is a C# class inheriting from Base:

      +
      +
      +public class CSharpDerived : Base
+{
+  public override uint UIntMethod(uint x)
+  {
+    Console.WriteLine("CSharpDerived - UIntMethod({0})", x);
+    return x;
+  }
+}
+
      +
      +

      The Caller class can demonstrate the UIntMethod + method being called from unmanaged code using the following C# code:

      +
      +
      +public class runme
+{
+  static void Main() 
+  {
+    Caller myCaller = new Caller();
+
+    // Test pure C++ class
+    using (Base myBase = new Base())
+    {
+      makeCalls(myCaller, myBase);
+    }
+
+    // Test director / C# derived class
+    using (Base myBase = new CSharpDerived())
+    {
+      makeCalls(myCaller, myBase);
+    }
+  }
+
+  static void makeCalls(Caller myCaller, Base myBase)
+  {
+    myCaller.set(myBase);
+    myCaller.UIntMethodCall(123);
+    myCaller.reset();
+  }
+}
+
      +
      +

      If the above is run, the output is then:

      +
      +
      +Base - UIntMethod(123)
+CSharpDerived - UIntMethod(123)
+
      +
      +

      18.5.2 Directors + implementation

      +

      The previous section demonstrated a simple example where the virtual + UIntMethod method was called from C++ code, even when the + overridden method is implemented in C#. The intention of this section + is to gain an insight into how the director feature works. It shows the + generated code for the two virtual methods, UIntMethod and +BaseBoolMethod, when the director feature is enabled for the +Base class.

      +

      Below is the generated C# Base director class.

      +
      +
      +using System;
+using System.Runtime.InteropServices;
+
+public class Base : IDisposable {
+  private HandleRef swigCPtr;
+  protected bool swigCMemOwn;
+
+  internal Base(IntPtr cPtr, bool cMemoryOwn) {
+    swigCMemOwn = cMemoryOwn;
+    swigCPtr = new HandleRef(this, cPtr);
+  }
+
+  internal static HandleRef getCPtr(Base obj) {
+    return (obj == null) ? new HandleRef(null, IntPtr.Zero) : obj.swigCPtr;
+  }
+
+  ~Base() {
+    Dispose();
+  }
+
+  public virtual void Dispose() {
+    lock(this) {
+      if(swigCPtr.Handle != IntPtr.Zero && swigCMemOwn) {
+        swigCMemOwn = false;
+        examplePINVOKE.delete_Base(swigCPtr);
+      }
+      swigCPtr = new HandleRef(null, IntPtr.Zero);
+      GC.SuppressFinalize(this);
+    }
+  }
+
+  public virtual uint UIntMethod(uint x) {
+    uint ret = examplePINVOKE.Base_UIntMethod(swigCPtr, x);
+    return ret;
+  }
+
+  public virtual void BaseBoolMethod(Base b, bool flag) {
+    examplePINVOKE.Base_BaseBoolMethod(swigCPtr, Base.getCPtr(b), flag);
+    if (examplePINVOKE.SWIGPendingException.Pending)
+      throw examplePINVOKE.SWIGPendingException.Retrieve();
+  }
+
+  public Base() : this(examplePINVOKE.new_Base(), true) {
+    SwigDirectorConnect();
+  }
+
+  private void SwigDirectorConnect() {
+    if (SwigDerivedClassHasMethod("UIntMethod", swigMethodTypes0))
+      swigDelegate0 = new SwigDelegateBase_0(SwigDirectorUIntMethod);
+    if (SwigDerivedClassHasMethod("BaseBoolMethod", swigMethodTypes1))
+      swigDelegate1 = new SwigDelegateBase_1(SwigDirectorBaseBoolMethod);
+    examplePINVOKE.Base_director_connect(swigCPtr, swigDelegate0, swigDelegate1);
+  }
+
+  private bool SwigDerivedClassHasMethod(string methodName, Type[] methodTypes) {
+    System.Reflection.MethodInfo methodInfo = this.GetType().GetMethod(methodName, methodTypes);
+    bool hasDerivedMethod = methodInfo.DeclaringType.IsSubclassOf(typeof(Base));
+    return hasDerivedMethod;
+  }
+
+  private uint SwigDirectorUIntMethod(uint x) {
+    return UIntMethod(x);
+  }
+
+  private void SwigDirectorBaseBoolMethod(IntPtr b, bool flag) {
+    BaseBoolMethod(new Base(b, false), flag);
+  }
+
+  internal delegate uint SwigDelegateBase_0(uint x);
+  internal delegate void SwigDelegateBase_1(IntPtr b, bool flag);
+
+  private SwigDelegateBase_0 swigDelegate0;
+  private SwigDelegateBase_1 swigDelegate1;
+
+  private static Type[] swigMethodTypes0 = new Type[] { typeof(uint) };
+  private static Type[] swigMethodTypes1 = new Type[] { typeof(Base), typeof(bool) };
+}
+
      +
      +

      Everything from the SwigDirectorConnect() method and below + is code that is only generated when directors are enabled. The design + comprises a C# delegate being initialised for each virtual method on + construction of the class. Let's examine the BaseBoolMethod.

      +

      In the Base constructor a call is made to +SwigDirectorConnect() which contains the initialisation code for + all the virtual methods. It uses a support method, +SwigDerivedClassHasMethod(), which simply uses reflection to + determine if the named method, BaseBoolMethod, with the list of + required parameter types, exists in a subclass. If it does not exist, + the delegate is not initialised as there is no need for unmanaged code + to call back into managed C# code. However, if there is an overridden + method in any subclass, the delegate is required. It is then + initialised to the SwigDirectorBaseBoolMethod which in turn + will call BaseBoolMethod if invoked. The delegate is not + initialised to the BaseBoolMethod directly as quite often + types will need marshalling from the unmanaged type to the managed type + in which case an intermediary method (SwigDirectorBaseBoolMethod +) is required for the marshalling. In this case, the C# Base + class needs to be created from the unmanaged IntPtr type.

      +

      The last thing that SwigDirectorConnect() does is to pass + the delegates to the unmanaged code. It calls the intermediary method +Base_director_connect() which is really a call to the C function +CSharp_Base_director_connect(). This method simply maps each C# + delegate onto a C function pointer.

      +
      +
      +SWIGEXPORT void SWIGSTDCALL CSharp_Base_director_connect(void *objarg, 
+                                        SwigDirector_Base::SWIG_Callback0_t callback0,
+                                        SwigDirector_Base::SWIG_Callback1_t callback1) {
+  Base *obj = (Base *)objarg;
+  SwigDirector_Base *director = dynamic_cast<SwigDirector_Base *>(obj);
+  if (director) {
+    director->swig_connect_director(callback0, callback1);
+  }
+}
+
+class SwigDirector_Base : public Base, public Swig::Director {
+public:
+    SwigDirector_Base();
+    virtual unsigned int UIntMethod(unsigned int x);
+    virtual ~SwigDirector_Base();
+    virtual void BaseBoolMethod(Base const &b, bool flag);
+
+    typedef unsigned int (SWIGSTDCALL* SWIG_Callback0_t)(unsigned int);
+    typedef void (SWIGSTDCALL* SWIG_Callback1_t)(void *, unsigned int);
+    void swig_connect_director(SWIG_Callback0_t callbackUIntMethod, 
+                               SWIG_Callback1_t callbackBaseBoolMethod);
+
+private:
+    SWIG_Callback0_t swig_callbackUIntMethod;
+    SWIG_Callback1_t swig_callbackBaseBoolMethod;
+    void swig_init_callbacks();
+};
+
+void SwigDirector_Base::swig_connect_director(SWIG_Callback0_t callbackUIntMethod, 
+                                              SWIG_Callback1_t callbackBaseBoolMethod) {
+  swig_callbackUIntMethod = callbackUIntMethod;
+  swig_callbackBaseBoolMethod = callbackBaseBoolMethod;
+}
+
      +
      +

      Note that for each director class SWIG creates an unmanaged director + class for making the callbacks. For example Base has +SwigDirector_Base and SwigDirector_Base is derived from +Base. Should a C# class be derived from Base, the + underlying C++ SwigDirector_Base is created rather than +Base. The SwigDirector_Base class then implements all the + virtual methods, redirecting calls up to managed code if the + callback/delegate is non-zero. The implementation of +SwigDirector_Base::BaseBoolMethod shows this - the callback is made + by invoking the swig_callbackBaseBoolMethod function pointer:

      +
      +
      +void SwigDirector_Base::BaseBoolMethod(Base const &b, bool flag) {
+  void * jb = 0 ;
+  unsigned int jflag  ;
+  
+  if (!swig_callbackBaseBoolMethod) {
+    Base::BaseBoolMethod(b,flag);
+    return;
+  } else {
+    jb = (Base *) &b; 
+    jflag = flag;
+    swig_callbackBaseBoolMethod(jb, jflag);
+  }
+}
+
      +
      +

      18.5.3 Director caveats

      +

      There is a subtle gotcha with directors. If default parameters are + used, it is recommended to follow a pattern of always calling a single + method in any C# derived class. An example will clarify this and the + reasoning behind the recommendation. Consider the following C++ class + wrapped as a director class:

      +
      +
      +class Defaults {
+public:
+  virtual ~Defaults();
+  virtual void DefaultMethod(int a=-100);
+};
+
      +
      +

      Recall that C++ methods with default parameters generate overloaded + methods for each defaulted parameter, so a C# derived class can be + created with two DefaultMethod override methods:

      +
      +
      +public class CSharpDefaults : Defaults
+{
+  public override void DefaultMethod()
+  {
+    DefaultMethod(-100); // note C++ default value used
+  }
+  public override void DefaultMethod(int x)
+  {
+  }
+}
+
      +
      +

      It may not be clear at first, but should a user intend to call +CSharpDefaults.DefaultMethod() from C++, a call is actually made to + CSharpDefaults.DefaultMethod(int). This is because the initial + call is made in C++ and therefore the DefaultMethod(int) + method will be called as is expected with C++ calls to methods with + defaults, with the default being set to -100. The callback/delegate + matching this method is of course the overloaded method +DefaultMethod(int). However, a call from C# to +CSharpDefaults.DefaultMethod() will of course call this exact + method and in order for behaviour to be consistent with calls from C++, + the implementation should pass the call on to +CSharpDefaults.DefaultMethod(int)using the C++ default value, as + shown above.

      +

      18.6 C# Typemap examples

      + This section includes a few examples of typemaps. For more examples, + you might look at the files "csharp.swg" and "typemaps.i +" in the SWIG library. +

      18.6.1 + Memory management when returning references to member variables

      +

      This example shows how to prevent premature garbage collection of + objects when the underlying C++ class returns a pointer or reference to + a member variable. The example is a direct equivalent to this +Java equivalent.

      +

      Consider the following C++ code:

      +
      +
      +struct Wheel {
+  int size;
+  Wheel(int sz) : size(sz) {}
+};
+
+class Bike {
+  Wheel wheel;
+public:
+  Bike(int val) : wheel(val) {}
+  Wheel& getWheel() { return wheel; }
+};
+
      +
      +

      and the following usage from C# after running the code through SWIG:

      +
      +
      +      Wheel wheel = new Bike(10).getWheel();
+      Console.WriteLine("wheel size: " + wheel.size);
+      // Simulate a garbage collection
+      System.GC.Collect();
+      System.GC.WaitForPendingFinalizers();
+      Console.WriteLine("wheel size: " + wheel.size);
+
      +
      +

      Don't be surprised that if the resulting output gives strange + results such as...

      +
      +
      +wheel size: 10
+wheel size: 135019664
+
      +
      +

      What has happened here is the garbage collector has collected the +Bike instance as it doesn't think it is needed any more. The proxy + instance, wheel, contains a reference to memory that was + deleted when the Bike instance was collected. In order to + prevent the garbage collector from collecting the Bike + instance a reference to the Bike must be added to the +wheel instance. You can do this by adding the reference when the +getWheel() method is called using the following typemaps.

      +
      +
      +%typemap(cscode) Wheel %{
+  // Ensure that the GC doesn't collect any Bike instance set from C#
+  private Bike bikeReference;
+  internal void addReference(Bike bike) {
+    bikeReference = bike;
+  }
+%}
+
+// Add a C# reference to prevent premature garbage collection and resulting use
+// of dangling C++ pointer. Intended for methods that return pointers or
+// references to a member variable.
+%typemap(csout, excode=SWIGEXCODE) Wheel& getWheel {
+    IntPtr cPtr = $imcall;$excode
+    $csclassname ret = null;
+    if (cPtr != IntPtr.Zero) {
+      ret = new $csclassname(cPtr, $owner);
+      ret.addReference(this);
+    }
+    return ret;
+  }
+
      +
      +

      The code in the first typemap gets added to the Wheel proxy + class. The code in the second typemap constitutes the bulk of the code + in the generated getWheel() function:

      +
      +
      +public class Wheel : IDisposable {
+  ...
+  // Ensure that the GC doesn't collect any Bike instance set from C#
+  private Bike bikeReference;
+  internal void addReference(Bike bike) {
+    bikeReference = bike;
+  }
+}
+
+public class Bike : IDisposable {
+  ...
+  public Wheel getWheel() {
+    IntPtr cPtr = examplePINVOKE.Bike_getWheel(swigCPtr);
+    Wheel ret = null;
+    if (cPtr != IntPtr.Zero) {
+      ret = new Wheel(cPtr, false);
+      ret.addReference(this);
+    }
+    return ret;
+  }
+}
+
      +
      +

      Note the addReference call.

      +

      18.6.2 Memory + management for objects passed to the C++ layer

      +

      The example is a direct equivalent to this +Java equivalent. Managing memory can be tricky when using C++ and C# + proxy classes. The previous example shows one such case and this + example looks at memory management for a class passed to a C++ method + which expects the object to remain in scope after the function has + returned. Consider the following two C++ classes:

      +
      +
      +struct Element {
+  int value;
+  Element(int val) : value(val) {}
+};
+class Container {
+  Element* element;
+public:
+  Container() : element(0) {}
+  void setElement(Element* e) { element = e; }
+  Element* getElement() { return element; }
+};
+
      +
      +

      and usage from C++

      +
      +
      +    Container container;
+    Element element(20);
+    container.setElement(&element);
+    cout << "element.value: " << container.getElement()->value << endl;
+
      +
      +

      and more or less equivalent usage from C#

      +
      +
      +      Container container = new Container();
+      Element element = new Element(20);
+      container.setElement(element);
+
      +
      +

      The C++ code will always print out 20, but the value printed out may + not be this in the C# equivalent code. In order to understand why, + consider a garbage collection occuring...

      +
      +
      +      Container container = new Container();
+      Element element = new Element(20);
+      container.setElement(element);
+      Console.WriteLine("element.value: " + container.getElement().value);
+      // Simulate a garbage collection
+      System.GC.Collect();
+      System.GC.WaitForPendingFinalizers();
+      Console.WriteLine("element.value: " + container.getElement().value);
+
      +
      +

      The temporary element created with new Element(20) could + get garbage collected which ultimately means the container + variable is holding a dangling pointer, thereby printing out any old + random value instead of the expected value of 20. One solution is to + add in the appropriate references in the C# layer...

      +
      +
      +public class Container : IDisposable {
+
+  ...
+
+  // Ensure that the GC doesn't collect any Element set from C#
+  // as the underlying C++ class stores a shallow copy
+  private Element elementReference;
+  private HandleRef getCPtrAndAddReference(Element element) {
+    elementReference = element;
+    return Element.getCPtr(element);
+  }
+
+  public void setElement(Element e) {
+    examplePINVOKE.Container_setElement(swigCPtr, getCPtrAndAddReference(e));
+  }
+}
+
      +
      +

      The following typemaps will generate the desired code. The 'csin' + typemap matches the input parameter type for the setElement + method. The 'cscode' typemap simply adds in the specified code into the + C# proxy class.

      +
      +
      +%typemap(csin) Element *e "getCPtrAndAddReference($csinput)"
+
+%typemap(cscode) Container %{
+  // Ensure that the GC doesn't collect any Element set from C#
+  // as the underlying C++ class stores a shallow copy
+  private Element elementReference;
+  private HandleRef getCPtrAndAddReference(Element element) {
+    elementReference = element;
+    return Element.getCPtr(element);
+  }
+%}
+
      +
      +

      18.6.3 Date marshalling using + the csin typemap and associated attributes

      +

      The NaN Exception example is a + simple example of the "javain" typemap and its 'pre' attribute. This + example demonstrates how a C++ date class, say CDate, can be + mapped onto the standard .NET date class, System.DateTime by + using the 'pre', 'post' and 'pgcppname' attributes of the "csin" + typemap (the C# equivalent to the "javain" typemap). The example is an + equivalent to the Java Date + marshalling example. The idea is that the System.DateTime + is used wherever the C++ API uses a CDate. Let's assume the + code being wrapped is as follows:

      +
      +
      +class CDate {
+public:
+  CDate();
+  CDate(int year, int month, int day);
+  int getYear();
+  int getMonth();
+  int getDay();
+  ...
+};
+struct Action {
+  static int doSomething(const CDate &dateIn, CDate &dateOut);
+  Action(const CDate &date, CDate &dateOut);
+};
+
      +
      +

      Note that dateIn is const and therefore read only and +dateOut is a non-const output type.

      +

      First let's look at the code that is generated by default, where the + C# proxy class CDate is used in the proxy interface:

      +
      +
      +public class Action : IDisposable {
+  ...
+  public Action(CDate dateIn, CDate dateOut) 
+      : this(examplePINVOKE.new_Action(CDate.getCPtr(dateIn), CDate.getCPtr(dateOut)), true) {
+    if (examplePINVOKE.SWIGPendingException.Pending) 
+      throw examplePINVOKE.SWIGPendingException.Retrieve();
+  }
+
+  public int doSomething(CDate dateIn, CDate dateOut) {
+    int ret = examplePINVOKE.Action_doSomething(swigCPtr, 
+                                                CDate.getCPtr(dateIn), 
+                                                CDate.getCPtr(dateOut));
+    if (examplePINVOKE.SWIGPendingException.Pending) 
+      throw examplePINVOKE.SWIGPendingException.Retrieve();
+    return ret;
+  }
+}
+
      +
      +

      The CDate & and const CDate & C# code is generated + from the following two default typemaps:

      +
      +
      +%typemap(cstype) SWIGTYPE & "$csclassname"
+%typemap(csin) SWIGTYPE & "$csclassname.getCPtr($csinput)"
+
      +
      +

      where '$csclassname' is translated into the proxy class name, +CDate and '$csinput' is translated into the name of the parameter, + eg dateIn. From C#, the intention is then to call into a + modifed API with something like:

      +
      +
      +System.DateTime dateIn = new System.DateTime(2011, 4, 13);
+System.DateTime dateOut = new System.DateTime();
+
+// Note in calls below, dateIn remains unchanged and dateOut 
+// is set to a new value by the C++ call
+Action action = new Action(dateIn, out dateOut);
+dateIn = new System.DateTime(2012, 7, 14);
+
      +
      +

      To achieve this mapping, we need to alter the default code + generation slightly so that at the C# layer, a System.DateTime + is converted into a CDate. The intermediary layer will still + take a pointer to the underlying CDate class. The typemaps to + achieve this are shown below.

      +
      +
      +%typemap(cstype) const CDate& "System.DateTime"
+%typemap(csin, 
+         pre="    CDate temp$csinput = new CDate($csinput.Year, $csinput.Month, $csinput.Day);"
+        ) const CDate &
+         "$csclassname.getCPtr(temp$csinput)"
+
+%typemap(cstype) CDate& "out System.DateTime"
+%typemap(csin, 
+         pre="    CDate temp$csinput = new CDate();", 
+         post="      $csinput = new System.DateTime(temp$csinput.getYear(),"
+              " temp$csinput.getMonth(), temp$csinput.getDay(), 0, 0, 0);", 
+         cshin="out $csinput"
+        ) CDate &
+         "$csclassname.getCPtr(temp$csinput)"
+
+
      +
      +

      The resulting generated proxy code in the Action class + follows:

      +
      +
      +public class Action : IDisposable {
+  ...
+  public int doSomething(System.DateTime dateIn, out System.DateTime dateOut) {
+    CDate tempdateIn = new CDate(dateIn.Year, dateIn.Month, dateIn.Day);
+    CDate tempdateOut = new CDate();
+    try {
+      int ret = examplePINVOKE.Action_doSomething(swigCPtr, 
+                                                  CDate.getCPtr(tempdateIn), 
+                                                  CDate.getCPtr(tempdateOut));
+      if (examplePINVOKE.SWIGPendingException.Pending) 
+        throw examplePINVOKE.SWIGPendingException.Retrieve();
+      return ret;
+    } finally {
+      dateOut = new System.DateTime(tempdateOut.getYear(), 
+                                    tempdateOut.getMonth(), tempdateOut.getDay(), 0, 0, 0);
+    }
+  }
+
+  static private IntPtr SwigConstructAction(System.DateTime dateIn, out System.DateTime dateOut) {
+    CDate tempdateIn = new CDate(dateIn.Year, dateIn.Month, dateIn.Day);
+    CDate tempdateOut = new CDate();
+    try {
+      return examplePINVOKE.new_Action(CDate.getCPtr(tempdateIn), CDate.getCPtr(tempdateOut));
+    } finally {
+      dateOut = new System.DateTime(tempdateOut.getYear(), 
+                                    tempdateOut.getMonth(), tempdateOut.getDay(), 0, 0, 0);
+    }
+  }
+
+  public Action(System.DateTime dateIn, out System.DateTime dateOut) 
+      : this(Action.SwigConstructAction(dateIn, out dateOut), true) {
+    if (examplePINVOKE.SWIGPendingException.Pending) 
+      throw examplePINVOKE.SWIGPendingException.Retrieve();
+  }
+}
+
      +
      +

      A few things to note:

      +
        +
      • The "cstype" typemap has changed the parameter type to +System.DateTime instead of the default generated CDate + proxy.
        • +
      • The non-const CDate & type is marshalled as a reference + parameter in C# as the date cannot be explicitly set once the object + has been created, so a new object is created instead.
        • +
      • The code in the 'pre' attribute appears before the intermediary + call (examplePINVOKE.new_Action / +examplePINVOKE.Action_doSomething).
        • +
      • The code in the 'post' attribute appears after the intermediary + call.
        • +
      • A try .. finally block is generated with the intermediary call in + the try block and 'post' code in the finally block. The alternative of + just using a temporary variable for the return value from the + intermediary call and the 'post' code being inserted before the return + statement is not possible given that the intermediary call and method + return comes from a single source (the "csout" typemap).
        • +
      • The temporary variables in the "csin" typemaps are called +temp$csin, where "$csin" is replaced with the parameter name. + "$csin" is used to mangle the variable name so that more than one +CDate & type can be used as a parameter in a method, otherwise two + or more local variables with the same name would be generated.
        • +
      • The use of the "csin" typemap causes a constructor helper function + (SwigConstructAction) to be generated. This allows C# code to + be called before the intermediary call made in the constructor + initialization list.
        • +
      • The 'cshin' attribute is required for the SwigConstructAction + constructor helper function so that the 2nd parameter is declared as +out dateOut instead of just dateOut.
        • +
      +

      So far we have considered the date as an input only and an output + only type. Now let's consider CDate * used as an input/output + type. Consider the following C++ function which modifies the date + passed in:

      +
      +
      +void addYears(CDate *pDate, int years) {
+  *pDate = CDate(pDate->getYear() + years, pDate->getMonth(), pDate->getDay());
+}
+
      +
      +

      If usage of CDate * commonly follows this input/output + pattern, usage from C# like the following

      +
      +
      +System.DateTime christmasEve = new System.DateTime(2000, 12, 24);
+example.addYears(ref christmasEve, 10); // christmasEve now contains 2010-12-24
+
      +
      +

      will be possible with the following CDate * typemaps

      +
      +
      +%typemap(cstype, out="System.DateTime") CDate * "ref System.DateTime"
+
+%typemap(csin,
+         pre="    CDate temp$csinput = new CDate($csinput.Year, $csinput.Month, $csinput.Day);",
+         post="      $csinput = new System.DateTime(temp$csinput.getYear(),"
+              " temp$csinput.getMonth(), temp$csinput.getDay(), 0, 0, 0);", 
+         cshin="ref $csinput"
+        ) CDate *
+         "$csclassname.getCPtr(temp$csinput)"
+
      +
      +

      Globals are wrapped by the module class and for a module called + example, the typemaps result in the following code:

      +
      +
      +public class example {
+  public static void addYears(ref System.DateTime pDate, int years) {
+    CDate temppDate = new CDate(pDate.Year, pDate.Month, pDate.Day);
+    try {
+      examplePINVOKE.addYears(CDate.getCPtr(temppDate), years);
+    } finally {
+      pDate = new System.DateTime(temppDate.getYear(), temppDate.getMonth(), temppDate.getDay(), 0, 0, 0);
+    }
+  }
+  ...
+}
+
      +
      +

      The following typemap is the same as the previous but demonstrates + how a using block can be used for the temporary variable. The only + change to the previous typemap is the introduction of the 'terminator' + attribute to terminate the using block. The subtractYears + method is nearly identical to the above addYears method.

      +
      +
      +%typemap(csin,
+         pre="    using (CDate temp$csinput = new CDate($csinput.Year, $csinput.Month, $csinput.Day)) {",
+         post="      $csinput = new System.DateTime(temp$csinput.getYear(),"
+              " temp$csinput.getMonth(), temp$csinput.getDay(), 0, 0, 0);", 
+         terminator="    } // terminate temp$csinput using block",
+         cshin="ref $csinput"
+        ) CDate *
+         "$csclassname.getCPtr(temp$csinput)"
+
+void subtractYears(CDate *pDate, int years) {
+  *pDate = CDate(pDate->getYear() - years, pDate->getMonth(), pDate->getDay());
+}
+
      +
      +

      The resulting generated code shows the termination of the using + block:

      +
      +
      +public class example {
+  public static void subtractYears(ref System.DateTime pDate, int years) {
+    using (CDate temppDate = new CDate(pDate.Year, pDate.Month, pDate.Day)) {
+    try {
+      examplePINVOKE.subtractYears(CDate.getCPtr(temppDate), years);
+    } finally {
+      pDate = new System.DateTime(temppDate.getYear(), temppDate.getMonth(), temppDate.getDay(), 0, 0, 0);
+    }
+    } // terminate temppDate using block
+  }
+  ...
+}
+
      +
      +

      18.6.4 A date example + demonstrating marshalling of C# properties

      +

      The previous section looked at converting a C++ date class to +System.DateTime for parameters. This section extends this idea so + that the correct marshalling is obtained when wrapping C++ variables. + Consider the same CDate class from the previous section and a + global variable:

      +
      +
      +CDate ImportantDate = CDate(1999, 12, 31);
+
      +
      +

      The aim is to use System.DateTime from C# when accessing + this date as shown in the following usage where the module name is + 'example':

      +
      +
      +example.ImportantDate = new System.DateTime(2000, 11, 22);
+System.DateTime importantDate = example.ImportantDate;
+Console.WriteLine("Important date: " + importantDate);
+
      +
      +

      When SWIG wraps a variable that is a class/struct/union, it is + wrapped using a pointer to the type for the reasons given in +Stucture data members. The typemap type required is thus CDate * +. Given that the previous section already designed CDate * + typemaps, we'll use those same typemaps plus the 'csvarin' and + 'csvarout' typemaps.

      +
      +%typemap(cstype, out="System.DateTime") CDate * "ref System.DateTime"
+
+%typemap(csin,
+         pre="    CDate temp$csinput = new CDate($csinput.Year, $csinput.Month, $csinput.Day);",
+         post="      $csinput = new System.DateTime(temp$csinput.getYear(),"
+              " temp$csinput.getMonth(), temp$csinput.getDay(), 0, 0, 0);", 
+         cshin="ref $csinput"
+        ) CDate *
+         "$csclassname.getCPtr(temp$csinput)"
+
+%typemap(csvarin, excode=SWIGEXCODE2) CDate * %{
+    /* csvarin typemap code */
+    set {
+      CDate temp$csinput = new CDate($csinput.Year, $csinput.Month, $csinput.Day);
+      $imcall;$excode
+    } %}
+
+%typemap(csvarout, excode=SWIGEXCODE2) CDate * %{
+    /* csvarout typemap code */
+    get {
+      IntPtr cPtr = $imcall;
+      CDate tempDate = (cPtr == IntPtr.Zero) ? null : new CDate(cPtr, $owner);$excode
+      return new System.DateTime(tempDate.getYear(), tempDate.getMonth(), tempDate.getDay(),
+                                 0, 0, 0);
+    } %}
+
      +

      +

      For a module called example, the typemaps result in the following + code:

      +
      +
      +public class example {
+  public static System.DateTime ImportantDate {
+    /* csvarin typemap code */
+    set {
+      CDate tempvalue = new CDate(value.Year, value.Month, value.Day);
+      examplePINVOKE.ImportantDate_set(CDate.getCPtr(tempvalue));
+    } 
+    /* csvarout typemap code */
+    get {
+      IntPtr cPtr = examplePINVOKE.ImportantDate_get();
+      CDate tempDate = (cPtr == IntPtr.Zero) ? null : new CDate(cPtr, false);
+      return new System.DateTime(tempDate.getYear(), tempDate.getMonth(), tempDate.getDay(),
+                                 0, 0, 0);
+    } 
+  }
+  ...
+}
+
      +
      +

      Some points to note:

      +
        +
      • The property set comes from the 'csvarin' typemap and the property + get comes from the 'csvarout' typemap.
        • +
      • The type used for the property comes from the 'cstype' typemap. This + particular example has the 'out' attribute set in the typemap and as it + is specified, it is used in preference to the type in the typemap body. + This is because the type in the 'out' attribute can never include + modifiers such as 'ref', thereby avoiding code such as public + static ref System.DateTime ImportantDate { ..., which would of + course not compile.
        • +
      • The $excode special variable expands to nothing as there + are no exception handlers specified in any of the unmanaged code + typemaps (in fact the marshalling was done using the default unmanaged + code typemaps.)
        • +
      • The $imcall typemap expands to the appropriate intermediary + method call in the examplePINVOKE class.
        • +
      • The $csinput special variable in the 'csin' typemap always + expands to value for properties. In this case +$csclassname.getCPtr(temp$csinput) expands to +CDate.getCPtr(tempvalue).
        • +
      • The 'csin' typemap has 'pre', 'post' and 'cshin' attributes, and + these are all ignored in the property set. The code in these attributes + must instead be replicated within the 'csvarin' typemap. The line + creating the temp$csinput variable is such an example; it is + identical to what is in the 'pre' attribute.
        • +
      +

      18.6.5 Turning wrapped classes + into partial classes

      +

      C# supports the notion of partial classes whereby a class definition + can be split into more than one file. It is possible to turn the + wrapped C++ class into a partial C# class using the +csclassmodifiers typemap. Consider a C++ class called ExtendMe +:

      +
      +
      +class ExtendMe {
+public:
+  int Part1() { return 1; }
+};
+
      +
      +

      The default C# proxy class generated is:

      +
      +
      +public class ExtendMe : IDisposable {
+  ...
+  public int Part1() {
+    ...
+  }
+}
+
      +
      +

      The default csclassmodifiers typemap shipped with SWIG is

      +
      +
      +%typemap(csclassmodifiers) SWIGTYPE "public class"
+
      +
      +

      Note that the type used is the special catch all type SWIGTYPE +. If instead we use the following typemap to override this for just the +ExtendMe class:

      +
      +
      +%typemap(csclassmodifiers) ExtendMe "public partial class"
+
      +
      +

      The C# proxy class becomes a partial class:

      +
      +
      +public partial class ExtendMe : IDisposable {
+  ...
+  public int Part1() {
+    ...
+  }
+}
+
      +
      +

      You can then of course declare another part of the partial class + elsewhere, for example:

      +
      +
      +public partial class ExtendMe : IDisposable {
+  public int Part2() {
+    return 2;
+  }
+}
+
      +
      +

      and compile the following code:

      +
      +
      +ExtendMe em = new ExtendMe();
+Console.WriteLine("part1: {0}", em.Part1());
+Console.WriteLine("part2: {0}", em.Part2());
+
      +
      +

      demonstrating that the class contains methods calling both unmanaged + code - Part1() and managed code - Part2(). The + following example is an alternative approach to adding managed code to + the generated proxy class.

      +

      18.6.6 Extending proxy + classes with additional C# code

      +

      The previous example showed how to use partial classes to add + functionality to a generated C# proxy class. It is also possible to + extend a wrapped struct/class with C/C++ code by using the +%extend directive. A third approach is to add some C# methods into + the generated proxy class with the cscode typemap. If we + declare the following typemap before SWIG parses the ExtendMe + class used in the previous example

      +
      +
      +%typemap(cscode) ExtendMe %{
+  public int Part3() {
+    return 3;
+  }
+%}
+
+
      +
      +

      The generated C# proxy class will instead be:

      +
      +
      +public class ExtendMe : IDisposable {
+  ...
+  public int Part3() {
+    return 3;
+  }
+  public int Part1() {
+    ...
+  }
+}
+
      +
      + + +

      19 SWIG and Chicken

      + + +
      + +
      + +

      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 Revised^5 Report on Scheme. Its main attributes + are that it

      +
        +
      1. generates portable C code
        2. +
      2. includes a customizable interpreter
        3. +
      3. links to C libraries with a simple Foreign Function Interface
        4. +
      4. supports full tail-recursion and first-class continuations
        5. +
      +

      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 support for C++ + -- object-oriented code is difficult to wrap by hand in CHICKEN -- and + its typed pointer representation, essential for C and + C++ libraries involving structures or classes.

      +

      19.1 Preliminaries

      +

      CHICKEN support was introduced to SWIG in version 1.3.18. SWIG + relies on some recent additions to CHICKEN, which are only present in + releases of CHICKEN with version number greater than or equal + to 1.89. To use a chicken version between 1.40 and 1.89, see + the Garbage collection section below.

      +

      You may want to look at any of the examples in Examples/chicken/ or + Examples/GIFPlot/Chicken for the basic steps to run SWIG CHICKEN.

      +

      19.1.1 Running SWIG in C mode

      +

      To run SWIG CHICKEN in C mode, use the -chicken option.

      +
      +
      % swig -chicken example.i
      +
      +

      To allow the wrapper to take advantage of future CHICKEN code + generation improvements, part of the wrapper is direct CHICKEN function + calls (example_wrap.c) and part is CHICKEN Scheme ( +example.scm). The basic Scheme code must be compiled to C using + your system's CHICKEN compiler or both files can be compiled directly + using the much simpler csc.

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

      So for the C mode of SWIG CHICKEN, example_wrap.c and +oexample.c are the files that must be compiled to object files and + linked into your project.

      +

      19.1.2 Running SWIG in C++ mode

      +

      To run SWIG CHICKEN in C++ mode, use the -chicken -c++ option.

      +
      +
      % swig -chicken -c++ example.i
      +
      +

      This will generate example_wrap.cxx and example.scm +. 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 csc.

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

      So for the C++ mode of SWIG CHICKEN, example_wrap.cxx and +oexample.c are the files that must be compiled to object files and + linked into your project.

      +

      19.2 Code Generation

      +

      19.2.1 Naming Conventions

      +

      Given a C variable, function or constant declaration named +Foo_Bar, the declaration will be available in CHICKEN as an + identifier ending with Foo-Bar. That is, an underscore is + converted to a dash.

      +

      You may control what the CHICKEN identifier will be by using the +%rename SWIG directive in the SWIG interface file.

      +

      19.2.2 Modules

      +

      The name of the module must be declared one of two ways:

      +
        +
      • Placing %module example in the SWIG interface file.
        • +
      • Using -module example on the SWIG command line.
        • +
      +

      The generated example.scm file then exports (declare (unit + modulename)). If you do not want SWIG to export the +(declare (unit modulename)), pass the -nounit option to SWIG.

      +

      CHICKEN will be able to access the module using the (declare + (uses modulename)) CHICKEN Scheme form.

      +

      19.2.3 Constants and Variables

      +

      Constants may be created using any of the four constructs in the + interface file:

      +
        +
      1. #define MYCONSTANT1 ...
        2. +
      2. %constant int MYCONSTANT2 = ...
        3. +
      3. const int MYCONSTANT3 = ...
        4. +
      4. enum { MYCONSTANT4 = ... };
        5. +
      +

      In all cases, the constants may be accessed from within CHICKEN + using the form (MYCONSTANT1); that is, the constants may be + accessed using the read-only parameter form.

      +

      Variables are accessed using the full parameter form. For example, + to set the C variable "int my_variable;", use the Scheme form +(my-variable 2345). To get the C variable, use (my-variable) +.

      +

      The %feature("constasvar") 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 (set! + MYCONSTANT1 (MYCONSTANT1)). See Features and + the %feature directive for info on how to apply the %feature.

      +

      19.2.4 Functions

      +

      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 (sqrt + 2345.0). A void return value will give + C_SCHEME_UNDEFINED as a result.

      +

      A function may return more than one value by using the OUTPUT + specifier (see Lib/chicken/typemaps.i). They will be returned as + multiple values using (values) 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 (call-with-values) +.

      +

      19.2.5 Exceptions

      +

      The SWIG chicken module has support for exceptions thrown from C or + C++ code to be caught in scheme. See Exception + handling with %exception for more information about declaring + exceptions in the interface file.

      +

      Chicken supports both the SWIG_exception(int code, const char + *msg) interface as well as a SWIG_ThrowException(C_word + val) function for throwing exceptions from inside the %exception + blocks. SWIG_exception will throw a list consisting of the + code (as an integer) and the message. Both of these will throw an + exception using (abort), which can be handled by +(handle-exceptions). See +Chicken manual on Exceptions and +SFRI-12. Since the exception values are thrown directly, if +(condition-case) is used to catch an exception the exception will + come through in the val () case.

      +

      The following simple module

      +
      +
      +%module exception_test
+
+%inline %{
+  void test_throw(int i) throws (int) { 
+    if (i == 1) throw 15; 
+  }
+%}
+
      +
      +

      could be run with

      +
      +
      +(handle-exceptions exvar 
+  (if (= exvar 15)
+    (print "Correct!") 
+    (print "Threw something else " exvar))
+  (test-throw 1))
+
      +
      +

      19.3 TinyCLOS

      +

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

      +

      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.

      +

      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.

      +

      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:"

      +

      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.

      +

      19.4 Linkage

      +

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

      +

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

      +

      19.4.1 Static binary or shared library + linked at compile time

      +

      We can easily use csc to build a static binary.

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

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

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

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

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

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

      +

      19.4.2 Building chicken extension + libraries

      +

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

      +

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

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

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

      +

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

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

      Which would then be compiled with

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

      Then the extension library can be loaded with (require 'mod) +. As we can see here, mod_load.scm contains the code that gets + 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 %import

      +

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

      +

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

      +

      19.4.3 Linking multiple SWIG modules with + TinyCLOS

      +

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

      +

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

      +

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

      +

      19.5 Typemaps

      +

      The Chicken module handles all types via typemaps. This information + is read from Lib/chicken/typemaps.i and +Lib/chicken/chicken.swg.

      +

      19.6 Pointers

      +

      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.

      +

      To construct a Scheme object from a C pointer, the wrapper code + calls the function SWIG_NewPointerObj(void *ptr, swig_type_info + *type, int owner), The function that calls +SWIG_NewPointerObj must have a variable declared C_word + *known_space = C_alloc(C_SIZEOF_SWIG_POINTER); It is ok to call +SWIG_NewPointerObj more than once, just make sure known_space has + enough space for all the created pointers.

      +

      To get the pointer represented by a CHICKEN tagged pointer, the + wrapper code calls the function SWIG_ConvertPtr(C_word s, void + **result, swig_type_info *type, int flags), passing a pointer to + a struct representing the expected pointer type. flags is either zero + or SWIG_POINTER_DISOWN (see below).

      +

      19.6.1 Garbage collection

      +

      If the owner flag passed to SWIG_NewPointerObj is 1, +NewPointerObj 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 +%newobject directive must be specified for functions whose return + values should be garbage collected. See Object + ownership and %newobject for more information.

      +

      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 DISOWN input typemap. After applying this + typemap (see the Typemaps chapter 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 SWIG_POINTER_DISOWN flag to SWIG_ConvertPtr +. Warning: 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.

      +

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

      +

      19.7 Unsupported features and known + problems

      +
        +
      • No director support.
        • +
      • No support for c++ standard types like std::vector.
        • +
      • The TinyCLOS wrappers for overloaded functions will not work + correctly when using +%feature(compactdefaultargs).
        • +
      +

      19.7.1 TinyCLOS problems with Chicken + version <= 1.92

      +

      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

      +
      +
      +class Foo {};
+int foo(int a, Foo *b);
+int foo(int a);
+
      +
      +

      will produce scheme code

      +
      +
      +(define-method (foo (arg0 <top>) (arg1 <Foo>)) (call primitive function))
+(define-method (foo (arg0 <top>)) (call primitive function))
+
      +
      +

      Using unpatched TinyCLOS, the second (define-method) + will replace the first one, so calling (foo 3 f) will + produce an error.

      +

      There are three solutions to this. The easist is to upgrade to the + latest Chicken version. Otherwise, the file +Lib/chicken/tinyclos-multi-generic.patch 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 +Lib/chicken/multi-generic.scm 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.

      +
      + + +

      20 SWIG and Guile

      + + +
      + +
      + +

      This section details guile-specific support in SWIG.

      +

      20.1 Meaning of "Module"

      +

      There are three different concepts of "module" involved, defined + separately for SWIG, Guile, and Libtool. To avoid horrible confusion, + we explicitly prefix the context, e.g., "guile-module".

      +

      20.2 Using the SCM or GH Guile API

      +

      The guile module can currently export wrapper files that use the + guile GH interface or the SCM interface. This is controlled by an + argument passed to swig. The "-gh" argument causes swig to output GH + code, and the "-scm" argument causes swig to output SCM code. Right now + the "-scm" argument is the default. The "-scm" wrapper generation + assumes a guile version >= 1.6 and has several advantages over the + "-gh" wrapper generation including garbage collection and GOOPS + support. The "-gh" wrapper generation can be used for older versions of + guile. The guile GH wrapper code generation is depreciated and the SCM + interface is the default. The SCM and GH interface differ greatly in + how they store pointers and have completely different run-time code. + See below for more info.

      +

      The GH interface to guile is deprecated. Read more about why in the +Guile manual. The idea of the GH interface was to provide a high + level API that other languages and projects could adopt. This was a + good idea, but didn't pan out well for general development. But for the + specific, minimal uses that the SWIG typemaps put the GH interface to + use is ideal for using a high level API. So even though the GH + interface is depreciated, SWIG will continue to use the GH interface + and provide mappings from the GH interface to whatever API we need. We + can maintain this mapping where guile failed because SWIG uses a small + subset of all the GH functions which map easily. All the guile typemaps + like typemaps.i and std_vector.i will continue to use the GH functions + to do things like create lists of values, convert strings to integers, + etc. Then every language module will define a mapping between the GH + interface and whatever custom API the language uses. This is currently + implemented by the guile module to use the SCM guile API rather than + the GH guile API. For example, here are some of the current mapping + file for the SCM API

      +
      +
      +
+#define gh_append2(a, b) scm_append(scm_listify(a, b, SCM_UNDEFINED)) 
+#define gh_apply(a, b) scm_apply(a, b, SCM_EOL) 
+#define gh_bool2scm SCM_BOOL 
+#define gh_boolean_p SCM_BOOLP 
+#define gh_car SCM_CAR 
+#define gh_cdr SCM_CDR 
+#define gh_cons scm_cons 
+#define gh_double2scm scm_make_real 
+...
+
      +
      +

      This file is parsed by SWIG at wrapper generation time, so every + reference to a gh_ function is replaced by a scm_ function in the + wrapper file. Thus the gh_ function calls will never be seen in the + wrapper; the wrapper will look exactly like it was generated for the + specific API. Currently only the guile language module has created a + mapping policy from gh_ to scm_, but there is no reason other languages + (like mzscheme or chicken) couldn't also use this. If that happens, + there is A LOT less code duplication in the standard typemaps.

      +

      20.3 Linkage

      +

      Guile support is complicated by a lack of user community + cohesiveness, which manifests in multiple shared-library usage + conventions. A set of policies implementing a usage convention is + called a linkage.

      +

      20.3.1 Simple Linkage

      +

      The default linkage is the simplest; nothing special is done. In + this case the function SWIG_init() is exported. Simple + linkage can be used in several ways:

      +
        +
      • Embedded Guile, no modules. You want to embed a Guile + interpreter into your program; all bindings made by SWIG shall show up + in the root module. Then call SWIG_init() in the +inner_main() function. See the "simple" and "matrix" examples + under Examples/guile.
        • +
      • +

        Dynamic module mix-in. You want to create a Guile module using + define-module, containing both Scheme code and bindings + made by SWIG; you want to load the SWIG modules as shared libraries + into Guile.

        +
        +
        +(define-module (my module))
+(define my-so (dynamic-link "./example.so"))
+(dynamic-call "SWIG_init" my-so) ; make SWIG bindings
+;; Scheme definitions can go here
+
        +
        +

        Newer Guile versions provide a shorthand for dynamic-link + and dynamic-call:

        +
        +
        +(load-extension "./example.so" "SWIG_init")
+
        +
        +

        You need to explicitly export those bindings made by SWIG that you + want to import into other modules:

        +
        +
        +(export foo bar)
+
        +
        +

        In this example, the procedures foo and bar + would be exported. Alternatively, you can export all bindings with the + following module-system hack:

        +
        +
        +(module-map (lambda (sym var)
+	      (module-export! (current-module) (list sym)))
+	    (current-module))
+
        +
        +

        SWIG can also generate this Scheme stub (from define-module + up to export) semi-automagically if you pass it the + command-line argument -scmstub. The code will be exported + in a file called module.scm in the directory + specified by -outdir or the current directory if +-outdir is not specified. Since SWIG doesn't know how to load + your extension module (with dynamic-link or +load-extension), you need to supply this information by including + a directive like this in the interface file:

        +
        +
        +%scheme %{ (load-extension "./example.so" "SWIG_init") %}
+
        +
        +

        (The %scheme directive allows to insert arbitrary + Scheme code into the generated file module.scm; + it is placed between the define-module form and the +export form.)

        +
        • +
      +

      If you want to include several SWIG modules, you would need to rename + SWIG_init via a preprocessor define to avoid symbol + clashes. For this case, however, passive linkage is available.

      +

      20.3.2 Passive Linkage

      +

      Passive linkage is just like simple linkage, but it generates an + initialization function whose name is derived from the module and + package name (see below).

      +

      You should use passive linkage rather than simple linkage when you + are using multiple modules.

      +

      20.3.3 Native Guile Module Linkage

      +

      SWIG can also generate wrapper code that does all the Guile module + declarations on its own if you pass it the -Linkage module + command-line option. This requires Guile 1.5.0 or later.

      +

      The module name is set with the -package and +-module command-line options. Suppose you want to define a module + with name (my lib foo); then you would have to pass the + options -package my/lib -module foo +. Note that the last part of the name can also be set via the + SWIG directive %module.

      +

      You can use this linkage in several ways:

      +
        +
      • Embedded Guile with SWIG modules. You want to embed a Guile + interpreter into your program; the SWIG bindings shall be put into + different modules. Simply call the function scm_init_my +_modules_foo_module in the +inner_main() function.
        • +
      • Dynamic Guile modules. You want to load the SWIG modules as + shared libraries into Guile; all bindings are automatically put in + newly created Guile modules.
        +
        +(define my-so (dynamic-link "./foo.so"))
+;; create new module and put bindings there:
+(dynamic-call "scm_init_my_modules_foo_module" my-so) 
+
        +
        Newer Guile versions have a shorthand procedure for this:
        +
        +(load-extension "./foo.so" "scm_init_my_modules_foo_module")
+
        +
        • +
      +

      20.3.4 Old Auto-Loading Guile Module Linkage

      +

      Guile used to support an autoloading facility for object-code + modules. This support has been marked deprecated in version 1.4.1 and + is going to disappear sooner or later. SWIG still supports building + auto-loading modules if you pass it the -Linkage ltdlmod + command-line option.

      +

      Auto-loading worked like this: Suppose a module with name (my + lib foo) is required and not loaded yet. Guile will then search + all directories in its search path for a Scheme file +my/modules/foo.scm or a shared library my/ +modules/libfoo.so (or my/ +modules/libfoo.la; see the GNU libtool + documentation). If a shared library is found that contains the symbol +scm_init_my_modules_foo_module, + the library is loaded, and the function at that symbol is called with + no arguments in order to initialize the module.

      +

      When invoked with the -Linkage ltdlmod command-line + option, SWIG generates an exported module initialization function with + an appropriate name.

      +

      20.3.5 Hobbit4D Linkage

      +

      The only other linkage supported at this time creates shared object + libraries suitable for use by hobbit's (hobbit4d link) + guile module. This is called the "hobbit" linkage, and requires also + using the "-package" command line option to set the part of the module + name before the last symbol. For example, both command lines:

      +
      +
      +swig -guile -package my/lib foo.i
+swig -guile -package my/lib -module foo foo.i
+
      +
      +

      would create module (my lib foo) (assuming in the first + case foo.i declares the module to be "foo"). The installed files are + my/lib/libfoo.so.X.Y.Z and friends. This scheme is still very + experimental; the (hobbit4d link) conventions are not well understood.

      +

      20.4 Underscore Folding

      +

      Underscores are converted to dashes in identifiers. Guile support + may grow an option to inhibit this folding in the future, but no one + has complained so far.

      +

      You can use the SWIG directives %name and %rename + to specify the Guile name of the wrapped functions and variables (see + CHANGES).

      +

      20.5 Typemaps

      +

      The Guile module handles all types via typemaps. This information is + read from Lib/guile/typemaps.i. Some non-standard typemap + substitutions are supported:

      +
        +
      • $descriptor expands to a type descriptor for use with + the SWIG_NewPointerObj() and SWIG_ConvertPtr + functions.
        • +
      • For pointer types, $*descriptor expands to a descriptor + for the direct base type (i.e., one pointer is stripped), whereas +$basedescriptor expands to a descriptor for the base type (i.e., + all pointers are stripped).
        • +
      +

      A function returning void (more precisely, a function + whose out typemap returns SCM_UNSPECIFIED) is + treated as returning no values. In argout typemaps, one + can use the macro GUILE_APPEND_RESULT in order to append a + value to the list of function return values.

      +

      Multiple values can be passed up to Scheme in one of three ways:

      +
        +
      • +

        Multiple values as lists. By default, if more than one value + is to be returned, a list of the values is created and returned; to + switch back to this behavior, use

        +
        +
        +%values_as_list;
        +
        • +
      • +

        Multiple values as vectors. By issuing

        +
        +
        +%values_as_vector;
        +
        +

        vectors instead of lists will be used.

        +
        • +
      • +

        Multiple values for multiple-value continuations. + This is the most elegant way. By issuing

        +
        +
        +%multiple_values;
        +
        +

        multiple values are passed to the multiple-value continuation, as + created by call-with-values or the convenience macro +receive. The latter is available if you issue (use-modules + (srfi srfi-8)). Assuming that your divide function + wants to return two values, a quotient and a remainder, you can write:

        +
        +
        +(receive (quotient remainder)
+    (divide 35 17)
+  body...)
+
        +
        +

        In body, the first result of divide + will be bound to the variable quotient, and the second + result to remainder.

        +
        • +
      +

      See also the "multivalue" example.

      +

      Constants are exported as a function that returns the value. The + %feature("constasvar") can be applied to any constant, immutable + variable, or enum. Instead of exporting the constant as a function that + must be called, the constant will appear as a scheme variable. See +Features and the %feature directive for info on how to apply the + %feature.

      +

      20.6 Representation of pointers as smobs

      +

      For pointer types, SWIG uses Guile smobs. SWIG smobs print like + this: #<swig struct xyzzy * 0x1234affe> Two of them are +equal? if and only if they have the same type and value.

      +

      To construct a Scheme object from a C pointer, the wrapper code + calls the function SWIG_NewPointerObj(), passing a pointer + to a struct representing the pointer type. The type index to store in + the upper half of the CAR is read from this struct. To get the pointer + represented by a smob, the wrapper code calls the function +SWIG_ConvertPtr(), passing a pointer to a struct representing the + expected pointer type. See also The + run-time type checker. If the Scheme object passed was not a SWIG + smob representing a compatible pointer, a wrong-type-arg + exception is raised.

      +

      20.6.1 GH Smobs

      +

      In earlier versions of SWIG, C pointers were represented as Scheme + strings containing a hexadecimal rendering of the pointer value and a + mangled type name. As Guile allows registering user types, so-called + "smobs" (small objects), a much cleaner representation has been + implemented now. The details will be discussed in the following.

      +

      A smob is a cons cell where the lower half of the CAR contains the + smob type tag, while the upper half of the CAR and the whole CDR are + available. Every module creates its own smob type in the clientdata + field of the module. So the lower 16 bits of the car of the smob store + the tag and the upper 16 bits store the index this type is in the + array. We can then, given a smob, find its swig_type_info struct by + using the tag (lower 16 bits of car) to find which module this type is + in (since each tag is unique for the module). Then we use the upper 16 + bits to index into the array of types attached to this module. Looking + up the module from the tag is worst case O(# of modules) but average + case O(1). This is because the modules are stored in a circularly + linked list, and when we start searching the modules for the tag, we + start looking with the module that the function doing the lookup is in. + SWIG_Guile_ConvertPtr() takes as its first argument the + swig_module_info * of the calling function, which is where we start + comparing tags. Most types will be looked up in the same module that + created them, so the first module we check will most likely be correct. + Once we have a swig_type_info structure, we loop through the linked + list of casts, using pointer comparisons.

      +

      20.6.2 SCM Smobs

      +

      The SCM interface (using the "-scm" argument to swig) uses + swigrun.swg. The whole type system, when it is first initialized, + creates two smobs named "swig" and "collected_swig". The swig smob is + used for non-garbage collected smobs, while the collected_swig smob is + used as described below. Each smob has the same format, which is a + double cell created by SCM_NEWSMOB2() The first word of data is the + pointer to the object and the second word of data is the swig_type_info + * structure describing this type. This is a lot easier than the GH + interface above because we can store a pointer to the type info + structure right in the type. With the GH interface, there was not + enough room in the smob to store two whole words of data so we needed + to store part of the "swig_type_info address" in the smob tag. If a + generated GOOPS module has been loaded, smobs will be wrapped by the + corresponding GOOPS class.

      +

      20.6.3 Garbage Collection

      +

      Garbage collection is a feature of the new SCM interface, and it is + automatically included if you pass the "-scm" flag to swig. Thus the + swig garbage collection support requires guile >1.6. Garbage collection + works like this. Every swig_type_info structure stores in its + clientdata field a pointer to the destructor for this type. The + destructor is the generated wrapper around the delete function. So swig + still exports a wrapper for the destructor, it just does not call + scm_c_define_gsubr() for the wrapped delete function. So the only way + to delete an object is from the garbage collector, since the delete + function is not available to scripts. How swig determines if a type + should be garbage collected is exactly like described in + Object ownership and %newobject in the SWIG manual. All typemaps + use an $owner var, and the guile module replaces $owner with 0 or 1 + depending on feature:new.

      +

      20.7 Exception Handling

      +

      SWIG code calls scm_error on exception, using the + following mapping:

      +
      +      MAP(SWIG_MemoryError,	"swig-memory-error");
+      MAP(SWIG_IOError,		"swig-io-error");
+      MAP(SWIG_RuntimeError,	"swig-runtime-error");
+      MAP(SWIG_IndexError,	"swig-index-error");
+      MAP(SWIG_TypeError,	"swig-type-error");
+      MAP(SWIG_DivisionByZero,	"swig-division-by-zero");
+      MAP(SWIG_OverflowError,	"swig-overflow-error");
+      MAP(SWIG_SyntaxError,	"swig-syntax-error");
+      MAP(SWIG_ValueError,	"swig-value-error");
+      MAP(SWIG_SystemError,	"swig-system-error");
+
      +

      +

      The default when not specified here is to use "swig-error". See + Lib/exception.i for details.

      +

      20.8 Procedure documentation

      +

      If invoked with the command-line option -procdoc file +, SWIG creates documentation strings for the generated wrapper + functions, describing the procedure signature and return value, and + writes them to file. You need Guile 1.4 or later to make use + of the documentation files.

      +

      SWIG can generate documentation strings in three formats, which are + selected via the command-line option -procdocformat format +:

      +
        +
      • guile-1.4 (default): Generates a format suitable for + Guile 1.4.
        • +
      • plain: Generates a format suitable for Guile 1.4.1 and + later.
        • +
      • texinfo: Generates texinfo source, which must be run + through texinfo in order to get a format suitable for Guile 1.4.1 and + later.
        • +
      +

      You need to register the generated documentation file with Guile like + this:

      +
      +(use-modules (ice-9 documentation))
+(set! documentation-files 
+      (cons "file" documentation-files))
+
      +

      +

      Documentation strings can be configured using the Guile-specific + typemap argument doc. See Lib/guile/typemaps.i + for details.

      +

      20.9 Procedures with setters

      +

      For global variables, SWIG creates a single wrapper procedure ( +variable :optional value), which is used for both getting + and setting the value. For struct members, SWIG creates two wrapper + procedures (struct-member-get pointer) + and (struct-member-set pointer value).

      +

      If invoked with the command-line option -emit-setters ( +recommended), SWIG will additionally create procedures with + setters. For global variables, the procedure-with-setter +variable is created, so you can use (variable +) to get the value and (set! (variable) + value) to set it. For struct members, the + procedure-with-setter struct-member + is created, so you can use (struct-member + pointer) to get the value and (set! (struct +-member pointer) value) to set + it.

      +

      If invoked with the command-line option -only-setters, + SWIG will only create procedures with setters, i.e., for + struct members, the procedures (struct-member +-get pointer) and (struct-member-set pointer + value) are not generated.

      +

      20.10 GOOPS Proxy Classes

      +

      SWIG can also generate classes and generic functions for use with + Guile's Object-Oriented Programming System (GOOPS). GOOPS is a + sophisticated object system in the spirit of the Common Lisp Object + System (CLOS).

      +

      GOOPS support is only available with the new SCM interface (enabled + with the -scm command-line option of SWIG). To enable + GOOPS support, pass the -proxy argument to swig. This will + export the GOOPS wrapper definitions into the module.scm + file in the directory specified by -outdir or the current directory. + GOOPS support requires either passive or module linkage.

      +

      The generated file will contain definitions of GOOPS classes + mimicking the C++ class hierarchy.

      +

      Enabling GOOPS support implies -emit-setters.

      +

      If -emit-slot-accessors is also passed as an argument, + then the generated file will contain accessor methods for all the slots + in the classes and for global variables. The input class

      +
      +
      +  class Foo {
+    public:
+      Foo(int i) : a(i) {}
+      int a;
+      int getMultBy(int i) { return a * i; }
+      Foo getFooMultBy(int i) { return Foo(a * i); }
+  }; 
+  Foo getFooPlus(int i) { return Foo(a + i); }
+
      +
      +

      will produce (if -emit-slot-accessors is not passed as + a parameter)

      +
      +
      +(define-class <Foo> (<swig>)
+  (a #:allocation #:swig-virtual 
+     #:slot-ref primitive:Foo-a-get 
+     #:slot-set! primitive:Foo-a-set)
+  #:metaclass <swig-metaclass>
+  #:new-function primitive:new-Foo
+)
+(define-method (getMultBy (swig_smob <Foo>) i)
+  (primitive:Foo-getMultBy  (slot-ref swig_smob 'smob) i))
+(define-method (getFooMultBy (swig_smob <Foo>) i)
+  (make <Foo> #:init-smob (primitive:Foo-getFooMultBy  (slot-ref swig_smob 'smob) i)))
+
+(define-method (getFooPlus i)
+  (make <Foo> #:init-smob (primitive:getFooPlus i)))
+
+(export <Foo> getMultBy getFooMultBy getFooPlus )
+
      +
      +

      and will produce (if -emit-slot-accessors is passed as + a parameter)

      +
      +
      +(define-class <Foo> (<swig>)
+  (a #:allocation #:swig-virtual 
+     #:slot-ref primitive:Foo-a-get 
+     #:slot-set! primitive:Foo-a-set 
+     #:accessor a)
+  #:metaclass <swig-metaclass>
+  #:new-function primitive:new-Foo
+)
+(define-method (getMultBy (swig_smob <Foo>) i)
+  (primitive:Foo-getMultBy  (slot-ref swig_smob 'smob) i))
+(define-method (getFooMultBy (swig_smob <Foo>) i)
+  (make <Foo> #:init-smob (primitive:Foo-getFooMultBy  (slot-ref swig_smob 'smob) i)))
+
+(define-method (getFooPlus i)
+  (make <Foo> #:init-smob (primitive:getFooPlus i)))
+
+(export <Foo> a getMultBy getFooMultBy getFooPlus )
+
      +
      +

      which can then be used by this code

      +
      +
      +;; not using getters and setters
+(define foo (make <Foo> #:args '(45)))
+(slot-ref foo 'a)
+(slot-set! foo 'a 3)
+(getMultBy foo 4)
+(define foo2 (getFooMultBy foo 7))
+(slot-ref foo 'a)
+(slot-ref (getFooPlus foo 4) 'a)
+
+;; using getters and setters
+(define foo (make <Foo> #:args '(45)))
+(a foo)
+(set! (a foo) 5)
+(getMultBy foo 4)
+(a (getFooMultBy foo 7))
+
      +
      +

      Notice that constructor arguments are passed as a list after the +#:args keyword. Hopefully in the future the following will be + valid (make <Foo> #:a 5 #:b 4)

      +

      Also note that the order the declarations occur in the .i file make a + difference. For example,

      +
      +
      +%module test
+
+%{ #include "foo.h" %}
+
+%inline %{
+  int someFunc(Foo &a) {
+    ...
+  }
+%}
+
+%include "foo.h"
+
      +
      +

      This is a valid SWIG file it will work as you think it will for + primitive support, but the generated GOOPS file will be broken. Since + the someFunc definition is parsed by SWIG before all the + declarations in foo.h, the generated GOOPS file will contain the + definition of someFunc() before the definition of <Foo>. + The generated GOOPS file would look like

      +
      +
      +;;...
+
+(define-method (someFunc (swig_smob <Foo>))
+  (primitive:someFunc (slot-ref swig_smob 'smob)))
+
+;;...
+
+(define-class <Foo> (<swig>)
+  ;;...
+)
+
+;;...
+
      +
      +

      Notice that <Foo> is used before it is defined. The fix is to just + put the %import "foo.h" before the %inline + block.

      +

      20.10.1 Naming Issues

      +

      As you can see in the example above, there are potential naming + conflicts. The default exported accessor for the Foo::a + variable is named a. The name of the wrapper global + function is getFooPlus. If the -useclassprefix + option is passed to swig, the name of all accessors and member + functions will be prepended with the class name. So the accessor will + be called Foo-a and the member functions will be called +Foo-getMultBy. Also, if the -goopsprefix goops: + argument is passed to swig, every identifier will be prefixed by +goops:

      +

      Two guile-modules are created by SWIG. The first module contains the + primitive definitions of all the wrapped functions and variables, and + is located either in the _wrap.cxx file (with -Linkage module +) or in the scmstub file (if -Linkage passive -scmstub). + The name of this guile-module is the swig-module name (given on the + command line with the -module argument or with the %module directive) + concatenated with the string "-primitive". For example, if +%module Test is set in the swig interface file, the name of the + guile-module in the scmstub or -Linkage module will be +Test-primitive. Also, the scmstub file will be named +Test-primitive.scm. The string "primitive" can be changed by the +-primsuffix swig argument. So the same interface, with the +-primsuffix base will produce a module called Test-base +. The second generated guile-module contains all the GOOPS class + definitions and is located in a file named module.scm in the + directory specified with -outdir or the current directory. The name of + this guile-module is the name of the swig-module (given on the command + line or with the %module directive). In the previous + example, the GOOPS definitions will be in a file named Test.scm.

      +

      Because of the naming conflicts, you can't in general use both the +-primitive and the GOOPS guile-modules at the same time. To do + this, you need to rename the exported symbols from one or both + guile-modules. For example,

      +
      +
      +(use-modules ((Test-primitive) #:renamer (symbol-prefix-proc 'primitive:)))
+(use-modules ((Test) #:renamer (symbol-prefix-proc 'goops:)))
+
      +
      +

      TODO: Renaming class name prefixes?

      +

      20.10.2 Linking

      +

      The guile-modules generated above all need to be linked together. + GOOPS support requires either passive or module linkage. The exported + GOOPS guile-module will be the name of the swig-module and should be + located in a file called Module.scm. This should be installed on + the autoload path for guile, so that (use-modules (Package + Module)) will load everything needed. Thus, the top of the + GOOPS guile-module will contain code to load everything needed by the + interface (the shared library, the scmstub module, etc.). The +%goops directive inserts arbitrary code into the generated GOOPS + guile-module, and should be used to load the dependent libraries.

      +

      This breaks up into three cases

      +
        +
      • Passive Linkage without -scmstub: Note that this linkage + style has the potential for naming conflicts, since the primitive + exported function and variable names are not wrapped in a guile-module + and might conflict with names from the GOOPS guile-module (see above). + Pass the -goopsprefix argument to solve this problem. If the +-exportprimitive option is passed to SWIG the (export ...) + code that would be exported into the scmstub file is exported at the + bottom of the generated GOOPS guile-module. The %goops + directive should contain code to load the .so library.
        +
        +%goops %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %}
+
        +
        +

        Produces the following code at the top of the generated GOOPS + guile-module (with the -package my/modules -module foo + command line arguments)

        +
        +
        +(define-module (my modules foo))
+
+;; %goops directive goes here
+(load-extension "./foo.so" "scm_init_my_modules_foo_module") 
+
+(use-modules (oop goops) (Swig common))
+
        +
        • +
      • +

        Passive Linkage with -scmstub: Here, the name of the scmstub + file should be Module-primitive.scm (with primitive + replaced with whatever is given with the -primsuffix + argument. The code to load the .so library should be + located in the %scheme directive, which will then be added + to the scmstub file. Swig will automatically generate the line +(use-modules (Package Module-primitive)) into the + GOOPS guile-module. So if Module-primitive.scm is on the + autoload path for guile, the %goops directive can be + empty. Otherwise, the %goops directive should contain + whatever code is needed to load the Module-primitive.scm file + into guile.

        +
        +
        +%scheme %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %}
+// only include the following definition if (my modules foo) cannot
+// be loaded automatically
+%goops %{ 
+  (primitive-load "/path/to/foo-primitive.scm") 
+  (primitive-load "/path/to/Swig/common.scm")
+%}
+
        +
        +

        Produces the following code at the top of the generated GOOPS + guile-module

        +
        +
        +(define-module (my modules foo))
+
+;; %goops directive goes here (if any)
+(primitive-load "/path/to/foo-primitive.scm")
+(primitive-load "/path/to/Swig/common.scm")
+
+(use-modules (oop goops) (Swig common))
+(use-modules ((my modules foo-primitive) :renamer (symbol-prefix-proc
+                                                       'primitive:)))
+
+
        +
        • +
      • +

        Module Linkage: This is very similar to passive linkage with a + scmstub file. Swig will also automatically generate the line +(use-modules (Package Module-primitive)) into the + GOOPS guile-module. Again the %goops directive should + contain whatever code is needed to get that module loaded into guile.

        +
        +
        +%goops %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %}
+
        +
        +

        Produces the following code at the top of the generated GOOPS + guile-module

        +
        +
        +(define-module (my modules foo))
+
+;; %goops directive goes here (if any)
+(load-extension "./foo.so" "scm_init_my_modules_foo_module") 
+
+(use-modules (oop goops) (Swig common))
+(use-modules ((my modules foo-primitive) :renamer (symbol-prefix-proc
+                                                         'primitive:)))
+
+
        +
        • +
      +

      (Swig common): The generated GOOPS guile-module also imports + definitions from the (Swig common) guile-module. This module is + included with SWIG and should be installed by SWIG into the autoload + path for guile (based on the configure script and whatever arguments + are passed). If it is not, then the %goops directive also + needs to contain code to load the common.scm file into + guile. Also note that if you are trying to install the generated + wrappers on a computer without SWIG installed, you will need to include + the common.swg file along with the install.

      +

      Multiple Modules: Type dependencies between modules is + supported. For example, if mod1 includes definitions of + some classes, and mod2 includes some classes derived from + classes in mod1, the generated GOOPS file for mod2 + will declare the correct superclasses. The only problem is that since +mod2 uses symbols from mod1, the mod2 + GOOPS file must include a (use-modules (mod2)). Currently, + SWIG does not automatically export this line; it must be included in + the %goops directive of mod2. Maybe in the + future SWIG can detect dependencies and export this line. (how do other + language modules handle this problem?)

      +
      +

      21 SWIG and Java

      + + +
      + +
      + +

      This chapter describes SWIG's support of Java. It covers most SWIG + features, but certain low-level details are covered in less depth than + in earlier chapters.

      +

      21.1 Overview

      +

      The 100% Pure Java effort is a commendable concept, however in the + real world programmers often either need to re-use their existing code + or in some situations want to take advantage of Java but are forced + into using some native (C/C++) code. The Java extension to SWIG makes + it very easy to plumb in existing C/C++ code for access from Java, as + SWIG writes the Java Native Interface (JNI) code for you. It is + different to using the 'javah' tool as SWIG will wrap existing C/C++ + code, whereas javah takes 'native' Java function declarations and + creates C/C++ function prototypes. SWIG wraps C/C++ code using Java + proxy classes and is very useful if you want to have access to large + amounts of C/C++ code from Java. If only one or two JNI functions are + needed then using SWIG may be overkill. SWIG enables a Java program to + easily call into C/C++ code from Java. Historically, SWIG was not able + to generate any code to call into Java code from C++. However, SWIG now + supports full cross language polymorphism and code is generated to call + up from C++ to Java when wrapping C++ virtual methods.

      +

      Java is one of the few non-scripting language modules in SWIG. As + SWIG utilizes the type safety that the Java language offers, it takes a + somewhat different approach to that used for scripting languages. In + particular runtime type checking and the runtime library are not used + by Java. This should be borne in mind when reading the rest of the SWIG + documentation. This chapter on Java is relatively self contained and + will provide you with nearly everything you need for using SWIG and + Java. However, the "SWIG Basics" chapter will be a + useful read in conjunction with this one.

      +

      This chapter starts with a few practicalities on running SWIG and + compiling the generated code. If you are looking for the minimum amount + to read, have a look at the sections up to and including the +tour of basic C/C++ wrapping section which explains how to call the + various C/C++ code constructs from Java. Following this section are + details of the C/C++ code and Java classes that SWIG generates. Due to + the complexities of C and C++ there are different ways in which C/C++ + code could be wrapped and called from Java. SWIG is a powerful tool and + the rest of the chapter details how the default code wrapping can be + tailored. Various customisation tips and techniques using SWIG + directives are covered. The latter sections cover the advanced + techniques of using typemaps for complete control of the wrapping + process.

      +

      21.2 Preliminaries

      +

      SWIG 1.1 works with JDKs from JDK 1.1 to JDK1.4 (Java 2 SDK1.4) and + should also work with any later versions. Given the choice, you should + probably use the latest version of Sun's JDK. The SWIG Java module is + known to work using Sun's JVM on Solaris, Linux and the various + flavours of Microsoft Windows including Cygwin. The Kaffe JVM is known + to give a few problems and at the time of writing was not a fully + fledged JVM with full JNI support. The generated code is also known to + work on vxWorks using WindRiver's PJava 3.1. The best way to determine + whether your combination of operating system and JDK will work is to + test the examples and test-suite that comes with SWIG. Run make -k + check from the SWIG root directory after installing SWIG on Unix + systems.

      +

      The Java module requires your system to support shared libraries and + dynamic loading. This is the commonly used method to load JNI code so + your system will more than likely support this.

      +

      21.2.1 Running SWIG

      +

      Suppose that you defined a SWIG module such as the following:

      +
      +
      +/* File: example.i */
+%module test
+%{
+#include "stuff.h"
+%}
+int fact(int n);
+
      +
      +

      To build a Java module, run SWIG using the -java option :

      +
      +
      +%swig -java example.i
+
      +
      +

      If building C++, add the -c++ option:

      +
      +
      +$ swig -c++ -java example.i
+
      +
      +

      This creates two different files; a C/C++ source file +example_wrap.c or example_wrap.cxx and numerous Java + files. The generated C/C++ source file contains the JNI wrapper code + that needs to be compiled and linked with the rest of your C/C++ + application.

      +

      The name of the wrapper file is derived from the name of the input + file. For example, if the input file is example.i, the name of + the wrapper file is example_wrap.c. To change this, you can + use the -o option. It is also possible to change the +output directory that the Java files are generated into using +-outdir.

      +

      The module name, specified with %module, determines the + name of various generated classes as discussed +later. Note that the module name does not define a Java package and + by default, the generated Java classes do not have a Java package. The +-package option described below can specify a Java package name to + use.

      +

      The following sections have further practical examples and details + on how you might go about compiling and using the generated files.

      +

      21.2.2 Additional Commandline Options

      +

      The following table list the additional commandline options + available for the Java module. They can also be seen by using:

      +
      +
      +swig -java -help 
+
      +
      + + + + + + +
      Java specific options
      -nopgcppsuppress the premature garbage collection + prevention parameter
      -noproxygenerate the low-level functional interface + instead of proxy classes
      -package <name>set name of the Java package to <name>
      +

      Their use will become clearer by the time you have finished reading + this section on SWIG and Java.

      +

      21.2.3 Getting the right header + files

      +

      In order to compile the C/C++ wrappers, the compiler needs the +jni.h and jni_md.h header files which are part of the JDK. + They are usually in directories like this:

      +
      +
      +/usr/java/include
+/usr/java/include/<operating_system>
+
      +
      +

      The exact location may vary on your machine, but the above locations + are typical.

      +

      21.2.4 Compiling a dynamic module

      +

      The JNI code exists in a dynamic module or shared library (DLL on + Windows) and gets loaded by the JVM. To build a shared library file, + you need to compile your module in a manner similar to the following + (shown for Solaris):

      +
      +
      +$ swig -java example.i
+$ gcc -c example_wrap.c  -I/usr/java/include -I/usr/java/include/solaris
+$ ld -G example_wrap.o  -o libexample.so
+
      +
      +

      The exact commands for doing this vary from platform to platform. + However, SWIG tries to guess the right options when it is installed. + Therefore, you may want to start with one of the examples in the +Examples/java directory. If that doesn't work, you will need to + read the man-pages for your compiler and linker to get the right set of + options. You might also check the +SWIG Wiki for additional information. +JNI compilation is a useful reference for compiling on different + platforms.

      +

      Important +
      If you are going to use optimisations turned on with gcc (for + example -O2), ensure you also compile with -fno-strict-aliasing. The + GCC optimisations have become more aggressive from gcc-4.0 onwards and + will result in code that fails with strict aliasing optimisations + turned on. See the C/C++ to Java + typemaps section for more details.

      +

      The name of the shared library output file is important. If the name + of your SWIG module is "example", the name of the + corresponding shared library file should be "libexample.so" + (or equivalent depending on your machine, see +Dynamic linking problems for more information). The name of the + module is specified using the %module directive or -module + command line option.

      +

      21.2.5 Using your module

      +

      To load your shared native library module in Java, simply use Java's + System.loadLibrary method in a Java class:

      +
      +
      +// runme.java
+
+public class runme {
+  static {
+    System.loadLibrary("example");
+  }
+
+  public static void main(String argv[]) {
+    System.out.println(example.fact(4));
+  }
+}
+
      +
      +

      Compile all the Java files and run:

      +
      +
      +$ javac *.java
+$ java runme
+24
+$
+
      +
      +

      If it doesn't work have a look at the following section which + discusses problems loading the shared library.

      +

      21.2.6 Dynamic linking + problems

      +

      As shown in the previous section the code to load a native library + (shared library) is System.loadLibrary("name"). This can fail + with an UnsatisfiedLinkError exception and can be due to a number of + reasons.

      +

      You may get an exception similar to this:

      +
      +
      +$ java runme
+Exception in thread "main" java.lang.UnsatisfiedLinkError: no example in java.library.path
+        at java.lang.ClassLoader.loadLibrary(ClassLoader.java:1312)
+        at java.lang.Runtime.loadLibrary0(Runtime.java:749)
+        at java.lang.System.loadLibrary(System.java:820)
+        at runme.<clinit>(runme.java:5)
+
      +
      +

      The most common cause for this is an incorrect naming of the native + library for the name passed to the loadLibrary function. The + string passed to the loadLibrary function must not include the + file extension name in the string, that is .dll or .so. + The string must be name and not libname for all + platforms. On Windows the native library must then be called + name.dll and on most Unix systems it must be called libname.so +.

      +

      Another common reason for the native library not loading is because + it is not in your path. On Windows make sure the path + environment variable contains the path to the native library. On Unix + make sure that your LD_LIBRARY_PATH contains the path to the + native library. Adding paths to LD_LIBRARY_PATH can slow down + other programs on your system so you may want to consider alternative + approaches. For example you could recompile your native library with + extra path information using -rpath if you're using GNU, see + the GNU linker documentation (ld man page). You could use a + command such as ldconfig (Linux) or crle (Solaris) to + add additional search paths to the default system configuration (this + requires root access and you will need to read the man pages).

      +

      The native library will also not load if there are any unresolved + symbols in the compiled C/C++ code. The following exception is + indicative of this:

      +
      +
      +$ java runme
+Exception in thread "main" java.lang.UnsatisfiedLinkError: libexample.so: undefined
+symbol: fact
+        at java.lang.ClassLoader$NativeLibrary.load(Native Method)
+        at java.lang.ClassLoader.loadLibrary0(ClassLoader.java, Compiled Code)
+        at java.lang.ClassLoader.loadLibrary(ClassLoader.java, Compiled Code)
+        at java.lang.Runtime.loadLibrary0(Runtime.java, Compiled Code)
+        at java.lang.System.loadLibrary(System.java, Compiled Code)
+        at runme.<clinit>(runme.java:5)
+$
+
      +
      +

      This error usually indicates that you forgot to include some object + files or libraries in the linking of the native library file. Make sure + you compile both the SWIG wrapper file and the code you are wrapping + into the native library file. If you forget to compile and link in the + SWIG wrapper file into your native library file, you will get a message + similar to the following:

      +
      +
      +$ java runme
+Exception in thread "main" java.lang.UnsatisfiedLinkError: exampleJNI.gcd(II)I
+	at exampleJNI.gcd(Native Method)
+	at example.gcd(example.java:12)
+	at runme.main(runme.java:18)
+
      +
      +

      where gcd is the missing JNI function that SWIG generated + into the wrapper file. Also make sure you pass all of the required + libraries to the linker. The java -verbose:jni commandline + switch is also a great way to get more information on unresolved + symbols. One last piece of advice is to beware of the common faux pas + of having more than one native library version in your path.

      +

      In summary, ensure that you are using the correct C/C++ compiler and + linker combination and options for successful native library loading. + If you are using the examples that ship with SWIG, then the + Examples/Makefile must have these set up correctly for your system. The + SWIG installation package makes a best attempt at getting these correct + but does not get it right 100% of the time. The +SWIG Wiki also has some settings for commonly used compiler and + operating system combinations. The following section also contains some + C++ specific linking problems and solutions.

      +

      21.2.7 Compilation problems + and compiling with C++

      +

      On most machines, shared library files should be linked using the + C++ compiler. For example:

      +
      +
      +% swig -c++ -java example.i
+% g++ -c -fpic example.cxx
+% g++ -c -fpic example_wrap.cxx -I/usr/java/j2sdk1.4.1/include -I/usr/java/
+j2sdk1.4.1/include/linux
+% g++ -shared example.o example_wrap.o -o libexample.so
+
      +
      +

      In addition to this, you may need to include additional library + files to make it work. For example, if you are using the Sun C++ + compiler on Solaris, you often need to add an extra library -lCrun + like this:

      +
      +
      +% swig -c++ -java example.i
+% CC -c example.cxx
+% CC -c example_wrap.cxx -I/usr/java/include -I/usr/java/include/solaris
+% CC -G example.o example_wrap.o -L/opt/SUNWspro/lib -o libexample.so -lCrun
+
      +
      +

      If you aren't entirely sure about the linking for C++, you might + look at an existing C++ program. On many Unix machines, the ldd + command will list library dependencies. This should give you some clues + about what you might have to include when you link your shared library. + For example:

      +
      +
      +$ ldd swig
+        libstdc++-libc6.1-1.so.2 => /usr/lib/libstdc++-libc6.1-1.so.2 (0x40019000)
+        libm.so.6 => /lib/libm.so.6 (0x4005b000)
+        libc.so.6 => /lib/libc.so.6 (0x40077000)
+        /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
+$
+
      +
      +

      Finally make sure the version of JDK header files matches the + version of Java that you are running as incompatibilities could lead to + compilation problems or unpredictable behaviour.

      +

      21.2.8 Building on Windows

      +

      Building on Windows is roughly similar to the process used with + Unix. You will want to produce a DLL that can be loaded by the Java + Virtual Machine. This section covers the process of using SWIG with + Microsoft Visual C++ 6 although the procedure may be similar with other + compilers. In order for everything to work, you will need to have a JDK + installed on your machine in order to read the JNI header files.

      +

      21.2.8.1 Running SWIG from Visual Studio

      +

      If you are developing your application within Microsoft Visual + studio, SWIG can be invoked as a custom build option. The Examples\java + directory has a few Windows Examples + containing Visual Studio project (.dsp) files. The process to re-create + the project files for a C project are roughly:

      +
        +
      • Open up a new workspace and use the AppWizard to select a DLL + project.
        • +
      • Add both the SWIG interface file (the .i file), any supporting C + files, and the name of the wrapper file that will be created by SWIG + (ie. example_wrap.c). Don't worry if the wrapper file doesn't + exist yet--Visual Studio will keep a reference to it.
        • +
      • Select the SWIG interface file and go to the settings menu. Under + settings, select the "Custom Build" option.
        • +
      • Enter "SWIG" in the description field.
        • +
      • Enter "swig -java -o $(ProjDir)\$(InputName)_wrap.c $(InputPath) +" in the "Build command(s) field"
        • +
      • Enter "$(ProjDir)\$(InputName)_wrap.c" in the "Output + files(s) field".
        • +
      • Next, select the settings for the entire project and go to C/C++ tab + and select the Preprocessor category . Add the include directories to + the JNI header files under "Additional include directories", eg + "C:\jdk1.3\include,C:\jdk1.3\include\win32".
        • +
      • Next, select the settings for the entire project and go to Link tab + and select the General category. Set the name of the output file to + match the name of your Java module (ie. example.dll).
        • +
      • Next, select the example.c and example_wrap.c files and go to the + C/C++ tab and select the Precompiled Headers tab in the project + settings. Disabling precompiled headers for these files will overcome + any precompiled header errors while building.
        • +
      • Finally, add the java compilation as a post build rule in the + Post-build step tab in project settings, eg, "c:\jdk1.3\bin\javac + *.java"
        • +
      • Build your project.
        • +
      +

      Note: If using C++, choose a C++ suffix for the wrapper file, for + example example_wrap.cxx. Use _wrap.cxx instead of +_wrap.c in the instructions above and add -c++ when invoking swig.

      +

      Now, assuming all went well, SWIG will be automatically invoked when + you build your project. When doing a build, any changes made to the + interface file will result in SWIG being automatically invoked to + produce a new version of the wrapper file.

      +

      The Java classes that SWIG output should also be compiled into + .class files. To run the native code in the DLL (example.dll), make + sure that it is in your path then run your Java program which uses it, + as described in the previous section. If the library fails to load have + a look at Dynamic linking problems +.

      +

      21.2.8.2 Using NMAKE

      +

      Alternatively, a Makefile for use by NMAKE can be written. Make sure + the environment variables for MSVC++ are available and the MSVC++ tools + are in your path. Now, just write a short Makefile like this :

      +
      +
      +# Makefile for using SWIG and Java for C code
+
+SRCS          = example.c
+IFILE         = example
+INTERFACE     = $(IFILE).i
+WRAPFILE      = $(IFILE)_wrap.c
+
+# Location of the Visual C++ tools (32 bit assumed)
+
+TOOLS         = c:\msdev
+TARGET        = example.dll
+CC            = $(TOOLS)\bin\cl.exe
+LINK          = $(TOOLS)\bin\link.exe
+INCLUDE32     = -I$(TOOLS)\include
+MACHINE       = IX86
+
+# C Library needed to build a DLL
+
+DLLIBC        = msvcrt.lib oldnames.lib  
+
+# Windows libraries that are apparently needed
+WINLIB        = kernel32.lib advapi32.lib user32.lib gdi32.lib comdlg32.lib winspool.lib
+
+# Libraries common to all DLLs
+LIBS          = $(DLLIBC) $(WINLIB) 
+
+# Linker options
+LOPT      = -debug:full -debugtype:cv /NODEFAULTLIB /RELEASE /NOLOGO \
+             /MACHINE:$(MACHINE) -entry:_DllMainCRTStartup@12 -dll
+
+# C compiler flags
+
+CFLAGS        = /Z7 /Od /c /nologo
+JAVA_INCLUDE    = -ID:\jdk1.3\include -ID:\jdk1.3\include\win32
+
+java::
+	swig -java -o $(WRAPFILE) $(INTERFACE)
+	$(CC) $(CFLAGS) $(JAVA_INCLUDE) $(SRCS) $(WRAPFILE)
+	set LIB=$(TOOLS)\lib
+	$(LINK) $(LOPT) -out:example.dll $(LIBS) example.obj example_wrap.obj
+	javac *.java
+
      +
      +

      To build the DLL and compile the java code, run NMAKE (you may need + to run vcvars32 first). This is a pretty simplistic Makefile, + but hopefully its enough to get you started. Of course you may want to + make changes for it to work for C++ by adding in the -c++ command line + switch for swig and replacing .c with .cxx.

      +

      21.3 A tour of basic C/C++ wrapping

      +

      By default, SWIG attempts to build a natural Java interface to your + C/C++ code. Functions are wrapped as functions, classes are wrapped as + classes, variables are wrapped with JavaBean type getters and setters + and so forth. This section briefly covers the essential aspects of this + wrapping.

      +

      21.3.1 Modules, packages and + generated Java classes

      +

      The SWIG %module directive specifies the name of the Java + module. When you specify `%module example', the module name + determines the name of some of the generated files in the module. The + generated code consists of a module class file example.java +, an intermediary JNI class file, exampleJNI.java as + well as numerous other Java proxy class files. Each proxy class + is named after the structs, unions and classes you are wrapping. You + may also get a constants interface file if you are wrapping any + unnamed enumerations or constants, for example +exampleConstants.java. When choosing a module name, make sure you + don't use the same name as one of the generated proxy class files nor a + Java keyword. Sometimes a C/C++ type cannot be wrapped by a proxy + class, for example a pointer to a primitive type. In these situations a + type wrapper class is generated. Wrapping an enum generates an + enum class, either a proper Java enum or a Java class that + simulates the enums pattern. Details of all these generated classes + will unfold as you read this section.

      +

      The JNI (C/C++) code is generated into a file which also contains + the module name, for example example_wrap.cxx or +example_wrap.c. These C or C++ files complete the contents of the + module.

      +

      The generated Java classes can be placed into a Java package by + using the -package commandline option. This is often combined + with the -outdir to specify a package directory for generating + the Java files.

      +
      +
      +swig -java -package com.bloggs.swig -outdir com/bloggs/swig example.i
+
      +
      SWIG won't create the directory, so make sure it exists + beforehand. +

      21.3.2 Functions

      +

      There is no such thing as a global Java function so global C + functions are wrapped as static methods in the module class. For + example,

      +
      +
      +%module example
+int fact(int n);
+
+
      +
      +

      creates a static function that works exactly like you think it + might:

      +
      +
      +public class example {
+  public static int fact(int n) {
+    // makes call using JNI to the C function
+  }
+}
+
      +
      +

      The Java class example is the module class. The + function can be used as follows from Java:

      +
      +
      +System.out.println(example.fact(4));
+
      +
      +

      21.3.3 Global variables

      +

      C/C++ global variables are fully supported by SWIG. Java does not + allow the overriding of the dot operator so all variables are accessed + through getters and setters. Again because there is no such thing as a + Java global variable, access to C/C++ global variables is done through + static getter and setter functions in the module class.

      +
      +
      +// SWIG interface file with global variables
+%module example
+...
+%inline %{
+extern int My_variable;
+extern double density;
+%}
+...
+
      +
      +

      Now in Java :

      +
      +
      +// Print out value of a C global variable
+System.out.println("My_variable = " + example.getMy_variable());
+// Set the value of a C global variable
+example.setDensity(0.8442);
+
      +
      +

      The value returned by the getter will always be up to date even if + the value is changed in C. Note that the getters and setters produced + follow the JavaBean property design pattern. That is the first letter + of the variable name is capitalized and preceded with set or get. If + you have the misfortune of wrapping two variables that differ only in + the capitalization of their first letters, use %rename to change one of + the variable names. For example:

      +
      +
      +%rename Clash RenamedClash;
+float Clash;
+int clash;
+
      +
      +

      If a variable is declared as const, it is wrapped as a + read-only variable. That is only a getter is produced.

      +

      To make ordinary variables read-only, you can use the %immutable + directive. For example:

      +
      +
      +%{
+extern char *path;
+%}
+%immutable;
+extern char *path;
+%mutable;
+
      +
      +

      The %immutable directive stays in effect until it is + explicitly disabled or cleared using %mutable. See the +Creating read-only variables section for further details.

      +

      If you just want to make a specific variable immutable, supply a + declaration name. For example:

      +
      +
      +%{
+extern char *path;
+%}
+%immutable path;
+...
+extern char *path;      // Read-only (due to %immutable)
+
      +
      +

      21.3.4 Constants

      +

      C/C++ constants are wrapped as Java static final variables. To + create a constant, use #define or the %constant + directive. For example:

      +
      +
      +#define PI 3.14159
+#define VERSION "1.0"
+%constant int FOO = 42;
+%constant const char *path = "/usr/local";
+
      +
      +

      By default the generated static final variables are initialized by + making a JNI call to get their value. The constants are generated into + the constants interface and look like this:

      +
      +
      +public interface exampleConstants {
+  public final static double PI = exampleJNI.PI_get();
+  public final static String VERSION = exampleJNI.VERSION_get();
+  public final static int FOO = exampleJNI.FOO_get();
+  public final static String path = exampleJNI.path_get();
+}
+
      +
      +

      Note that SWIG has inferred the C type and used an appropriate Java + type that will fit the range of all possible values for the C type. By + default SWIG generates runtime constants. They are not + compiler constants that can, for example, be used in a switch + statement. This can be changed by using the %javaconst(flag) + directive. It works like all the other %feature + directives. The default is %javaconst(0). It is possible + to initialize all wrapped constants from pure Java code by placing a +%javaconst(1) before SWIG parses the constants. Putting it + at the top of your interface file would ensure this. Here is an + example:

      +
      +
      +%javaconst(1);
+%javaconst(0) BIG;
+%javaconst(0) LARGE;
+
+#define EXPRESSION (0x100+5)
+#define BIG 1000LL
+#define LARGE 2000ULL
+
      +
      +

      generates:

      +
      +
      +public interface exampleConstants {
+  public final static int EXPRESSION = (0x100+5);
+  public final static long BIG = exampleJNI.BIG_get();
+  public final static java.math.BigInteger LARGE = exampleJNI.LARGE_get();
+}
+
      +
      +

      Note that SWIG has inferred the C long long type from +BIG and used an appropriate Java type (long) as a Java +long is the smallest sized Java type that will take all possible + values for a C long long. Similarly for LARGE.

      +

      Be careful using the %javaconst(1) directive as not all C + code will compile as Java code. For example neither the 1000LL + value for BIG nor 2000ULL for LARGE above + would generate valid Java code. The example demonstrates how you can + target particular constants (BIG and LARGE) with +%javaconst. SWIG doesn't use %javaconst(1) as the default + as it tries to generate code that will always compile. However, using a + %javaconst(1) at the top of your interface file is strongly + recommended as the preferred compile time constants will be generated + and most C constants will compile as Java code and in any case the odd + constant that doesn't can be fixed using %javaconst(0).

      +

      There is an alternative directive which can be used for these rare + constant values that won't compile as Java code. This is the +%javaconstvalue(value) directive, where value is a Java + code replacement for the C constant and can be either a string or a + number. This is useful if you do not want to use either the parsed C + value nor a JNI call, such as when the C parsed value will not compile + as Java code and a compile time constant is required. The same example + demonstrates this:

      +
      +
      +%javaconst(1);
+%javaconstvalue("new java.math.BigInteger(\"2000\")") LARGE;
+%javaconstvalue(1000) BIG;
+
+#define EXPRESSION (0x100+5)
+#define BIG 1000LL
+#define LARGE 2000ULL
+
      +
      +

      Note the string quotes for "2000" are escaped. The + following is then generated:

      +
      +
      +public interface exampleConstants {
+  public final static int EXPRESSION = (0x100+5);
+  public final static long BIG = 1000;
+  public final static java.math.BigInteger LARGE = new java.math.BigInteger("2000");
+}
+
      +
      +

      Note: declarations declared as const are wrapped as + read-only variables and will be accessed using a getter as described in + the previous section. They are not wrapped as constants. The exception + to this rule are static const integral values defined within a + class/struct, where they are wrapped as constants, eg:.

      +
      +
      +struct Maths {
+  static const int FIVE = 5;
+};
+
      +
      +

      Compatibility Note: In SWIG-1.3.19 and earlier releases, the + constants were generated into the module class and the constants + interface didn't exist. Backwards compatibility is maintained as the + module class implements the constants interface (even though some + consider this type of interface implementation to be bad practice):

      +
      +
      +public class example implements exampleConstants {
+}
+
      +
      +

      You thus have the choice of accessing these constants from either + the module class or the constants interface, for example, +example.EXPRESSION or exampleConstants.EXPRESSION. Or if + you decide this practice isn't so bad and your own class implements +exampleConstants, you can of course just use EXPRESSION.

      +

      21.3.5 Enumerations

      +

      SWIG handles both named and unnamed (anonymous) enumerations. There + is a choice of approaches to wrapping named C/C++ enums. This is due to + historical reasons as SWIG's initial support for enums was limited and + Java did not originally have support for enums. Each approach has + advantages and disadvantages and it is important for the user to decide + which is the most appropriate solution. There are four approaches of + which the first is the default approach based on the so called Java + typesafe enum pattern. The second generates proper Java enums. The + final two approaches use simple integers for each enum item. Before + looking at the various approaches for wrapping named C/C++ enums, + anonymous enums are considered.

      +

      21.3.5.1 Anonymous enums

      +

      There is no name for anonymous enums and so they are handled like + constants. For example:

      +
      +
      +enum { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
+
      +
      +

      is wrapped into the constants interface, in a similar manner as + constants (see previous section):

      +
      +
      +public interface exampleConstants {
+  public final static int ALE = exampleJNI.ALE_get();
+  public final static int LAGER = exampleJNI.LAGER_get();
+  public final static int STOUT = exampleJNI.STOUT_get();
+  public final static int PILSNER = exampleJNI.PILSNER_get();
+  public final static int PILZ = exampleJNI.PILZ_get();
+}
+
      +
      +

      The %javaconst(flag) and %javaconstvalue(value) + directive introduced in the previous section on constants can also be + used with enums. As is the case for constants, the default is +%javaconst(0) as not all C values will compile as Java code. + However, it is strongly recommended to add in a %javaconst(1) + directive at the top of your interface file as it is only on very rare + occasions that this will produce code that won't compile under Java. + Using %javaconst(1) will ensure compile time constants are + generated, thereby allowing the enum values to be used in Java switch + statements. Example usage:

      +
      +
      +%javaconst(1);
+%javaconst(0) PILSNER;
+enum { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
+
      +
      +

      generates:

      +
      +
      +public interface exampleConstants {
+  public final static int ALE = 0;
+  public final static int LAGER = 10;
+  public final static int STOUT = LAGER + 1;
+  public final static int PILSNER = exampleJNI.PILSNER_get();
+  public final static int PILZ = PILSNER;
+}
+
      +
      +

      As in the case of constants, you can access them through either the + module class or the constants interface, for example, example.ALE + or exampleConstants.ALE.

      +

      21.3.5.2 Typesafe enums

      +

      This is the default approach to wrapping named enums. The typesafe + enum pattern is a relatively well known construct to work around the + lack of enums in versions of Java prior to JDK 1.5. It basically + defines a class for the enumeration and permits a limited number of + final static instances of the class. Each instance equates to an enum + item within the enumeration. The implementation is in the + "enumtypesafe.swg" file. Let's look at an example:

      +
      +
      +%include "enumtypesafe.swg" // optional as typesafe enums are the default
+enum Beverage { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
+
      +
      +

      will generate:

      +
      +
      +public final class Beverage {
+  public final static Beverage ALE = new Beverage("ALE");
+  public final static Beverage LAGER = new Beverage("LAGER", exampleJNI.LAGER_get());
+  public final static Beverage STOUT = new Beverage("STOUT");
+  public final static Beverage PILSNER = new Beverage("PILSNER");
+  public final static Beverage PILZ = new Beverage("PILZ", exampleJNI.PILZ_get());
+  [... additional support methods omitted for brevity ...]
+}
+
      +
      +

      See Typesafe enum classes to + see the omitted support methods. Note that the enum item with an + initializer (LAGER) is initialized with the enum value obtained via a + JNI call. However, as with anonymous enums and constants, use of the +%javaconst directive is strongly recommended to change this + behaviour:

      +
      +
      +%include "enumtypesafe.swg" // optional as typesafe enums are the default
+%javaconst(1);
+enum Beverage { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
+
      +
      +

      will generate:

      +
      +
      +public final class Beverage {
+  public final static Beverage ALE = new Beverage("ALE");
+  public final static Beverage LAGER = new Beverage("LAGER", 10);
+  public final static Beverage STOUT = new Beverage("STOUT");
+  public final static Beverage PILSNER = new Beverage("PILSNER");
+  public final static Beverage PILZ = new Beverage("PILZ", PILSNER);
+  [... additional support methods omitted for brevity ...]
+}
+
      +
      +

      The generated code is easier to read and more efficient as a true + constant is used instead of a JNI call. As is the case for constants, + the default is %javaconst(0) as not all C values will compile + as Java code. However, it is recommended to add in a %javaconst(1) + directive at the top of your interface file as it is only on very rare + occasions that this will produce code that won't compile under Java. + The %javaconstvalue(value) directive can also be used for + typesafe enums. Note that global enums are generated into a Java class + within whatever package you are using. C++ enums defined within a C++ + class are generated into a static final inner Java class within the + Java proxy class.

      +

      Typesafe enums have their advantages over using plain integers in + that they they can be used in a typesafe manner. However, there are + limitations. For example, they cannot be used in switch statements and + serialization is an issue. Please look at the following references for + further information: +Replace Enums with Classes in Effective Java Programming on + the Sun website, +Create enumerated constants in Java JavaWorld article, +Java Tip 133: More on typesafe enums and +Java Tip 122: Beware of Java typesafe enumerations JavaWorld tips.

      +

      Note that the syntax required for using typesafe enums is the same + as that for proper Java enums. This is useful during the period that a + project has to support legacy versions of Java. When upgrading to JDK + 1.5 or later, proper Java enums could be used instead, without users + having to change their code. The following section details proper Java + enum generation.

      +

      21.3.5.3 Proper Java enums

      +

      Proper Java enums were only introduced in JDK 1.5 so this approach + is only compatible with more recent versions of Java. Java enums have + been designed to overcome all the limitations of both typesafe and type + unsafe enums and should be the choice solution, provided older versions + of Java do not have to be supported. In this approach, each named C/C++ + enum is wrapped by a Java enum. Java enums, by default, do not support + enums with initializers. Java enums are in many respects similar to + Java classes in that they can be customised with additional methods. + SWIG takes advantage of this feature to facilitate wrapping C/C++ enums + that have initializers. In order to wrap all possible C/C++ enums using + proper Java enums, the "enums.swg" file must be used. Let's take a look + at an example.

      +
      +
      +%include "enums.swg"
+%javaconst(1);
+enum Beverage { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
+
      +
      +

      will generate:

      +
      +
      +public enum Beverage {
+  ALE,
+  LAGER(10),
+  STOUT,
+  PILSNER,
+  PILZ(PILSNER);
+  [... additional support methods omitted for brevity ...]
+}
+
      +
      +

      See Proper Java enum classes to + see the omitted support methods. The generated Java enum has numerous + additional methods to support enums with initializers, such as +LAGER above. Note that as with the typesafe enum pattern, enum + items with initializers are by default initialized with the enum value + obtained via a JNI call. However, this is not the case above as we have + used the recommended %javaconst(1) to avoid the JNI call. The +%javaconstvalue(value) directive covered in the +Constants section can also be used for proper Java enums.

      +

      The additional support methods need not be generated if none of the + enum items have initializers and this is covered later in the +Simpler Java enums for enums without initializers section.

      +

      21.3.5.4 Type unsafe enums

      +

      In this approach each enum item in a named enumeration is wrapped as + a static final integer in a class named after the C/C++ enum name. This + is a commonly used pattern in Java to simulate C/C++ enums, but it is + not typesafe. However, the main advantage over the typesafe enum + pattern is enum items can be used in switch statements. In order to use + this approach, the "enumtypeunsafe.swg" file must be used. Let's take a + look at an example.

      +
      +
      +%include "enumtypeunsafe.swg"
+%javaconst(1);
+enum Beverage { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
+
      +
      +

      will generate:

      +
      +
      +public final class Beverage {
+  public final static int ALE = 0;
+  public final static int LAGER = 10;
+  public final static int STOUT = LAGER + 1;
+  public final static int PILSNER = STOUT + 1;
+  public final static int PILZ = PILSNER;
+}
+
      +
      +

      As is the case previously, the default is %javaconst(0) as + not all C/C++ values will compile as Java code. However, again it is + recommended to add in a %javaconst(1) directive. and the +%javaconstvalue(value) directive covered in the +Constants section can also be used for type unsafe enums. Note that + global enums are generated into a Java class within whatever package + you are using. C++ enums defined within a C++ class are generated into + a static final inner Java class within the Java proxy class.

      +

      Note that unlike typesafe enums, this approach requires users to + mostly use different syntax compared with proper Java enums. Thus the + upgrade path to proper enums provided in JDK 1.5 is more painful.

      +

      21.3.5.5 Simple enums

      +

      This approach is similar to the type unsafe approach. Each enum item + is also wrapped as a static final integer. However, these integers are + not generated into a class named after the C/C++ enum. Instead, global + enums are generated into the constants interface. Also, enums defined + in a C++ class have their enum items generated directly into the Java + proxy class rather than an inner class within the Java proxy class. In + fact, this approach is effectively wrapping the enums as if they were + anonymous enums and the resulting code is as per +anonymous enums. The implementation is in the "enumsimple.swg" file.

      +

      Compatibility Note: SWIG-1.3.21 and earlier versions wrapped + all enums using this approach. The type unsafe approach is preferable + to this one and this simple approach is only included for backwards + compatibility with these earlier versions of SWIG.

      +

      21.3.6 Pointers

      +

      C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no + problem working with incomplete type information. Here is a rather + simple interface:

      +
      +
      +%module example
+
+FILE *fopen(const char *filename, const char *mode);
+int fputs(const char *, FILE *);
+int fclose(FILE *);
+
      +
      +

      When wrapped, you will be able to use the functions in a natural way + from Java. For example:

      +
      +
      +SWIGTYPE_p_FILE f = example.fopen("junk","w");
+example.fputs("Hello World\n", f);
+example.fclose(f);
+
      +
      +

      C pointers in the Java module are stored in a Java long and + cross the JNI boundary held within this 64 bit number. Many other SWIG + language modules use an encoding of the pointer in a string. These + scripting languages use the SWIG runtime type checker for dynamic type + checking as they do not support static type checking by a compiler. In + order to implement static type checking of pointers within Java, they + are wrapped by a simple Java class. In the example above the FILE * + pointer is wrapped with a type wrapper class called +SWIGTYPE_p_FILE.

      +

      Once obtained, a type wrapper object can be freely passed around to + different C functions that expect to receive an object of that type. + The only thing you can't do is dereference the pointer from Java. Of + course, that isn't much of a concern in this example.

      +

      As much as you might be inclined to modify a pointer value directly + from Java, don't. The value is not necessarily the same as the logical + memory address of the underlying object. The value will vary depending + on the native byte-ordering of the platform (i.e., big-endian vs. + little-endian). Most JVMs are 32 bit applications so any JNI code must + also be compiled as 32 bit. The net result is pointers in JNI code are + also 32 bits and are stored in the high order 4 bytes on big-endian + machines and in the low order 4 bytes on little-endian machines. By + design it is also not possible to manually cast a pointer to a new type + by using Java casts as it is particularly dangerous especially when + casting C++ objects. If you need to cast a pointer or change its value, + consider writing some helper functions instead. For example:

      +
      +
      +%inline %{
+/* C-style cast */
+Bar *FooToBar(Foo *f) {
+   return (Bar *) f;
+}
+
+/* C++-style cast */
+Foo *BarToFoo(Bar *b) {
+   return dynamic_cast<Foo*>(b);
+}
+
+Foo *IncrFoo(Foo *f, int i) {
+    return f+i;
+}
+%}
+
      +
      +

      Also, if working with C++, you should always try to use the new C++ + style casts. For example, in the above code, the C-style cast may + return a bogus result whereas as the C++-style cast will return a NULL + pointer if the conversion can't be performed.

      +

      21.3.7 Structures

      +

      If you wrap a C structure, it is wrapped by a Java class with + getters and setters for access to the member variables. For example,

      +
      +
      +struct Vector {
+	double x,y,z;
+};
+
+
      +
      +

      is used as follows:

      +
      +
      +Vector v = new Vector();
+v.setX(3.5);
+v.setY(7.2);
+double x = v.getX();
+double y = v.getY();
+
      +
      +

      The variable setters and getters are also based on the JavaBean + design pattern already covered under the Global variables section. + Similar access is provided for unions and the public data members of + C++ classes.

      +

      This object is actually an instance of a Java class that has been + wrapped around a pointer to the C structure. This instance doesn't + actually do anything--it just serves as a proxy. The pointer to the C + object is held in the Java proxy class in much the same way as pointers + are held by type wrapper classes. Further details about Java proxy + classes are covered a little later.

      +

      const members of a structure are read-only. Data members + can also be forced to be read-only using the %immutable + directive. For example:

      +
      +
      +struct Foo {
+   ...
+   %immutable;
+   int x;        /* Read-only members */
+   char *name;
+   %mutable;
+   ...
+};
+
      +
      +

      When char * members of a structure are wrapped, the + contents are assumed to be dynamically allocated using malloc + or new (depending on whether or not SWIG is run with the -c++ + option). When the structure member is set, the old contents will be + released and a new value created. If this is not the behavior you want, + you will have to use a typemap (described later).

      +

      If a structure contains arrays, access to those arrays is managed + through pointers. For example, consider this:

      +
      +
      +struct Bar {
+    int  x[16];
+};
+
      +
      +

      If accessed in Java, you will see behavior like this:

      +
      +
      +Bar b = new Bar();
+SWIGTYPE_p_int x = b.getX();
+
      +
      +

      This pointer can be passed around to functions that expect to + receive an int * (just like C). You can also set the value of + an array member using another pointer. For example:

      +
      +
      +Bar b = new Bar();
+SWIGTYPE_p_int x = b.getX();
+Bar c = new Bar();
+c.setX(x);                    // Copy contents of b.x to c.x
+
      +
      +

      For array assignment (setters not getters), SWIG copies the entire + contents of the array starting with the data pointed to by b.x +. In this example, 16 integers would be copied. Like C, SWIG makes no + assumptions about bounds checking---if you pass a bad pointer, you may + get a segmentation fault or access violation. The default wrapping + makes it hard to set or get just one element of the array and so array + access from Java is somewhat limited. This can be changed easily though + by using the approach outlined later in the +Wrapping C arrays with Java arrays and +Unbounded C Arrays sections.

      +

      When a member of a structure is itself a structure, it is handled as + a pointer. For example, suppose you have two structures like this:

      +
      +
      +struct Foo {
+   int a;
+};
+
+struct Bar {
+   Foo f;
+};
+
      +
      +

      Now, suppose that you access the f member of Bar + like this:

      +
      +
      +Bar b = new Bar();
+Foo x = b.getF();
+
      +
      +

      In this case, x is a pointer that points to the Foo + that is inside b. This is the same value as generated by this + C code:

      +
      +
      +Bar b;
+Foo *x = &b->f;       /* Points inside b */
+
      +
      +

      Because the pointer points inside the structure, you can modify the + contents and everything works just like you would expect. For example:

      +
      +
      +Bar b = new Bar();
+b.getF().setA(3);   // Modify b.f.a
+Foo x = b.getF();                   
+x.setA(3);          // Modify x.a - this is the same as b.f.a
+
      +
      +

      21.3.8 C++ classes

      +

      C++ classes are wrapped by Java classes as well. For example, if you + have this class,

      +
      +
      +class List {
+public:
+  List();
+  ~List();
+  int  search(char *item);
+  void insert(char *item);
+  void remove(char *item);
+  char *get(int n);
+  int  length;
+};
+
      +
      +

      you can use it in Java like this:

      +
      +
      +List l = new List();
+l.insert("Ale");
+l.insert("Stout");
+l.insert("Lager");
+String item = l.get(2);
+int length = l.getLength();
+
      +
      +

      Class data members are accessed in the same manner as C structures.

      +

      Static class members are unsurprisingly wrapped as static members of + the Java class:

      +
      +
      +class Spam {
+public:
+   static void foo();
+   static int bar;
+};
+
      +
      +

      The static members work like any other Java static member:

      +
      +
      +Spam.foo();
+int bar = Spam.getBar();
+
      +
      +

      21.3.9 C++ inheritance

      +

      SWIG is fully aware of issues related to C++ inheritance. Therefore, + if you have classes like this

      +
      +
      +class Foo {
+...
+};
+
+class Bar : public Foo {
+...
+};
+
      +
      +

      those classes are wrapped into a hierarchy of Java classes that + reflect the same inheritance structure:

      +
      +
      +Bar b = new Bar();
+Class c = b.getClass();
+System.out.println(c.getSuperclass().getName());
+
      +
      +

      will of course display:

      +
      +
      +Foo
+
      +
      +

      Furthermore, if you have functions like this

      +
      +
      +void spam(Foo *f);
+
      +
      +

      then the Java function spam() accepts instances of Foo + or instances of any other proxy classes derived from Foo.

      +

      Note that Java does not support multiple inheritance so any multiple + inheritance in the C++ code is not going to work. A warning is given + when multiple inheritance is detected and only the first base class is + used.

      +

      21.3.10 Pointers, references, + arrays and pass by value

      +

      In C++, there are many different ways a function might receive and + manipulate objects. For example:

      +
      +
      +void spam1(Foo *x);      // Pass by pointer
+void spam2(Foo &x);      // Pass by reference
+void spam3(Foo x);       // Pass by value
+void spam4(Foo x[]);     // Array of objects
+
      +
      +

      In Java, there is no detailed distinction like this--specifically, + there are only instances of classes. There are no pointers nor + references. Because of this, SWIG unifies all of these types together + in the wrapper code. For instance, if you actually had the above + functions, it is perfectly legal to do this from Java:

      +
      +
      +Foo f = new Foo();  // Create a Foo
+example.spam1(f);   // Ok. Pointer
+example.spam2(f);   // Ok. Reference
+example.spam3(f);   // Ok. Value.
+example.spam4(f);   // Ok. Array (1 element)
+
      +
      +

      Similar behavior occurs for return values. For example, if you had + functions like this,

      +
      +
      +Foo *spam5();
+Foo &spam6();
+Foo  spam7();
+
      +
      +

      then all three functions will return a pointer to some Foo + object. Since the third function (spam7) returns a value, newly + allocated memory is used to hold the result and a pointer is returned + (Java will release this memory when the returned object's finalizer is + run by the garbage collector).

      +

      21.3.10.1 Null pointers

      +

      Working with null pointers is easy. A Java null can be used + whenever a method expects a proxy class or typewrapper class. However, + it is not possible to pass null to C/C++ functions that take parameters + by value or by reference. If you try you will get a + NullPointerException.

      +
      +
      +example.spam1(null);   // Pointer - ok
+example.spam2(null);   // Reference - NullPointerException
+example.spam3(null);   // Value - NullPointerException
+example.spam4(null);   // Array - ok
+
      +
      +

      For spam1 and spam4 above the Java null + gets translated into a NULL pointer for passing to the C/C++ function. + The converse also occurs, that is, NULL pointers are translated into +null Java objects when returned from a C/C++ function.

      +

      21.3.11 C++ overloaded functions

      +

      C++ overloaded functions, methods, and constructors are mostly + supported by SWIG. For example, if you have two functions like this:

      +
      +
      +%module example
+
+void foo(int);
+void foo(char *c);
+
      +
      +

      You can use them in Java in a straightforward manner:

      +
      +
      +example.foo(3);           // foo(int)
+example.foo("Hello");     // foo(char *c)
+
      +
      +

      Similarly, if you have a class like this,

      +
      +
      +class Foo {
+public:
+    Foo();
+    Foo(const Foo &);
+    ...
+};
+
      +
      +

      you can write Java code like this:

      +
      +
      +Foo f = new Foo();        // Create a Foo
+Foo g = new Foo(f);       // Copy f
+
      +
      +

      Overloading support is not quite as flexible as in C++. Sometimes + there are methods that SWIG cannot disambiguate as there can be more + than one C++ type mapping onto a single Java type. For example:

      +
      +
      +void spam(int);
+void spam(unsigned short);
+
      +
      +

      Here both int and unsigned short map onto a Java int. Here is + another example:

      +
      +
      +void foo(Bar *b);
+void foo(Bar &b);
+
      +
      +

      If declarations such as these appear, you will get a warning message + like this:

      +
      +
      +example.i:12: Warning(515): Overloaded method spam(unsigned short) ignored.
+Method spam(int) at example.i:11 used.
+
      +
      +

      To fix this, you either need to either +rename or ignore one of the methods. For example:

      +
      +
      +%rename(spam_ushort) spam(unsigned short);
+...
+void spam(int);    
+void spam(unsigned short);   // Now renamed to spam_ushort
+
      +
      +

      or

      +
      +
      +%ignore spam(unsigned short);
+...
+void spam(int);    
+void spam(unsigned short);   // Ignored
+
      +
      +

      21.3.12 C++ default arguments

      +

      Any function with a default argument is wrapped by generating an + additional function for each argument that is defaulted. For example, + if we have the following C++:

      +
      +
      +%module example
+
+void defaults(double d=10.0, int i=0);
+
      +
      +

      The following methods are generated in the Java module class:

      +
      +
      +public class example {
+  public static void defaults(double d, int i) { ... }
+  public static void defaults(double d) { ... }
+  public static void defaults() { ... }
+}
+
      +
      +

      It is as if SWIG had parsed three separate overloaded methods. The + same approach is taken for static methods, constructors and member + methods.

      +

      Compatibility note: Versions of SWIG prior to SWIG-1.3.23 + wrapped these with a single wrapper method and so the default values + could not be taken advantage of from Java. Further details on default + arguments and how to restore this approach are given in the more + general Default arguments section.

      +

      21.3.13 C++ namespaces

      +

      SWIG is aware of C++ namespaces, but namespace names do not appear + in the module nor do namespaces result in a module that is broken up + into submodules or packages. For example, if you have a file like this,

      +
      +
      +%module example
+
+namespace foo {
+   int fact(int n);
+   struct Vector {
+       double x,y,z;
+   };
+};
+
      +
      +

      it works in Java as follows:

      +
      +
      +int f = example.fact(3);
+Vector v = new Vector();
+v.setX(3.4);
+double y = v.getY();
+
      +
      +

      If your program has more than one namespace, name conflicts (if any) + can be resolved using %rename For example:

      +
      +
      +%rename(Bar_spam) Bar::spam;
+
+namespace Foo {
+    int spam();
+}
+
+namespace Bar {
+    int spam();
+}
+
      +
      +

      If you have more than one namespace and you want to keep their + symbols separate, consider wrapping them as separate SWIG modules. Each + SWIG module can be placed into a separate package.

      +

      21.3.14 C++ templates

      +

      C++ templates don't present a huge problem for SWIG. However, in + order to create wrappers, you have to tell SWIG to create wrappers for + a particular template instantiation. To do this, you use the +%template directive. For example:

      +
      +
      +%module example
+%{
+#include <utility>
+%}
+
+template<class T1, class T2>
+struct pair {
+   typedef T1 first_type;
+   typedef T2 second_type;
+   T1 first;
+   T2 second;
+   pair();
+   pair(const T1&, const T2&);
+  ~pair();
+};
+
+%template(pairii) pair<int,int>;
+
      +
      +

      In Java:

      +
      +
      +pairii p = new pairii(3,4);
+int first = p.getFirst();
+int second = p.getSecond();
+
      +
      +

      Obviously, there is more to template wrapping than shown in this + example. More details can be found in the SWIG and + C++ chapter.

      +

      21.3.15 C++ Smart Pointers

      +

      In certain C++ programs, it is common to use classes that have been + wrapped by so-called "smart pointers." Generally, this involves the use + of a template class that implements operator->() like this:

      +
      +
      +template<class T> class SmartPtr {
+   ...
+   T *operator->();
+   ...
+}
+
      +
      +

      Then, if you have a class like this,

      +
      +
      +class Foo {
+public:
+     int x;
+     int bar();
+};
+
      +
      +

      A smart pointer would be used in C++ as follows:

      +
      +
      +SmartPtr<Foo> p = CreateFoo();   // Created somehow (not shown)
+...
+p->x = 3;                        // Foo::x
+int y = p->bar();                // Foo::bar
+
      +
      +

      To wrap this in Java, simply tell SWIG about the SmartPtr + class and the low-level Foo object. Make sure you instantiate +SmartPtr using %template if necessary. For example:

      +
      +
      +%module example
+...
+%template(SmartPtrFoo) SmartPtr<Foo>;
+...
+
      +
      +

      Now, in Java, everything should just "work":

      +
      +
      +SmartPtrFoo p = example.CreateFoo(); // Create a smart-pointer somehow
+p.setX(3);                           // Foo::x
+int y = p.bar();                     // Foo::bar
+
      +
      +

      If you ever need to access the underlying pointer returned by +operator->() itself, simply use the __deref__() method. + For example:

      +
      +
      +Foo f = p.__deref__();               // Returns underlying Foo *
+
      +
      +

      21.4 Further details on the generated + Java classes

      +

      In the previous section, a high-level view of Java wrapping was + presented. A key component of this wrapping is that structures and + classes are wrapped by Java proxy classes and type wrapper classes are + used in situations where no proxies are generated. This provides a very + natural, type safe Java interface to the C/C++ code and fits in with + the Java programming paradigm. However, a number of low-level details + were omitted. This section provides a brief overview of how the proxy + classes work and then covers the type wrapper classes. Finally enum + classes are covered. First, the crucial intermediary JNI class is + considered.

      +

      21.4.1 The intermediary JNI class

      +

      In the "SWIG basics" and +"SWIG and C++" chapters, details of low-level structure and class + wrapping are described. To summarize those chapters, if you have a + global function and class like this

      +
      +
      +class Foo {
+public:
+     int x;
+     int spam(int num, Foo* foo);
+};
+void egg(Foo* chips);
+
      +
      +

      then SWIG transforms the class into a set of low-level procedural + wrappers. These procedural wrappers essentially perform the equivalent + of this C++ code:

      +
      +
      +Foo *new_Foo() {
+    return new Foo();
+}
+void delete_Foo(Foo *f) {
+    delete f;
+}
+int Foo_x_get(Foo *f) {
+    return f->x;
+}
+void Foo_x_set(Foo *f, int value) {
+    f->x = value;
+}
+int Foo_spam(Foo *f, int num, Foo* foo) {
+    return f->spam(num, foo);
+}
+
      +
      +

      These procedural function names don't actually exist, but their + functionality appears inside the generated JNI functions. The JNI + functions have to follow a particular naming convention so the function + names are actually:

      +
      +
      +SWIGEXPORT jlong JNICALL Java_exampleJNI_new_1Foo(JNIEnv *jenv, jclass jcls);
+SWIGEXPORT void JNICALL Java_exampleJNI_delete_1Foo(JNIEnv *jenv, jclass jcls,
+                                                    jlong jarg1);
+SWIGEXPORT void JNICALL Java_exampleJNI_Foo_1x_1set(JNIEnv *jenv, jclass jcls,
+                                                    jlong jarg1, jobject jarg1_, jint jarg2);
+SWIGEXPORT jint JNICALL Java_exampleJNI_Foo_1x_1get(JNIEnv *jenv, jclass jcls,
+                                                    jlong jarg1, jobject jarg1_);
+SWIGEXPORT jint JNICALL Java_exampleJNI_Foo_1spam(JNIEnv *jenv, jclass jcls,
+                                                  jlong jarg1, jobject jarg1_, jint jarg2,
+                                                  jlong jarg3, jobject jarg3_);
+SWIGEXPORT void JNICALL Java_exampleJNI_egg(JNIEnv *jenv, jclass jcls,
+                                            jlong jarg1, jobject jarg1_);
+
      +
      +

      For every JNI C function there has to be a static native Java + function. These appear in the intermediary JNI class:

      +
      +
      +class exampleJNI {
+  public final static native long new_Foo();
+  public final static native void delete_Foo(long jarg1);
+  public final static native void Foo_x_set(long jarg1, Foo jarg1_, int jarg2);
+  public final static native int Foo_x_get(long jarg1, Foo jarg1_);
+  public final static native int Foo_spam(long jarg1, Foo jarg1_, int jarg2,
+                                          long jarg3, Foo jarg3_);
+  public final static native void egg(long jarg1, Foo jarg1_);
+}
+
      +
      +

      This class contains the complete Java - C/C++ interface so all + function calls go via this class. As this class acts as a go-between + for all JNI calls to C/C++ code from the Java +proxy classes, type wrapper classes + and module class, it is known as the + intermediary JNI class.

      +

      You may notice that SWIG uses a Java long wherever a pointer or + class object needs to be marshalled across the Java-C/C++ boundary. + This approach leads to minimal JNI code which makes for better + performance as JNI code involves a lot of string manipulation. SWIG + favours generating Java code over JNI code as Java code is compiled + into byte code and avoids the costly string operations needed in JNI + code. This approach has a downside though as the proxy class might get + collected before the native method has completed. You might notice + above that there is an additional parameters with a underscore postfix, + eg jarg1_. These are added in order to prevent +premature garbage collection when marshalling proxy classes.

      +

      The functions in the intermediary JNI class cannot be accessed + outside of its package. Access to them is gained through the module + class for globals otherwise the appropriate proxy class.

      + +

      The name of the intermediary JNI class can be changed from its + default, that is, the module name with JNI appended after it. The + module directive attribute jniclassname is used to achieve + this:

      +
      +
      +%module (jniclassname="name") modulename
+
      +
      +

      If name is the same as modulename then the module + class name gets changed from modulename to +modulenameModule.

      +

      21.4.1.1 The intermediary JNI class + pragmas

      +

      The intermediary JNI class can be tailored through the use of + pragmas, but is not commonly done. The pragmas for this class are:

      + + + + + + + + +
      PragmaDescription
      jniclassbaseBase class for the intermediary JNI class
      jniclassclassmodifiersClass modifiers and class type + for the intermediary JNI class
      jniclasscodeJava code is copied verbatim into the + intermediary JNI class
      jniclassimportsJava code, usually one or more import + statements, placed before the intermediary JNI class definition
      jniclassinterfacesComma separated interface classes for + the intermediary JNI class
      +

      The pragma code appears in the generated intermediary JNI class + where you would expect:

      +
      +
      +[ jniclassimports pragma ]
+[ jniclassclassmodifiers pragma ] jniclassname extends [ jniclassbase pragma ]
+                                          implements [ jniclassinterfaces pragma ] {
+[ jniclasscode pragma ]
+... SWIG generated native methods ...
+}
+
      +
      +

      The jniclasscode pragma is quite useful for adding in a + static block for loading the shared library / dynamic link library and + demonstrates how pragmas work:

      +
      +
      +%pragma(java) jniclasscode=%{
+  static {
+    try {
+        System.loadLibrary("example");
+    } catch (UnsatisfiedLinkError e) {
+      System.err.println("Native code library failed to load. \n" + e);
+      System.exit(1);
+    }
+  }
+%}
+
      +
      +

      Pragmas will take either "" or %{ %} as + delimiters. For example, let's change the intermediary JNI class access + to public.

      +
      +
      +%pragma(java) jniclassclassmodifiers="public class"
+
      +
      +

      All the methods in the intermediary JNI class will then be callable + outside of the package as the method modifiers are public by default.

      +

      21.4.2 The Java module class

      +

      All global functions and variable getters/setters appear in the + module class. For our example, there is just one function:

      +
      +
      +public class example {
+  public static void egg(Foo chips) {
+    exampleJNI.egg(Foo.getCPtr(chips), chips);
+  }
+}
+
      +
      +

      The module class is necessary as there is no such thing as a global + in Java so all the C globals are put into this class. They are + generated as static functions and so must be accessed as such by using + the module name in the static function call:

      +
      +
      +example.egg(new Foo());
+
      +
      +

      The primary reason for having the module class wrapping the calls in + the intermediary JNI class is to implement static type checking. In + this case only a Foo can be passed to the egg + function, whereas any long can be passed to the egg + function in the intermediary JNI class.

      +

      21.4.2.1 The Java module class + pragmas

      +

      The module class can be tailored through the use of pragmas, in the + same manner as the intermediary JNI class. The pragmas are similarly + named and are used in the same way. The complete list follows:

      + + + + + + + +
      PragmaDescription
      modulebaseBase class for the module class
      moduleclassmodifiersClass modifiers and class type for + the module class
      modulecodeJava code is copied verbatim into the module + class
      moduleimportsJava code, usually one or more import + statements, placed before the module class definition
      moduleinterfacesComma separated interface classes for + the module class
      +

      The pragma code appears in the generated module class like this:

      +
      +
      +[ moduleimports pragma ]
+[ modulemodifiers pragma ] modulename extends [ modulebase pragma ]
+                                      implements [ moduleinterfaces pragma ] {
+[ modulecode pragma ]
+... SWIG generated wrapper functions ...
+}
+
      +
      +

      See The intermediary JNI class pragmas + section for further details on using pragmas.

      +

      21.4.3 Java proxy classes

      +

      A Java proxy class is generated for each structure, union or C++ + class that is wrapped. Proxy classes have also been called +peer classes. The default proxy class for our previous example looks + like this:

      +
      +
      +public class Foo {
+  private long swigCPtr;
+  protected boolean swigCMemOwn;
+
+  protected Foo(long cPtr, boolean cMemoryOwn) {
+    swigCMemOwn = cMemoryOwn;
+    swigCPtr = cPtr;
+  }
+
+  protected static long getCPtr(Foo obj) {
+    return (obj == null) ? 0 : obj.swigCPtr;
+  }
+
+  protected void finalize() {
+    delete();
+  }
+
+  public synchronized void delete() {
+    if(swigCPtr != 0 && swigCMemOwn) {
+      swigCMemOwn = false;
+      exampleJNI.delete_Foo(swigCPtr);
+    }
+    swigCPtr = 0;
+  }
+
+  public void setX(int value) {
+    exampleJNI.Foo_x_set(swigCPtr, this, value);
+  }
+
+  public int getX() {
+    return exampleJNI.Foo_x_get(swigCPtr, this);
+  }
+
+  public int spam(int num, Foo foo) {
+    return exampleJNI.Foo_spam(swigCPtr, this, num, Foo.getCPtr(foo), foo);
+  }
+
+  public Foo() {
+    this(exampleJNI.new_Foo(), true);
+  }
+
+}
+
      +
      +

      This class merely holds a pointer to the underlying C++ object ( +swigCPtr). It also contains all the methods in the C++ class it is + proxying plus getters and setters for public member variables. These + functions call the native methods in the intermediary JNI class. The + advantage of having this extra layer is the type safety that the proxy + class functions offer. It adds static type checking which leads to + fewer surprises at runtime. For example, you can see that if you + attempt to use the spam() function it will only compile when + the parameters passed are an int and a Foo. From a + user's point of view, it makes the class work as if it were a Java + class:

      +
      +
      +Foo f = new Foo();
+f.setX(3);
+int y = f.spam(5, new Foo());
+
      +
      +

      21.4.3.1 Memory management

      +

      Each proxy class has an ownership flag swigCMemOwn. The + value of this flag determines who is responsible for deleting the + underlying C++ object. If set to true, the proxy class's + finalizer will destroy the C++ object when the proxy class is garbage + collected. If set to false, then the destruction of the proxy class has + no effect on the C++ object.

      +

      When an object is created by a constructor or returned by value, + Java automatically takes ownership of the result. On the other hand, + when pointers or references are returned to Java, there is often no way + to know where they came from. Therefore, the ownership is set to false. + For example:

      +
      +
      +class Foo {
+public:
+    Foo();
+    Foo bar1();
+    Foo &bar2();
+    Foo *bar2();
+};
+
      +
      +

      In Java:

      +
      +
      +Foo f = new Foo();   //  f.swigCMemOwn = true
+Foo f1 = f.bar1();   // f1.swigCMemOwn = true
+Foo f2 = f.bar2();   // f2.swigCMemOwn = false
+Foo f3 = f.bar3();   // f3.swigCMemOwn = false
+
      +
      +

      This behavior for pointers and references is especially important + for classes that act as containers. For example, if a method returns a + pointer to an object that is contained inside another object, you + definitely don't want Java to assume ownership and destroy it!

      +

      For the most part, memory management issues remain hidden. However, + there are situations where you might have to manually change the + ownership of an object. For instance, consider code like this:

      +
      +
      +class Obj {};
+class Node {
+   Obj *value;
+public:
+   void set_value(Obj *v) { value = v; }
+};
+
      +
      +

      Now, consider the following Java code:

      +
      +
      +Node n = new Node();    // Create a node
+{
+  Obj o = new Obj();    // Create an object
+  n.set_value(o);       // Set value
+}                       // o goes out of scope
+
      +
      +

      In this case, the Node n is holding a reference to o + internally. However, SWIG has no way to know that this has occurred. + The Java proxy class still thinks that it has ownership of o. + As o has gone out of scope, it could be garbage collected in + which case the C++ destructor will be invoked and n will then + be holding a stale-pointer to o. If you're lucky, you will + only get a segmentation fault.

      +

      To work around this, the ownership flag of o needs changing + to false. The ownership flag is a private member variable of + the proxy class so this is not possible without some customization of + the proxy class. This can be achieved by using a typemap to customise + the proxy class with pure Java code as detailed later in the section on + Java typemaps.

      +

      Sometimes a function will create memory and return a pointer to a + newly allocated object. SWIG has no way of knowing this so by default + the proxy class does not manage the returned object. However, you can + tell the proxy class to manage the memory if you specify the +%newobject directive. Consider:

      +
      +
      +class Obj {...};
+class Factory {
+public:
+    static Obj *createObj() { return new Obj(); }
+};
+
      +
      +

      If we call the factory function, then we have to manually delete the + memory:

      +
      +
      +Obj obj = Factory.createObj();   // obj.swigCMemOwn = false
+...
+obj.delete();
+
      +
      +

      Now add in the %newobject directive:

      +
      +
      +%newobject Factory::createObj();
+
+class Obj {...};
+class Factory {
+public:
+    static Obj *createObj() { return new Obj(); }
+};
+
      +
      +

      A call to delete() is no longer necessary as the garbage + collector will make the C++ destructor call because swigCMemOwn + is now true.

      +
      +
      +Obj obj = Factory.createObj();   // obj.swigCMemOwn = true;
+...
+
      +
      +

      Some memory management issues are quite tricky to fix and may only + be noticeable after using for a long time. One such issue is premature + garbage collection of an object created from Java and resultant usage + from C++ code. The section on typemap examples cover two such + scenarios, Memory management + for objects passed to the C++ layer and +Memory management when returning references to member variables

      +

      21.4.3.2 Inheritance

      +

      Java proxy classes will mirror C++ inheritance chains. For example, + given the base class Base and its derived class Derived +:

      +
      +
      +class Base {
+public:
+  virtual double foo();
+};
+
+class Derived : public Base {
+public:
+  virtual double foo();
+};
+
      +
      +

      The base class is generated much like any other proxy class seen so + far:

      +
      +
      +public class Base {
+  private long swigCPtr;
+  protected boolean swigCMemOwn;
+
+  protected Base(long cPtr, boolean cMemoryOwn) {
+    swigCMemOwn = cMemoryOwn;
+    swigCPtr = cPtr;
+  }
+
+  protected static long getCPtr(Base obj) {
+    return (obj == null) ? 0 : obj.swigCPtr;
+  }
+
+  protected void finalize() {
+    delete();
+  }
+
+  public synchronized void delete() {
+    if(swigCPtr != 0 && swigCMemOwn) {
+      swigCMemOwn = false;
+      exampleJNI.delete_Base(swigCPtr);
+    }
+    swigCPtr = 0;
+  }
+
+  public double foo() {
+    return exampleJNI.Base_foo(swigCPtr, this);
+  }
+
+  public Base() {
+    this(exampleJNI.new_Base(), true);
+  }
+
+}
+
      +
      +

      The Derived class extends Base mirroring the C++ + class inheritance hierarchy.

      +
      +
      +public class Derived extends Base {
+  private long swigCPtr;
+
+  protected Derived(long cPtr, boolean cMemoryOwn) {
+    super(exampleJNI.SWIGDerivedUpcast(cPtr), cMemoryOwn);
+    swigCPtr = cPtr;
+  }
+
+  protected static long getCPtr(Derived obj) {
+    return (obj == null) ? 0 : obj.swigCPtr;
+  }
+
+  protected void finalize() {
+    delete();
+  }
+
+  public synchronized void delete() {
+    if(swigCPtr != 0 && swigCMemOwn) {
+      swigCMemOwn = false;
+      exampleJNI.delete_Derived(swigCPtr);
+    }
+    swigCPtr = 0;
+    super.delete();
+  }
+
+  public double foo() {
+    return exampleJNI.Derived_foo(swigCPtr, this);
+  }
+
+  public Derived() {
+    this(exampleJNI.new_Derived(), true);
+  }
+
+}
+
      +
      +

      Note the memory ownership is controlled by the base class. However + each class in the inheritance hierarchy has its own pointer value which + is obtained during construction. The SWIGDerivedUpcast() call + converts the pointer from a Derived * to a Base *. + This is a necessity as C++ compilers are free to implement pointers in + the inheritance hierarchy with different values.

      +

      It is of course possible to extend Base using your own Java + classes. If Derived is provided by the C++ code, you could for + example add in a pure Java class Extended derived from +Base. There is a caveat and that is any C++ code will not know + about your pure Java class Extended so this type of derivation + is restricted. However, true cross language polymorphism can be + achieved using the directors feature.

      +

      21.4.3.3 Proxy classes and garbage + collection

      +

      By default each proxy class has a delete() and a +finalize() method. The finalize() method calls +delete() which frees any malloc'd memory for wrapped C structs or + calls the C++ class destructors. The idea is for delete() to + be called when you have finished with the C/C++ object. Ideally you + need not call delete(), but rather leave it to the garbage + collector to call it from the finalizer. When a program exits, the + garbage collector does not guarantee to call all finalizers. An insight + into the reasoning behind this can be obtained from +Hans Boehm's Destructors, Finalizers, and Synchronization paper. + Depending on what the finalizers do and which operating system you use, + this may or may not be a problem.

      +

      If the delete() call into JNI code is just for memory + handling, there is not a problem when run on most operating systems, + for example Windows and Unix. Say your JNI code creates memory on the + heap which your finalizers should clean up, the finalizers may or may + not be called before the program exits. In Windows and Unix all memory + that a process uses is returned to the system on exit, so this isn't a + problem. This is not the case in some operating systems like vxWorks. + If however, your finalizer calls into JNI code invoking the C++ + destructor which in turn releases a TCP/IP socket for example, there is + no guarantee that it will be released. Note that with long running + programs the garbage collector will eventually run, thereby calling any + unreferenced object's finalizers.

      +

      Some not so ideal solutions are:

      +
        +
      1. +

        Call the System.runFinalizersOnExit(true) or +Runtime.getRuntime().runFinalizersOnExit(true) to ensure the + finalizers are called before the program exits. The catch is that this + is a deprecated function call as the documentation says:

        +
        This method is inherently unsafe. It may result in + finalizers being called on live objects while other threads are + concurrently manipulating those objects, resulting in erratic behavior + or deadlock.
        +

        In many cases you will be lucky and find that it works, but it is not + to be advocated. Have a look at Sun's + Java web site and search for runFinalizersOnExit.

        +
        2. +
      2. +

        From jdk1.3 onwards a new function, addShutdownHook(), was + introduced which is guaranteed to be called when your program exits. + You can encourage the garbage collector to call the finalizers, for + example, add this static block to the class that has the main() + function:

        +
        +
        +  static {
+    Runtime.getRuntime().addShutdownHook( 
+      new Thread() {
+        public void run() { System.gc(); System.runFinalization(); }
+      }
+    );
+  }
+
        +
        +

        Although this usually works, the documentation doesn't guarantee that + runFinalization() will actually call the finalizers. As the + the shutdown hook is guaranteed you could also make a JNI call to clean + up any resources that are being tracked by the C/C++ code.

        +
        3. +
      3. +

        Call the delete() function manually which will immediately + invoke the C++ destructor. As a suggestion it may be a good idea to set + the object to null so that should the object be inadvertently used + again a Java null pointer exception is thrown, the alternative would + crash the JVM by using a null C pointer. For example given a SWIG + generated class A:

        +
        +
        +A myA = new A();
+// use myA ...
+myA.delete();
+// any use of myA here would crash the JVM 
+myA=null;
+// any use of myA here would cause a Java null pointer exception to be thrown
+
        +
        +

        The SWIG generated code ensures that the memory is not deleted + twice, in the event the finalizers get called in addition to the manual + delete() call.

        +
        4. +
      4. +

        Write your own object manager in Java. You could derive all SWIG + classes from a single base class which could track which objects have + had their finalizers run, then call the rest of them on program + termination. The section on Java typemaps + details how to specify a pure Java base class.

        +
        5. +
      +

      See the How to + Handle Java Finalization's Memory-Retention Issues article for + alternative approaches to managing memory by avoiding finalizers + altogether.

      +

      21.4.3.4 The premature garbage collection + prevention parameter for proxy class marshalling

      +

      As covered earlier, the C/C++ struct/class pointer is stored in the + proxy class as a Java long and when needed is passed into the native + method where it is cast into the appropriate type. This approach + provides very fast marshalling but could be susceptible to premature + garbage collection. Consider the following C++ code:

      +
      +
      +class Wibble {
+};
+void wobble(Wibble &w);
+
      +
      +

      The module class contains the Java wrapper for the global wobble + method:

      +
      +
      +public class example {
+  ...
+  public static void wobble(Wibble w) {
+    exampleJNI.wobble(Wibble.getCPtr(w), w);
+  }
+}
+
      +
      +

      where example is the name of the module. All native methods + go through the intermediary class which has the native method declared + as such:

      +
      +
      +public class exampleJNI {
+  ...
+  public final static native void wobble(long jarg1, Wibble jarg1_);
+}
+
      +
      +

      The second parameter, jarg1_, is the premature garbage + collection prevention parameter and is added to the native method + parameter list whenever a C/C++ struct or class is marshalled as a Java + long. In order to understand why, consider the alternative where the + intermediary class method is declared without the additional parameter:

      +
      +
      +public class exampleJNI {
+  ...
+  public final static native void wobble(long jarg1);
+}
+
      +
      +

      and the following simple call to wobble:

      +
      +
      +{
+  Wibble w = new Wibble();
+  example.wobble(w);
+}
+
      +
      +

      The hotspot compiler effectively sees something like:

      +
      +
      +{
+  Wibble w = new Wibble();
+  long w_ptr = Wibble.getCPtr(w);
+  // w is no longer reachable
+  exampleJNI.wobble(w_ptr);
+}
+
      +
      +

      The Wibble object is no longer reachable after the point + shown as in this bit of code, the Wibble object is not + referenced again after this point. This means that it is a candidate + for garbage collection. Should wobble be a long running + method, it is quite likely that the finalizer for the Wibble + instance will be called. This in turn will call its underlying C++ + destructor which is obviously disastrous while the method wobble + is running using this object. Even if wobble is not a long + running method, it is possible for the Wibble instance to be + finalized. By passing the Wibble instance into the native + method, it will not be finalized as the JVM guarantees not to finalize + any objects until the native method returns. Effectively, the code then + becomes

      +
      +
      +{
+  Wibble w = new Wibble();
+  long w_ptr = Wibble.getCPtr(w);
+  exampleJNI.wobble(w_ptr, w);
+  // w is no longer reachable
+}
+
      +
      +

      and therefore there is no possibility of premature garbage + collection. In practice, this premature garbage collection was only + ever observed in Sun's server JVM from jdk-1.3 onwards and in Sun's + client JVM from jdk-1.6 onwards.

      +

      The premature garbage collection prevention parameter for proxy + classes is generated by default whenever proxy classes are passed by + value, reference or with a pointer. The implementation for this extra + parameter generation requires the "jtype" typemap to contain long + and the "jstype" typemap to contain the name of a proxy class.

      +

      The additional parameter does impose a slight performance overhead + and the parameter generation can be suppressed globally with the +-nopgcpp commandline option. More selective suppression is possible + with the 'nopgcpp' attribute in the "jtype" +Java typemap. The attribute is a flag and so should be set to "1" to + enable the suppression, or it can be omitted or set to "0" to disable. + For example:

      +
      +
      +%typemap(jtype, nopgcpp="1") Wibble & "long"
+
      +
      +

      Compatibility note: The generation of this additional + parameter did not occur in versions prior to SWIG-1.3.30.

      +

      21.4.3.5 Single threaded + applications and thread safety

      +

      Single threaded Java applications using JNI need to consider thread + safety. The same applies for the C# module where the .NET wrappers use + PInvoke. Consider the C++ class:

      +
      +
      +class Test {
+  string str;
+public:
+  Test() : str("initial") {}
+};
+
      +
      +

      and the Java proxy class generated by SWIG:

      +
      +
      +public class Test {
+  private long swigCPtr;
+  protected boolean swigCMemOwn;
+
+  protected Test(long cPtr, boolean cMemoryOwn) {
+    swigCMemOwn = cMemoryOwn;
+    swigCPtr = cPtr;
+  }
+
+  protected static long getCPtr(Test obj) {
+    return (obj == null) ? 0 : obj.swigCPtr;
+  }
+
+  protected void finalize() {
+    delete();
+  }
+
+  // Call C++ destructor
+  public synchronized void delete() {
+    if(swigCPtr != 0 && swigCMemOwn) {
+      swigCMemOwn = false;
+      exampleJNI.delete_Test(swigCPtr);
+    }
+    swigCPtr = 0;
+  }
+
+  // Call C++ constructor
+  public Test() {
+    this(exampleJNI.new_Test(), true);
+  }
+
+}
+
      +
      +

      It has two methods that call JNI methods, namely, +exampleJNI.new_Test() for the C++ constructor and +exampleJNI.delete_Test() for the C++ destructor. If the garbage + collector collects an instance of this class, ie delete() is + not explicitly called, then the C++ destructor will be run in a + different thread to the main thread. This is because when an object is + marked for garbage collection, any objects with finalizers are added to + a finalization queue and the objects in the finalization queue have + their finalize() methods run in a separate finalization + thread. Therefore, if the C memory allocator is not thread safe, then + the heap will get corrupted sooner or later, when a concurrent C++ + delete and new are executed. It is thus essential, even in single + threaded usage, to link to the C multi-thread runtime libraries, for + example, use the /MD option for Visual C++ on Windows. Alternatively, + lock all access to C++ functions that have heap + allocation/deallocation.

      +

      Note that some of the STL in Visual C++ 6 is not thread safe, so + although code might be linked to the multithread runtime libraries, + undefined behaviour might still occur in a single threaded Java + program. Similarly some older versions of Sun Studio have bugs in the + multi-threaded implementation of the std::string class and so will lead + to undefined behaviour in these supposedly single threaded Java + applications.

      +

      The following innocuous Java usage of Test is an example that will + crash very quickly on a multiprocessor machine if the JNI compiled code + is linked against the single thread C runtime libraries.

      +
      +
      +for (int i=0; i<100000; i++) {
+  System.out.println("Iteration " + i);
+  for (int k=0; k<10; k++) {
+    Test test = new Test();
+  }
+  System.gc();
+}
+
      +
      +

      21.4.4 Type wrapper classes

      +

      The generated type wrapper class, for say an int *, looks + like this:

      +
      +
      +public class SWIGTYPE_p_int {
+  private long swigCPtr;
+
+  protected SWIGTYPE_p_int(long cPtr, boolean bFutureUse) {
+    swigCPtr = cPtr;
+  }
+
+  protected SWIGTYPE_p_int() {
+    swigCPtr = 0;
+  }
+
+  protected static long getCPtr(SWIGTYPE_p_int obj) {
+    return obj.swigCPtr;
+  }
+}
+
      +
      +

      The methods do not have public access, so by default it is + impossible to do anything with objects of this class other than pass + them around. The methods in the class are part of the inner workings of + SWIG. If you need to mess around with pointers you will have to use + some typemaps specific to the Java module to achieve this. The section + on Java typemaps details how to modify the + generated code.

      +

      Note that if you use a pointer or reference to a proxy class in a + function then no type wrapper class is generated because the proxy + class can be used as the function parameter. If however, you need + anything more complicated like a pointer to a pointer to a proxy class + then a typewrapper class is generated for your use.

      +

      Note that SWIG generates a type wrapper class and not a proxy class + when it has not parsed the definition of a type that gets used. For + example, say SWIG has not parsed the definition of class Snazzy + because it is in a header file that you may have forgotten to use the +%include directive on. Should SWIG parse Snazzy * being + used in a function parameter, it will then generates a type wrapper + class around a Snazzy pointer. Also recall from earlier that + SWIG will use a pointer when a class is passed by value or by + reference:

      +
      +
      +void spam(Snazzy *x, Snazzy &y, Snazzy z);
+
      +
      +

      Should SWIG not know anything about Snazzy then a +SWIGTYPE_p_Snazzy must be used for all 3 parameters in the spam + function. The Java function generated is:

      +
      +
      +public static void spam(SWIGTYPE_p_Snazzy x, SWIGTYPE_p_Snazzy y, SWIGTYPE_p_Snazzy z) {
+ ...
+}
+
      +
      +

      Note that typedefs are tracked by SWIG and the typedef name is used + to construct the type wrapper class name. For example, consider the + case where Snazzy is a typedef to an int which SWIG + does parse:

      +
      +
      +typedef int Snazzy;
+void spam(Snazzy *x, Snazzy &y, Snazzy z);
+
      +
      +

      Because the typedefs have been tracked the Java function generated + is:

      +
      +
      +public static void spam(SWIGTYPE_p_int x, SWIGTYPE_p_int y, int z) { ... }
+
      +
      +

      21.4.5 Enum classes

      +

      SWIG can generate three types of enum classes. The +Enumerations section discussed these but omitted all the details. + The following sub-sections detail the various types of enum classes + that can be generated.

      +

      21.4.5.1 Typesafe enum classes

      +

      The following example demonstrates the typesafe enum classes which + SWIG generates:

      +
      +
      +%include "enumtypesafe.swg"
+%javaconst(1);
+enum Beverage { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
+
      +
      +

      The following is the code that SWIG generates:

      +
      +
      +public final class Beverage {
+  public final static Beverage ALE = new Beverage("ALE");
+  public final static Beverage LAGER = new Beverage("LAGER", 10);
+  public final static Beverage STOUT = new Beverage("STOUT");
+  public final static Beverage PILSNER = new Beverage("PILSNER");
+  public final static Beverage PILZ = new Beverage("PILZ", PILSNER);
+
+  public final int swigValue() {
+    return swigValue;
+  }
+
+  public String toString() {
+    return swigName;
+  }
+
+  public static Beverage swigToEnum(int swigValue) {
+    if (swigValue < swigValues.length && swigValue >= 0 &&
+        swigValues[swigValue].swigValue == swigValue)
+      return swigValues[swigValue];
+    for (int i = 0; i < swigValues.length; i++)
+      if (swigValues[i].swigValue == swigValue)
+        return swigValues[i];
+    throw new IllegalArgumentException("No enum " + Beverage.class + " with value " +
+                                                                         swigValue);
+  }
+
+  private Beverage(String swigName) {
+    this.swigName = swigName;
+    this.swigValue = swigNext++;
+  }
+
+  private Beverage(String swigName, int swigValue) {
+    this.swigName = swigName;
+    this.swigValue = swigValue;
+    swigNext = swigValue+1;
+  }
+
+  private Beverage(String swigName, Beverage swigEnum) {
+    this.swigName = swigName;
+    this.swigValue = swigEnum.swigValue;
+    swigNext = this.swigValue+1;
+  }
+
+  private static Beverage[] swigValues = { ALE, LAGER, STOUT, PILSNER, PILZ };
+  private static int swigNext = 0;
+  private final int swigValue;
+  private final String swigName;
+}
+
      +
      +

      As can be seen, there are a fair number of support methods for the + typesafe enum pattern. The typesafe enum pattern involves creating a + fixed number of static instances of the enum class. The constructors + are private to enforce this. Three constructors are available - two for + C/C++ enums with an initializer and one for those without an + initializer. Note that the two enums with initializers, LAGER + and PILZ, each call one the two different initializer + constructors. In order to use one of these typesafe enums, the +swigToEnum static method must be called to return a reference to + one of the static instances. The JNI layer returns the enum value from + the C/C++ world as an integer and this method is used to find the + appropriate Java enum static instance. The swigValue method is + used for marshalling in the other direction. The toString + method is overridden so that the enum name is available.

      +

      21.4.5.2 Proper Java enum classes

      +

      The following example demonstrates the Java enums approach:

      +
      +
      +%include "enums.swg"
+%javaconst(1);
+enum Beverage { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
+
      +
      +

      SWIG will generate the following Java enum:

      +
      +
      +public enum Beverage {
+  ALE,
+  LAGER(10),
+  STOUT,
+  PILSNER,
+  PILZ(PILSNER);
+
+  public final int swigValue() {
+    return swigValue;
+  }
+
+  public static Beverage swigToEnum(int swigValue) {
+    Beverage[] swigValues = Beverage.class.getEnumConstants();
+    if (swigValue < swigValues.length && swigValue >= 0 &&
+        swigValues[swigValue].swigValue == swigValue)
+      return swigValues[swigValue];
+    for (Beverage swigEnum : swigValues)
+      if (swigEnum.swigValue == swigValue)
+        return swigEnum;
+    throw new IllegalArgumentException("No enum " + Beverage.class +
+                                       " with value " + swigValue);
+  }
+
+  private Beverage() {
+    this.swigValue = SwigNext.next++;
+  }
+
+  private Beverage(int swigValue) {
+    this.swigValue = swigValue;
+    SwigNext.next = swigValue+1;
+  }
+
+  private Beverage(Beverage swigEnum) {
+    this.swigValue = swigEnum.swigValue;
+    SwigNext.next = this.swigValue+1;
+  }
+
+  private final int swigValue;
+
+  private static class SwigNext {
+    private static int next = 0;
+  }
+}
+
      +
      +

      The enum items appear first. Like the typesafe enum pattern, the + constructors are private. The constructors are required to handle C/C++ + enums with initializers. The next variable is in the +SwigNext inner class rather than in the enum class as static + primitive variables cannot be modified from within enum constructors. + Marshalling between Java enums and the C/C++ enum integer value is + handled via the swigToEnum and swigValue methods. All + the constructors and methods in the Java enum are required just to + handle C/C++ enums with initializers. These needn't be generated if the + enum being wrapped does not have any initializers and the +Simpler Java enums for enums without initializers section describes + how typemaps can be used to achieve this.

      +

      21.4.5.3 Type unsafe enum + classes

      +

      The following example demonstrates type unsafe enums:

      +
      +
      +%include "enumtypeunsafe.swg"
+%javaconst(1);
+enum Beverage { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
+
      +
      +

      SWIG will generate the following simple class:

      +
      +
      +public final class Beverage {
+  public final static int ALE = 0;
+  public final static int LAGER = 10;
+  public final static int STOUT = LAGER + 1;
+  public final static int PILSNER = STOUT + 1;
+  public final static int PILZ = PILSNER;
+}
+
      +
      +

      21.5 Cross language polymorphism using + directors

      +

      Proxy classes provide a natural, object-oriented way to wrap C++ + classes. as described earlier, each proxy instance has an associated + C++ instance, and method calls from Java to the proxy are passed to the + C++ instance transparently via C wrapper functions.

      +

      This arrangement is asymmetric in the sense that no corresponding + mechanism exists to pass method calls down the inheritance chain from + C++ to Java. In particular, if a C++ class has been extended in Java + (by deriving from the proxy class), these classes will not be visible + from C++ code. Virtual method calls from C++ are thus not able to + access the lowest implementation in the inheritance chain.

      +

      SWIG can address this problem and make the relationship between C++ + classes and proxy classes more symmetric. To achieve this goal, new + classes called directors are introduced at the bottom of the C++ + inheritance chain. The job of the directors is to route method calls + correctly, either to C++ implementations higher in the inheritance + chain or to Java implementations lower in the inheritance chain. The + upshot is that C++ classes can be extended in Java and from C++ these + extensions look exactly like native C++ classes. Neither C++ code nor + Java code needs to know where a particular method is implemented: the + combination of proxy classes, director classes, and C wrapper functions + transparently takes care of all the cross-language method routing.

      +

      21.5.1 Enabling directors

      +

      The director feature is disabled by default. To use directors you + must make two changes to the interface file. First, add the "directors" + option to the %module directive, like this:

      +
      +
      +%module(directors="1") modulename
+
      +
      +

      Without this option no director code will be generated. Second, you + must use the %feature("director") directive to tell SWIG which classes + and methods should get directors. The %feature directive can be applied + globally, to specific classes, and to specific methods, like this:

      +
      +
      +// generate directors for all classes that have virtual methods
+%feature("director");         
+
+// generate directors for all virtual methods in class Foo
+%feature("director") Foo;      
+
+// generate a director for just Foo::bar()
+%feature("director") Foo::bar; 
+
      +
      +

      You can use the %feature("nodirector") directive to turn off + directors for specific classes or methods. So for example,

      +
      +
      +%feature("director") Foo;
+%feature("nodirector") Foo::bar;
+
      +
      +

      will generate directors for all virtual methods of class Foo except + bar().

      +

      Directors can also be generated implicitly through inheritance. In + the following, class Bar will get a director class that handles the + methods one() and two() (but not three()):

      +
      +
      +%feature("director") Foo;
+class Foo {
+public:
+    virtual void one();
+    virtual void two();
+};
+
+class Bar: public Foo {
+public:
+    virtual void three();
+};
+
      +
      +

      21.5.2 Director classes

      +

      For each class that has directors enabled, SWIG generates a new + class that derives from both the class in question and a special +Swig::Director class. These new classes, referred to as director + classes, can be loosely thought of as the C++ equivalent of the Java + proxy classes. The director classes store a pointer to their underlying + Java proxy classes.

      +

      For simplicity let's ignore the Swig::Director class and + refer to the original C++ class as the director's base class. By + default, a director class extends all virtual methods in the + inheritance chain of its base class (see the preceding section for how + to modify this behavior). Thus all virtual method calls, whether they + originate in C++ or in Java via proxy classes, eventually end up in at + the implementation in the director class. The job of the director + methods is to route these method calls to the appropriate place in the + inheritance chain. By "appropriate place" we mean the method that would + have been called if the C++ base class and its Java derived classes + were seamlessly integrated. That seamless integration is exactly what + the director classes provide, transparently skipping over all the messy + JNI glue code that binds the two languages together.

      +

      In reality, the "appropriate place" is one of only two + possibilities: C++ or Java. Once this decision is made, the rest is + fairly easy. If the correct implementation is in C++, then the lowest + implementation of the method in the C++ inheritance chain is called + explicitly. If the correct implementation is in Java, the Java API is + used to call the method of the underlying Java object (after which the + usual virtual method resolution in Java automatically finds the right + implementation).

      +

      21.5.3 Overhead and code bloat

      +

      Enabling directors for a class will generate a new director method + for every virtual method in the class' inheritance chain. This alone + can generate a lot of code bloat for large hierarchies. Method + arguments that require complex conversions to and from Java types can + result in large director methods. For this reason it is recommended + that directors are selectively enabled only for specific classes that + are likely to be extended in Java and used in C++.

      +

      Although directors make it natural to mix native C++ objects with + Java objects (as director objects), one should be aware of the obvious + fact that method calls to Java objects from C++ will be much slower + than calls to C++ objects. Additionally, compared to classes that do + not use directors, the call routing in the director methods adds a + small overhead. This situation can be optimized by selectively enabling + director methods (using the %feature directive) for only those methods + that are likely to be extended in Java.

      +

      21.5.4 Simple directors example

      +

      Consider the following SWIG interface file:

      +
      +
      +%module(directors="1") example;
+
+%feature("director") DirectorBase;
+
+class DirectorBase {
+public:
+  virtual ~DirectorBase() {}
+  virtual void upcall_method() {}
+};
+
+void callup(DirectorBase *director) {
+  director->upcall_method();
+}
+
      +
      +

      The following DirectorDerived Java class is derived + from the Java proxy class DirectorBase and overrides +upcall_method(). When C++ code invokes upcall_method() +, the SWIG-generated C++ code redirects the call via JNI to the Java +DirectorDerived subclass. Naturally, the SWIG generated C++ code + and the generated Java intermediate class marshal and convert arguments + between C++ and Java when needed.

      +
      +
      +public class DirectorDerived extends DirectorBase {
+  public DirectorDerived() {
+  }
+
+  public void upcall_method() {
+    System.out.println("DirectorDerived::upcall_method() invoked.");
+  }
+}
+
      +
      +

      Running the following Java code

      +
      +
      +DirectorDerived director = new DirectorDerived();
+example.callup(director);
+
      +
      +

      will result in the following being output:

      +
      +
      +DirectorDerived::upcall_method() invoked.
+
      +
      +

      21.5.5 Director threading + issues

      +

      Depending on your operating system and version of Java and how you + are using threads, you might find the JVM hangs on exit. There are a + couple of solutions to try out. The preferred solution requires jdk-1.4 + and later and uses AttachCurrentThreadAsDaemon instead of +AttachCurrentThread whenever a call into the JVM is required. This + can be enabled by defining the + SWIG_JAVA_ATTACH_CURRENT_THREAD_AS_DAEMON macro when compiling the C++ + wrapper code. For older JVMs define SWIG_JAVA_NO_DETACH_CURRENT_THREAD + instead, to avoid the DetachCurrentThread call but this will + result in a memory leak instead. For further details inspect the source + code in the java/director.swg library file.

      +

      Macros can be defined on the commandline when compiling your C++ + code, or alternatively added to the C++ wrapper file as shown below:

      +
      +
      +%insert("runtime") %{
+#define SWIG_JAVA_NO_DETACH_CURRENT_THREAD
+%}
+
      +
      +

      21.6 Accessing protected members

      +

      When using directors, the protected virtual methods are also + wrapped. These methods are wrapped with a protected Java proxy method, + so the only way that Java code can access these is from within a Java + class derived from the director class.

      +

      Members which are protected and non-virtual can also be accessed + when using the 'allprotected' mode. The allprotected mode requires + directors and is turned on by setting the allprotected option + in addition to the directors option in the %module directive, + like this:

      +
      +
      +%module(directors="1", allprotected="1") modulename
+
      +
      +

      Protected member variables and methods (both static and non-static) + will then be wrapped with protected access in the Java proxy class.

      +

      Note: Neither the directors option nor the allprotected mode + support types defined with protected scope. This includes any enums or + typedefs declared in the protected section of the C++ class.

      +

      The following simple example is a class with numerous protected + members, including the constructor and destructor:

      +
      +
      +%module(directors="1", allprotected="1") example
+
+%feature("director") ProtectedBase;
+
+// Ignore use of unsupported types (those defined in the protected section)
+%ignore ProtectedBase::typedefs;
+
+%inline %{
+
+class ProtectedBase {
+protected:
+  ProtectedBase() {}
+  virtual ~ProtectedBase() {}
+  virtual void virtualMethod() const {}
+  void nonStaticMethod(double d) const {}
+  static void staticMethod(int i) {}
+  int instanceMemberVariable;
+  static int staticMemberVariable;
+
+  // unsupported: types defined with protected access and the methods/variables which use them
+  typedef int IntegerType;
+  IntegerType typedefs(IntegerType it) { return it; }
+};
+int ProtectedBase::staticMemberVariable = 10;
+
+%}
+
+
      +
      +

      Note that the IntegerType has protected scope and the + members which use this type must be ignored as they cannot be wrapped.

      +

      The proxy methods are protected, so the only way the protected + members can be accessed is within a class that derives from the + director class, such as the following:

      +
      +
      +class MyProtectedBase extends ProtectedBase
+{
+  public MyProtectedBase() {
+  }
+
+  public void accessProtected() {
+    virtualMethod();
+    nonStaticMethod(1.2);
+    staticMethod(99);
+
+    setInstanceMemberVariable(5);
+    int i = getInstanceMemberVariable();
+
+    setStaticMemberVariable(10);
+    i = getStaticMemberVariable();
+  }
+}
+
      +
      +

      21.7 Common customization + features

      +

      An earlier section presented the absolute basics of C/C++ wrapping. + If you do nothing but feed SWIG a header file, you will get an + interface that mimics the behavior described. However, sometimes this + isn't enough to produce a nice module. Certain types of functionality + might be missing or the interface to certain functions might be + awkward. This section describes some common SWIG features that are used + to improve the interface to existing C/C++ code.

      +

      21.7.1 C/C++ helper functions

      +

      Sometimes when you create a module, it is missing certain bits of + functionality. For example, if you had a function like this

      +
      +
      +typedef struct Image {...};
+void set_transform(Image *im, double m[4][4]);
+
      +
      +

      it would be accessible from Java, but there may be no easy way to + call it. The problem here is that a type wrapper class is generated for + the two dimensional array parameter so there is no easy way to + construct and manipulate a suitable double [4][4] value. To + fix this, you can write some extra C helper functions. Just use the +%inline directive. For example:

      +
      +
      +%inline %{
+/* Note: double[4][4] is equivalent to a pointer to an array double (*)[4] */
+double (*new_mat44())[4] {
+   return (double (*)[4]) malloc(16*sizeof(double));
+}
+void free_mat44(double (*x)[4]) {
+   free(x);
+}
+void mat44_set(double x[4][4], int i, int j, double v) {
+   x[i][j] = v;
+}
+double mat44_get(double x[4][4], int i, int j) {
+   return x[i][j];
+}
+%}
+
      +
      +

      From Java, you could then write code like this:

      +
      +
      +Image im = new Image();
+SWIGTYPE_p_a_4__double a = example.new_mat44();
+example.mat44_set(a,0,0,1.0);
+example.mat44_set(a,1,1,1.0);
+example.mat44_set(a,2,2,1.0);
+...
+example.set_transform(im,a);
+example.free_mat44(a);
+
      +
      +

      Admittedly, this is not the most elegant looking approach. However, + it works and it wasn't too hard to implement. It is possible to improve + on this using Java code, typemaps, and other customization features as + covered in later sections, but sometimes helper functions are a quick + and easy solution to difficult cases.

      +

      21.7.2 Class extension with %extend

      +

      One of the more interesting features of SWIG is that it can extend + structures and classes with new methods or constructors. Here is a + simple example:

      +
      +
      +%module example
+%{
+#include "someheader.h"
+%}
+
+struct Vector {
+   double x,y,z;
+};
+
+%extend Vector {
+   char *toString() {
+       static char tmp[1024];
+       sprintf(tmp,"Vector(%g,%g,%g)", $self->x,$self->y,$self->z);
+       return tmp;
+   }
+   Vector(double x, double y, double z) {
+       Vector *v = (Vector *) malloc(sizeof(Vector));
+       v->x = x;
+       v->y = y;
+       v->z = z;
+       return v;
+   }
+};
+
      +
      +

      Now, in Java

      +
      +
      +Vector v = new Vector(2,3,4);
+System.out.println(v);
+
      +
      +

      will display

      +
      +
      +Vector(2,3,4)
+
      +
      +

      %extend works with both C and C++ code. It does not modify + the underlying object in any way---the extensions only show up in the + Java interface.

      +

      21.7.3 Exception handling with + %exception and %javaexception

      +

      If a C or C++ function throws an error, you may want to convert that + error into a Java exception. To do this, you can use the %exception + directive. The %exception directive simply lets you rewrite + part of the generated wrapper code to include an error check. It is + detailed in full in the Exception handling with + %exception section.

      +

      In C, a function often indicates an error by returning a status code + (a negative number or a NULL pointer perhaps). Here is a simple example + of how you might handle that:

      +
      +
      +%exception malloc {
+  $action
+  if (!result) {
+    jclass clazz = (*jenv)->FindClass(jenv, "java/lang/OutOfMemoryError");
+    (*jenv)->ThrowNew(jenv, clazz, "Not enough memory");
+    return $null;
+  }
+}
+void *malloc(size_t nbytes);
+
      +
      +

      In Java,

      +
      +
      +SWIGTYPE_p_void a = example.malloc(2000000000);
+
      +
      +

      will produce a familiar looking Java exception:

      +
      +
      +Exception in thread "main" java.lang.OutOfMemoryError: Not enough memory
+        at exampleJNI.malloc(Native Method)
+        at example.malloc(example.java:16)
+        at runme.main(runme.java:112)
+
      +
      +

      If a library provides some kind of general error handling framework, + you can also use that. For example:

      +
      +
      +%exception malloc {
+  $action
+  if (err_occurred()) {
+    jclass clazz = (*jenv)->FindClass(jenv, "java/lang/OutOfMemoryError");
+    (*jenv)->ThrowNew(jenv, clazz, "Not enough memory");
+    return $null;
+  }
+}
+void *malloc(size_t nbytes);
+
      +
      +

      If no declaration name is given to %exception, it is + applied to all wrapper functions. The $action is a SWIG + special variable and is replaced by the C/C++ function call being + wrapped. The return $null; handles all native method return + types, namely those that have a void return and those that do not. This + is useful for typemaps that will be used in native method returning all + return types. See the section on Java + special variables for further explanation.

      +

      C++ exceptions are also easy to handle. We can catch the C++ + exception and rethrow it as a Java exception like this:

      +
      +
      +%exception getitem {
+  try {
+     $action
+  } catch (std::out_of_range &e) {
+    jclass clazz = jenv->FindClass("java/lang/Exception");
+    jenv->ThrowNew(clazz, "Range error");
+    return $null;
+   }
+}
+
+class FooClass {
+public:
+     FooClass *getitem(int index);      // Might throw std::out_of_range exception
+     ...
+};
+
      +
      +

      In the example above, java.lang.Exception is a checked + exception class and so ought to be declared in the throws clause of +getitem. Classes can be specified for adding to the throws clause + using %javaexception(classes) instead of %exception, + where classes is a string containing one or more comma + separated Java classes. The %clearjavaexception feature is the + equivalent to %clearexception and clears previously declared + exception handlers. The %nojavaexception feature is the + equivalent to %noexception and disables the exception handler. + See Clearing features + for the difference on disabling and clearing features.

      +
      +
      +%javaexception("java.lang.Exception") getitem {
+  try {
+     $action
+  } catch (std::out_of_range &e) {
+    jclass clazz = jenv->FindClass("java/lang/Exception");
+    jenv->ThrowNew(clazz, "Range error");
+    return $null;
+   }
+}
+
+class FooClass {
+public:
+     FooClass *getitem(int index);      // Might throw std::out_of_range exception
+     ...
+};
+
      +
      +

      The generated proxy method now generates a throws clause containing +java.lang.Exception:

      +
      +
      +public class FooClass {
+  ...
+  public FooClass getitem(int index) throws java.lang.Exception { ... }
+  ...
+}
+
      +
      +

      The examples above first use the C JNI calling syntax then the C++ + JNI calling syntax. The C++ calling syntax will not compile as C and + also vice versa. It is however possible to write JNI calls which will + compile under both C and C++ and is covered in the +Typemaps for both C and C++ compilation section.

      +

      The language-independent exception.i library file can also + be used to raise exceptions. See the SWIG Library + chapter. The typemap example Handling C++ + exception specifications as Java exceptions provides further + exception handling capabilities.

      +

      21.7.4 Method access with + %javamethodmodifiers

      +

      A Java feature called %javamethodmodifiers can be used to + change the method modifiers from the default public. It + applies to both module class methods and proxy class methods. For + example:

      +
      +
      +%javamethodmodifiers protect_me() "protected";
+void protect_me();
+
      +
      +

      Will produce the method in the module class with protected access.

      +
      +
      +protected static void protect_me() {
+  exampleJNI.protect_me();
+}
+
      +
      +

      21.8 Tips and techniques

      +

      Although SWIG is largely automatic, there are certain types of + wrapping problems that require additional user input. Examples include + dealing with output parameters, strings and arrays. This chapter + discusses the common techniques for solving these problems.

      +

      21.8.1 Input and output + parameters using primitive pointers and references

      +

      A common problem in some C programs is handling parameters passed as + simple pointers or references. For example:

      +
      +
      +void add(int x, int y, int *result) {
+   *result = x + y;
+}
+
      +
      +

      or perhaps

      +
      +
      +int sub(int *x, int *y) {
+   return *x-*y;
+}
+
      +
      +

      The typemaps.i library file will help in these situations. + For example:

      +
      +
      +%module example
+%include "typemaps.i"
+
+void add(int, int, int *OUTPUT);
+int  sub(int *INPUT, int *INPUT);
+
      +
      +

      In Java, this allows you to pass simple values. For example:

      +
      +
      +int result = example.sub(7,4);
+System.out.println("7 - 4 = " + result);
+int[] sum = {0};
+example.add(3,4,sum);
+System.out.println("3 + 4 = " + sum[0]);
+
      +
      +

      Which will display:

      +
      +
      +7 - 4 = 3
+3 + 4 = 7
+
      +
      +

      Notice how the INPUT parameters allow integer values to be + passed instead of pointers and how the OUTPUT parameter will + return the result in the first element of the integer array.

      +

      If you don't want to use the names INPUT or OUTPUT +, use the %apply directive. For example:

      +
      +
      +%module example
+%include "typemaps.i"
+
+%apply int *OUTPUT { int *result };
+%apply int *INPUT  { int *x, int *y};
+
+void add(int x, int y, int *result);
+int  sub(int *x, int *y);
+
      +
      +

      If a function mutates one of its parameters like this,

      +
      +
      +void negate(int *x) {
+   *x = -(*x);
+}
+
      +
      +

      you can use INOUT like this:

      +
      +
      +%include "typemaps.i"
+...
+void negate(int *INOUT);
+
      +
      +

      In Java, the input parameter is the first element in a 1 element + array and is replaced by the output of the function. For example:

      +
      +
      +int[] neg = {3};
+example.negate(neg);
+System.out.println("Negative of 3 = " + neg[0]);
+
      +
      +

      And no prizes for guessing the output:

      +
      +
      +Negative of 3 = -3
+
      +
      +

      These typemaps can also be applied to C++ references. The above + examples would work the same if they had been defined using references + instead of pointers. For example, the Java code to use the negate + function would be the same if it were defined either as it is above:

      +
      +
      +void negate(int *INOUT);
+
      +
      +

      or using a reference:

      +
      +
      +void negate(int &INOUT);
+
      +
      +

      Note: Since most Java primitive types are immutable and are passed + by value, it is not possible to perform in-place modification of a type + passed as a parameter.

      +

      Be aware that the primary purpose of the typemaps.i file is + to support primitive datatypes. Writing a function like this

      +
      +
      +void foo(Bar *OUTPUT);
+
      +
      +

      will not have the intended effect since typemaps.i does not + define an OUTPUT rule for Bar.

      +

      21.8.2 Simple pointers

      +

      If you must work with simple pointers such as int * or +double * another approach to using typemaps.i is to use + the cpointer.i pointer library file. For example:

      +
      +
      +%module example
+%include "cpointer.i"
+
+%inline %{
+extern void add(int x, int y, int *result);
+%}
+
+%pointer_functions(int, intp);
+
      +
      +

      The %pointer_functions(type,name) macro generates five + helper functions that can be used to create, destroy, copy, assign, and + dereference a pointer. In this case, the functions are as follows:

      +
      +
      +int  *new_intp();
+int  *copy_intp(int *x);
+void  delete_intp(int *x);
+void  intp_assign(int *x, int value);
+int   intp_value(int *x);
+
      +
      +

      In Java, you would use the functions like this:

      +
      +
      +SWIGTYPE_p_int intPtr = example.new_intp();
+example.add(3,4,intPtr);
+int result = example.intp_value(intPtr);
+System.out.println("3 + 4 = " + result);
+
      +
      +

      If you replace %pointer_functions(int,intp) by +%pointer_class(int,intp), the interface is more class-like.

      +
      +
      +intp intPtr = new intp();
+example.add(3,4,intPtr.cast());
+int result = intPtr.value();
+System.out.println("3 + 4 = " + result);
+
      +
      +

      See the SWIG Library chapter for further + details.

      +

      21.8.3 Wrapping C arrays with Java arrays

      +

      SWIG can wrap arrays in a more natural Java manner than the default + by using the arrays_java.i library file. Let's consider an + example:

      +
      +
      +%include "arrays_java.i";
+int array[4];
+void populate(int x[]) {
+    int i;
+    for (i=0; i<4; i++)
+        x[i] = 100 + i;
+}
+
      +
      +

      These one dimensional arrays can then be used as if they were Java + arrays:

      +
      +
      +int[] array = new int[4];
+example.populate(array);
+
+System.out.print("array: ");
+for (int i=0; i<array.length; i++)
+    System.out.print(array[i] + " ");
+
+example.setArray(array);
+
+int[] global_array = example.getArray();
+
+System.out.print("\nglobal_array: ");
+for (int i=0; i<array.length; i++)
+    System.out.print(global_array[i] + " ");
+
      +
      +

      Java arrays are always passed by reference, so any changes a + function makes to the array will be seen by the calling function. Here + is the output after running this code:

      +
      +
      +array: 100 101 102 103
+global_array: 100 101 102 103
+
      +
      +

      Note that for assigning array variables the length of the C variable + is used, so it is possible to use a Java array that is bigger than the + C code will cope with. Only the number of elements in the C array will + be used. However, if the Java array is not large enough then you are + likely to get a segmentation fault or access violation, just like you + would in C. When arrays are used in functions like populate, + the size of the C array passed to the function is determined by the + size of the Java array.

      +

      Please be aware that the typemaps in this library are not efficient + as all the elements are copied from the Java array to a C array + whenever the array is passed to and from JNI code. There is an + alternative approach using the SWIG array library and this is covered + in the next section.

      +

      21.8.4 Unbounded C Arrays

      +

      Sometimes a C function expects an array to be passed as a pointer. + For example,

      +
      +
      +int sumitems(int *first, int nitems) {
+    int i, sum = 0;
+    for (i = 0; i < nitems; i++) {
+        sum += first[i];
+    }
+    return sum;
+}
+
      +
      +

      One of the ways to wrap this is to apply the Java array typemaps + that come in the arrays_java.i library file:

      +
      +
      +%include "arrays_java.i"
+%apply int[] {int *};
+
      +
      +

      The ANY size will ensure the typemap is applied to arrays + of all sizes. You could narrow the typemap matching rules by specifying + a particular array size. Now you can use a pure Java array and pass it + to the C code:

      +
      +
      +int[] array = new int[10000000];          // Array of 10-million integers
+for (int i=0; i<array.length; i++) {      // Set some values
+  array[i] = i;
+}
+int sum = example.sumitems(array,10000);
+System.out.println("Sum = " + sum);
+
      +
      +

      and the sum would be displayed:

      +
      +
      +Sum = 49995000
+
      +
      +

      This approach is probably the most natural way to use arrays. + However, it suffers from performance problems when using large arrays + as a lot of copying of the elements occurs in transferring the array + from the Java world to the C++ world. An alternative approach to using + Java arrays for C arrays is to use an alternative SWIG library file +carrays.i. This approach can be more efficient for large arrays as + the array is accessed one element at a time. For example:

      +
      +
      +%include "carrays.i"
+%array_functions(int, intArray);
+
      +
      +

      The %array_functions(type,name) macro generates four helper + functions that can be used to create and destroy arrays and operate on + elements. In this case, the functions are as follows:

      +
      +
      +int *new_intArray(int nelements);
+void delete_intArray(int *x);
+int intArray_getitem(int *x, int index);
+void intArray_setitem(int *x, int index, int value);
+
      +
      +

      In Java, you would use the functions like this:

      +
      +
      +SWIGTYPE_p_int array = example.new_intArray(10000000);  // Array of 10-million integers
+for (int i=0; i<10000; i++) {                           // Set some values
+    example.intArray_setitem(array,i,i);
+}
+int sum = example.sumitems(array,10000);
+System.out.println("Sum = " + sum);
+
      +
      +

      If you replace %array_functions(int,intp) by +%array_class(int,intp), the interface is more class-like and a + couple more helper functions are available for casting between the + array and the type wrapper class.

      +
      +
      +%include "carrays.i"
+%array_class(int, intArray);
+
      +
      +

      The %array_class(type, name) macro creates wrappers for an + unbounded array object that can be passed around as a simple pointer + like int * or double *. For instance, you will be + able to do this in Java:

      +
      +
      +intArray array = new intArray(10000000);  // Array of 10-million integers
+for (int i=0; i<10000; i++) {             // Set some values
+    array.setitem(i,i);
+}
+int sum = example.sumitems(array.cast(),10000);
+System.out.println("Sum = " + sum);
+
      +
      +

      The array "object" created by %array_class() does not + encapsulate pointers inside a special array object. In fact, there is + no bounds checking or safety of any kind (just like in C). Because of + this, the arrays created by this library are extremely low-level + indeed. You can't iterate over them nor can you even query their + length. In fact, any valid memory address can be accessed if you want + (negative indices, indices beyond the end of the array, etc.). Needless + to say, this approach is not going to suit all applications. On the + other hand, this low-level approach is extremely efficient and well + suited for applications in which you need to create buffers, package + binary data, etc.

      +

      21.8.5 Overriding new and delete + to allocate from Java heap

      +

      Unlike some languages supported by SWIG, Java has a true garbage + collection subsystem. Other languages will free SWIG wrapped objects + when their reference count reaches zero. Java only schedules these + objects for finalization, which may not occur for some time. Because + SWIG objects are allocated on the C heap, Java users may find the JVM + memory use quickly exceeds the assigned limits, as memory fills with + unfinalized proxy objects. Forcing garbage collection is clearly an + undesirable solution.

      +

      An elegant fix for C++ users is to override new and delete using the + following code (here shown included in a SWIG interface file)

      +
      +
      +/* File: java_heap.i */
+%module test
+%{
+#include <stdexcept>
+#include "jni.h"
+
+/**
+ *  A stash area embedded in each allocation to hold java handles
+ */
+struct Jalloc {
+  jbyteArray jba;
+  jobject ref;
+};
+
+static JavaVM *cached_jvm = 0;
+
+JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *jvm, void *reserved) {
+  cached_jvm = jvm;
+  return JNI_VERSION_1_2;
+}
+
+static JNIEnv * JNU_GetEnv() {
+  JNIEnv *env;
+  jint rc = cached_jvm->GetEnv((void **)&env, JNI_VERSION_1_2);
+  if (rc == JNI_EDETACHED)
+    throw std::runtime_error("current thread not attached");
+  if (rc == JNI_EVERSION)
+    throw std::runtime_error("jni version not supported");
+  return env;
+}
+
+void * operator new(size_t t) {
+  if (cached_jvm != 0) {
+    JNIEnv *env = JNU_GetEnv();
+    jbyteArray jba = env->NewByteArray((int) t + sizeof(Jalloc));
+    if (env->ExceptionOccurred())
+      throw bad_alloc();
+    void *jbuffer = static_cast<void *>(env->GetByteArrayElements(jba, 0));
+    if (env->ExceptionOccurred())
+      throw bad_alloc();
+    Jalloc *pJalloc = static_cast<Jalloc *>(jbuffer);
+    pJalloc->jba = jba;
+    /* Assign a global reference so byte array will persist until delete'ed */
+    pJalloc->ref = env->NewGlobalRef(jba);
+    if (env->ExceptionOccurred())
+      throw bad_alloc();
+    return static_cast<void *>(static_cast<char *>(jbuffer) + sizeof(Jalloc));
+  }
+  else { /* JNI_OnLoad not called, use malloc and mark as special */
+    Jalloc *pJalloc = static_cast<Jalloc *>(malloc((int) t + sizeof(Jalloc)));
+    if (!pJalloc)
+      throw bad_alloc();
+    pJalloc->ref = 0;
+    return static_cast<void *>(
+        static_cast<char *>(static_cast<void *>(pJalloc)) + sizeof(Jalloc));
+  }
+}
+
+void operator delete(void *v) {
+  if (v != 0) {
+    void *buffer = static_cast<void *>( static_cast<char *>(v) - sizeof(Jalloc));
+    Jalloc *pJalloc = static_cast<Jalloc *>(buffer);
+    if (pJalloc->ref) {
+      JNIEnv *env = JNU_GetEnv();
+      env->DeleteGlobalRef(pJalloc->ref);
+      env->ReleaseByteArrayElements(pJalloc->jba, static_cast<jbyte *>(buffer), 0);
+    }
+    else {
+      free(buffer);
+    }
+  }
+}
+%}
+...
+
      +
      +

      This code caches the Java environment during initialization, and + when new is called, a Java ByteArray is allocated to provide the SWIG + objects with space in the Java heap. This has the combined effect of + re-asserting the Java virtual machine's limit on memory allocation, and + puts additional pressure on the garbage collection system to run more + frequently. This code is made slightly more complicated because + allowances must be made if new is called before the JNI_OnLoad is + executed. This can happen during static class initialization, for + example.

      +

      Unfortunately, because most Java implementations call malloc and + free, this solution will not work for C wrapped structures. However, + you are free to make functions that allocate and free memory from the + Java heap using this model and use these functions in place of malloc + and free in your own code.

      +

      21.9 Java typemaps

      +

      This section describes how you can modify SWIG's default wrapping + behavior for various C/C++ datatypes using the %typemap + directive. You are advised to be familiar with the the material in the + "Typemaps" chapter. While not absolutely + essential knowledge, this section assumes some familiarity with the + Java Native Interface (JNI). JNI documentation can be consulted either + online at Sun's Java web site or from + a good JNI book. The following two books are recommended:

      +
        +
      • Title: 'Essential JNI: Java Native Interface.' Author: Rob Gordon. + Publisher: Prentice Hall. ISBN: 0-13-679895-0.
        • +
      • Title: 'The Java Native Interface: Programmer's Guide and + Specification.' Author: Sheng Liang. Publisher: Addison-Wesley. ISBN: + 0-201-32577-2. Also available +online at the Sun Developer Network.
        • +
      +

      Before proceeding, it should be stressed that typemaps are not a + required part of using SWIG---the default wrapping behavior is enough + in most cases. Typemaps are only used if you want to change some aspect + of the generated code.

      +

      21.9.1 Default + primitive type mappings

      +

      The following table lists the default type mapping from Java to + C/C++.

      + + + + + + + + + + + + + + + + + +
      C/C++ typeJava typeJNI type +
      bool +
      const bool &      		booleanjboolean
      char +
      const char &      		charjchar
      signed char +
      const signed char &      		bytejbyte
      unsigned char +
      const unsigned char &      		shortjshort
      short +
      const short &      		shortjshort
      unsigned short +
      const unsigned short &      		intjint
      int +
      const int &      		intjint
      unsigned int +
      const unsigned int &      		longjlong
      long +
      const long &      		intjint
      unsigned long +
      const unsigned long &      		longjlong
      long long +
      const long long &      		longjlong
      unsigned long long +
      const unsigned long long &      		java.math.BigInteger +jobject
      float +
      const float &      		floatjfloat
      double +
      const double &      		doublejdouble
      char * +
      char []      		Stringjstring
      +

      Note that SWIG wraps the C char type as a character. + Pointers and arrays of this type are wrapped as strings. The signed + char type can be used if you want to treat char as a + signed number rather than a character. Also note that all const + references to primitive types are treated as if they are passed by + value.

      +

      Given the following C function:

      +
      +
      +void func(unsigned short a, char *b, const long &c, unsigned long long d);
+
      +
      +

      The module class method would be:

      +
      +
      +public static void func(int a, String b, int c, java.math.BigInteger d) {...}
+
      +
      +

      The intermediary JNI class would use the same types:

      +
      +
      +public final static native void func(int jarg1, String jarg2, int jarg3,
+                                     java.math.BigInteger jarg4);
+
      +
      +

      and the JNI function would look like this:

      +
      +
      +SWIGEXPORT void JNICALL Java_exampleJNI_func(JNIEnv *jenv, jclass jcls,
+                jint jarg1, jstring jarg2, jint jarg3, jobject jarg4) {...}
+
      +
      +

      The mappings for C int and C long are appropriate + for 32 bit applications which are used in the 32 bit JVMs. There is no + perfect mapping between Java and C as Java doesn't support all the + unsigned C data types. However, the mappings allow the full range of + values for each C type from Java.

      +

      21.9.2 Default + typemaps for non-primitive types

      +

      The previous section covered the primitive type mappings. + Non-primitive types such as classes and structs are mapped using + pointers on the C/C++ side and storing the pointer into a Java long + variable which is held by the proxy class or type wrapper class. This + applies whether the type is marshalled as a pointer, by reference or by + value. It also applies for any unknown/incomplete types which use type + wrapper classes.

      +

      So in summary, the C/C++ pointer to non-primitive types is cast into + the 64 bit Java long type and therefore the JNI type is a +jlong. The Java type is either the proxy class or type wrapper + class.

      +

      21.9.3 Sixty four bit JVMs

      +

      If you are using a 64 bit JVM you may have to override the C long, + but probably not C int default mappings. Mappings will be system + dependent, for example long will need remapping on Unix LP64 systems + (long, pointer 64 bits, int 32 bits), but not on Microsoft 64 bit + Windows which will be using a P64 IL32 (pointer 64 bits and int, long + 32 bits) model. This may be automated in a future version of SWIG. Note + that the Java write once run anywhere philosophy holds true for all + pure Java code when moving to a 64 bit JVM. Unfortunately it won't of + course hold true for JNI code.

      +

      21.9.4 What is a typemap?

      +

      A typemap is nothing more than a code generation rule that is + attached to a specific C datatype. For example, to convert integers + from Java to C, you might define a typemap like this:

      +
      +
      +%module example
+
+%typemap(in) int {
+  $1 = $input;
+  printf("Received an integer : %d\n",  $1);
+}
+%inline %{
+extern int fact(int nonnegative);
+%}
+
      +
      +

      Typemaps are always associated with some specific aspect of code + generation. In this case, the "in" method refers to the conversion of + input arguments to C/C++. The datatype int is the datatype to + which the typemap will be applied. The supplied C code is used to + convert values. In this code a number of special variables prefaced by + a $ are used. The $1 variable is a placeholder for a + local variable of type int. The $input variable + contains the Java data, the JNI jint in this case.

      +

      When this example is compiled into a Java module, it can be used as + follows:

      +
      +
      +System.out.println(example.fact(6));
+
      +
      +

      and the output will be:

      +
      +
      +Received an integer : 6
+720
+
      +
      +

      In this example, the typemap is applied to all occurrences of the +int datatype. You can refine this by supplying an optional + parameter name. For example:

      +
      +
      +%module example
+
+%typemap(in) int nonnegative {
+  $1 = $input;
+  printf("Received an integer : %d\n",  $1);
+}
+
+%inline %{
+extern int fact(int nonnegative);
+%}
+
      +
      +

      In this case, the typemap code is only attached to arguments that + exactly match int nonnegative.

      +

      The application of a typemap to specific datatypes and argument + names involves more than simple text-matching--typemaps are fully + integrated into the SWIG C++ type-system. When you define a typemap for + int, that typemap applies to int and qualified + variations such as const int. In addition, the typemap system + follows typedef declarations. For example:

      +
      +
      +%typemap(in) int nonnegative {
+  $1 = $input;
+  printf("Received an integer : %d\n",  $1);
+}
+%inline %{
+typedef int Integer;
+extern int fact(Integer nonnegative);    // Above typemap is applied
+%}
+
      +
      +

      However, the matching of typedef only occurs in one + direction. If you defined a typemap for Integer, it is not + applied to arguments of type int.

      +

      Typemaps can also be defined for groups of consecutive arguments. + For example:

      +
      +
      +%typemap(in) (char *str, int len) {
+...
+};
+
+int count(char c, char *str, int len);
+
      +
      +

      When a multi-argument typemap is defined, the arguments are always + handled as a single Java parameter. This allows the function to be used + like this (notice how the length parameter is omitted):

      +
      +
      +int c = example.count('e',"Hello World");
+
      +
      +

      21.9.5 Typemaps for mapping + C/C++ types to Java types

      +

      The typemaps available to the Java module include the common + typemaps listed in the main typemaps section. There are a number of + additional typemaps which are necessary for using SWIG with Java. The + most important of these implement the mapping of C/C++ types to Java + types:

      +
        + + + + + + + + + + + +
      TypemapDescription
      jniJNI C types. These provide the default mapping of + types from C/C++ to JNI for use in the JNI (C/C++) code.
      jtypeJava intermediary types. These provide the default + mapping of types from C/C++ to Java for use in the native functions in + the intermediary JNI class. The type must be the equivalent Java type + for the JNI C type specified in the "jni" typemap.
      jstypeJava types. These provide the default mapping of + types from C/C++ to Java for use in the Java module class, proxy + classes and type wrapper classes.
      javainConversion from jstype to jtype. These are Java + code typemaps which transform the type used in the Java module class, + proxy classes and type wrapper classes (as specified in the "jstype" + typemap) to the type used in the Java intermediary JNI class (as + specified in the "jtype" typemap). In other words the typemap provides + the conversion to the native method call parameter types.
      javaoutConversion from jtype to jstype. These are Java + code typemaps which transform the type used in the Java intermediary + JNI class (as specified in the "jtype" typemap) to the Java type used + in the Java module class, proxy classes and type wrapper classes (as + specified in the "jstype" typemap). In other words the typemap provides + the conversion from the native method call return type.
      javadirectorinConversion from jtype to jstype for + director methods. These are Java code typemaps which transform the type + used in the Java intermediary JNI class (as specified in the "jtype" + typemap) to the Java type used in the Java module class, proxy classes + and type wrapper classes (as specified in the "jstype" typemap). This + typemap provides the conversion for the parameters in the director + methods when calling up from C++ to Java. See +Director typemaps.
      javadirectoroutConversion from jstype to jtype for + director methods. These are Java code typemaps which transform the type + used in the Java module class, proxy classes and type wrapper classes + (as specified in the "jstype" typemap) to the type used in the Java + intermediary JNI class (as specified in the "jtype" typemap). This + typemap provides the conversion for the return type in the director + methods when returning from the C++ to Java upcall. See +Director typemaps.
      directorinConversion from C++ type to jni type for + director methods. These are C++ typemaps which convert the parameters + used in the C++ director method to the appropriate JNI intermediary + type. The conversion is done in JNI code prior to calling the Java + function from the JNI code. See +Director typemaps.
      directoroutConversion from jni type to C++ type for + director methods. These are C++ typemaps which convert the JNI return + type used in the C++ director method to the appropriate C++ return + type. The conversion is done in JNI code after calling the Java + function from the JNI code. See +Director typemaps.
      +

      If you are writing your own typemaps to handle a particular type, + you will normally have to write a collection of them. The default + typemaps are in "java.swg" and so might be a good place for + finding typemaps to base any new ones on.

      +

      The "jni", "jtype" and "jstype" typemaps are usually defined + together to handle the Java to C/C++ type mapping. An "in" typemap + should be accompanied by a "javain" typemap and likewise an "out" + typemap by a "javaout" typemap. If an "in" typemap is written, a + "freearg" and "argout" typemap may also need to be written as some + types have a default "freearg" and/or "argout" typemap which may need + overriding. The "freearg" typemap sometimes releases memory allocated + by the "in" typemap. The "argout" typemap sometimes sets values in + function parameters which are passed by reference in Java.

      +

      Note that the "in" typemap marshals the JNI type held in the "jni" + typemap to the real C/C++ type and for the opposite direction, the + "out" typemap marshals the real C/C++ type to the JNI type held in the + "jni" typemap. For +non-primitive types the "in" and "out" typemaps are responsible for + casting between the C/C++ pointer and the 64 bit jlong type. + There is no portable way to cast a pointer into a 64 bit integer type + and the approach taken by SWIG is mostly portable, but breaks C/C++ + aliasing rules. In summary, these rules state that a pointer to any + type must never be dereferenced by a pointer to any other incompatible + type. The following code snippet might aid in understand aliasing rules + better:

      +
      +
      +    short a;
+    short* pa = 0;
+    int i = 0x1234;
+
+    a = (short)i;    /* okay */
+    a = *(short*)&i; /* breaks aliasing rules */
+
      +
      +

      An email posting, +Aliasing, pointer casts and gcc 3.3 elaborates further on the + subject. In SWIG, the "in" and "out" typemaps for pointers are + typically

      +
      +
      +    %typemap(in) struct Foo * %{
+      $1 = *(struct Foo **)&$input; /* cast jlong into C ptr */
+    %}
+    %typemap(out) struct Bar * %{
+      *(struct Bar **)&$result = $1; /* cast C ptr into jlong */
+    %} 
+    struct Bar {...};
+    struct Foo {...};
+    struct Bar * FooBar(struct Foo *f);
+
      +
      +

      resulting in the following code which breaks the aliasing rules:

      +
      +
      +SWIGEXPORT jlong JNICALL Java_exampleJNI_FooBar(JNIEnv *jenv, jclass jcls,
+                                                jlong jarg1, jobject jarg1_) {
+  jlong jresult = 0 ;
+  struct Foo *arg1 = (struct Foo *) 0 ;
+  struct Bar *result = 0 ;
+  
+  (void)jenv;
+  (void)jcls;
+  (void)jarg1_;
+  arg1 = *(struct Foo **)&jarg1; 
+  result = (struct Bar *)FooBar(arg1);
+  *(struct Bar **)&jresult = result; 
+  return jresult;
+}
+
      +
      +

      If you are using gcc as your C compiler, you might get a + "dereferencing type-punned pointer will break strict-aliasing rules" + warning about this. Please see Compiling a + dynamic module to avoid runtime problems with these strict aliasing + rules.

      +

      The default code generated by SWIG for the Java module comes from + the typemaps in the "java.swg" library file which implements + the Default primitive type + mappings and Default + typemaps for non-primitive types covered earlier. There are other + type mapping typemaps in the Java library. These are listed below:

      +
        + + + + + + + + + + + + +
      C TypeTypemap +FileKindJava Type +Function
      primitive pointers and referencesINPUT +typemaps.iinputJava basic typesAllows values + to be used for C functions taking pointers for data input.
      primitive pointers and referencesOUTPUT +typemaps.ioutputJava basic type arraysAllows + values held within an array to be used for C functions taking pointers + for data output.
      primitive pointers and referencesINOUT +typemaps.iinput +
      output      		Java basic type arraysAllows values held + within an array to be used for C functions taking pointers for data + input and output.
      string +
      wstring      		[unnamed]std_string.iinput +
      output      		StringUse for std::string mapping to Java + String.
      arrays of primitive types[unnamed] +arrays_java.iinput +
      output      		arrays of primitive Java typesUse for + mapping C arrays to Java arrays.
      arrays of classes/structs/unionsJAVA_ARRAYSOFCLASSES + macroarrays_java.iinput +
      output      		arrays of proxy classesUse for mapping C + arrays to Java arrays.
      arrays of enumsARRAYSOFENUMSarrays_java.i +input +
      output      		int[]Use for mapping C arrays to Java + arrays (typeunsafe and simple enum wrapping approaches only).
      char *BYTEvarious.iinput +byte[]Java byte array is converted to char array
      char **STRING_ARRAYvarious.iinput +
      output      		String[]Use for mapping NULL terminated + arrays of C strings to Java String arrays
      +

      21.9.6 Java typemap attributes

      +

      There are a few additional typemap attributes that the Java module + supports.

      +

      The first of these is the 'throws' attribute. The throws attribute + is optional and specified after the typemap name and contains one or + more comma separated classes for adding to the throws clause for any + methods that use that typemap. It is analogous to the +%javaexception feature's throws attribute.

      +
      +
      +%typemap(typemapname, throws="ExceptionClass1, ExceptionClass2") type { ... }
+
      +
      +

      The attribute is necessary for supporting Java checked exceptions + and can be added to just about any typemap. The list of typemaps + include all the C/C++ (JNI) typemaps in the " +Typemaps" chapter and the Java specific typemaps listed in +the previous section, barring the "jni", "jtype" and "jstype" + typemaps as they could never contain code to throw an exception.

      +

      The throws clause is generated for the proxy method as well as the + JNI method in the JNI intermediary class. If a method uses more than + one typemap and each of those typemaps have classes specified in the + throws clause, the union of the exception classes is added to the + throws clause ensuring there are no duplicate classes. See the +NaN exception example for further usage.

      +

      The "jtype" typemap has the optional 'nopgcpp' attribute which can + be used to suppress the generation of the +premature garbage collection prevention parameter.

      +

      The "javain" typemap has the optional 'pre', 'post' and 'pgcppname' + attributes. These are used for generating code before and after the JNI + call in the proxy class or module class. The 'pre' attribute contains + code that is generated before the JNI call and the 'post' attribute + contains code generated after the JNI call. The 'pgcppname' attribute + is used to change the premature garbage collection + prevention parameter name passed to the JNI function. This is + sometimes needed when the 'pre' typemap creates a temporary variable + which is then passed to the JNI function.

      +

      Note that when the + 'pre' or 'post' attributes are specified and the associated type is + used in a constructor, a constructor helper function is generated. This + is necessary as the Java proxy constructor wrapper makes a call to a + support constructor using a this call. In Java the this + call must be the first statement in the constructor body. The + constructor body thus calls the helper function and the helper function + instead makes the JNI call, ensuring the 'pre' code is called before + the JNI call is made. There is a Date + marshalling example showing 'pre', 'post' and 'pgcppname' + attributes in action.

      +

      21.9.7 Java special variables

      +

      The standard SWIG special variables are available for use within + typemaps as described in the Typemaps documentation +, for example $1, $input,$result etc.

      +

      The Java module uses a few additional special variables:

      +

      $javaclassname +
      This special variable works like the other +special variables and $javaclassname is similar to +$1_type. It expands to the class name for use in Java given a + pointer. SWIG wraps unions, structs and classes using pointers and in + this case it expands to the Java proxy class name. For example, +$javaclassname is replaced by the proxy classname Foo when + wrapping a Foo * and $&javaclassname expands to the + proxy classname when wrapping the C/C++ type Foo and +$*javaclassname expands to the proxy classname when wrapping +Foo *&. If the type does not have an associated proxy class, it + expands to the type wrapper class name, for example, +SWIGTYPE_p_unsigned_short is generated when wrapping unsigned + short *.

      +

      $null +
      Used in input typemaps to return early from JNI functions that have + either void or a non-void return type. Example:

      +
      +
      +%typemap(check) int * %{ 
+  if (error) {
+    SWIG_JavaThrowException(jenv, SWIG_JavaIndexOutOfBoundsException, "Array element error");
+    return $null;
+  }
+%}
+
      +
      +

      If the typemap gets put into a function with void as return, $null + will expand to nothing:

      +
      +
      +SWIGEXPORT void JNICALL Java_jnifn(...) {
+    if (error) {
+      SWIG_JavaThrowException(jenv, SWIG_JavaIndexOutOfBoundsException, "Array element error");
+      return ;
+    }
+  ...
+}
+
      +
      +

      otherwise $null expands to NULL

      +
      +
      +SWIGEXPORT jobject JNICALL Java_jnifn(...) {
+    if (error) {
+      SWIG_JavaThrowException(jenv, SWIG_JavaIndexOutOfBoundsException, "Array element error");
+      return NULL;
+    }
+  ...
+}
+
      +
      +

      $javainput, $jnicall and $owner +
      The $javainput special variable is used in "javain" typemaps and + $jnicall and $owner are used in "javaout" typemaps. $jnicall is + analogous to $action in %exception. It is replaced by the call to the + native method in the intermediary JNI class. $owner is replaced by + either true if %newobject has been used, otherwise false +. $javainput is analogous to the $input special variable. It is replaced + by the parameter name.

      +

      Here is an example:

      +
      +
      +%typemap(javain) Class "Class.getCPtr($javainput)"
+%typemap(javain) unsigned short "$javainput"
+%typemap(javaout) Class * {
+    return new Class($jnicall, $owner);
+  }
+
+%inline %{
+    class Class {...};
+    Class * bar(Class cls, unsigned short ush) { return new Class(); };
+%}
+
      +
      +

      The generated proxy code is then:

      +
      +
      +public static Class bar(Class cls, int ush) {
+  return new Class(exampleJNI.bar(Class.getCPtr(cls), cls, ush), false);
+}
+
      +
      +

      Here $javainput has been replaced by cls and ush. + $jnicall has been replaced by the native method call, +exampleJNI.bar(...) and $owner has been replaced by false. + If %newobject is used by adding the following at the beginning of our + example:

      +
      +
      +%newobject bar(Class cls, unsigned short ush);
+
      +
      +

      The generated code constructs the return type using true + indicating the proxy class Class is responsible for destroying + the C++ memory allocated for it in bar:

      +
      +
      +public static Class bar(Class cls, int ush) {
+  return new Class(exampleJNI.bar(Class.getCPtr(cls), cls, ush), true);
+}
+
      +
      +

      $static +
      This special variable expands to either static or nothing + depending on whether the class is an inner Java class or not. It is + used in the "javaclassmodifiers" typemap so that global classes can be + wrapped as Java proxy classes and nested C++ classes/enums can be + wrapped with the Java equivalent, that is, static inner proxy classes.

      +

      $jniinput, $javacall and $packagepath +
      These special variables are used in the directors typemaps. See +Director specific typemaps for details.

      +

      $module +
      This special variable expands to the module name, as specified by +%module or the -module commandline option.

      +

      $imclassname +
      This special variable expands to the intermediary class name. + Usually this is the same as '$moduleJNI', unless the jniclassname + attribute is specified in the %module + directive.

      +

      21.9.8 Typemaps for both C and + C++ compilation

      +

      JNI calls must be written differently depending on whether the code + is being compiled as C or C++. For example C compilation requires the + pointer to a function pointer struct member syntax like

      +
      +
      +const jclass clazz = (*jenv)->FindClass(jenv, "java/lang/String");
+
      +
      +

      whereas C++ code compilation of the same function call is a member + function call using a class pointer like

      +
      +
      +const jclass clazz = jenv->FindClass("java/lang/String");
+
      +
      +

      To enable typemaps to be used for either C or C++ compilation, a set + of JCALLx macros have been defined in Lib/java/javahead.swg, where x is + the number of arguments in the C++ version of the JNI call. The above + JNI calls would be written in a typemap like this

      +
      +
      +const jclass clazz = JCALL1(FindClass, jenv, "java/lang/String");
+
      +
      +

      Note that the SWIG preprocessor expands these into the appropriate C + or C++ JNI calling convention. The C calling convention is emitted by + default and the C++ calling convention is emitted when using the -c++ + SWIG commandline option. If you do not intend your code to be targeting + both C and C++ then your typemaps can use the appropriate JNI calling + convention and need not use the JCALLx macros.

      +

      21.9.9 Java code typemaps

      +

      Most of SWIG's typemaps are used for the generation of C/C++ code. + The typemaps in this section are used solely for the generation of Java + code. Elements of proxy classes and type wrapper classes come from the + following typemaps (the defaults).

      +

      %typemap(javabase)

      +
      base (extends) for Java class: empty default +
      Note that this typemap accepts a replace attribute as an + optional flag. When set to "1", it will replace/override any C++ base + classes that might have been parsed. If this flag is not specified and + there are C++ base classes, then a multiple inheritance warning is + issued and the code in the typemap is ignored. The typemap also accepts + a notderived attribute as an optional flag. When set to "1", + it will not apply to classes that are derived from a C++ base. When + used with the SWIGTYPE type, it is useful for giving a common base for + all proxy classes, that is, providing a base class that sits in between + all proxy classes and the Java base class Object for example: +%typemap(javabase, notderived="1") SWIGTYPE "CommonBase".
      +

      %typemap(javabody)

      +
      the essential support body for proxy classes (proxy + base classes only), typewrapper classes and enum classes. Default + contains extra constructors, memory ownership control member variables + (swigCMemOwn, swigCPtr), the getCPtr method + etc.
      +

      %typemap(javabody_derived)

      +
      the essential support body for proxy classes + (derived classes only). Same as "javabody" typemap, but only used for + proxy derived classes.
      +

      %typemap(javaclassmodifiers)

      +
      class modifiers for the Java class: default is + "public class"
      +

      %typemap(javacode)

      +
      Java code is copied verbatim to the Java class: + empty default
      +

      %typemap(javadestruct, methodname="delete", + methodmodifiers="public synchronized") +

      +
      destructor wrapper - the delete() method + (proxy classes only), used for all proxy classes except those which + have a base class : default calls C++ destructor (or frees C memory) + and resets swigCPtr and swigCMemOwn flags +
      +
      Note that the delete() method name is configurable and is + specified by the methodname attribute. The method modifiers + are also configurable via the methodmodifiers attribute.
      +

      %typemap(javadestruct_derived, methodname="delete", + methodmodifiers="public synchronized")

      +
      destructor wrapper - the delete() method + (proxy classes only), same as "javadestruct" but only used for derived + proxy classes : default calls C++ destructor (or frees C memory) and + resets swigCPtr and swigCMemOwn flags +
      +
      Note that the delete() method name is configurable and is + specified by the methodname attribute. The method modifiers + are also configurable via the methodmodifiers attribute.
      +

      %typemap(javaimports)

      +
      import statements for Java class: empty default
      +

      %typemap(javainterfaces)

      +
      interfaces (extends) for Java class: empty default
      +

      %typemap(javafinalize)

      +
      the finalize() method (proxy classes + only): default calls the delete() method
      +

      Compatibility Note: In SWIG-1.3.21 and earlier releases, + typemaps called "javagetcptr" and "javaptrconstructormodifiers" were + available. These are deprecated and the "javabody" typemap can be used + instead.

      +

      In summary the contents of the typemaps make up a proxy class like + this:

      +
      +
      +[ javaimports typemap ]
+[ javaclassmodifiers typemap ] javaclassname extends [ javabase typemap ]
+                                             implements [ javainterfaces typemap ] {
+[ javabody or javabody_derived typemap ]
+[ javafinalize typemap ]
+public synchronized void delete() [ javadestruct OR javadestruct_derived typemap ]
+[ javacode typemap ]
+... proxy functions ...
+}
+
      +
      +

      Note the delete() methodname and method modifiers + are configurable, see "javadestruct" and "javadestruct_derived" + typemaps above.

      +

      The type wrapper class is similar in construction:

      +
      +
      +[ javaimports typemap ]
+[ javaclassmodifiers typemap ] javaclassname extends [ javabase typemap ]
+                                             implements [ javainterfaces typemap ] {
+[ javabody typemap ]
+[ javacode typemap ]
+}
+
      +
      +

      The enum class is also similar in construction:

      +
      +
      +[ javaimports typemap ]
+[ javaclassmodifiers typemap ] javaclassname extends [ javabase typemap ]
+                                             implements [ javainterfaces typemap ] {
+... Enum values ...
+[ javabody typemap ]
+[ javacode typemap ]
+}
+
      +
      +

      The "javaimports" typemap is ignored if the enum class is wrapped by + an inner Java class, that is when wrapping an enum declared within a + C++ class.

      +

      The defaults can be overridden to tailor these classes. Here is an + example which will change the getCPtr method and constructor + from the default protected access to public access. This has a + practical application if you are invoking SWIG more than once and + generating the wrapped classes into different packages in each + invocation. If the classes in one package are using the classes in + another package, then these methods need to be public.

      +
      +
      +%typemap(javabody) SWIGTYPE %{
+  private long swigCPtr;
+  protected boolean swigCMemOwn;
+
+  public $javaclassname(long cPtr, boolean cMemoryOwn) {
+    swigCMemOwn = cMemoryOwn;
+    swigCPtr = cPtr;
+  }
+
+  public static long getCPtr($javaclassname obj) {
+    return (obj == null) ? 0 : obj.swigCPtr;
+  }
+%}
+
      +
      +

      The typemap code is the same that is in "java.swg", barring + the two method modifiers. Note that SWIGTYPE will target all + proxy classes, but not the type wrapper classes. Also the above typemap + is only used for proxy classes that are potential base classes. To + target proxy classes that are derived from a wrapped class as well, the + "javabody_derived" typemap should also be overridden.

      +

      For the typemap to be used in all type wrapper classes, all the + different types that type wrapper classes could be used for should be + targeted:

      +
      +
      +%typemap(javabody) SWIGTYPE *, SWIGTYPE &, SWIGTYPE [], SWIGTYPE (CLASS::*) %{
+  private long swigCPtr;
+
+  public $javaclassname(long cPtr, boolean bFutureUse) {
+    swigCPtr = cPtr;
+  }
+
+  protected $javaclassname() {
+    swigCPtr = 0;
+  }
+
+  public static long getCPtr($javaclassname obj) {
+    return (obj == null) ? 0 : obj.swigCPtr;
+  }
+%}
+
      +
      +

      Again this is the same that is in "java.swg", barring the + method modifier for getCPtr.

      +

      21.9.10 Director specific + typemaps

      +

      The Java directors feature requires the "javadirectorin", + "javadirectorout", "directorin" and the "directorout" typemaps in order + to work properly. The "javapackage" typemap is an optional typemap used + to identify the Java package path for individual SWIG generated proxy + classes.

      +

      %typemap(directorin)

      +
      +

      The "directorin" typemap is used for converting arguments in the C++ + director class to the appropriate JNI type before the upcall to Java. + This typemap also specifies the JNI field descriptor for the type in + the "descriptor" attribute. For example, integers are converted as + follows:

      +
      +
      +%typemap(directorin,descriptor="I") int "$input = (jint) $1;"
+
      +
      +

      $input is the SWIG name of the JNI temporary variable + passed to Java in the upcall. The descriptor="I" will put + an I into the JNI field descriptor that identifies the + Java method that will be called from C++. For more about JNI field + descriptors and their importance, refer to the +JNI documentation mentioned earlier. A typemap for C character + strings is:

      +
      +
      +%typemap(directorin,descriptor="Ljava/lang/String;") char *
+  %{ $input = jenv->NewStringUTF($1); %}
+
      +
      +

      User-defined types have the default "descriptor" attribute " +L$packagepath/$javaclassname;" where $packagepath is + the package name passed from the SWIG command line and +$javaclassname is the Java proxy class' name. If the -package + commandline option is not used to specify the package, then + '$packagepath/' will be removed from the resulting output JNI field + descriptor. Do not forget the terminating ';' for JNI field + descriptors starting with 'L'. If the ';' is left out, Java will + generate a "method not found" runtime error.

      +
      +

      %typemap(directorout)

      +
      +

      The "directorout" typemap is used for converting the JNI return type + in the C++ director class to the appropriate C++ type after the upcall + to Java. For example, integers are converted as follows:

      +
      +
      +%typemap(directorout) int %{ $result = (int)$input; %}
+
      +
      +

      $input is the SWIG name of the JNI temporary variable + returned from Java after the upcall. $result is the + resulting output. A typemap for C character strings is:

      +
      +
      +%typemap(directorout) char * {
+  $1 = 0;
+  if ($input) {
+    $result = (char *)jenv->GetStringUTFChars($input, 0);
+    if (!$1) return $null;
+  }
+}
+
      +
      +

      %typemap(javadirectorin)

      +
      +

      Conversion from jtype to jstype for director methods. These are Java + code typemaps which transform the type used in the Java intermediary + JNI class (as specified in the "jtype" typemap) to the Java type used + in the Java module class, proxy classes and type wrapper classes (as + specified in the "jstype" typemap). This typemap provides the + conversion for the parameters in the director methods when calling up + from C++ to Java.

      +

      For primitive types, this typemap is usually specified as:

      +
      +
      +%typemap(javadirectorin) int "$jniinput"
+
      +
      +

      The $jniinput special variable is analogous to +$javainput special variable. It is replaced by the input + parameter name.

      +
      +

      %typemap(javadirectorout)

      +
      +

      Conversion from jstype to jtype for director methods. These are Java + code typemaps which transform the type used in the Java module class, + proxy classes and type wrapper classes (as specified in the "jstype" + typemap) to the type used in the Java intermediary JNI class (as + specified in the "jtype" typemap). This typemap provides the conversion + for the return type in the director methods when returning from the C++ + to Java upcall.

      +

      For primitive types, this typemap is usually specified as:

      +
      +
      +%typemap(javadirectorout) int "$javacall"
+
      +
      +

      The $javacall special variable is analogous to the +$jnicall special variable. It is replaced by the call to the + target Java method. The target method is the method in the Java proxy + class which overrides the virtual C++ method in the C++ base class.

      +
      +

      %typemap(javapackage)

      +
      +

      The "javapackage" typemap is optional; it serves to identify a + class's Java package. This typemap should be used in conjunction with + classes that are defined outside of the current SWIG interface file. + For example:

      +
      +
      +// class Foo is handled in a different interface file:
+%import "Foo.i"
+
+%feature("director") Example;
+
+%inline {
+  class Bar { };
+
+  class Example {
+  public:
+    virtual ~Example();
+    void     ping(Foo *arg1, Bar *arg2);
+  };
+}
+
      +
      +

      Assume that the Foo class is part of the Java package + com.wombat.foo but the above interface file is part of the Java + package com.wombat.example. Without the "javapackage" typemap, + SWIG will assume that the Foo class belongs to com.wombat.example + class. The corrected interface file looks like:

      +
      +
      +// class Foo is handled in a different interface file:
+%import "Foo.i"
+%typemap("javapackage") Foo, Foo *, Foo & "com.wombat.foo";
+%feature("director") Example;
+
+%inline {
+  class Bar { };
+
+  class Example {
+  public:
+    virtual ~Example();
+    void     ping(Foo *arg1, Bar *arg2);
+  };
+}
+
      +
      +

      SWIG looks up the package based on the actual type (plain + Foo, Foo pointer and Foo reference), so it is important to associate + all three types with the desired package. Practically speaking, you + should create a separate SWIG interface file, which is %import-ed into + each SWIG interface file, when you have multiple Java packages. Note + the helper macros below, OTHER_PACKAGE_SPEC and +ANOTHER_PACKAGE_SPEC, which reduce the amount of extra typing. " +TYPE..." is useful when passing templated types to the macro, + since multiargument template types appear to the SWIG preprocessor as + multiple macro arguments.

      +
      +
      +%typemap("javapackage") SWIGTYPE, SWIGTYPE *, SWIGTYPE &
+                                            "package.for.most.classes";
+
+%define OTHER_PACKAGE_SPEC(TYPE...)
+%typemap("javapackage") TYPE, TYPE *, TYPE & "package.for.other.classes";
+%enddef
+
+%define ANOTHER_PACKAGE_SPEC(TYPE...)
+%typemap("javapackage") TYPE, TYPE *, TYPE & "package.for.another.set";
+%enddef
+
+OTHER_PACKAGE_SPEC(Package_2_class_one)
+ANOTHER_PACKAGE_SPEC(Package_3_class_two)
+/* etc */
+
      +
      +

      The basic strategy here is to provide a default package typemap for + the majority of the classes, only providing "javapackage" typemaps for + the exceptions.

      +
      +

      21.10 Typemap Examples

      +

      This section includes a few examples of typemaps. For more examples, + you might look at the files "java.swg" and "typemaps.i +" in the SWIG library.

      +

      21.10.1 Simpler Java enums for + enums without initializers

      +

      The default Proper Java enums + approach to wrapping enums is somewhat verbose. This is to handle all + possible C/C++ enums, in particular enums with initializers. The + generated code can be simplified if the enum being wrapped does not + have any initializers.

      +

      The following shows how to remove the support methods that are + generated by default and instead use the methods in the Java enum base + class java.lang.Enum and java.lang.Class for + marshalling enums between C/C++ and Java. The type used for the + typemaps below is enum SWIGTYPE which is the default type used + for all enums. The "enums.swg" file should be examined in order to see + the original overridden versions of the typemaps.

      +
      +
      +%include "enums.swg"
+
+%typemap(javain) enum SWIGTYPE "$javainput.ordinal()"
+%typemap(javaout) enum SWIGTYPE {
+    return $javaclassname.class.getEnumConstants()[$jnicall];
+  }
+%typemap(javabody) enum SWIGTYPE ""
+
+%inline %{
+  enum HairType { blonde, ginger, brunette };
+  void setHair(HairType h);
+  HairType getHair();
+%}
+
      +
      +

      SWIG will generate the following Java enum, which is somewhat + simpler than the default:

      +
      +
      +public enum HairType {
+  blonde,
+  ginger,
+  brunette;
+}
+
      +
      +

      and the two Java proxy methods will be:

      +
      +
      +public static void setHair(HairType h) {
+  exampleJNI.setHair(h.ordinal());
+}
+
+public static HairType getHair() {
+  return HairType.class.getEnumConstants()[exampleJNI.getHair()];
+}
+
      +
      +

      For marshalling Java enums to C/C++ enums, the ordinal + method is used to convert the Java enum into an integer value for + passing to the JNI layer, see the "javain" typemap. For marshalling + C/C++ enums to Java enums, the C/C++ enum value is cast to an integer + in the C/C++ typemaps (not shown). This integer value is then used to + index into the array of enum constants that the Java language provides. + See the getEnumConstants method in the "javaout" typemap.

      +

      These typemaps can often be used as the default for wrapping enums + as in many cases there won't be any enum initializers. In fact a good + strategy is to always use these typemaps and to specifically handle + enums with initializers using %apply. This would be done by using the + original versions of these typemaps in "enums.swg" under another + typemap name for applying using %apply.

      +

      21.10.2 Handling C++ exception + specifications as Java exceptions

      +

      This example demonstrates various ways in which C++ exceptions can + be tailored and converted into Java exceptions. Let's consider a simple + file class SimpleFile and an exception class FileException + which it may throw on error:

      +
      +
      +%include "std_string.i" // for std::string typemaps
+#include <string>
+
+class FileException {
+  std::string message;
+public:
+  FileException(const std::string& msg) : message(msg) {}
+  std::string what() {
+    return message;
+  }
+};
+
+class SimpleFile {
+  std::string filename;
+public:
+  SimpleFile(const std::string& filename) : filename(filename) {}
+  void open() throw(FileException) {
+  ...
+  }
+};
+
      +
      +

      As the open method has a C++ exception specification, SWIG + will parse this and know that the method can throw an exception. The +"throws" typemap is then used when SWIG encounters an exception + specification. The default generic "throws" typemap looks like this:

      +
      +
      +%typemap(throws) SWIGTYPE, SWIGTYPE &, SWIGTYPE *, SWIGTYPE [ANY] %{
+  SWIG_JavaThrowException(jenv, SWIG_JavaRuntimeException,
+                          "C++ $1_type exception thrown");
+  return $null;
+%}
+
      +
      +

      Basically SWIG will generate a C++ try catch block and the body of + the "throws" typemap constitutes the catch block. The above typemap + calls a SWIG supplied method which throws a +java.lang.RuntimeException. This exception class is a runtime + exception and therefore not a checked exception. If, however, we wanted + to throw a checked exception, say java.io.IOException, then we + could use the following typemap:

      +
      +
      +%typemap(throws, throws="java.io.IOException") FileException {
+  jclass excep = jenv->FindClass("java/io/IOException");
+  if (excep)
+    jenv->ThrowNew(excep, $1.what().c_str());
+  return $null;
+}
+
      +
      +

      Note that this typemap uses the 'throws' +typemap attribute to ensure a throws clause is generated. The + generated proxy method then specifies the checked exception by + containing java.io.IOException in the throws clause:

      +
      +
      +public class SimpleFile {
+  ...
+  public void open() throws java.io.IOException { ... }
+}
+
      +
      +

      Lastly, if you don't want to map your C++ exception into one of the + standard Java exceptions, the C++ class can be wrapped and turned into + a custom Java exception class. If we go back to our example, the first + thing we must do is get SWIG to wrap FileException and ensure + that it derives from java.lang.Exception. Additionally, we + might want to override the java.lang.Exception.getMessage() + method. The typemaps to use then are as follows:

      +
      +
      +%typemap(javabase) FileException "java.lang.Exception";
+%typemap(javacode) FileException %{
+  public String getMessage() {
+    return what();
+  }
+%}
+
      +
      +

      This generates:

      +
      +
      +public class FileException extends java.lang.Exception {
+  ...
+  public String getMessage() {
+    return what();
+  }
+
+  public FileException(String msg) { ... }
+
+  public String what() {
+    return exampleJNI.FileException_what(swigCPtr, this);
+  }
+}
+
      +
      +

      We could alternatively have used %rename to rename +what() into getMessage().

      +

      21.10.3 NaN Exception - + exception handling for a particular type

      +

      A Java exception can be thrown from any Java or JNI code. Therefore, + as most typemaps contain either Java or JNI code, just about any + typemap could throw an exception. The following example demonstrates + exception handling on a type by type basis by checking for 'Not a + number' (NaN) whenever a parameter of type float is wrapped.

      +

      Consider the following C++ code:

      +
      +
      +bool calculate(float first, float second);
+
      +
      +

      To validate every float being passed to C++, we could + precede the code being wrapped by the following typemap which throws a + runtime exception whenever the float is 'Not a Number':

      +
      +
      +%module example
+%typemap(javain) float "$module.CheckForNaN($javainput)"
+%pragma(java) modulecode=%{
+  /** Simply returns the input value unless it is not a number,
+      whereupon an exception is thrown. */
+  static protected float CheckForNaN(float num) {
+    if (Float.isNaN(num))
+      throw new RuntimeException("Not a number");
+    return num;
+  }
+%}
+
      +
      +

      Note that the CheckForNaN support method has been added to + the module class using the modulecode pragma. The following + shows the generated code of interest:

      +
      +
      +public class example {
+  ...
+
+  /** Simply returns the input value unless it is not a number,
+      whereupon an exception is thrown. */
+  static protected float CheckForNaN(float num) {
+    if (Float.isNaN(num))
+      throw new RuntimeException("Not a number");
+    return num;
+  }
+
+  public static boolean calculate(float first, float second) {
+    return exampleJNI.calculate(example.CheckForNaN(first), example.CheckForNaN(second));
+  }
+}
+
      +
      +

      Note that the "javain" typemap is used for every occurrence of a +float being used as an input. Of course, we could have targeted the + typemap at a particular parameter by using float first, say, + instead of just float.

      +

      The exception checking could alternatively have been placed into the + 'pre' attribute that the "javain" typemap supports. The "javain" + typemap above could be replaced with the following:

      +
      +
      +%typemap(javain, pre="    $module.CheckForNaN($javainput);") float "$javainput"
+
      +
      +

      which would modify the calculate function to instead be + generated as:

      +
      +
      +public class example {
+  ...
+  public static boolean calculate(float first, float second) {
+    example.CheckForNaN(first);
+    example.CheckForNaN(second);
+    {
+      return exampleJNI.calculate(first, second);
+    }
+  }
+}
+
      +
      +

      See the Date marshalling example + for an example using further "javain" typemap attributes.

      +

      If we decide that what we actually want is a checked exception + instead of a runtime exception, we can change this easily enough. The + proxy method that uses float as an input, must then add the + exception class to the throws clause. SWIG can handle this as it + supports the 'throws' typemap attribute + for specifying classes for the throws clause. Thus we can modify the + pragma and the typemap for the throws clause:

      +
      +
      +%typemap(javain, throws="java.lang.Exception") float "$module.CheckForNaN($javainput)"
+%pragma(java) modulecode=%{
+  /** Simply returns the input value unless it is not a number,
+      whereupon an exception is thrown. */
+  static protected float CheckForNaN(float num) throws java.lang.Exception {
+    if (Float.isNaN(num))
+      throw new RuntimeException("Not a number");
+    return num;
+  }
+%}
+
      +
      +

      The calculate method now has a throws clause and even + though the typemap is used twice for both float first and +float second, the throws clause contains a single instance of +java.lang.Exception:

      +
      +
      +public class example {
+  ...
+
+  /** Simply returns the input value unless it is not a number,
+      whereupon an exception is thrown. */
+  static protected float CheckForNaN(float num) throws java.lang.Exception {
+    if (Float.isNaN(num))
+      throw new RuntimeException("Not a number");
+    return num;
+  }
+
+  public static boolean calculate(float first, float second) throws java.lang.Exception {
+    return exampleJNI.calculate(example.CheckForNaN(first), example.CheckForNaN(second));
+  }
+}
+
      +
      +

      If we were a martyr to the JNI cause, we could replace the succinct + code within the "javain" typemap with a few pages of JNI code. If we + had, we would have put it in the "in" typemap which, like all JNI and + Java typemaps, also supports the 'throws' attribute.

      +

      21.10.4 Converting Java + String arrays to char **

      +

      A common problem in many C programs is the processing of command + line arguments, which are usually passed in an array of NULL terminated + strings. The following SWIG interface file allows a Java String array + to be used as a char ** object.

      +
      +
      +%module example
+
+/* This tells SWIG to treat char ** as a special case when used as a parameter
+   in a function call */
+%typemap(in) char ** (jint size) {
+    int i = 0;
+    size = (*jenv)->GetArrayLength(jenv, $input);
+    $1 = (char **) malloc((size+1)*sizeof(char *));
+    /* make a copy of each string */
+    for (i = 0; i<size; i++) {
+        jstring j_string = (jstring)(*jenv)->GetObjectArrayElement(jenv, $input, i);
+        const char * c_string = (*jenv)->GetStringUTFChars(jenv, j_string, 0);
+        $1[i] = malloc((strlen(c_string)+1)*sizeof(char));
+        strcpy($1[i], c_string);
+        (*jenv)->ReleaseStringUTFChars(jenv, j_string, c_string);
+        (*jenv)->DeleteLocalRef(jenv, j_string);
+    }
+    $1[i] = 0;
+}
+
+/* This cleans up the memory we malloc'd before the function call */
+%typemap(freearg) char ** {
+    int i;
+    for (i=0; i<size$argnum-1; i++)
+      free($1[i]);
+    free($1);
+}
+
+/* This allows a C function to return a char ** as a Java String array */
+%typemap(out) char ** {
+    int i;
+    int len=0;
+    jstring temp_string;
+    const jclass clazz = (*jenv)->FindClass(jenv, "java/lang/String");
+
+    while ($1[len]) len++;    
+    jresult = (*jenv)->NewObjectArray(jenv, len, clazz, NULL);
+    /* exception checking omitted */
+
+    for (i=0; i<len; i++) {
+      temp_string = (*jenv)->NewStringUTF(jenv, *result++);
+      (*jenv)->SetObjectArrayElement(jenv, jresult, i, temp_string);
+      (*jenv)->DeleteLocalRef(jenv, temp_string);
+    }
+}
+
+/* These 3 typemaps tell SWIG what JNI and Java types to use */
+%typemap(jni) char ** "jobjectArray"
+%typemap(jtype) char ** "String[]"
+%typemap(jstype) char ** "String[]"
+
+/* These 2 typemaps handle the conversion of the jtype to jstype typemap type
+   and vice versa */
+%typemap(javain) char ** "$javainput"
+%typemap(javaout) char ** {
+    return $jnicall;
+  }
+
+/* Now a few test functions */
+%inline %{
+
+int print_args(char **argv) {
+    int i = 0;
+    while (argv[i]) {
+         printf("argv[%d] = %s\n", i, argv[i]);
+         i++;
+    }
+    return i;
+}
+
+char **get_args() {
+  static char *values[] = { "Dave", "Mike", "Susan", "John", "Michelle", 0};
+  return &values[0];
+}
+
+%}
+
      +
      +

      Note that the 'C' JNI calling convention is used. Checking for any + thrown exceptions after JNI function calls has been omitted. When this + module is compiled, our wrapped C functions can be used by the + following Java program:

      +
      +
      +// File runme.java
+
+public class runme {
+
+  static {
+    try {
+     System.loadLibrary("example");
+    } catch (UnsatisfiedLinkError e) {
+      System.err.println("Native code library failed to load. " + e);
+      System.exit(1);
+    }
+  }
+
+  public static void main(String argv[]) {
+    String animals[] = {"Cat","Dog","Cow","Goat"};
+    example.print_args(animals);
+    String args[] = example.get_args();
+    for (int i=0; i<args.length; i++)
+        System.out.println(i + ":" + args[i]);
+  }
+}
+
      +
      +

      When compiled and run we get:

      +
      +
      +$ java runme
+argv[0] = Cat
+argv[1] = Dog
+argv[2] = Cow
+argv[3] = Goat
+0:Dave
+1:Mike
+2:Susan
+3:John
+4:Michelle
+
      +
      +

      In the example, a few different typemaps are used. The "in" typemap + is used to receive an input argument and convert it to a C array. Since + dynamic memory allocation is used to allocate memory for the array, the + "freearg" typemap is used to later release this memory after the + execution of the C function. The "out" typemap is used for function + return values. Lastly the "jni", "jtype" and "jstype" typemaps are also + required to specify what Java types to use.

      +

      21.10.5 Expanding a Java object + to multiple arguments

      +

      Suppose that you had a collection of C functions with arguments such + as the following:

      +
      +
      +int foo(int argc, char **argv);
+
      +
      +

      In the previous example, a typemap was written to pass a Java String + array as the char **argv. This allows the function to be used + from Java as follows:

      +
      +
      +example.foo(4, new String[]{"red", "green", "blue", "white"});
+
      +
      +

      Although this works, it's a little awkward to specify the argument + count. To fix this, a multi-argument typemap can be defined. This is + not very difficult--you only have to make slight modifications to the + previous example's typemaps:

      +
      +
      +%typemap(in) (int argc, char **argv) {
+    int i = 0;
+    $1 = (*jenv)->GetArrayLength(jenv, $input);
+    $2 = (char **) malloc(($1+1)*sizeof(char *));
+    /* make a copy of each string */
+    for (i = 0; i<$1; i++) {
+        jstring j_string = (jstring)(*jenv)->GetObjectArrayElement(jenv, $input, i);
+        const char * c_string = (*jenv)->GetStringUTFChars(jenv, j_string, 0);
+        $2[i] = malloc((strlen(c_string)+1)*sizeof(char));
+        strcpy($2[i], c_string);
+        (*jenv)->ReleaseStringUTFChars(jenv, j_string, c_string);
+        (*jenv)->DeleteLocalRef(jenv, j_string);
+    }
+    $2[i] = 0;
+}
+
+%typemap(freearg) (int argc, char **argv) {
+    int i;
+    for (i=0; i<$1-1; i++)
+      free($2[i]);
+    free($2);
+}
+
+%typemap(jni) (int argc, char **argv) "jobjectArray"
+%typemap(jtype) (int argc, char **argv) "String[]"
+%typemap(jstype) (int argc, char **argv) "String[]"
+
+%typemap(javain) (int argc, char **argv) "$javainput"
+
      +
      +

      When writing a multiple-argument typemap, each of the types is + referenced by a variable such as $1 or $2. The + typemap code simply fills in the appropriate values from the supplied + Java parameter.

      +

      With the above typemap in place, you will find it no longer + necessary to supply the argument count. This is automatically set by + the typemap code. For example:

      +
      +
      +example.foo(new String[]{"red", "green", "blue", "white"});
+
      +
      +

      21.10.6 Using typemaps + to return arguments

      +

      A common problem in some C programs is that values may be returned + in function parameters rather than in the return value of a function. + The typemaps.i file defines INPUT, OUTPUT and INOUT typemaps + which can be used to solve some instances of this problem. This library + file uses an array as a means of moving data to and from Java when + wrapping a C function that takes non const pointers or non const + references as parameters.

      +

      Now we are going to outline an alternative approach to using arrays + for C pointers. The INOUT typemap uses a double[] array for + receiving and returning the double* parameters. In this + approach we are able to use a Java class myDouble instead of +double[] arrays where the C pointer double* is required.

      +

      Here is our example function:

      +
      +
      +/* Returns a status value and two values in out1 and out2 */
+int spam(double a, double b, double *out1, double *out2);
+
      +
      +

      If we define a structure MyDouble containing a double + member variable and use some typemaps we can solve this problem. For + example we could put the following through SWIG:

      +
      +
      +%module example
+
+/* Define a new structure to use instead of double * */
+%inline %{
+typedef struct {
+    double value;
+} MyDouble;
+%}
+
+
+%{
+/* Returns a status value and two values in out1 and out2 */
+int spam(double a, double b, double *out1, double *out2) {
+  int status = 1;
+  *out1 = a*10.0;
+  *out2 = b*100.0;
+  return status;
+};
+%}
+
+/* 
+This typemap will make any double * function parameters with name OUTVALUE take an
+argument of MyDouble instead of double *. This will 
+allow the calling function to read the double * value after returning from the function.
+*/
+%typemap(in) double *OUTVALUE {
+    jclass clazz = jenv->FindClass("MyDouble");
+    jfieldID fid = jenv->GetFieldID(clazz, "swigCPtr", "J");
+    jlong cPtr = jenv->GetLongField($input, fid);
+    MyDouble *pMyDouble = NULL;
+    *(MyDouble **)&pMyDouble = *(MyDouble **)&cPtr;
+    $1 = &pMyDouble->value;
+}
+
+%typemap(jtype) double *OUTVALUE "MyDouble"
+%typemap(jstype) double *OUTVALUE "MyDouble"
+%typemap(jni) double *OUTVALUE "jobject"
+
+%typemap(javain) double *OUTVALUE "$javainput"
+
+/* Now we apply the typemap to the named variables */
+%apply double *OUTVALUE { double *out1, double *out2 };
+int spam(double a, double b, double *out1, double *out2);
+
      +
      +

      Note that the C++ JNI calling convention has been used this time and + so must be compiled as C++ and the -c++ commandline must be passed to + SWIG. JNI error checking has been omitted for clarity.

      +

      What the typemaps do are make the named double* function + parameters use our new MyDouble wrapper structure. The "in" + typemap takes this structure, gets the C++ pointer to it, takes the +double value member variable and passes it to the C++ spam + function. In Java, when the function returns, we use the SWIG created +getValue() function to get the output value. The following Java + program demonstrates this:

      +
      +
      +// File: runme.java
+
+public class runme {
+
+  static {
+    try {
+      System.loadLibrary("example");
+    } catch (UnsatisfiedLinkError e) {
+      System.err.println("Native code library failed to load. " + e);
+      System.exit(1);
+    }
+  }
+
+  public static void main(String argv[]) {
+    MyDouble out1 = new MyDouble();
+    MyDouble out2 = new MyDouble();
+    int ret = example.spam(1.2, 3.4, out1, out2);
+    System.out.println(ret + "  " + out1.getValue() + "  " + out2.getValue());
+  }
+}
+
      +
      +

      When compiled and run we get:

      +
      +
      +$ java runme
+1 12.0  340.0
+
      +
      +

      21.10.7 Adding Java downcasts to + polymorphic return types

      +

      SWIG support for polymorphism works in that the appropriate virtual + function is called. However, the default generated code does not allow + for downcasting. Let's examine this with the following code:

      +
      +
      +%include "std_string.i"
+
+#include <iostream>
+using namespace std;
+class Vehicle {
+public:
+    virtual void start() = 0;
+...
+};
+
+class Ambulance : public Vehicle {
+    string vol;
+public:
+    Ambulance(string volume) : vol(volume) {}
+    virtual void start() {
+        cout << "Ambulance started" << endl;
+    }
+    void sound_siren() {
+        cout << vol << " siren sounded!" << endl;
+    }
+...
+};
+
+Vehicle *vehicle_factory() {
+    return new Ambulance("Very loud");
+}
+
      +
      +

      If we execute the following Java code:

      +
      +
      +Vehicle vehicle = example.vehicle_factory();
+vehicle.start();
+
+Ambulance ambulance = (Ambulance)vehicle;
+ambulance.sound_siren();
+
      +
      +

      We get:

      +
      +
      +Ambulance started
+java.lang.ClassCastException
+        at runme.main(runme.java:16)
+
      +
      +

      Even though we know from examination of the C++ code that +vehicle_factory returns an object of type Ambulance, we + are not able to use this knowledge to perform the downcast in Java. + This occurs because the runtime type information is not completely + passed from C++ to Java when returning the type from +vehicle_factory(). Usually this is not a problem as virtual + functions do work by default, such as in the case of start(). + There are a few solutions to getting downcasts to work.

      +

      The first is not to use a Java cast but a call to C++ to make the + cast. Add this to your code:

      +
      +
      +%exception Ambulance::dynamic_cast(Vehicle *vehicle) {
+    $action
+    if (!result) {
+        jclass excep = jenv->FindClass("java/lang/ClassCastException");
+        if (excep) {
+            jenv->ThrowNew(excep, "dynamic_cast exception");
+        }
+    }
+}
+%extend Ambulance {
+    static Ambulance *dynamic_cast(Vehicle *vehicle) {
+        return dynamic_cast<Ambulance *>(vehicle);
+    }
+};
+
      +
      +

      It would then be used from Java like this

      +
      +
      +Ambulance ambulance = Ambulance.dynamic_cast(vehicle);
+ambulance.sound_siren();
+
      +
      +

      Should vehicle not be of type ambulance then a + Java ClassCastException is thrown. The next solution is a + purer solution in that Java downcasts can be performed on the types. + Add the following before the definition of vehicle_factory:

      +
      +
      +%typemap(out) Vehicle * {
+    Ambulance *downcast = dynamic_cast<Ambulance *>($1);
+    *(Ambulance **)&$result = downcast;
+}
+
+%typemap(javaout) Vehicle * {
+    return new Ambulance($jnicall, $owner);
+  }
+
      +
      +

      Here we are using our knowledge that vehicle_factory always + returns type Ambulance so that the Java proxy is created as a + type Ambulance. If vehicle_factory can manufacture + any type of Vehicle and we want to be able to downcast using + Java casts for any of these types, then a different approach is needed. + Consider expanding our example with a new Vehicle type and a more + flexible factory function:

      +
      +
      +class FireEngine : public Vehicle {
+public:
+    FireEngine() {}
+    virtual void start() {
+        cout << "FireEngine started" << endl;
+    }
+    void roll_out_hose() {
+        cout << "Hose rolled out" << endl;
+    }
+ ...
+};
+Vehicle *vehicle_factory(int vehicle_number) {
+    if (vehicle_number == 0)
+        return new Ambulance("Very loud");
+    else
+        return new FireEngine();
+}
+
      +
      +

      To be able to downcast with this sort of Java code:

      +
      +
      +FireEngine fireengine = (FireEngine)example.vehicle_factory(1);
+fireengine.roll_out_hose();
+Ambulance ambulance = (Ambulance)example.vehicle_factory(0);
+ambulance.sound_siren();
+
      +
      +

      the following typemaps targeted at the vehicle_factory + function will achieve this. Note that in this case, the Java class is + constructed using JNI code rather than passing a pointer across the JNI + boundary in a Java long for construction in Java code.

      +
      +
      +%typemap(jni) Vehicle *vehicle_factory "jobject"
+%typemap(jtype) Vehicle *vehicle_factory "Vehicle"
+%typemap(jstype) Vehicle *vehicle_factory "Vehicle"
+%typemap(javaout) Vehicle *vehicle_factory {
+    return $jnicall;
+  }
+
+%typemap(out) Vehicle *vehicle_factory {
+    Ambulance *ambulance = dynamic_cast<Ambulance *>($1);
+    FireEngine *fireengine = dynamic_cast<FireEngine *>($1);
+    if (ambulance) {
+        // call the Ambulance(long cPtr, boolean cMemoryOwn) constructor
+        jclass clazz = jenv->FindClass("Ambulance");
+        if (clazz) {
+            jmethodID mid = jenv->GetMethodID(clazz, "<init>", "(JZ)V");
+            if (mid) {
+                jlong cptr = 0;
+                *(Ambulance **)&cptr = ambulance; 
+                $result = jenv->NewObject(clazz, mid, cptr, false);
+            }
+        }
+    } else if (fireengine) {
+        // call the FireEngine(long cPtr, boolean cMemoryOwn) constructor
+        jclass clazz = jenv->FindClass("FireEngine");
+        if (clazz) {
+            jmethodID mid = jenv->GetMethodID(clazz, "<init>", "(JZ)V");
+            if (mid) {
+                jlong cptr = 0;
+                *(FireEngine **)&cptr = fireengine; 
+                $result = jenv->NewObject(clazz, mid, cptr, false);
+            }
+        }
+    }
+    else {
+        cout << "Unexpected type " << endl;
+    }
+
+    if (!$result)
+        cout << "Failed to create new java object" << endl;
+}
+
      +
      +

      Better error handling would need to be added into this code. There + are other solutions to this problem, but this last example demonstrates + some more involved JNI code. SWIG usually generates code which + constructs the proxy classes using Java code as it is easier to handle + error conditions and is faster. Note that the JNI code above uses a + number of string lookups to call a constructor, whereas this would not + occur using byte compiled Java code.

      +

      21.10.8 Adding an equals method + to the Java classes

      +

      When a pointer is returned from a JNI function, it is wrapped using + a new Java proxy class or type wrapper class. Even when the pointers + are the same, it will not be possible to know that the two Java classes + containing those pointers are actually the same object. It is common in + Java to use the equals() method to check whether two objects + are equivalent. The equals() method is usually accompanied by + a hashCode() method in order to fulfill the requirement that + the hash code is equal for equal objects. Pure Java code methods like + these can be easily added:

      +
      +
      +%typemap(javacode) SWIGTYPE %{
+  public boolean equals(Object obj) {
+    boolean equal = false;
+    if (obj instanceof $javaclassname)
+      equal = ((($javaclassname)obj).swigCPtr == this.swigCPtr);
+    return equal;
+  }
+  public int hashCode() {
+     return (int)getPointer();
+  }
+%}
+
+class Foo { };
+Foo* returnFoo(Foo *foo) { return foo; }
+
      +
      +

      The following would display false without the javacode + typemap above. With the typemap defining the equals method the + result is true.

      +
      +
      +Foo foo1 = new Foo();
+Foo foo2 = example.returnFoo(foo1);
+System.out.println("foo1? " + foo1.equals(foo2));
+
      +
      +

      21.10.9 Void pointers and a common Java + base class

      +

      One might wonder why the common code that SWIG emits for the proxy + and type wrapper classes is not pushed into a base class. The reason is + that although swigCPtr could be put into a common base class + for all classes wrapping C structures, it would not work for C++ + classes involved in an inheritance chain. Each class derived from a + base needs a separate swigCPtr because C++ compilers sometimes + use a different pointer value when casting a derived class to a base. + Additionally as Java only supports single inheritance, it would not be + possible to derive wrapped classes from your own pure Java classes if + the base class has been 'used up' by SWIG. However, you may want to + move some of the common code into a base class. Here is an example + which uses a common base class for all proxy classes and type wrapper + classes:

      +
      +
      +%typemap(javabase) SWIGTYPE, SWIGTYPE *, SWIGTYPE &, SWIGTYPE [], 
+                                                         SWIGTYPE (CLASS::*) "SWIG"
+
+%typemap(javacode) SWIGTYPE, SWIGTYPE *, SWIGTYPE &, SWIGTYPE [], 
+                                                         SWIGTYPE (CLASS::*) %{
+  protected long getPointer() {
+    return swigCPtr;
+  }
+%}
+
      +
      +

      Define new base class called SWIG:

      +
      +
      +public abstract class SWIG {
+  protected abstract long getPointer();
+
+  public boolean equals(Object obj) {
+    boolean equal = false;
+    if (obj instanceof SWIG)
+      equal = (((SWIG)obj).getPointer() == this.getPointer());
+    return equal;
+  }
+  
+  SWIGTYPE_p_void getVoidPointer() {
+    return new SWIGTYPE_p_void(getPointer(), false);
+  }
+}
+
      +
      +

      This example contains some useful functionality which you may want + in your code.

      +
        +
      • It has an equals() method. Unlike the previous example, + the method code isn't replicated in all classes.
        • +
      • It also has a function which effectively implements a cast from the + type of the proxy/type wrapper class to a void pointer. This is + necessary for passing a proxy class or a type wrapper class to a + function that takes a void pointer.
        • +
      +

      21.10.10 Struct pointer to + pointer

      +

      Pointers to pointers are often used as output parameters in C + factory type functions. These are a bit more tricky to handle. Consider + the following situation where a Butler can be hired and fired:

      +
      +
      +typedef struct {
+  int hoursAvailable;
+  char *greeting;
+} Butler;
+
+// Note: HireButler will allocate the memory 
+// The caller must free the memory by calling FireButler()!!
+extern int HireButler(Butler **ppButler);
+extern void FireButler(Butler *pButler);
+
      +
      +

      C code implementation:

      +
      +
      +int HireButler(Butler **ppButler) {
+  Butler *pButler = (Butler *)malloc(sizeof(Butler));
+  pButler->hoursAvailable = 24;
+  pButler->greeting = (char *)malloc(32);
+  strcpy(pButler->greeting, "At your service Sir");
+  *ppButler = pButler;
+  return 1;
+}
+void FireButler(Butler *pButler) {
+  free(pButler->greeting);
+  free(pButler);
+}
+
      +
      +

      Let's take two approaches to wrapping this code. The first is to + provide a functional interface, much like the original C interface. The + following Java code shows how we intend the code to be used:

      +
      +
      +    Butler jeeves = new Butler();
+    example.HireButler(jeeves);
+    System.out.println("Greeting:     " + jeeves.getGreeting());
+    System.out.println("Availability: " + jeeves.getHoursAvailable() + " hours per day");
+    example.FireButler(jeeves);
+
      +
      +

      Resulting in the following output when run:

      +
      +
      +Greeting:     At your service Sir
+Availability: 24 hours per day
+
      +
      +

      Note the usage is very much like it would be used if we were writing + C code, that is, explicit memory management is needed. No C memory is + allocated in the construction of the Butler proxy class and + the proxy class will not destroy the underlying C memory when it is + collected. A number of typemaps and features are needed to implement + this approach. The following interface file code should be placed + before SWIG parses the above C code.

      +
      +
      +%module example
+
+// Do not generate the default proxy constructor or destructor
+%nodefaultctor Butler;
+%nodefaultdtor Butler;
+
+// Add in pure Java code proxy constructor
+%typemap(javacode) Butler %{
+  /** This constructor creates the proxy which initially does not create nor own any C memory */
+  public Butler() {
+    this(0, false);
+  }
+%}
+
+// Type typemaps for marshalling Butler **
+%typemap(jni) Butler ** "jobject"
+%typemap(jtype) Butler ** "Butler"
+%typemap(jstype) Butler ** "Butler"
+
+// Typemaps for Butler ** as a parameter output type
+%typemap(in) Butler ** (Butler *ppButler = 0) %{
+  $1 = &ppButler;
+%}
+%typemap(argout) Butler ** {
+  // Give Java proxy the C pointer (of newly created object)
+  jclass clazz = (*jenv)->FindClass(jenv, "Butler");
+  jfieldID fid = (*jenv)->GetFieldID(jenv, clazz, "swigCPtr", "J");
+  jlong cPtr = 0;
+  *(Butler **)&cPtr = *$1;
+  (*jenv)->SetLongField(jenv, $input, fid, cPtr);
+}
+%typemap(javain) Butler ** "$javainput"
+
      +
      +

      Note that the JNI code sets the proxy's swigCPtr member + variable to point to the newly created object. The swigCMemOwn + remains unchanged (at false), so that the proxy does not own the + memory.

      +

      Note: The old %nodefault directive disabled the default constructor + and destructor at the same time. This is unsafe in most of the cases, + and you can use the explicit %nodefaultctor and %nodefaultdtor + directives to achieve the same result if needed.

      +

      The second approach offers a more object oriented interface to the + Java user. We do this by making the Java proxy class's constructor call + the HireButler() method to create the underlying C object. + Additionally we get the proxy to take ownership of the memory so that + the finalizer will call the FireButler() function. The proxy + class will thus take ownership of the memory and clean it up when no + longer needed. We will also prevent the user from being able to + explicitly call the HireButler() and FireButler() + functions. Usage from Java will simply be:

      +
      +
      +Butler jeeves = new Butler();
+System.out.println("Greeting:     " + jeeves.getGreeting());
+System.out.println("Availability: " + jeeves.getHoursAvailable() + " hours per day");
+
      +
      +

      Note that the Butler class is used just like any other Java class + and no extra coding by the user needs to be written to clear up the + underlying C memory as the finalizer will be called by the garbage + collector which in turn will call the FireButler() function. + To implement this, we use the above interface file code but remove the +javacode typemap and add the following:

      +
      +
      +// Don't expose the memory allocation/de-allocation functions
+%ignore FireButler(Butler *pButler);
+%ignore HireButler(Butler **ppButler);
+
+// Add in a custom proxy constructor and destructor
+%extend Butler {
+  Butler() {
+    Butler *pButler = 0;
+    HireButler(&pButler);
+    return pButler;
+  }
+  ~Butler() {
+     FireButler($self);
+   }
+}
+
      +
      +

      Note that the code in %extend is using a C++ type + constructor and destructor, yet the generated code will still compile + as C code, see Adding member + functions to C structures. The C functional interface has been + completely morphed into an object-oriented interface and the Butler + class would behave much like any pure Java class and feel more natural + to Java users.

      +

      21.10.11 + Memory management when returning references to member variables

      +

      This example shows how to prevent premature garbage collection of + objects when the underlying C++ class returns a pointer or reference to + a member variable.

      +

      Consider the following C++ code:

      +
      +
      +struct Wheel {
+  int size;
+  Wheel(int sz) : size(sz) {}
+};
+
+class Bike {
+  Wheel wheel;
+public:
+  Bike(int val) : wheel(val) {}
+  Wheel& getWheel() { return wheel; }
+};
+
      +
      +

      and the following usage from Java after running the code through + SWIG:

      +
      +
      +    Wheel wheel = new Bike(10).getWheel();
+    System.out.println("wheel size: " + wheel.getSize());
+    // Simulate a garbage collection
+    System.gc();
+    System.runFinalization();
+    System.out.println("wheel size: " + wheel.getSize());
+
      +
      +

      Don't be surprised that if the resulting output gives strange + results such as...

      +
      +
      +wheel size: 10
+wheel size: 135019664
+
      +
      +

      What has happened here is the garbage collector has collected the +Bike instance as it doesn't think it is needed any more. The proxy + instance, wheel, contains a reference to memory that was + deleted when the Bike instance was collected. In order to + prevent the garbage collector from collecting the Bike + instance a reference to the Bike must be added to the +wheel instance. You can do this by adding the reference when the +getWheel() method is called using the following typemaps.

      +
      +
      +%typemap(javacode) Wheel %{
+  // Ensure that the GC doesn't collect any Bike instance set from Java
+  private Bike bikeReference;
+  protected void addReference(Bike bike) {
+    bikeReference = bike;
+  }
+%}
+
+// Add a Java reference to prevent premature garbage collection and resulting use
+// of dangling C++ pointer. Intended for methods that return pointers or
+// references to a member variable.
+%typemap(javaout) Wheel& getWheel {
+    long cPtr = $jnicall;
+    $javaclassname ret = null;
+    if (cPtr != 0) {
+      ret = new $javaclassname(cPtr, $owner);
+      ret.addReference(this);
+    }
+    return ret;
+  }
+
      +
      +

      The code in the first typemap gets added to the Wheel proxy + class. The code in the second typemap constitutes the bulk of the code + in the generated getWheel() function:

      +
      +
      +public class Wheel {
+  ...
+  // Ensure that the GC doesn't collect any bike set from Java 
+  private Bike bikeReference;
+  protected void addReference(Bike bike) {
+    bikeReference = bike;
+  }
+}
+
+public class Bike {
+  ...
+  public Wheel getWheel() {
+    long cPtr = exampleJNI.Bike_getWheel(swigCPtr, this);
+    Wheel ret = null;
+    if (cPtr != 0) {
+      ret = new Wheel(cPtr, false);
+      ret.addReference(this);
+    }
+    return ret;
+  }
+}
+
      +
      +

      Note the addReference call.

      +

      21.10.12 Memory + management for objects passed to the C++ layer

      +

      Managing memory can be tricky when using C++ and Java proxy classes. + The previous example shows one such case and this example looks at + memory management for a class passed to a C++ method which expects the + object to remain in scope after the function has returned. Consider the + following two C++ classes:

      +
      +
      +struct Element {
+  int value;
+  Element(int val) : value(val) {}
+};
+class Container {
+  Element* element;
+public:
+  Container() : element(0) {}
+  void setElement(Element* e) { element = e; }
+  Element* getElement() { return element; }
+};
+
      +
      +

      and usage from C++

      +
      +
      +    Container container;
+    Element element(20);
+    container.setElement(&element);
+    cout << "element.value: " << container.getElement()->value << endl;
+
      +
      +

      and more or less equivalent usage from Java

      +
      +
      +    Container container = new Container();
+    container.setElement(new Element(20));
+    System.out.println("element value: " + container.getElement().getValue());
+
      +
      +

      The C++ code will always print out 20, but the value printed out may + not be this in the Java equivalent code. In order to understand why, + consider a garbage collection occuring...

      +
      +
      +    Container container = new Container();
+    container.setElement(new Element(20));
+    // Simulate a garbage collection
+    System.gc();
+    System.runFinalization();
+    System.out.println("element value: " + container.getElement().getValue());
+
      +
      +

      The temporary element created with new Element(20) could + get garbage collected which ultimately means the container + variable is holding a dangling pointer, thereby printing out any old + random value instead of the expected value of 20. One solution is to + add in the appropriate references in the Java layer...

      +
      +
      +public class Container {
+
+  ...
+
+  // Ensure that the GC doesn't collect any Element set from Java
+  // as the underlying C++ class stores a shallow copy
+  private Element elementReference;
+  private long getCPtrAndAddReference(Element element) {
+    elementReference = element;
+    return Element.getCPtr(element);
+  }
+
+  public void setElement(Element e) {
+    exampleJNI.Container_setElement(swigCPtr, this, getCPtrAndAddReference(e), e);
+  }
+}
+
      +
      +

      The following typemaps will generate the desired code. The 'javain' + typemap matches the input parameter type for the setElement + method. The 'javacode' typemap simply adds in the specified code into + the Java proxy class.

      +
      +
      +%typemap(javain) Element *e "getCPtrAndAddReference($javainput)"
+
+%typemap(javacode) Container %{
+  // Ensure that the GC doesn't collect any element set from Java
+  // as the underlying C++ class stores a shallow copy
+  private Element elementReference;
+  private long getCPtrAndAddReference(Element element) {
+    elementReference = element;
+    return Element.getCPtr(element);
+  }
+%}
+
      +
      +

      21.10.13 Date marshalling using + the javain typemap and associated attributes

      +

      The NaN Exception example is a + simple example of the "javain" typemap and its 'pre' attribute. This + example demonstrates how a C++ date class, say CDate, can be + mapped onto the standard Java date class, +java.util.GregorianCalendar by using the 'pre', 'post' and + 'pgcppname' attributes of the "javain" typemap. The idea is that the +GregorianCalendar is used wherever the C++ API uses a CDate +. Let's assume the code being wrapped is as follows:

      +
      +
      +class CDate {
+public:
+  CDate(int year, int month, int day);
+  int getYear();
+  int getMonth();
+  int getDay();
+  ...
+};
+struct Action {
+  static int doSomething(const CDate &dateIn, CDate &dateOut);
+  Action(const CDate &date, CDate &dateOut);
+};
+
      +
      +

      Note that dateIn is const and therefore read only and +dateOut is a non-const output type.

      +

      First let's look at the code that is generated by default, where the + Java proxy class CDate is used in the proxy interface:

      +
      +
      +public class Action {
+  ...
+  public static int doSomething(CDate dateIn, CDate dateOut) {
+    return exampleJNI.Action_doSomething(CDate.getCPtr(dateIn), dateIn, 
+                                         CDate.getCPtr(dateOut), dateOut);
+  }
+
+  public Action(CDate date, CDate dateOut) {
+    this(exampleJNI.new_Action(CDate.getCPtr(date), date, 
+                               CDate.getCPtr(dateOut), dateOut), true);
+  }
+}
+
      +
      +

      The CDate & and const CDate & Java code is + generated from the following two default typemaps:

      +
      +
      +%typemap(jstype) SWIGTYPE & "$javaclassname"
+%typemap(javain) SWIGTYPE & "$javaclassname.getCPtr($javainput)"
+
      +
      +

      where '$javaclassname' is translated into the proxy class name, +CDate and '$javainput' is translated into the name of the + parameter, eg dateIn. From Java, the intention is then to call + into a modifed API with something like:

      +
      +
      +java.util.GregorianCalendar calendarIn = 
+    new java.util.GregorianCalendar(2011, java.util.Calendar.APRIL, 13, 0, 0, 0);
+java.util.GregorianCalendar calendarOut = new java.util.GregorianCalendar();
+
+// Note in calls below, calendarIn remains unchanged and calendarOut 
+// is set to a new value by the C++ call
+Action.doSomething(calendarIn, calendarOut);
+Action action = new Action(calendarIn, calendarOut);
+
      +
      +

      To achieve this mapping, we need to alter the default code + generation slightly so that at the Java layer, a GregorianCalendar + is converted into a CDate. The JNI intermediary layer will + still take a pointer to the underlying CDate class. The + typemaps to achieve this are shown below.

      +
      +
      +%typemap(jstype) const CDate& "java.util.GregorianCalendar"
+%typemap(javain, 
+         pre="    CDate temp$javainput = new CDate($javainput.get(java.util.Calendar.YEAR), "
+             "$javainput.get(java.util.Calendar.MONTH), $javainput.get(java.util.Calendar.DATE));", 
+         pgcppname="temp$javainput") const CDate &
+         "$javaclassname.getCPtr(temp$javainput)"
+
+%typemap(jstype) CDate& "java.util.Calendar"
+%typemap(javain, 
+         pre="    CDate temp$javainput = new CDate($javainput.get(java.util.Calendar.YEAR), "
+             "$javainput.get(java.util.Calendar.MONTH), $javainput.get(java.util.Calendar.DATE));", 
+         post="      $javainput.set(temp$javainput.getYear(), temp$javainput.getMonth(), "
+              "temp$javainput.getDay(), 0, 0, 0);", 
+         pgcppname="temp$javainput") CDate &
+         "$javaclassname.getCPtr(temp$javainput)"
+
      +
      +

      The resulting generated proxy code in the Action class + follows:

      +
      +
      +public class Action {
+  ...
+  public static int doSomething(java.util.GregorianCalendar dateIn, 
+                                java.util.Calendar dateOut) {
+    CDate tempdateIn = new CDate(dateIn.get(java.util.Calendar.YEAR), 
+                                 dateIn.get(java.util.Calendar.MONTH), 
+                                 dateIn.get(java.util.Calendar.DATE));
+    CDate tempdateOut = new CDate(dateOut.get(java.util.Calendar.YEAR), 
+                                  dateOut.get(java.util.Calendar.MONTH), 
+                                  dateOut.get(java.util.Calendar.DATE));
+    try {
+      return exampleJNI.Action_doSomething(CDate.getCPtr(tempdateIn), tempdateIn, 
+                                           CDate.getCPtr(tempdateOut), tempdateOut);
+    } finally {
+      dateOut.set(tempdateOut.getYear(), tempdateOut.getMonth(), tempdateOut.getDay(), 0, 0, 0);
+    }
+  }
+
+  static private long SwigConstructAction(java.util.GregorianCalendar date, 
+                                          java.util.Calendar dateOut) {
+    CDate tempdate = new CDate(date.get(java.util.Calendar.YEAR), 
+                               date.get(java.util.Calendar.MONTH), 
+                               date.get(java.util.Calendar.DATE));
+    CDate tempdateOut = new CDate(dateOut.get(java.util.Calendar.YEAR), 
+                                  dateOut.get(java.util.Calendar.MONTH), 
+                                  dateOut.get(java.util.Calendar.DATE));
+    try {
+      return exampleJNI.new_Action(CDate.getCPtr(tempdate), tempdate, 
+                                   CDate.getCPtr(tempdateOut), tempdateOut);
+    } finally {
+      dateOut.set(tempdateOut.getYear(), tempdateOut.getMonth(), tempdateOut.getDay(), 0, 0, 0);
+    }
+  }
+
+  public Action(java.util.GregorianCalendar date, java.util.Calendar dateOut) {
+    this(Action.SwigConstructAction(date, dateOut), true);
+  }
+}
+
      +
      +

      A few things to note:

      +
        +
      • The "javatype" typemap has changed the parameter type to +java.util.GregorianCalendar or java.util.Calendar instead + of the default generated CDate proxy.
        • +
      • The code in the 'pre' attribute appears before the JNI call ( +exampleJNI.new_Action / exampleJNI.Action_doSomething).
        • +
      • The code in the 'post' attribute appears after the JNI call.
        • +
      • A try .. finally block is generated with the JNI call in the try + block and 'post' code in the finally block. The alternative of just + using a temporary variable for the return value from the JNI call and + the 'post' code being generated before the return statement is not + possible given that the JNI call is in one line and comes from the + "javaout" typemap.
        • +
      • The temporary variables in the "javain" typemaps are called +temp$javain, where "$javain" is replaced with the parameter name. + "$javain" is used to mangle the variable name so that more than one +CDate & type can be used as a parameter in a method, otherwise two + or more local variables with the same name would be generated.
        • +
      • The use of the "javain" typemap causes a constructor helper + function (SwigConstructAction) to be generated. This allows + Java code to be called before the JNI call and is required as the Java + compiler won't compile code inserted before the 'this' call.
        • +
      • The 'pgcppname' attribute is used to modify the object being passed + as the premature garbage collection prevention + parameter (the 2nd and 4th parameters in the JNI calls).
        • +
      +

      21.11 Living with Java Directors

      +

      This section is intended to address frequently asked questions and + frequently encountered problems when using Java directors.

      +
        +
      1. When my program starts up, it complains that method_foo + cannot be found in a Java method called swig_module_init. How do + I fix this? +

        Open up the C++ wrapper source code file and look for +"method_foo" (include the double quotes, they are important!) + Look at the JNI field descriptor and make sure that each class that + occurs in the descriptor has the correct package name in front of it. + If the package name is incorrect, put a "javapackage" typemap in your + SWIG interface file.

        +
        2. +
      2. I'm compiling my code and I'm using templates. I provided a + javapackage typemap, but SWIG doesn't generate the right JNI field + descriptor. +

        Use the template's renamed name as the argument to the "javapackage" + typemap:

        +
        +
        +%typemap(javapackage)  std::vector<int>  "your.package.here"
+%template(VectorOfInt) std::vector<int>;
+
        +
        3. +
      3. +

        When I pass class pointers or references through a C++ upcall and + I try to type cast them, Java complains with a ClassCastException. What + am I doing wrong?

        +

        Normally, a non-director generated Java proxy class creates + temporary Java objects as follows:

        +
        +
        +public static void MyClass_method_upcall(MyClass self, long jarg1)
+{
+  Foo darg1 = new Foo(jarg1, false);
+
+  self.method_upcall(darg1);
+}
+
        +
        +

        Unfortunately, this loses the Java type information that is part of + the underlying Foo director proxy class's Java object pointer causing + the type cast to fail. The SWIG Java module's director code attempts to + correct the problem, but only for director-enabled classes, + since the director class retains a global reference to its Java object. + Thus, for director-enabled classes and only for director-enabled + classes, the generated proxy Java code looks something like:

        +
        +
        +public static void MyClass_method_upcall(MyClass self, long jarg1,
+                                         Foo jarg1_object)
+{
+  Foo darg1 = (jarg1_object != null ? jarg1_object : new Foo(jarg1, false));
+
+  self.method_upcall(darg1);
+}
+
        +
        +

        When you import a SWIG interface file containing class definitions, + the classes you want to be director-enabled must be have the +feature("director") enabled for type symmetry to work. This + applies even when the class being wrapped isn't a director-enabled + class but takes parameters that are director-enabled classes.

        +

        The current "type symmetry" design will work for simple C++ + inheritance, but will most likely fail for anything more complicated + such as tree or diamond C++ inheritance hierarchies. Those who are + interested in challenging problems are more than welcome to hack the +Java::Java_director_declaration method in +Source/Modules/java.cxx.

        +

        If all else fails, you can use the downcastXXXXX() method to attempt + to recover the director class's Java object pointer. For the Java Foo + proxy class, the Foo director class's java object pointer can be + accessed through the javaObjectFoo() method. The generated method's + signature is:

        +
        +
        +  public static Foo javaObjectFoo(Foo obj);
+
        +
        +

        From your code, this method is invoked as follows:

        +
        +
        +public class MyClassDerived {
+  public void method_upcall(Foo foo_object)
+  {
+    FooDerived    derived = (foo_object != null ?
+                 (FooDerived) Foo.downcastFoo(foo_object) : null);
+    /* rest of your code here */
+  }
+}
+
        +
        +

        An good approach for managing downcasting is placing a static method + in each derived class that performs the downcast from the superclass, + e.g.,

        +
        +
        +public class FooDerived extends Foo {
+  /* ... */
+  public static FooDerived downcastFooDerived(Foo foo_object)
+  {
+    try {
+     return (foo_object != null ? (FooDerived) Foo.downcastFoo(foo_object);
+    }
+
+    catch (ClassCastException exc) {
+      // Wasn't a FooDerived object, some other subclass of Foo
+      return null;
+    }
+  }
+}
+
        +
        +

        Then change the code in MyClassDerived as follows:

        +
        +
        +public class MyClassDerived extends MyClass {
+  /* ... */
+  public void method_upcall(Foo foo_object)
+  {
+    FooDerived    derived = FooDerived.downcastFooDerived(foo_object);
+    /* rest of your code here */
+  }
+}
+
        +
        4. +
      4. +

        Why isn't the proxy class declared abstract? Why aren't the + director upcall methods in the proxy class declared abstract?

        +

        Declaring the proxy class and its methods abstract would break the + JNI argument marshalling and SWIG's downcall functionality (going from + Java to C++.) Create an abstract Java subclass that inherits from the + director-enabled class instead. Using the previous Foo class example:

        +
        +
        +public abstract class UserVisibleFoo extends Foo {
+  /** Make sure user overrides this method, it's where the upcall
+   * happens.
+   */
+  public abstract void method_upcall(Foo foo_object);
+
+  /// Downcast from Foo to UserVisibleFoo
+  public static UserVisibleFoo downcastUserVisibleFoo(Foo foo_object)
+  {
+    try {
+     return (foo_object != null ? (FooDerived) Foo.downcastFoo(foo_object) : null);
+    }
+
+    catch (ClassCastException exc) {
+      // Wasn't a FooDerived object, some other subclass of Foo
+      return null;
+    }
+  }
+}
+
        +
        +

        This doesn't prevent the user from creating subclasses derived from + Foo, however, UserVisibleFoo provides the safety net that reminds the + user to override the method_upcall() method.

        +
        5. +
      +

      21.12 Odds and ends

      +

      21.12.1 JavaDoc comments

      +

      The SWIG documentation system is currently deprecated. When it is + resurrected JavaDoc comments will be fully supported. If you can't wait + for the full documentation system a couple of workarounds are + available. The %javamethodmodifiers feature can be used for + adding proxy class method comments and module class method comments. + The "javaimports" typemap can be hijacked for adding in proxy class + JavaDoc comments. The jniclassimports or +jniclassclassmodifiers pragmas can also be used for adding + intermediary JNI class comments and likewise the moduleimports + or moduleclassmodifiers pragmas for the module class. Here is + an example adding in a proxy class and method comment:

      +
      +
      +%javamethodmodifiers Barmy::lose_marbles() "
+  /**
+    * Calling this method will make you mad.
+    * Use with <b>utmost</b> caution. 
+    */
+  public";
+
+%typemap(javaimports) Barmy "
+/** The crazy class. Use as a last resort. */"
+
+class Barmy {
+public:
+  void lose_marbles() {}
+};
+
      +
      +

      Note the "public" added at the end of the %javamethodmodifiers + as this is the default for this feature. The generated proxy class with + JavaDoc comments is then as follows:

      +
      +
      +/** The crazy class. Use as a last resort. */
+public class Barmy {
+...
+  /**
+    * Calling this method will make you mad.
+    * Use with <b>utmost</b> caution. 
+    */
+  public void lose_marbles() {
+    ...
+  }
+...
+}
+
      +
      +

      21.12.2 Functional interface + without proxy classes

      +

      It is possible to run SWIG in a mode that does not produce proxy + classes by using the -noproxy commandline option. The interface is + rather primitive when wrapping structures or classes and is accessed + through function calls to the module class. All the functions in the + module class are wrapped by functions with identical names as those in + the intermediary JNI class.

      +

      Consider the example we looked at when examining proxy classes:

      +
      +
      +class Foo {
+public:
+     int x;
+     int spam(int num, Foo* foo);
+};
+
      +
      +

      When using -noproxy, type wrapper classes are generated + instead of proxy classes. Access to all the functions and variables is + through a C like set of functions where the first parameter passed is + the pointer to the class, that is an instance of a type wrapper class. + Here is what the module class looks like:

      +
      +
      +public class example {
+  public static void Foo_x_get(SWIGTYPE_p_Foo self, int x) {...}
+  public static int Foo_x_get(SWIGTYPE_p_Foo self) {...}
+  public static int Foo_spam(SWIGTYPE_p_Foo self, int num, SWIGTYPE_p_Foo foo) {...}
+  public static SWIGTYPE_p_Foo new_Foo() {...}
+  public static void delete_Foo(SWIGTYPE_p_Foo self) {...}
+}
+
      +
      +

      This approach is not nearly as natural as using proxy classes as the + functions need to be used like this:

      +
      +
      +SWIGTYPE_p_Foo foo = example.new_Foo();
+example.Foo_x_set(foo, 10);
+int var = example.Foo_x_get(foo);
+example.Foo_spam(foo, 20, foo);
+example.delete_Foo(foo);
+
      +
      +

      Unlike proxy classes, there is no attempt at tracking memory. All + destructors have to be called manually for example the +delete_Foo(foo) call above.

      +

      21.12.3 Using your own JNI + functions

      +

      You may have some hand written JNI functions that you want to use in + addition to the SWIG generated JNI functions. Adding these to your SWIG + generated package is possible using the %native directive. If + you don't want SWIG to wrap your JNI function then of course you can + simply use the %ignore directive. However, if you want SWIG to + generate just the Java code for a JNI function then use the %native + directive. The C types for the parameters and return type must be + specified in place of the JNI types and the function name must be the + native method name. For example:

      +
      +
      +%native (HandRolled) void HandRolled(int, char *);
+%{
+JNIEXPORT void JNICALL Java_packageName_moduleName_HandRolled(JNIEnv *, jclass,
+                                                              jlong, jstring);
+%}
+
      +
      +

      No C JNI function will be generated and the +Java_packageName_moduleName_HandRolled function will be accessible + using the SWIG generated Java native method call in the intermediary + JNI class which will look like this:

      +
      +
      +  public final static native void HandRolled(int jarg1, String jarg2);
+
      +
      +

      and as usual this function is wrapped by another which for a global + C function would appear in the module class:

      +
      +
      +  public static void HandRolled(int arg0, String arg1) {
+    exampleJNI.HandRolled(arg0, arg1);
+  }
+
      +
      +

      The packageName and moduleName must of course be + correct else you will get linker errors when the JVM dynamically loads + the JNI function. You may have to add in some "jtype", "jstype", + "javain" and "javaout" typemaps when wrapping some JNI types. Here the + default typemaps work for int and char *.

      +

      In summary the %native directive is telling SWIG to + generate the Java code to access the JNI C code, but not the JNI C + function itself. This directive is only really useful if you want to + mix your own hand crafted JNI code and the SWIG generated code into one + Java class or package.

      +

      21.12.4 Performance concerns and hints

      +

      If you're directly manipulating huge arrays of complex objects from + Java, performance may suffer greatly when using the array functions in +arrays_java.i. Try and minimise the expensive JNI calls to C/C++ + functions, perhaps by using temporary Java variables instead of + accessing the information directly from the C/C++ object.

      +

      Java classes without any finalizers generally speed up code + execution as there is less for the garbage collector to do. Finalizer + generation can be stopped by using an empty javafinalize + typemap:

      +
      +
      +%typemap(javafinalize) SWIGTYPE ""
+
      +
      +

      However, you will have to be careful about memory management and + make sure that you code in a call to the delete() member + function. This method normally calls the C++ destructor or free() + for C code.

      +

      21.12.5 Debugging

      +

      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, where it is possible to step + from Java code into a JNI method within one environment.

      +

      Alternatively, debugging can involve placing debug printout + statements in the JNI layer using the %exception directive. + See the special + variables for %exception section. Many of the default typemaps can + also be overidden and modified for adding in extra logging/debug + display information.

      +

      The -Xcheck:jni and -Xcheck:nabounds Java + executable options are useful for debugging to make sure the JNI code + is behaving. The -verbose:jni and -verbose:gc are also useful options + for monitoring code behaviour.

      +

      21.13 Examples

      +

      The directory Examples/java has a number of further examples. Take a + look at these if you want to see some of the techniques described in + action. The Examples/index.html file in the parent directory contains + the SWIG Examples Documentation and is a useful starting point. If your + SWIG installation went well Unix users should be able to type make + in each example directory, then java main to see them running. + For the benefit of Windows users, there are also Visual C++ project + files in a couple of the Windows Examples +. There are also many regression tests in the Examples/test-suite + directory. Many of these have runtime tests in the java subdirectory.

      +
      +

      22 SWIG and Common Lisp

      + + +
      + +
      + +

      Common Lisp is a high-level, all-purpose, object-oriented, dynamic, + functional programming language with long history. Common Lisp is used + in many fields, ranging from web development to finance, and also + common in computer science education. There are more than 9 different + implementations of common lisp which are available, all have different + foreign function interfaces. SWIG currently supports only the Allegro + Common Lisp, Common Foreign Function Interface(CFFI), CLisp and UFFI + foreign function interfaces.

      +

      22.1 Allegro Common Lisp

      +

      Allegro Common Lisp support in SWIG has been updated to include + support for both C and C++. You can read about the interface +here

      +

      22.2 Common Foreign Function Interface(CFFI)

      +

      CFFI, the Common Foreign Function Interface, is a portable foreign + function interface for ANSI Common Lisp systems, similar in spirit to + UFFI. Unlike UFFI, CFFI requires only a small set of low-level + functionality from the Lisp implementation, such as calling a foreign + function by name, allocating foreign memory, and dereferencing + pointers.

      +

      To run the cffi module of SWIG requires very little effort, you just + need to run:

      +
      +
      +swig -cffi -module module-name   file-name 
+
+
      +
      +

      But a better was of using all the power of SWIG is to write SWIG + interface files. Below we will explain how to write interface files and + the various things which you can do with them.

      +

      22.2.1 Additional Commandline Options

      +

      The following table list the additional commandline options + available for the CLISP module. They can also be seen by using:

      +
      +
      +swig -cffi -help 
+
      +
      +
      + + + + + +
      CFFI specific options
      -generate-typedefIf this option is given then defctype + will be used to generate + + shortcuts according to the typedefs in the input.
      -[no]cwrapTurn on or turn off generation of an + intermediate C file when + + creating a C interface. By default this is only done for C++ code.
      -[no]swig-lispTurns on or off generation of code for + helper lisp macro, functions, etc. which SWIG uses while generating + wrappers. These macros, functions may still be used by generated + wrapper code.
      +

      22.2.2 Generating CFFI bindings

      + As we mentioned earlier the ideal way to use SWIG is to use interface + files. To illustrate the use of it, lets assume that we have a file + named test.h with the following C code:
      +
      +#define y 5
+#define x (y >>  1)
+
+typedef int days;
+
+struct bar {
+  short p, q;
+    char a, b;
+    int *z[1000];
+    struct bar * n;
+};
+  
+struct   bar * my_struct;
+
+struct foo {
+    int a;
+    struct foo * b[100];
+  
+};
+
+int pointer_func(void (*ClosureFun)( void* _fun, void* _data, void* _evt ), int p);
+
+int func123(div_t * p,int **q[100],int r[][1000][10]);
+
+void lispsort_double (int n, double * array);
+
+enum color { RED, BLUE, GREEN};
+
      +
      Corresponding to this we will write a simple interface file:
      +
      +%module test
+
+%include "test.h"
+
+
      +
      The generated SWIG Code will be:
      +
      +;;;SWIG wrapper code starts here
+
+(cl:defmacro defanonenum (&body enums)
+   "Converts anonymous enums to defconstants."
+  `(cl:progn ,@(cl:loop for value in enums
+                        for index = 0 then (cl:1+ index)
+                        when (cl:listp value) do (cl:setf index (cl:second value)
+                                                          value (cl:first value))
+                        collect `(cl:defconstant ,value ,index))))
+
+(cl:eval-when (:compile-toplevel :load-toplevel)
+  (cl:unless (cl:fboundp 'swig-lispify)
+    (cl:defun swig-lispify (name flag cl:&optional (package cl:*package*))
+      (cl:labels ((helper (lst last rest cl:&aux (c (cl:car lst)))
+                    (cl:cond
+                      ((cl:null lst)
+                       rest)
+                      ((cl:upper-case-p c)
+                       (helper (cl:cdr lst) 'upper
+                               (cl:case last
+                                 ((lower digit) (cl:list* c #\- rest))
+                                 (cl:t (cl:cons c rest)))))
+                      ((cl:lower-case-p c)
+                       (helper (cl:cdr lst) 'lower (cl:cons (cl:char-upcase c) rest)))
+                      ((cl:digit-char-p c)
+                       (helper (cl:cdr lst) 'digit 
+                               (cl:case last
+                                 ((upper lower) (cl:list* c #\- rest))
+                                 (cl:t (cl:cons c rest)))))
+                      ((cl:char-equal c #\_)
+                       (helper (cl:cdr lst) '_ (cl:cons #\- rest)))
+                      (cl:t
+                       (cl:error "Invalid character: ~A" c)))))
+        (cl:let ((fix (cl:case flag
+                        ((constant enumvalue) "+")
+                        (variable "*")
+                        (cl:t ""))))
+          (cl:intern
+           (cl:concatenate
+            'cl:string
+            fix
+            (cl:nreverse (helper (cl:concatenate 'cl:list name) cl:nil cl:nil))
+            fix)
+           package))))))
+
+;;;SWIG wrapper code ends here
+
+
+(cl:defconstant y 5)
+
+(cl:defconstant x (cl:ash 5 -1))
+
+(cffi:defcstruct bar
+	(p :short)
+	(q :short)
+	(a :char)
+	(b :char)
+	(z :pointer)
+	(n :pointer))
+
+(cffi:defcvar ("my_struct" my_struct)
+ :pointer)
+
+(cffi:defcstruct foo
+	(a :int)
+	(b :pointer))
+
+(cffi:defcfun ("pointer_func" pointer_func) :int
+  (ClosureFun :pointer)
+  (p :int))
+
+(cffi:defcfun ("func123" func123) :int
+  (p :pointer)
+  (q :pointer)
+  (r :pointer))
+
+(cffi:defcfun ("lispsort_double" lispsort_double) :void
+  (n :int)
+  (array :pointer))
+
+(cffi:defcenum color
+	:RED
+	:BLUE
+	:GREEN)
+
      +
      +

      The SWIG wrapper code refers to the special code which SWIG + may need to use while wrapping C code. You can turn on/off the + generation of this code by using the -[no]swig-lisp option. You + must have noticed that SWIG goes one extra step to ensure that CFFI + does not do automatic lispification of the C function names. The reason + SWIG does this is because quite often developers want to build a nice + CLOS based lispy API, and this one to one correspondence between C + function names and lisp function name helps.

      +

      Maybe you want to have your own convention for generating lisp + function names for corresponding C function names, or you just want to + lispify the names, also, before we forget you want to export the + generated lisp names. To do this, we will use the SWIG +feature directive. Let's edit the interface file such that the C + type "div_t*" is changed to Lisp type ":my-pointer", we lispify all + names, export everything, and do some more stuff.

      +
      +
      +%module test
+
+%typemap(cin) div_t* ":my-pointer";
+
+%feature("intern_function","1");
+%feature("export");
+
+%feature("inline") lispsort_double;
+
+%feature("intern_function", "my-lispify") lispsort_double;
+%rename func123 renamed_cool_func;
+%ignore "pointer_func";
+
+%include "test.h"
+
+
      +
      +

      The typemap(cin) ensures that for all arguments which are + input to C with the type "div_t*", the ":my-pointer" type be used. + Similarly typemap(cout) are used for all types which are + returned from C.

      +

      The feature intern_function ensures that all C names are + interned using the swig-lispify function. The "1" given to the + feature is optional. The use of feature like + %feature("intern_function","1"); globally enables interning for + everything. If you want to target a single function, or declaration + then use the targeted version of feature, + %feature("intern_function", "my-lispify") lispsort_double;, here we + are using an additional feature which allows us to use our lispify + function.

      +

      The export feature allows us to export the symbols. The + inline feature declaims the declared function as inline. The + rename directive allows us to change the name(it is useful when + generating C wrapper code for handling overloaded functions). The + ignore directive ignores a certain declaration.

      +

      There are several other things which are possible, to see some + example of usage of SWIG look at the Lispbuilder and wxCL projects. The + generated code with 'noswig-lisp' option is:

      +
      +
      +(cl:defconstant #.(swig-lispify "y" 'constant) 5)
+
+(cl:export '#.(swig-lispify "y" 'constant))
+
+(cl:defconstant #.(swig-lispify "x" 'constant) (cl:ash 5 -1))
+
+(cl:export '#.(swig-lispify "x" 'constant))
+
+(cffi:defcstruct #.(swig-lispify "bar" 'classname)
+	(#.(swig-lispify "p" 'slotname) :short)
+	(#.(swig-lispify "q" 'slotname) :short)
+	(#.(swig-lispify "a" 'slotname) :char)
+	(#.(swig-lispify "b" 'slotname) :char)
+	(#.(swig-lispify "z" 'slotname) :pointer)
+	(#.(swig-lispify "n" 'slotname) :pointer))
+
+(cl:export '#.(swig-lispify "bar" 'classname))
+
+(cl:export '#.(swig-lispify "p" 'slotname))
+
+(cl:export '#.(swig-lispify "q" 'slotname))
+
+(cl:export '#.(swig-lispify "a" 'slotname))
+
+(cl:export '#.(swig-lispify "b" 'slotname))
+
+(cl:export '#.(swig-lispify "z" 'slotname))
+
+(cl:export '#.(swig-lispify "n" 'slotname))
+
+(cffi:defcvar ("my_struct" #.(swig-lispify "my_struct" 'variable))
+ :pointer)
+
+(cl:export '#.(swig-lispify "my_struct" 'variable))
+
+(cffi:defcstruct #.(swig-lispify "foo" 'classname)
+	(#.(swig-lispify "a" 'slotname) :int)
+	(#.(swig-lispify "b" 'slotname) :pointer))
+
+(cl:export '#.(swig-lispify "foo" 'classname))
+
+(cl:export '#.(swig-lispify "a" 'slotname))
+
+(cl:export '#.(swig-lispify "b" 'slotname))
+
+(cffi:defcfun ("renamed_cool_func" #.(swig-lispify "renamed_cool_func" 'function)) :int
+  (p :my-pointer)
+  (q :pointer)
+  (r :pointer))
+
+(cl:export '#.(swig-lispify "renamed_cool_func" 'function))
+
+(cl:declaim (cl:inline #.(my-lispify "lispsort_double" 'function)))
+
+(cffi:defcfun ("lispsort_double" #.(my-lispify "lispsort_double" 'function)) :void
+  (n :int)
+  (array :pointer))
+
+(cl:export '#.(my-lispify "lispsort_double" 'function))
+
+(cffi:defcenum #.(swig-lispify "color" 'enumname)
+	#.(swig-lispify "RED" 'enumvalue :keyword)
+	#.(swig-lispify "BLUE" 'enumvalue :keyword)
+	#.(swig-lispify "GREEN" 'enumvalue :keyword))
+
+(cl:export '#.(swig-lispify "color" 'enumname))
+
+
      +
      +

      22.2.3 Generating CFFI bindings for C++ code

      +

      This feature to SWIG (for CFFI) is very new and still far from + complete. Pitch in with your patches, bug reports and feature requests + to improve it.

      +

      Generating bindings for C++ code, requires -c++ option to be + present and it first generates C binding which will wrap the C++ code, + and then generates the corresponding CFFI wrapper code. In the + generated C wrapper code, you will often want to put your own C code, + such as the code to include various files. This can be done by making + use of "%{" and "%}" as shown below.

      +
      +
      +%{
+ #include "Test/test.h"
+%}
+
      +
      +

      Also, while parsing the C++ file and generating C wrapper code SWIG + may need to be able to understand various symbols used in other header + files. To help SWIG in doing this while ensuring that wrapper code is + generated for the target file, use the "import" directive. The + "include" directive specifies the target file for which wrapper code + will be generated.

      +
      +
      +
+%import "ancillary/header.h"
+
+%include "target/header.h"
+
+
      +
      Various features which were available for C headers can also be + used here. The target header which we are going to use here is:
      +
      +namespace OpenDemo {
+  class Test
+    {
+    public:
+        float x;
+        // constructors
+        Test (void) {x = 0;}
+        Test (float X) {x = X;}
+
+        // vector addition
+        Test operator+ (const Test& v) const {return Test (x+v.x);}
+
+      // length squared
+        float lengthSquared (void) const {return this->dot (*this);}
+
+        static float distance (const Test& a, const Test& b){return(a-b).length();}
+
+        inline Test parallelComponent (const Test& unitBasis) const {
+          return unitBasis * projection;
+        }
+
+        Test setYtoZero (void) const {return Test (this->x);}
+
+        static const Test zero;
+    };
+
+
+   inline Test operator* (float s, const Test& v) {return v*s;}
+
+
+    inline std::ostream& operator<< (std::ostream& o, const Test& v)
+    {
+        return o << "(" << v.x << ")";
+    }
+
+
+    inline Test RandomUnitVectorOnXZPlane (void)
+    {
+        return RandomVectorInUnitRadiusSphere().setYtoZero().normalize();
+    }
+}
+
      +
      +

      The interface used is:

      +
      +
      +%module test
+%include "test.cpp"
+
      +
      SWIG generates 3 files, the first one is a C wrap which we don't + show, the second is the plain CFFI wrapper which is as shown below:
      +
      +(cffi:defcfun ("_wrap_Test_x_set" Test_x_set) :void
+  (self :pointer)
+  (x :float))
+
+(cffi:defcfun ("_wrap_Test_x_get" Test_x_get) :float
+  (self :pointer))
+
+(cffi:defcfun ("_wrap_new_Test__SWIG_0" new_Test) :pointer)
+
+(cffi:defcfun ("_wrap_new_Test__SWIG_1" new_Test) :pointer
+  (X :float))
+
+(cffi:defcfun ("_wrap_Test___add__" Test___add__) :pointer
+  (self :pointer)
+  (v :pointer))
+
+(cffi:defcfun ("_wrap_Test_lengthSquared" Test_lengthSquared) :float
+  (self :pointer))
+
+(cffi:defcfun ("_wrap_Test_distance" Test_distance) :float
+  (a :pointer)
+  (b :pointer))
+
+(cffi:defcfun ("_wrap_Test_parallelComponent" Test_parallelComponent) :pointer
+  (self :pointer)
+  (unitBasis :pointer))
+
+(cffi:defcfun ("_wrap_Test_setYtoZero" Test_setYtoZero) :pointer
+  (self :pointer))
+
+(cffi:defcvar ("Test_zero" Test_zero)
+ :pointer)
+
+(cffi:defcfun ("_wrap_delete_Test" delete_Test) :void
+  (self :pointer))
+
+(cffi:defcfun ("_wrap___mul__" __mul__) :pointer
+  (s :float)
+  (v :pointer))
+
+(cffi:defcfun ("_wrap___lshift__" __lshift__) :pointer
+  (o :pointer)
+  (v :pointer))
+
+(cffi:defcfun ("_wrap_RandomUnitVectorOnXZPlane" RandomUnitVectorOnXZPlane) :pointer)
+
      +
      The output is pretty good but it fails in disambiguating + overloaded functions such as the constructor, in this case. One way of + resolving this problem is to make the interface use the rename + directiv, but hopefully there are better solutions. In addition SWIG + also generates, a CLOS file
      +
      +(clos:defclass test()
+  ((ff :reader ff-pointer)))
+
+(clos:defmethod (cl:setf x) (arg0 (obj test))
+  (Test_x_set (ff-pointer obj) arg0))
+
+(clos:defmethod x ((obj test))
+  (Test_x_get (ff-pointer obj)))
+
+(cl:shadow "+")
+(clos:defmethod + ((obj test) (self test) (v test))
+  (Test___add__ (ff-pointer obj) (ff-pointer self) (ff-pointer v)))
+
+(clos:defmethod length-squared ((obj test) (self test))
+  (Test_lengthSquared (ff-pointer obj) (ff-pointer self)))
+
+(clos:defmethod parallel-component ((obj test) (self test) (unitBasis test))
+  (Test_parallelComponent (ff-pointer obj) (ff-pointer self) (ff-pointer unitBasis)))
+
+(clos:defmethod set-yto-zero ((obj test) (self test))
+  (Test_setYtoZero (ff-pointer obj) (ff-pointer self)))
+
      +
      +

      I agree that the CFFI C++ module needs lot more work. But I hope it + provides a starting point, on which you can base your work of importing + C++ libraries to Lisp.

      +

      If you have any questions, suggestions, patches, etc., related to + CFFI module feel free to contact us on the SWIG mailing list, and also + please add a "[CFFI]" tag in the subject line.

      +

      22.2.4 Inserting user code into generated + files

      +

      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 #include "header.h" directive. This can be + done using the SWIG %insert(section) %{ ...code... %} + directive:

      +
      +
      +%module example
+
+%{
+#include "header.h"
+%}
+
+%include "header.h"
+
+int fact(int n);
+
      +
      +

      Additional sections have been added for inserting into the generated + lisp interface file:

      +
        +
      • lisphead - inserts before type declarations
        • +
      • swiglisp - inserts after type declarations according to + where it appears in the .i file
        • +
      +

      Note that the block %{ ... %} is effectively a shortcut for + %insert("header") %{ ... %}.

      +

      22.3 CLISP

      +

      CLISP is a feature-loaded + implementation of common lisp which is portable across most of the + operating system environments and hardware. CLISP includes an + interpreter, a compiler, a debugger, CLOS, MOP, a foreign language + interface, i18n, regular expressions, a socket interface, and more. An + X11 interface is available through CLX, Garnet and CLUE/CLIO. Command + line editing is provided by readline. CLISP runs Maxima, ACL2 and many + other Common Lisp packages.

      +

      To run the clisp module of SWIG requires very little effort, you + just need to execute:

      +
      +
      +swig -clisp -module module-name   file-name 
+
+
      +
      +

      Because of the high level nature of the CLISP FFI, the bindings + generated by SWIG may not be absolutely correct, and you may need to + modify them. The good thing is that you don't need to complex interface + file for the CLISP module. The CLISP module tries to produce code which + is both human readable and easily modifyable.

      +

      22.3.1 Additional Commandline Options

      +

      The following table list the additional commandline options + available for the CLISP module. They can also be seen by using:

      +
      +
      +swig -clisp -help 
+
      +
      +
      + + + + +
      CLISP specific options
      -extern-allIf this option is given then clisp + definitions for all the functions +
      and global variables will be created otherwise only definitions for +
      externed functions and variables are created.
      -generate-typedefIf this option is given then + def-c-type will be used to generate +
      shortcuts according to the typedefs in the input.
      +

      22.3.2 Details on CLISP bindings

      +

      As mentioned earlier the CLISP bindings generated by SWIG may need + some modifications. The clisp module creates a lisp file with the same + name as the module name. This lisp file contains a 'defpackage' + declaration, with the package name same as the module name. This + package uses the 'common-lisp' and 'ffi' packages. Also, package + exports all the functions, structures and variables for which an ffi + binding was generated. +
      After generating the defpackage statement, the clisp module also + sets the default language.

      +
      +(defpackage :test
+    (:use :common-lisp :ffi)
+  (:export
+   :make-bar
+   :bar-x
+   :bar-y
+   :bar-a
+   :bar-b
+   :bar-z
+   :bar-n
+   :pointer_func
+   :func123
+   :make-cfunr
+   :lispsort_double
+   :test123))
+
+(in-package :test)
+
+(default-foreign-language :stdc)
+
      +

      +

      The ffi wrappers for functions and variables are generated as shown + below. When functions have arguments of type "double * array", SWIG + doesn't knows whether it is an 'out' argument or it is an array which + will be passed, so SWIG plays it safe by declaring it as an '(array + (ffi:c-ptr DOUBLE-FLOAT))'. For arguments of type "int **z[100]" where + SWIG has more information, i.e., it knows that 'z' is an array of + pointers to pointers of integers, SWIG defines it to be '(z (ffi:c-ptr + (ffi:c-array (ffi:c-ptr (ffi:c-ptr ffi:int)) 100)))'

      +
      +
      +extern "C" {
+int pointer_func(void (*ClosureFun)( void* _fun, void* _data, void* _evt ), int y);
+
+int func123(div_t * x,int **z[100],int y[][1000][10]);
+
+void lispsort_double (int n, double * array);
+
+void test123(float x , double y);
+
+}
+
      +
      +
      +(ffi:def-call-out pointer_func
+    (:name "pointer_func")
+  (:arguments (ClosureFun (ffi:c-function (:arguments (arg0 (ffi:c-pointer NIL))
+						      (arg1 (ffi:c-pointer NIL))
+						      (arg2 (ffi:c-pointer NIL)))
+					  (:return-type NIL)))
+	      (y ffi:int))
+  (:return-type ffi:int)
+  (:library +library-name+))
+
+(ffi:def-call-out func123
+    (:name "func123")
+  (:arguments (x (ffi:c-pointer div_t))
+	      (z (ffi:c-ptr (ffi:c-array (ffi:c-ptr (ffi:c-ptr ffi:int)) 100)))
+	      (y (ffi:c-ptr (ffi:c-ptr (ffi:c-array ffi:int (1000 10))))))
+  (:return-type ffi:int)
+  (:library +library-name+))
+
+
+(ffi:def-call-out lispsort_double
+    (:name "lispsort_double")
+  (:arguments (n ffi:int)
+	      (array (ffi:c-ptr DOUBLE-FLOAT)))
+  (:return-type NIL)
+  (:library +library-name+))
+
+(ffi:def-call-out test123
+    (:name "test")
+  (:arguments (x SINGLE-FLOAT)
+	      (y DOUBLE-FLOAT))
+  (:return-type NIL)
+  (:library +library-name+))
+
+
      +
      +

      The module also handles strutcures and #define constants as shown + below. SWIG automatically adds the constructors and accessors created + for the struct to the list of symbols exported by the package.

      +
      +
      +struct bar {
+    short x, y;
+    char a, b;
+    int *z[1000];
+    struct bar * n;
+};
+
+#define max 1000
+
      +
      +
      +(ffi:def-c-struct bar
+    (x :type ffi:short)
+  (y :type ffi:short)
+  (a :type character)
+  (b :type character)
+  (z :type (ffi:c-array (ffi:c-ptr ffi:int) 1000))
+  (n :type (ffi:c-pointer bar)))
+
+(defconstant max 1000)
+
+
      +
      +

      22.4 UFFI

      +
      +

      23 SWIG and Lua

      + + +
      + +
      + +

      Lua is an extension programming language designed to support general + procedural programming with data description facilities. It also offers + good support for object-oriented programming, functional programming, + and data-driven programming. Lua is intended to be used as a powerful, + light-weight configuration language for any program that needs one. Lua + is implemented as a library, written in clean C (that is, in the common + subset of ANSI C and C++). Its also a really tiny language, + less than 6000 lines of code, which compiles to <100 kilobytes of + binary code. It can be found at +http://www.lua.org

      +

      23.1 Preliminaries

      +

      The current SWIG implementation is designed to work with Lua 5.0.x + and Lua 5.1.x. It should work with later versions of Lua, but certainly + not with Lua 4.0 due to substantial API changes. ((Currently SWIG + generated code has only been tested on Windows with MingW, though given + the nature of Lua, is should not have problems on other OS's)). It is + possible to either static link or dynamic link a Lua module into the + interpreter (normally Lua static links its libraries, as dynamic + linking is not available on all platforms).

      +

      23.2 Running SWIG

      +

      Suppose that you defined a SWIG module such as the following:

      +
      +
      +%module example
+%{
+#include "example.h"
+%}
+int gcd(int x, int y);
+extern double Foo;
+
      +
      +

      To build a Lua module, run SWIG using the -lua option.

      +
      +
      +$ swig -lua example.i
+
      +
      +

      If building a C++ extension, add the -c++ option:

      +
      +
      +$ swig -c++ -lua example.i
+
      +
      +

      This creates a C/C++ source file example_wrap.c or +example_wrap.cxx. The generated C 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.

      +

      The name of the wrapper file is derived from the name of the input + file. For example, if the input file is example.i, the name of + the wrapper file is example_wrap.c. To change this, you can + use the -o option. The wrappered module will export one function +"int luaopen_example(lua_State* L)" which must be called to + register the module with the Lua interpreter. The name + "luaopen_example" depends upon the name of the module.

      +

      23.2.1 Compiling and Linking and Interpreter

      +

      Normally Lua is embedded into another program and will be statically + linked. An extremely simple stand-alone interpreter (min.c) is + given below:

      +
      +
      +#include <stdio.h>
+#include "lua.h"
+#include "lualib.h"
+#include "lauxlib.h"
+
+extern int luaopen_example(lua_State* L); // declare the wrapped module
+
+int main(int argc,char* argv[])
+{
+ lua_State *L;
+ if (argc<2)
+ {
+  printf("%s: <filename.lua>\n",argv[0]);
+  return 0;
+ }
+ L=lua_open();
+ luaopen_base(L);	// load basic libs (eg. print)
+ luaopen_example(L);	// load the wrappered module
+ if (luaL_loadfile(L,argv[1])==0) // load and run the file
+  lua_pcall(L,0,0,0);
+ else
+  printf("unable to load %s\n",argv[1]);
+ lua_close(L);
+ return 0;
+}
+
      +
      +

      A much improved set of code can be found in the Lua distribution +src/lua/lua.c. Include your module, just add the external + declaration & add a #define LUA_EXTRALIBS + {"example",luaopen_example}, at the relevant place.

      +

      The exact commands for compiling and linking vary from platform to + platform. Here is a possible set of commands of doing this:

      +
      +
      +$ swig -lua example.i -o example_wrap.c
+$ gcc -I/usr/include/lua -c min.c -o min.o
+$ gcc -I/usr/include/lua -c example_wrap.c -o example_wrap.o
+$ gcc -c example.c -o example.o
+$ gcc -I/usr/include/lua -L/usr/lib/lua min.o example_wrap.o example.o -o my_lua
+
      +
      +

      23.2.2 Compiling a dynamic module

      +

      Most, but not all platforms support the dynamic loading of modules + (Windows & Linux do). Refer to the Lua manual to determine if your + platform supports it. For compiling a dynamically loaded module the + same wrapper can be used. The commands will be something like this:

      +
      +
      +$ swig -lua example.i -o example_wrap.c
+$ gcc -I/usr/include/lua -c example_wrap.c -o example_wrap.o
+$ gcc -c example.c -o example.o
+$ gcc -shared -I/usr/include/lua -L/usr/lib/lua example_wrap.o example.o -o example.so
+
      +
      +

      The wrappers produced by SWIG can be compiled and linked with Lua + 5.1.x. The loading is extremely simple.

      +
      +
      +require("example")
+
      +
      +

      For those using Lua 5.0.x, you will also need an interpreter with + the loadlib function (such as the default interpreter compiled with + Lua). In order to dynamically load a module you must call the loadlib + function with two parameters: the filename of the shared library, and + the function exported by SWIG. Calling loadlib should return the + function, which you then call to initialise the module

      +
      +
      +my_init=loadlib("example.so","luaopen_example") -- for Unix/Linux
+--my_init=loadlib("example.dll","luaopen_example") -- for Windows
+assert(my_init) -- name sure its not nil
+my_init()       -- call the init fn of the lib
+
      +
      +

      Or can be done in a single line of Lua code

      +
      +
      +assert(loadlib("example.so","luaopen_example"))()
+
      +
      +

      If the code didn't work, don't panic. The best thing to do is to + copy the module and your interpreter into a single directory and then + execute the interpreter and try to manually load the module (take care, + all this code is case sensitive).

      +
      +
      +a,b,c=package.loadlib("example.so","luaopen_example") -- for Unix/Linux
+--a,b,c=package.loadlib("example.dll","luaopen_example") -- for Windows
+print(a,b,c)
+
      +
      +

      Note: for Lua 5.0: +
      The loadlib() function is in the global namespace, not in package. + So its just loadlib().

      +

      if 'a' is a function, this its all working fine, all you need to do + is call it

      +
      +
      +  a()
+
      +
      +

      to load your library which will add a table 'example' with all the + functions added.

      +

      If it doesn't work, look at the error messages, in particular mesage + 'b' +
      The specified module could not be found. +
      Means that is cannot find the module, check your the location and + spelling of the module. +
      The specified procedure could not be found. +
      Means that it loaded the module, but cannot find the named + function. Again check the spelling, and if possible check to make sure + the functions were exported correctly. +
      'loadlib' not installed/supported +
      Is quite obvious (Go back and consult the Lua documents on how to + enable loadlib for your platform).

      +

      23.2.3 Using your module

      +

      Assuming all goes well, you will be able to this:

      +
      +
      +$ ./my_lua
+> print(example.gcd(4,6))
+2
+> print(example.Foo)
+3
+> example.Foo=4
+> print(example.Foo)
+4
+>
+
      +
      +

      23.3 A tour of basic C/C++ wrapping

      +

      By default, SWIG tries to build a very natural Lua interface to your + C/C++ code. This section briefly covers the essential aspects of this + wrapping.

      +

      23.3.1 Modules

      +

      The SWIG module directive specifies the name of the Lua module. If + you specify `module example', then everything is wrapped into a Lua + table 'example' containing all the functions and variables. When + choosing a module name, make sure you don't use the same name as a + built-in Lua command or standard module name.

      +

      23.3.2 Functions

      +

      Global functions are wrapped as new Lua built-in functions. For + example,

      +
      +
      +%module example
+int fact(int n);
      +
      +

      creates a built-in function example.fact(n) that works + exactly like you think it does:

      +
      +
      +> print example.fact(4)
+24
+>
+
      +
      +

      To avoid name collisions, SWIG create a Lua table which it keeps all + the functions and global variables in. It is possible to copy the + functions out of this and into the global environment with the + following code. This can easily overwrite existing functions, so this + must be used with care.

      +
      +
      +> for k,v in pairs(example) do _G[k]=v end
+> print(fact(4))
+24
+>
+
      +
      +

      It is also possible to rename the module with an assignment.

      +
      +
      +> e=example
+> print(e.fact(4))
+24
+> print(example.fact(4))
+24
+
      +
      +

      23.3.3 Global variables

      +

      Global variables (which are linked to C code) are supported, and + appear to be just another variable in Lua. However the actual mechanism + is more complex. Given a global variable:

      +
      +
      %module example
+extern double Foo;
+
      +
      +

      SWIG will effectively generate two functions example.Foo_set() + and example.Foo_get(). It then adds a metatable to the table + 'example' to call these functions at the correct time (when you attempt + to set or get examples.Foo). Therefore if you were to attempt to assign + the global to another variable, you will get a local copy within the + interpreter, which is no longer linked to the C code.

      +
      +
      +> print(example.Foo)
+3
+> c=example.Foo   -- c is a COPY of example.Foo, not the same thing
+> example.Foo=4
+> print(c)
+3
+> c=5 -- this will not effect the original example.Foo
+> print(example.Foo,c)
+4    5
+
      +
      +

      Its is therefore not possible to 'move' the global variable into the + global namespace as it is with functions. It is however, possible to + rename the module with an assignment, to make it more convenient.

      +
      +
      +> e=example
+> -- e and example are the same table
+> -- so e.Foo and example.Foo are the same thing
+> example.Foo=4
+> print(e.Foo)
+4
+
      +
      +

      If a variable is marked with the %immutable directive then any + attempts to set this variable will cause an Lua error. Given a global + variable:

      +
      +
      %module example
+%immutable;
+extern double Foo;
+%mutable;
+
      +
      +

      SWIG will allow the the reading of Foo but when a set + attempt is made, an error function will be called.

      +
      +
      +> print(e.Foo) -- reading works ok
+4
+> example.Foo=40 -- but writing does not
+This variable is immutable
+stack traceback:
+        [C]: ?
+        [C]: ?
+        stdin:1: in main chunk
+        [C]: ?
+
      +
      +

      For those people who would rather that SWIG silently ignore the + setting of immutables (as previous versions of the Lua bindings did), + adding a -DSWIGLUA_IGNORE_SET_IMMUTABLE compile option will + remove this.

      +

      Unlike earlier versions of the binding, it is now possible to add + new functions or variables to the module, just as if it were a normal + table. This also allows the user to rename/remove existing functions + and constants (but not linked variables, mutable or immutable). + Therefore users are recommended to be careful when doing so.

      +
      +
      +> -- example.PI does not exist
+> print(example.PI)
+nil
+> example.PI=3.142 -- new value added
+> print(example.PI)
+3.142
+
      +
      +

      23.3.4 Constants and enums

      +

      Because Lua doesn't really have the concept of constants, C/C++ + constants are not really constant in Lua. They are actually just a copy + of the value into the Lua interpreter. Therefore they can be changed + just as any other value. For example given some constants:

      +
      +
      %module example
+%constant int ICONST=42;
+#define    SCONST      "Hello World"
+enum Days{SUNDAY,MONDAY,TUESDAY,WEDNESDAY,THURSDAY,FRIDAY,SATURDAY};
+
      +
      +

      This is 'effectively' converted into the following Lua code:

      +
      +
      +example.ICONST=42
+example.SCONST="Hello World"
+example.SUNDAY=0
+....
+
      +
      +

      Constants are not guaranteed to remain constant in Lua. The name of + the constant could be accidentally reassigned to refer to some other + object. Unfortunately, there is no easy way for SWIG to generate code + that prevents this. You will just have to be careful.

      +

      23.3.5 Pointers

      +

      C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no + problem working with incomplete type information. Given a wrapping of + the <file.h> interface:

      +
      +
      %module example
+
+FILE *fopen(const char *filename, const char *mode);
+int fputs(const char *, FILE *);
+int fclose(FILE *);
+
      +
      +

      When wrapped, you will be able to use the functions in a natural way + from Lua. For example:

      +
      +
      +> f=example.fopen("junk","w")
+> example.fputs("Hello World",f)
+> example.fclose(f)
+
      +
      +

      Unlike many scripting languages, Lua has had support for pointers to + C/C++ object built in for a long time. They are called 'userdata'. + Unlike many other SWIG versions which use some kind of encoded + character string, all objects will be represented as a userdata. The + SWIG-Lua bindings provides a special function swig_type(), + which if given a userdata object will return the type of object pointed + to as a string (assuming it was a SWIG wrappered object).

      +
      +
      +> print(f)
+userdata: 003FDA80
+> print(swig_type(f))
+FILE * -- its a FILE*
+
      +
      +

      Lua enforces the integrity of its userdata, so it is virtually + impossible to corrupt the data. But as the user of the pointer, you are + responsible for freeing it, or closing any resources associated with it + (just as you would in a C program). This does not apply so strictly to + classes & structs (see below). One final note: if a function returns a + NULL pointer, this is not encoded as a userdata, but as a Lua nil.

      +
      +
      +> f=example.fopen("not there","r") -- this will return a NULL in C
+> print(f)
+nil
+
      +
      +

      23.3.6 Structures

      +

      If you wrap a C structure, it is also mapped to a Lua userdata. By + adding a metatable to the userdata, this provides a very natural + interface. For example,

      +
      +
      struct Point{
+  int x,y;
+};
+
      +
      +

      is used as follows:

      +
      +
      +> p=example.new_Point()
+> p.x=3
+> p.y=5
+> print(p.x,p.y)
+3       5
+>
+
      +
      +

      Similar access is provided for unions and the data members of C++ + classes. +
      C structures are created using a function new_Point(), but + for C++ classes are created using just the name Point().

      +

      If you print out the value of p in the above example, you will see + something like this:

      +
      +
      +> print(p)
+userdata: 003FA320
+
      +
      +

      Like the pointer in the previous section, this is held as a + userdata. However, additional features have been added to make this + more usable. SWIG effectivly creates some accessor/mutator functions to + get and set the data. These functions will be added to the userdata's + metatable. This provides the natural access to the member variables + that were shown above (see end of the document for full details).

      +

      const members of a structure are read-only. Data members + can also be forced to be read-only using the immutable directive. As + with other immutable's, setting attempts will be cause an error. For + example:

      +
      +
      struct Foo {
+   ...
+   %immutable;
+   int x;        // Read-only members
+   char *name;
+   %mutable;
+   ...
+};
+
      +
      +

      The mechanism for managing char* members as well as array members is + similar to other languages. It is somewhat cumbersome and should + probably be better handled by defining of typemaps (described later).

      +

      When a member of a structure is itself a structure, it is handled as + a pointer. For example, suppose you have two structures like this:

      +
      +
      struct Foo {
+   int a;
+};
+
+struct Bar {
+   Foo f;
+};
+
      +
      +

      Now, suppose that you access the f attribute of Bar like this:

      +
      +
      +> b = Bar()
+> x = b.f
+
      +
      +

      In this case, x is a pointer that points to the Foo that is inside + b. This is the same value as generated by this C code:

      +
      +
      +Bar b;
+Foo *x = &b->f;       // Points inside b
+
      +
      +

      Because the pointer points inside the structure, you can modify the + contents and everything works just like you would expect. For example:

      +
      +
      +> b = Bar()
+> b.f.a = 3               -- Modify attribute of structure member
+> x = b.f
+> x.a = 3                 -- Modifies the same structure
+
      +
      +

      23.3.7 C++ classes

      +

      C++ classes are wrapped by a Lua userdata as well. For example, if + you have this class,

      +
      +
      class List {
+public:
+  List();
+  ~List();
+  int  search(char *item);
+  void insert(char *item);
+  void remove(char *item);
+  char *get(int n);
+  int  length;
+};
+
      +
      +

      you can use it in Lua like this:

      +
      +
      +> l = example.List()
+> l:insert("Ale")
+> l:insert("Stout")
+> l:insert("Lager")
+> print(l:get(1))
+Stout
+> print(l:length)
+3
+>
+
      +
      +

      (Note: for calling methods of a class, you use +class:method(args), not class.method(args), its an easy + mistake to make. However for data attributes it is class.attribute +)

      +

      Class data members are accessed in the same manner as C structures. + Static class members present a special problem for Lua, as Lua doesn't + have support for such features. Therefore, SWIG generates wrappers that + try to work around some of these issues. To illustrate, suppose you + have a class like this:

      +
      +
      class Spam {
+public:
+   static void foo();
+   static int bar;
+
+};
+
      +
      +

      In Lua, the static members can be accessed as follows:

      +
      +
      +> example.Spam_foo()            -- calling Spam::foo()
+> a=example.Spam_bar            -- reading Spam::bar 
+> example.Spam_bar=b            -- writing to Spam::bar
+
      +
      +

      It is not (currently) possible to access static members of an + instance:

      +
      +
      +> s=example.Spam()      -- s is a Spam instance
+> s.foo()                       -- Spam::foo() via an instance
+                                -- does NOT work
+
      +
      +

      23.3.8 C++ inheritance

      +

      SWIG is fully aware of issues related to C++ inheritance. Therefore, + if you have classes like this

      +
      +
      class Foo {
+...
+};
+
+class Bar : public Foo {
+...
+};
+
      +
      +

      And if you have functions like this

      +
      +
      void spam(Foo *f);
+
      +
      +

      then the function spam() accepts a Foo pointer or a pointer + to any class derived from Foo.

      +

      It is safe to use multiple inheritance with SWIG.

      +

      23.3.9 Pointers, references, values, and + arrays

      +

      In C++, there are many different ways a function might receive and + manipulate objects. For example:

      +
      +
      void spam1(Foo *x);      // Pass by pointer
+void spam2(Foo &x);      // Pass by reference
+void spam3(Foo x);       // Pass by value
+void spam4(Foo x[]);     // Array of objects
+
      +
      +

      In SWIG, there is no detailed distinction like this--specifically, + there are only "objects". There are no pointers, references, arrays, + and so forth. Because of this, SWIG unifies all of these types together + in the wrapper code. For instance, if you actually had the above + functions, it is perfectly legal to do this:

      +
      +
      +> f = Foo()           -- Create a Foo
+> spam1(f)            -- Ok. Pointer
+> spam2(f)            -- Ok. Reference
+> spam3(f)            -- Ok. Value.
+> spam4(f)            -- Ok. Array (1 element)
+
      +
      +

      Similar behaviour occurs for return values. For example, if you had + functions like this,

      +
      +
      Foo *spam5();
+Foo &spam6();
+Foo  spam7();
+
      +
      +

      then all three functions will return a pointer to some Foo object. + Since the third function (spam7) returns a value, newly allocated + memory is used to hold the result and a pointer is returned (Lua will + release this memory when the return value is garbage collected). The + other two are pointers which are assumed to be managed by the C code + and so will not be garbage collected.

      +

      23.3.10 C++ overloaded functions

      +

      C++ overloaded functions, methods, and constructors are mostly + supported by SWIG. For example, if you have two functions like this:

      +
      +
      void foo(int);
+void foo(char *c);
+
      +
      +

      You can use them in Lua in a straightforward manner:

      +
      +
      +> foo(3)           -- foo(int)
+> foo("Hello")     -- foo(char *c)
+
      +
      +

      However due to Lua's coercion mechanism is can sometimes do strange + things.

      +
      +
      +> foo("3")           -- "3" can be coerced into an int, so it calls foo(int)!
+
      +
      +

      As this coercion mechanism is an integral part of Lua, there is no + easy way to get around this other than renaming of functions (see + below).

      +

      Similarly, if you have a class like this,

      +
      +
      class Foo {
+public:
+    Foo();
+    Foo(const Foo &);
+    ...
+};
+
      +
      +

      you can write Lua code like this:

      +
      +
      +> f = Foo()          -- Create a Foo
+> g = Foo(f)         -- Copy f
+
      +
      +

      Overloading support is not quite as flexible as in C++. Sometimes + there are methods that SWIG can't disambiguate. For example:

      +
      +
      void spam(int);
+void spam(short);
+
      +
      +

      or

      +
      +
      VOID FOO(bAR *B);
+void foo(Bar &b);
+
      +
      +

      If declarations such as these appear, you will get a warning message + like this:

      +
      +
      +example.i:12: Warning(509): Overloaded spam(short) is shadowed by spam(int)
+at example.i:11.
+
      +
      +

      To fix this, you either need to ignore or rename one of the methods. + For example:

      +
      +
      %rename(spam_short) spam(short);
+...
+void spam(int);
+void spam(short);   // Accessed as spam_short
+
      +
      +

      or

      +
      +
      %ignore spam(short);
+...
+void spam(int);
+void spam(short);   // Ignored
+
      +
      +

      SWIG resolves overloaded functions and methods using a + disambiguation scheme that ranks and sorts declarations according to a + set of type-precedence rules. The order in which declarations appear in + the input does not matter except in situations where ambiguity + arises--in this case, the first declaration takes precedence.

      +

      Please refer to the "SWIG and C++" chapter for more information + about overloading.

      +

      Dealing with the Lua coercion mechanism, the priority is roughly + (integers, floats, strings, userdata). But it is better to rename the + functions rather than rely upon the ordering.

      +

      23.3.11 C++ operators

      +

      Certain C++ overloaded operators can be handled automatically by + SWIG. For example, consider a class like this:

      +
      +
      class Complex {
+private:
+  double rpart, ipart;
+public:
+  Complex(double r = 0, double i = 0) : rpart(r), ipart(i) { }
+  Complex(const Complex &c) : rpart(c.rpart), ipart(c.ipart) { }
+  Complex &operator=(const Complex &c);
+  Complex operator+(const Complex &c) const;
+  Complex operator-(const Complex &c) const;
+  Complex operator*(const Complex &c) const;
+  Complex operator-() const;
+
+  double re() const { return rpart; }
+  double im() const { return ipart; }
+};
+
      +
      +

      When wrapped, it works like you expect:

      +
      +
      +> c = Complex(3,4)
+> d = Complex(7,8)
+> e = c + d
+> e:re()
+10.0
+> e:im()
+12.0
+
      +
      +

      One restriction with operator overloading support is that SWIG is + not able to fully handle operators that aren't defined as part of the + class. For example, if you had code like this

      +
      +
      class Complex {
+...
+friend Complex operator+(double, const Complex &c);
+...
+};
+
      +
      +

      then SWIG doesn't know what to do with the friend function--in fact, + it simply ignores it and issues a warning. You can still wrap the + operator, but you may have to encapsulate it in a special function. For + example:

      +
      +
      %rename(Complex_add_dc) operator+(double, const Complex &);
+...
+Complex operator+(double, const Complex &c);
+
      +
      +

      There are ways to make this operator appear as part of the class + using the %extend directive. Keep reading.

      +

      Also, be aware that certain operators don't map cleanly to Lua, and + some Lua operators don't map cleanly to C++ operators. For instance, + overloaded assignment operators don't map to Lua semantics and will be + ignored, and C++ doesn't support Lua's concatenation operator (.. +).

      +

      In order to keep maximum compatibility within the different + languages in SWIG, the Lua bindings uses the same set of operator names + as python. Although internally it renames the functions to something + else (on order to work with Lua).

      +

      The current list of operators which can be overloaded (and the + alternative function names) are:

      +
        +
      • __add__ operator+
        • +
      • __sub__ operator-
        • +
      • __mul__ operator *
        • +
      • __div__ operator/
        • +
      • __neg__ unary minus
        • +
      • __call__ operator() (often used in functor + classes)
        • +
      • __pow__ the exponential fn (no C++ equivalent, Lua uses +^)
        • +
      • __concat__ the concatenation operator (SWIG maps C++'s +~ to Lua's ..)
        • +
      • __eq__ operator==
        • +
      • __lt__ operator<
        • +
      • __le__ operator<=
        • +
      +

      Note: in Lua, only the equals, less than, and less than equals + operators are defined. The other operators (!=,>,>=) are achieved by + using a logical not applied to the results of other operators.

      +

      The following operators cannot be overloaded (mainly because they + are not supported in Lua)

      +
        +
      • ++ and --
        • +
      • +=,-=,*= etc
        • +
      • % operator (you have to use math.mod)
        • +
      • assignment operator
        • +
      • all bitwise/logical operations
        • +
      +

      SWIG also accepts the __str__() member function which + converts an object to a string. This function should return a const + char*, preferably to static memory. This will be used for the +print() and tostring() functions in Lua. Assuming the + complex class has a function

      +
      +
      const char* __str__()
+{
+        static char buffer[255];
+        sprintf(buffer,"Complex(%g,%g)",this->re(),this->im());
+        return buffer;
+}
+
      +
      +

      Then this will support the following code in Lua

      +
      +
      +> c = Complex(3,4)
+> d = Complex(7,8)
+> e = c + d
+> print(e)
+Complex(10,12)
+> s=tostring(e) -- s is the number in string form
+> print(s)
+Complex(10,12)
+
      +
      +

      It is also possible to overload the operator[], but + currently this cannot be automatically performed. To overload the + operator[] you need to provide two functions, +__getitem__() and __setitem__()

      +
      +
      class Complex
+{
+        //....
+        double __getitem__(int i)const; // i is the index, returns the data
+        void __setitem__(int i,double d); // i is the index, d is the data
+};
+
      +
      +

      23.3.12 Class extension with %extend

      +

      One of the more interesting features of SWIG is that it can extend + structures and classes with new methods. In the previous section, the + Complex class would have benefited greatly from an __str__() method as + well as some repairs to the operator overloading. It can also be used + to add additional functions to the class if they are needed.

      +

      Take the original Complex class

      +
      +
      class Complex {
+private:
+  double rpart, ipart;
+public:
+  Complex(double r = 0, double i = 0) : rpart(r), ipart(i) { }
+  Complex(const Complex &c) : rpart(c.rpart), ipart(c.ipart) { }
+  Complex &operator=(const Complex &c);
+  Complex operator+(const Complex &c) const;
+  Complex operator-(const Complex &c) const;
+  Complex operator*(const Complex &c) const;
+  Complex operator-() const;
+
+  double re() const { return rpart; }
+  double im() const { return ipart; }
+};
+
      +
      +

      Now we extend it with some new code

      +
      +
      %extend Complex {
+   const char *__str__() {
+       static char tmp[1024];
+       sprintf(tmp,"Complex(%g,%g)", $self->re(),$self->im());
+       return tmp;
+   }
+   bool operator==(const Complex& c)
+   {    return ($self->re()==c.re() && $self->im()==c.im();}
+};
+
      +
      +

      Now, in Lua

      +
      +
      +> c = Complex(3,4)
+> d = Complex(7,8)
+> e = c + d
+> print(e)      -- print uses __str__ to get the string form to print
+Complex(10,12)
+> print(e==Complex(10,12))      -- testing the == operator
+true
+> print(e!=Complex(12,12))  -- the != uses the == operator
+true
+
      +
      +

      Extend works with both C and C++ code, on classes and structs. It + does not modify the underlying object in any way---the extensions only + show up in the Lua interface. The only item to take note of is the code + has to use the '$self' instead of 'this', and that you cannot access + protected/private members of the code (as you are not officially part + of the class).

      +

      23.3.13 C++ templates

      +

      C++ templates don't present a huge problem for SWIG. However, in + order to create wrappers, you have to tell SWIG to create wrappers for + a particular template instantiation. To do this, you use the template + directive. For example:

      +
      +
      %module example
+%{
+#include "pair.h"
+%}
+
+template<class T1, class T2>
+struct pair {
+   typedef T1 first_type;
+   typedef T2 second_type;
+   T1 first;
+   T2 second;
+   pair();
+   pair(const T1&, const T2&);
+  ~pair();
+};
+
+%template(pairii) pair<int,int>;
+
      +
      +

      In Lua:

      +
      +
      +> p = example.pairii(3,4)
+> print(p.first,p.second)
+3    4
+
      +
      +

      Obviously, there is more to template wrapping than shown in this + example. More details can be found in the SWIG and C++ chapter. Some + more complicated examples will appear later.

      +

      23.3.14 C++ Smart Pointers

      +

      In certain C++ programs, it is common to use classes that have been + wrapped by so-called "smart pointers." Generally, this involves the use + of a template class that implements operator->() like this:

      +
      +
      template<class T> class SmartPtr {
+   ...
+   T *operator->();
+   ...
+}
+
      +
      +

      Then, if you have a class like this,

      +
      +
      class Foo {
+public:
+     int x;
+     int bar();
+};
+
      +
      +

      A smart pointer would be used in C++ as follows:

      +
      +
      SmartPtr<Foo> p = CreateFoo();   // Created somehow (not shown)
+...
+p->x = 3;                        // Foo::x
+int y = p->bar();                // Foo::bar
+
      +
      +

      To wrap this, simply tell SWIG about the SmartPtr class and the + low-level Foo object. Make sure you instantiate SmartPtr using template + if necessary. For example:

      +
      +
      %module example
+...
+%template(SmartPtrFoo) SmartPtr<Foo>;
+...
+
      +
      +

      Now, in Lua, everything should just "work":

      +
      +
      +> p = example.CreateFoo()          -- Create a smart-pointer somehow
+> p.x = 3                          -- Foo::x
+> print(p:bar())                   -- Foo::bar
+
      +
      +

      If you ever need to access the underlying pointer returned by +operator->() itself, simply use the __deref__() method. + For example:

      +
      +
      +> f = p:__deref__()     -- Returns underlying Foo *
+
      +
      +

      23.3.15 C++ Exceptions

      +

      Lua does not natively support exceptions, but it has errors which + are similar. When a Lua function terminates with an error it returns + one value back to the caller. SWIG automatically maps any basic type + which is thrown into a Lua error. Therefore for a function:

      +
      +
      +int message() throw(const char *) {
+  throw("I died.");
+  return 1;
+}
+
      +
      +

      SWIG will automatically convert this to a Lua error.

      +
      +
      +> message()
+I died.
+stack traceback:
+        [C]: in function 'message'
+        stdin:1: in main chunk
+        [C]: ?
+>
+
      +
      +

      If you want to catch an exception, you must use either pcall() or + xpcall(), which are documented in the Lua manual. Using xpcall will + allow you to obtain additional debug information (such as a + stacktrace).

      +
      +
      +> function a() b() end -- function a() calls function b()
+> function b() message() end -- function b() calls C++ function message(), which throws 
+> ok,res=pcall(a)  -- call the function
+> print(ok,res)
+false   I died.
+> ok,res=xpcall(a,debug.traceback)  -- call the function
+> print(ok,res)
+false   I died.
+stack traceback:
+        [C]: in function 'message'
+        runme.lua:70: in function 'b'
+        runme.lua:67: in function <runme.lua:66>
+        [C]: in function 'xpcall'
+        runme.lua:95: in main chunk
+        [C]: ?
+
      +
      +

      SWIG is able to throw numeric types, enums, chars, char*'s and + std::string's without problem. It has also written typemaps for + std::exception and its derived classes, which convert the exception + into and error string.

      +

      However its not so simple for to throw other types of objects. + Thrown objects are not valid outside the 'catch' block. Therefore they + cannot be returned to the interpreter. The obvious ways to overcome + this would be to either return a copy of the object, or so convert the + object to a string and return that. Though it seems obvious to perform + the former, in some cases this is not possible, most notably when SWIG + has no information about the object, or the object is not + copyable/creatable.

      +

      Therefore by default SWIG converts all thrown object into strings + and returns them. So given a function:

      +
      +
      +void throw_A() throw(A*) {
+  throw new A();
+}
+
      +
      +

      SWIG will just convert it (poorly) to a string and use that as its + error. (Yes its not that useful, but it always works).

      +
      +
      +> throw_A()
+object exception:A *
+stack traceback:
+        [C]: in function 'unknown'
+        stdin:1: in main chunk
+        [C]: ?
+>
+
      +
      +

      To get a more useful behaviour out of SWIG you must either: provide + a way to convert your exceptions into strings, or throw objects which + can be copied.

      +

      If you have your own class which you want output as a string you + will need to add a typemap something like this:

      +
      +
      +%typemap(throws) my_except
+%{ 
+  lua_pushstring(L,$1.what()); // assuming my_except::what() returns a const char* message
+  SWIG_fail; // trigger the error handler
+%}
+
      +
      +

      If you wish your exception to be returned to the interpreter, it + must firstly be copyable. Then you must have and additional %apply + statement, to inform SWIG to return a copy of this object to the + interpreter. For example:

      +
      +
      +%apply SWIGTYPE EXCEPTION_BY_VAL {Exc}; // tell SWIG to return Exc by value to interpreter
+
+class Exc {
+public:
+  Exc(int c, const char *m) {
+    code = c;
+    strncpy(msg,m,256);
+  }
+  int code;
+  char msg[256];
+};
+
+void throw_exc() throw(Exc) {
+  throw(Exc(42,"Hosed"));
+} 
+
      +
      +

      Then the following code can be used (note: we use pcall to catch the + error so we can process the exception).

      +
      +
      +> ok,res=pcall(throw_exc)
+> print(ok)
+false
+> print(res)
+userdata: 0003D880
+> print(res.code,res.msg)
+42      Hosed
+>
+
      +
      +

      Note: is is also possible (though tedious) to have a function throw + several different kinds of exceptions. To process this will require a + pcall, followed by a set of if statements checking the type of the + error.

      +

      All of this code assumes that your C++ code uses exception + specification (which a lot doesn't). If it doesn't consult the " +Exception handling with %catches" section and the " +Exception handling with %exception" section, for more details on how + to add exception specification to functions or globally (respectively).

      +

      23.4 Typemaps

      +

      This section explains what typemaps are and the usage of them. The + default wrappering behaviour of SWIG is enough in most cases. However + sometimes SWIG may need a little additional assistance to know which + typemap to apply to provide the best wrappering. This section will be + explaining how to use typemaps to best effect

      +

      23.4.1 What is a typemap?

      +

      A typemap is nothing more than a code generation rule that is + attached to a specific C datatype. For example, to convert integers + from Lua to C, you might define a typemap like this:

      +
      +
      %module example
+
+%typemap(in) int {
+	$1 = (int) lua_tonumber(L,$input);
+	printf("Received an integer : %d\n",$1);
+}
+%inline %{
+extern int fact(int n);
+%}
+
      +
      +

      Note: you shouldn't use this typemap, as SWIG already has a + typemap for this task. This is purely for example.

      +

      Typemaps are always associated with some specific aspect of code + generation. In this case, the "in" method refers to the conversion of + input arguments to C/C++. The datatype int is the datatype to which the + typemap will be applied. The supplied C code is used to convert values. + In this code a number of special variable prefaced by a $ are used. The + $1 variable is placeholder for a local variable of type int. The $input + is the index on the Lua stack for the value to be used.

      +

      When this example is compiled into a Lua module, it operates as + follows:

      +
      +
      > require "example"
+> print(example.fact(6))
+Received an integer : 6
+720
+
      +
      +

      23.4.2 Using typemaps

      +

      There are many ready written typemaps built into SWIG for all common + types (int, float, short, long, char*, enum and more), which SWIG uses + automatically, with no effort required on your part.

      +

      However for more complex functions which use input/output parameters + or arrays, you will need to make use of <typemaps.i>, which contains + typemaps for these situations. For example, consider these functions:

      +
      +
      void add(int x, int y, int *result) {
+   *result = x + y;
+}
+
+int sub(int *x1, int *y1) {
+   return *x1-*y1;
+}
+
+void swap(int *sx, int *sy) {
+   int t=*sx;
+   *sx=*sy;
+   *sy=t;
+}
+
      +
      +

      It is clear to the programmer, that 'result' is an output parameter, + 'x1' and 'y1' are input parameters and 'sx' and 'sy' are input/output + parameters. However is not apparent to SWIG, so SWIG must to informed + about which kind they are, so it can wrapper accordingly.

      +

      One means would be to rename the argument name to help SWIG, eg +void add(int x, int y, int *OUTPUT), however it is easier to use + the %apply to achieve the same result, as shown below.

      +
      +
      %include <typemaps.i>
+%apply int* OUTPUT {int *result}; // int *result is output
+%apply int* INPUT {int *x1, int *y1}; // int *x1 and int *y1 are input
+%apply int* INOUT {int *sx, int *sy}; // int *sx and int *sy are input and output
+
+void add(int x, int y, int *result);
+int sub(int *x1, int *y1);
+void swap(int *sx, int *sy);
+
      +
      +

      When wrapped, it gives the following results:

      +
      +
      > require "example"
+> print(example.add(1,2))
+3
+> print(demo.sub(1,2))
+-1
+> a,b=1,2
+> c,d=demo.swap(a,b)
+> print(a,b,c,d)
+1       2       2       1
+
      +
      +

      Notice, that 'result' is not required in the arguments to call the + function, as it an output parameter only. For 'sx' and 'sy' they must + be passed in (as they are input), but the original value is not + modified (Lua does not have a pass by reference feature). The modified + results are then returned as two return values. All INPUT/OUTPUT/INOUT + arguments will behave in a similar manner.

      +

      Note: C++ references must be handled exactly the same way. However + SWIG will automatically wrap a const int& as an input + parameter (since that it obviously input).

      +

      23.4.3 Typemaps and arrays

      +

      Arrays present a challenge for SWIG, because like pointers SWIG does + not know whether these are input or output values, nor does SWIG have + any indication of how large an array should be. However with the proper + guidance SWIG can easily wrapper arrays for convenient usage.

      +

      Given the functions:

      +
      +
      extern void sort_int(int* arr, int len);
+extern void sort_double(double* arr, int len);
+
      +
      +

      There are basically two ways that SWIG can deal with this. The first + way, uses the <carrays.i> library to create an array in C/C++ + then this can be filled within Lua and passed into the function. It + works, but its a bit tedious. More details can be found in the +carrays.i documention.

      +

      The second and more intuitive way, would be to pass a Lua table + directly into the function, and have SWIG automatically convert between + Lua-table and C-array. Within the <typemaps.i> file there are + typemaps ready written to perform this task. To use them is again a + matter of using %appy in the correct manner.

      +

      The wrapper file below, shows both the use of carrays as well as the + use of the typemap to wrap arrays.

      +
      +
      // using the C-array
+%include <carrays.i>
+// this declares a batch of function for manipulating C integer arrays
+%array_functions(int,int)
+
+extern void sort_int(int* arr, int len); // the function to wrap
+
+// using typemaps
+%include <typemaps.i>
+%apply (double *INOUT,int) {(double* arr,int len)};
+
+extern void sort_double(double* arr, int len); // the function to wrap
+
      +
      +

      Once wrappered, the functions can both be called, though with + different ease of use:

      +
      +
      require "example"
+ARRAY_SIZE=10
+
+-- passing a C array to the sort_int()
+arr=example.new_int(ARRAY_SIZE) -- create the array
+for i=0,ARRAY_SIZE-1 do -- index 0..9 (just like C)
+    example.int_setitem(arr,i,math.random(1000))
+end
+example.sort_int(arr,ARRAY_SIZE)  -- call the function
+example.delete_int(arr) -- must delete the allocated memory
+
+-- use a typemap to call with a Lua-table
+-- one item of note: the typemap creates a copy, rather than edit-in-place
+t={} -- a Lua table
+for i=1,ARRAY_SIZE do -- index 1..10 (Lua style)
+    t[i]=math.random(1000)/10
+end
+t=example.sort_double(t) -- replace t with the result
+
      +
      +

      Obviously the first version could be made less tedious by writing a + Lua function to perform the conversion from a table to a C-array. The +%luacode directive is good for this. See SWIG\Examples\lua\arrays + for an example of this.

      +

      Warning: in C indexes start at ZERO, in Lua indexes start at + ONE. SWIG expects C-arrays to be filled for 0..N-1 and Lua tables to be + 1..N, (the indexing follows the norm for the language). In the typemap + when it converts the table to an array it quietly changes the indexing + accordingly. Take note of this behaviour if you have a C function which + returns indexes.

      +

      Note: SWIG also can support arrays of pointers in a similar manner.

      +

      23.4.4 Typemaps and pointer-pointer functions

      +

      Several C++ libraries use a pointer-pointer functions to create its + objects. These functions require a pointer to a pointer which is then + filled with the pointer to the new object. Microsoft's COM and DirectX + as well as many other libraries have this kind of function. An example + is given below:

      +
      +
      struct iMath;    // some structure
+int Create_Math(iMath** pptr); // its creator (assume it mallocs)
+
      +
      +

      Which would be used with the following C code:

      +
      +
      iMath* ptr;
+int ok;
+ok=Create_Math(&ptr);
+// do things with ptr
+//...
+free(ptr); // dispose of iMath
+
      +
      +

      SWIG has a ready written typemap to deal with such a kind of function + in <typemaps.i>. It provides the correct wrappering as well as setting + the flag to inform Lua that the object in question should be garbage + collected. Therefore the code is simply:

      +
      +
      %include <typemaps.i>
+%apply SWIGTYPE** OUTPUT{iMath **pptr }; // tell SWIG its an output
+
+struct iMath;    // some structure
+int Create_Math(iMath** pptr); // its creator (assume it mallocs)
+
      +
      +

      The usage is as follows:

      +
      +
      ok,ptr=Create_Math() -- ptr is a iMath* which is returned with the int (ok)
+ptr=nil -- the iMath* will be GC'ed as normal
+
      +
      +

      23.5 Writing typemaps

      +

      This section describes how you can modify SWIG's default wrapping + behavior for various C/C++ datatypes using the %typemap + directive. This is an advanced topic that assumes familiarity with the + Lua C API as well as the material in the "Typemaps +" chapter.

      +

      Before proceeding, it should be stressed that writing typemaps is + rarely needed unless you want to change some aspect of the wrappering, + or to achieve an effect which in not available with the default + bindings.

      +

      Before proceeding, you should read the previous section on using + typemaps, as well as read the ready written typemaps found in + luatypemaps.swg and typemaps.i. These are both well documented and + fairly easy to read. You should not attempt to write your own typemaps + until you have read and can understand both of these files (they may + well also give you a idea to base your worn on).

      +

      23.5.1 Typemaps you can write

      +

      There are many different types of typemap that can be written, the + full list can be found in the "Typemaps" + chapter. However the following are the most commonly used ones.

      +
        +
      • in this is for input arguments to functions
        • +
      • out this is for return types from functions
        • +
      • argout this is for a function argument which is actually + returning something
        • +
      • typecheck this is used to determine which overloaded + function should be called (the syntax for the typecheck is different + from the typemap, see typemaps for details).
        • +
      +

      23.5.2 SWIG's Lua-C API

      +

      This section explains the SWIG specific Lua-C API. It does not cover + the main Lua-C api, as this is well documented and not worth covering.

      +

      int SWIG_ConvertPtr(lua_State* L,int index,void** + ptr,swig_type_info *type,int flags);

      +
      This is the standard function used for converting a + Lua userdata to a void*. It takes the value at the given index in the + Lua state and converts it to a userdata. It will then provide the + neccesary type checks, confirming that the pointer is compatible with + the type given in 'type'. Then finally setting '*ptr' to the pointer. + If flags is set to SWIG_POINTER_DISOWN, this is will clear any + ownership flag set on the object. +
      The returns a value which can be checked with the macro SWIG_IsOK()
      +

      void SWIG_NewPointerObj(lua_State* L,void* ptr,swig_type_info + *type,int own);

      +
      This is the opposite of SWIG_ConvertPtr, as it + pushes a new userdata which wrappers the pointer 'ptr' of type 'type'. + The parameter 'own' specifies if the object is owned be Lua and if it + is 1 then Lua will GC the object when the userdata is disposed of.
      +

      void* SWIG_MustGetPtr(lua_State* L,int index,swig_type_info + *type,int flags,int argnum,const char* func_name);

      +
      This function is a version of SWIG_ConvertPtr(), + except that it will either work, or it will trigger a lua_error() with + a text error message. This function is rarely used, and may be + deprecated in the future.
      +

      SWIG_fail

      +
      This macro, when called within the context of a + SWIG wrappered function, will jump to the error handler code. This will + call any cleanup code (freeing any temp variables) and then triggers a + lua_error. +
      A common use for this code is: +
      +
      +if (!SWIG_IsOK(SWIG_ConvertPtr( .....)){
+ lua_pushstring(L,"something bad happened");
+ SWIG_fail;
+}
      +
      +

      SWIG_fail_arg(char* func_name,int argnum,char* type)

      +
      This macro, when called within the context of a + SWIG wrappered function, will display the error message and jump to the + error handler code. The error message is of the form +
      +"Error in func_name (arg argnum), expected 'type' got 'whatever the type was'"
+
      +
      +

      SWIG_fail_ptr(const char* fn_name,int argnum,swig_type_info* + type);

      +
      Similar to SWIG_fail_arg, except that it will + display the swig_type_info information instead.
      +

      23.6 Customization of your Bindings

      +

      This section covers adding of some small extra bits to your module + to add the last finishing touches.

      +

      23.6.1 Writing your own custom wrappers

      +

      Sometimes, it may be neccesary to add your own special functions, + which bypass the normal SWIG wrappering method, and just use the native + Lua API calls. These 'native' functions allow direct adding of your own + code into the module. This is performed with the %native + directive as follows:

      +
      +
      %native(my_func) int native_function(lua_State*L);  // registers native_function() with SWIG
+...
+%{
+int native_function(lua_State*L) // my native code
+{
+ ...
+}
+%}
+
      +
      +

      The %native directive in the above example, tells SWIG that + there is a function int native_function(lua_State*L); which is + to be added into the module under the name 'my_func'. SWIG + will not add any wrappering for this function, beyond adding it into + the function table. How you write your code is entirely up to you.

      +

      23.6.2 Adding additional Lua code

      +

      As well as adding additional C/C++ code, its also possible to add + your own Lua code to the module as well. This code is executed once all + other initialisation, including the %init code has been called.

      +

      The directive %luacode adds code into the module which is + executed upon loading. Normally you would use this to add your own + functions to the module. Though you could easily perform other tasks.

      +
      +
      %module example;
+
+%luacode {
+  function example.greet() 
+    print "hello world" 
+  end
+
+  print "Module loaded ok"
+}
+...
+%}
+
      +
      +

      Notice that the code is not part of the module table. Therefore any + references to the module must have the module name added.

      +

      Should there be an error in the Lua code, this will not + stop loading of the module. The default behaviour of SWIG is to print a + error message to stderr and then continue. It is possible to change + this behaviour by using a #define SWIG_DOSTRING_FAIL(STR) to + define a different behaviour should the code fail.

      +

      Good uses for this feature is adding of new code, or writing helper + functions to simplify some of the code. See Examples/lua/arrays for an + example of this code.

      +

      23.7 Details on the Lua binding

      +

      In the previous section, a high-level view of Lua wrapping was + presented. Obviously a lot of stuff happens behind the scenes to make + this happen. This section will explain some of the low-level details on + how this is achieved.

      +

      If you just want to use SWIG and don't care how it works, then + stop reading here. This is going into the guts of the code and how it + works. Its mainly for people who need to know whats going on within the + code.

      +

      23.7.1 Binding global data into the module.

      +

      Assuming that you had some global data that you wanted to share + between C and Lua. How does SWIG do it?

      +
      +
      %module example;
+extern double Foo;
+
      +
      +

      SWIG will effectively generate the pair of functions

      +
      +
      void Foo_set(double);
+double Foo_get();
+
      +
      +

      At initialisation time, it will then add to the interpreter a table + called 'example', which represents the module. It will then add all its + functions to the module. (Note: older versions of SWIG actually added + the Foo_set() and Foo_get() functions, current implementation does not + add these functions any more.) But it also adds a metatable to this + table, which has two functions (__index and __newindex +) as well as two tables (.get and .set) The following + Lua code will show these hidden features.

      +
      +
      +> print(example)
+table: 003F8F90
+> m=getmetatable(example)
+> table.foreach(m,print)
+.set    table: 003F9088
+.get    table: 003F9038
+__index function: 003F8FE0
+__newindex      function: 003F8FF8
+> g=m['.get']
+> table.foreach(g,print)
+Foo     function: 003FAFD8
+>
+
      +
      +

      The .get and .set tables are lookups connecting the variable name + 'Foo' to the accessor/mutator functions (Foo_set,Foo_get)

      +

      The Lua equivalent of the code for the __index and +__newindex looks a bit like this

      +
      +
      +function __index(mod,name)
+        local g=getmetatable(mod)['.get'] -- gets the table
+        if not g then return nil end
+        local f=g[name] -- looks for the function
+        -- calls it & returns the value
+        if type(f)=="function" then return f() end
+        return nil
+end
+
+function __newindex(mod,name,value)
+        local s=getmetatable(mod)['.set'] -- gets the table
+        if not s then return end
+        local f=s[name] -- looks for the function
+        -- calls it to set the value
+        if type(f)=="function" then f(value)
+        else rawset(mod,name,value) end
+end
+
      +
      +

      That way when you call 'a=example.Foo', the interpreter + looks at the table 'example' sees that there is no field 'Foo' and + calls __index. This will in turn check in '.get' table and find the + existence of 'Foo' and then return the value of the C function call + 'Foo_get()'. Similarly for the code 'example.Foo=10', the + interpreter will check the table, then call the __newindex which will + then check the '.set' table and call the C function 'Foo_set(10)'.

      +

      23.7.2 Userdata and Metatables

      +

      As mentioned earlier, classes and structures, are all held as + pointer, using the Lua 'userdata' structure. This structure is actually + a pointer to a C structure 'swig_lua_userdata', which contains the + pointer to the data, a pointer to the swig_type_info (an internal SWIG + struct) and a flag which marks if the object is to be disposed of when + the interpreter no longer needs it. The actual accessing of the object + is done via the metatable attached to this userdata.

      +

      The metatable is a Lua 5.0 feature (which is also why SWIG cannot + wrap Lua 4.0). Its a table which holds a list of functions, operators + and attributes. This is what gives the userdata the feeling that it is + a real object and not just a hunk of memory.

      +

      Given a class

      +
      +
      %module excpp;
+
+class Point
+{
+public:
+ int x,y;
+ Point(){x=y=0;}
+ ~Point(){}
+ virtual void Print(){printf("Point @%p (%d,%d)\n",this,x,y);}
+};
+
      +
      +

      SWIG will create a module excpp, with all the various function + inside. However to allow the intuitive use of the userdata is also + creates up a set of metatables. As seen in the above section on global + variables, use of the metatables allows for wrappers to be used + intuitively. To save effort, the code creates one metatable per class + and stores it inside Lua's registry. Then when an new object is + instantiated, the metatable is found in the registry and the userdata + associated to the metatable. Currently derived classes make a complete + copy of the base classes table and then add on their own additional + function.

      +

      Some of the internals can be seen by looking at a classes metatable.

      +
      +
      +> p=excpp.Point()
+> print(p)
+userdata: 003FDB28
+> m=getmetatable(p)
+> table.foreach(m,print)
+.type   Point
+__gc    function: 003FB6C8
+__newindex      function: 003FB6B0
+__index function: 003FB698
+.get    table: 003FB4D8
+.set    table: 003FB500
+.fn     table: 003FB528
+
      +
      +

      The '.type' attribute is the name of the class. The '.get' and + '.set' tables work in a similar manner to the modules, the main + difference is the '.fn' table which also holds all the member + functions. (The '__gc' function is the classes destructor function)

      +

      The Lua equivalent of the code for enabling functions looks a little + like this

      +
      +
      +function __index(obj,name)
+        local m=getmetatable(obj) -- gets the metatable
+        if not m then return nil end
+        local g=m['.get'] -- gets the attribute table
+        if not g then return nil end
+        local f=g[name] -- looks for the get_attribute function
+        -- calls it & returns the value
+        if type(f)=="function" then return f() end
+        -- ok, so it not an attribute, maybe its a function
+        local fn=m['.fn'] -- gets the function table
+        if not fn then return nil end
+        local f=fn[name] -- looks for the function
+        -- if found the fn then return the function
+        -- so the interpreter can call it
+        if type(f)=="function" then return f end
+        return nil
+end
+
      +
      +

      So when 'p:Print()' is called, the __index looks on the object + metatable for a 'Print' attribute, then looks for a 'Print' function. + When it finds the function, it returns the function, and then + interpreter can call 'Point_Print(p)'

      +

      In theory, you can play with this usertable & add new features, but + remember that it is a shared table between all instances of one class, + and you could very easily corrupt the functions in all the instances.

      +

      Note: Both the opaque structures (like the FILE*) and normal + wrappered classes/structs use the same 'swig_lua_userdata' structure. + Though the opaque structures has do not have a metatable attached, or + any information on how to dispose of them when the interpreter has + finished with them.

      +

      Note: Operator overloads are basically done in the same way, by + adding functions such as '__add' & '__call' to the classes metatable. + The current implementation is a bit rough as it will add any member + function beginning with '__' into the metatable too, assuming its an + operator overload.

      +

      23.7.3 Memory management

      +

      Lua is very helpful with the memory management. The + 'swig_lua_userdata' is fully managed by the interpreter itself. This + means that neither the C code nor the Lua code can damage it. Once a + piece of userdata has no references to it, it is not instantly + collected, but will be collected when Lua deems is necessary. (You can + force collection by calling the Lua function collectgarbage() +). Once the userdata is about to be free'ed, the interpreter will check + the userdata for a metatable and for a function '__gc'. If this exists + this is called. For all complete types (ie normal wrappered classes & + structs) this should exist. The '__gc' function will check the + 'swig_lua_userdata' to check for the 'own' field and if this is true + (which is will be for all owned data's) it will then call the + destructor on the pointer.

      +

      It is currently not recommended to edit this field or add some user + code, to change the behaviour. Though for those who wish to try, here + is where to look.

      +

      It is also currently not possible to change the ownership flag on + the data (unlike most other scripting languages, Lua does not permit + access to the data from within the interpreter)

      +
      +

      24 SWIG and Modula-3

      + + +
      + +
      + +

      This chapter describes SWIG's support of +Modula-3. You should be familiar with the basics + of SWIG, especially typemaps.

      +

      24.1 Overview

      +

      The Modula-3 support is 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! The Modula-3 generator was already + useful for interfacing to the libraries

      +
        +
      1. + PLPlot
        2. +
      2. + FFTW .
        3. +
      +

      I took some more time to explain why I think it's right what I'm + doing. So the introduction got a bit longer than it should ... ;-)

      +

      24.1.1 Why not scripting ?

      +

      SWIG started as wrapper from the fast compiled languages C and C++ + to high level scripting languages like Python. Although scripting + languages are designed to make programming life easier by hiding + machine internals from the programmer there are several aspects of + today's scripting languages that are unfavourable in my opinion.

      +

      Besides C, C++, Cluster (a Modula derivate for Amiga computers) I + evaluated several scripting like languages in the past: Different + dialects of BASIC, Perl, ARexx (a variant of Rexx for Amiga computers), + shell scripts. I found them too inconsistent, too weak in + distinguishing types, too weak in encapsulating pieces of code. + Eventually I have started several projects in Python because of the + fine syntax. But when projects became larger I lost the track. I got + convinced that one can not have maintainable code in a language that is + not statically typed. In fact the main advantages of scripting + languages e.g. matching regular expressions, complex built-in datatypes + like lists, dictionaries, are not advantages of the language itself but + can be provided by function libraries.

      +

      24.1.2 Why Modula-3 ?

      +

      Modula-3 is a compiler language in the tradition of Niklaus Wirth's + Modula 2, which is in turn a successor of the popular Pascal. I have + chosen Modula-3 because of its logical syntax, strong modularization, + the type system which is very detailed for machine types compared to + other languages. Of course it supports all of the modern games like + exceptions, objects, garbage collection, threads. While C++ programmers + must control three languages, namely the preprocessor, C and ++, + Modula-3 is made in one go and the language definition is really + compact.

      +

      On the one hand Modula-3 can be safe (but probably less efficient) + in normal modules while providing much static and dynamic safety. On + the other hand you can write efficient but less safe code in the style + of C within UNSAFE modules.

      +

      Unfortunately Modula's safety and strength requires more writing + than scripting languages do. Today if I want to safe characters I + prefer Haskell (similar to OCAML) - it's statically typed, too.

      +

      24.1.3 Why C / C++ ?

      +

      Although it is no problem to write Modula-3 programs that performs + as fast as C most libraries are not written in Modula-3 but in C. + Fortunately the binary interface of most function libraries can be + addressed by Modula-3. Even more fortunately even non-C libraries may + provide C header files. This is where SWIG becomes helpful.

      +

      24.1.4 Why SWIG ?

      +

      The C headers and the possibility to interface to C libraries still + leaves the work for you to write Modula-3 interfaces to them. To make + things comfortable you will also need wrappers that convert between + high-level features of Modula-3 (garbage collecting, exceptions) and + the low level of the C libraries.

      +

      SWIG converts C headers to Modula-3 interfaces for you. You could + call the C functions without loss of efficiency but it won't be joy + because you could not pass TEXTs or open arrays and you would + have to process error return codes rather then exceptions. But using + some typemaps SWIG will also generate wrappers that bring the whole + Modula-3 comfort to you. If the library API is ill designed writing + appropriate typemaps can be still 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.

      +

      But you have still a problem: C library interfaces are often ill. + They lack for certain information because C compilers wouldn't care + about. You should integrate detailed type information by adding +typedefs and consts and you should persuade the C library + programmer to add this information to his interface. Only this way + other language users can benefit from your work and only this way you + can easily update your interfaces when a new library version is + released. You will realise that writing good SWIG interfaces is + very costly and it will only amortise when considering evolving + libraries.

      +

      Without SWIG you would probably never consider to call C++ libraries + from Modula-3. But with SWIG this is worth a consideration. SWIG can + write C wrappers to C++ functions and object methods that may throw + exceptions. In fact it breaks down C++ libraries to C interfaces which + can be in turn called from Modula-3. To make it complete you can hide + the C interface with Modula-3 classes and exceptions.

      +

      Although SWIG does the best it can do it can only serve as a one-way + strategy. That means you can use C++ libraries with Modula-3 (even with + call back functions), but it's certainly not possible to smoothly + integrate Modula-3 code into a C / C++ project.

      +

      24.2 Conception

      +

      24.2.1 Interfaces to C libraries

      +

      Modula-3 has an 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.

      + + + + + + + + +
      C library support integrated in Modula-3
      Pragma <* EXTERNAL *>Precedes a declaration of + a PROCEDURE that is implemented in an external library instead of a + Modula-3 module.
      Pragma <* CALLBACK *>Precedes a declaration of + a PROCEDURE that should be called by external library code.
      Module CtypesContains Modula-3 types that + match some basic C types.
      Module M3toCContains routines that convert + between Modula-3's TEXT type and C's char * type.
      +

      In each run of SWIG the Modula-3 part generates several files:

      + + + + + + + + +
      Module name schemeIdentifier for %insert +Description
      ModuleRaw.i3m3rawintf +Declaration of types that are equivalent to those of the C library, +EXTERNAL procedures as interface to the C library functions
      ModuleRaw.m3m3rawimplAlmost + empty.
      Module.i3m3wrapintf +Declaration of comfortable wrappers to the C library functions.
      Module.m3m3wrapimpl +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 WeakRefs and raises exceptions.
      m3makefilem3makefileAdd 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 m3makefile in each run, because SWIG + must be started for each Modula-3 module it creates. Thus the + m3makefile is overwritten each time. :-(
      +

      Here's a scheme of how the function calls to Modula-3 wrappers are + redirected to C library functions:

      + + + + + +
      Modula-3 wrapper +
      Module.i3 +
      generated by Modula-3 part of SWIG
      + + | +
      v
      Modula-3 interface to C +
      ModuleRaw.i3 +
      generated by Modula-3 part of SWIG      		--> + C library
      +

      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 +Database, it is good Modula-3 style to set up one Module with the + name Database where the database type is declared with the + name T and where all functions are declared that operates on + it.

      +

      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 (%ignore +) and the principal type must be renamed (%typemap).

      +

      24.2.2 Interfaces to C++ libraries

      +

      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.

      +

      Here's a scheme of how the function calls to Modula-3 wrappers a + redirected to C library functions:

      + + + + +
      Modula-3 wrapper +
      Module.i3 +
      generated by Modula-3 part of SWIG      		 +C++ library
      + + | +
      v      		 ^ +
      |
      Modula-3 interface to C +
      ModuleRaw.i3 +
      generated by Modula-3 part of SWIG      		--> + C interface to C++ +
      module_wrap.cxx +
      generated by the SWIG core
      +

      Wrapping C++ libraries arises additional problems:

      +
        +
      • Is it sensible to wrap C++ classes with Modula-3 classes?
        • +
      • How to find the wrapping Modula-3 class for a class pointer that is + returned by a C++ routine?
        • +
      • How to deal with multiple inheritance which was neglected for + Modula-3 for good reasons?
        • +
      • 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 Java + and Python.
        • +
      • How to manage storage with the garbage collector of Modula-3? + Support for %newobject and +%typemap(newfree) 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.
        • +
      • How to turn C++ exceptions into Modula-3 exceptions? There's also + no support for %exception, yet.
        • +
      +

      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.

      +

      24.3 Preliminaries

      +

      24.3.1 Compilers

      +

      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 library file +modula3.swg may do so. For testing examples I use Critical + Mass cm3.

      +

      24.3.2 Additional Commandline Options

      +

      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.

      + + + + + +
      Modula-3 specific optionsDescription
      -generateconst <file> Disable generation + of interfaces and wrappers. Instead write code for computing numeric + values of constants to the specified file. +
      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 (1 << + FLAG_MAXIMIZEWINDOW) 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. +
      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 double. + 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.
      -generaterename <file> Disable generation + of interfaces and wrappers. Instead generate suggestions for +%rename. +
      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 %rename + directive. This switch outputs a list of such directives with a name + suggestion generated by a simple heuristic.
      -generatetypemap <file> Disable generation + of interfaces and wrappers. Instead generate templates for some basic + typemaps.
      +

      24.4 Modula-3 typemaps

      +

      24.4.1 Inputs and outputs

      +

      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.

      +

      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 typemap library +modula3.swg . 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.

      +

      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 ModuleRaw.i3 or the + Module.i3, 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.

      +

      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:

      +
        +
      • Generate PROCEDURE signature.
        • +
      • Declare local variables.
        • +
      • Convert input values from Modula-3 to C.
        • +
      • Check for input value integrity.
        • +
      • Call the C function.
        • +
      • Check returned values, e.g. error codes.
        • +
      • Convert and write back values into Modula-3 records.
        • +
      • Free temporary storage.
        • +
      • Return values.
        • +
      + + + + + + + + + + + + + + + + + + + + + + + + + + +
      TypemapExampleDescription
      m3wrapargvar$1: INTEGER := $1_name; + Declaration of some variables needed for temporary results.
      m3wrapargconst$1 = "$1_name"; + Declaration of some constant, maybe for debug purposes.
      m3wrapargrawORD($1_name) The + expression that should be passed as argument to the raw Modula-3 + interface function.
      m3wrapargdirout Referential arguments + can be used for input, output, update. ???
      m3wrapinmodeREADONLY One of Modula-3 + parameter modes VALUE (or empty), VAR, READONLY +
      m3wrapinname New name of the input argument.
      m3wrapintype Modula-3 type of the input + argument.
      m3wrapindefault Default value of the input + argument
      m3wrapinconv$1 := M3toC.SharedTtoS($1_name); + Statement for converting the Modula-3 input value to C compliant value.
      m3wrapincheckIF Text.Length($1_name) > 10 THEN + RAISE E("str too long"); END; Check the integrity of the + input value.
      m3wrapoutname Name of the RECORD + field to be used for returning multiple values. This applies to + referential output arguments that shall be turned into return values.
      m3wrapouttype Type of the value that is + returned instead of a referential output argument.
      m3wrapoutconv
      m3wrapoutcheck
      m3wrapretraw
      m3wrapretname
      m3wraprettype
      m3wrapretvar
      m3wrapretconv
      m3wrapretcheck
      m3wrapfreeargM3toC.FreeSharedS(str,arg1); + Free resources that were temporarily used in the wrapper. Since this + step should never be skipped, SWIG will put it in the FINALLY + branch of a TRY .. FINALLY structure.
      +

      24.4.2 Subranges, Enumerations, Sets

      +

      Subranges, enumerations, and sets are machine oriented types that + make Modula very strong and expressive compared with the type systems + of many other languages.

      +
        +
      • Subranges are used for statically restricted choices of integers.
        • +
      • Enumerations are used for named choices.
        • +
      • Sets are commonly used for flag (option) sets.
        • +
      +

      Using them extensively makes Modula code very safe and readable.

      +

      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 (#define, const int, +enum) is somewhere used for defining something that must be handled + completely different in Modula-3 (INTEGER, enumeration, +SET).

      +

      I played around with several %features and %pragma +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.

      +

      24.4.3 Objects

      +

      Declarations of C++ classes are mapped to OBJECT 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.

      +

      24.4.4 Imports

      +

      Pieces of Modula-3 code provided by typemaps may contain identifiers + from foreign modules. If the typemap m3wrapinconv for blah + * contains code using the function M3toC.SharedTtoS you + may declare %typemap("m3wrapinconv:import") blah * %{M3toC%}. + Then the module M3toC is imported if the m3wrapinconv + typemap for blah * is used at least once. Use +%typemap("m3wrapinconv:import") blah * %{MyConversions AS M3toC%} + if you need module renaming. Unqualified import is not supported.

      +

      It is cumbersome to add this typemap to each piece of Modula-3 code. + It is especially useful when writing general typemaps for the typemap + library modula3.swg + . For a monolithic module you might be better off if you add the + imports directly:

      +
      +
      +%insert(m3rawintf) %{
+IMPORT M3toC;
+%}
+
      +
      +

      24.4.5 Exceptions

      +

      Modula-3 provides another possibility of an output of a function: + exceptions.

      +

      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.

      +

      The RAISES clause is controlled by typemaps with the +throws extension. If the typemap m3wrapinconv for blah + * contains code that may raise the exceptions OSError.E + you should declare %typemap("m3wrapinconv:throws") blah * + %{OSError.E%}.

      +

      24.4.6 Example

      +

      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:

      +
      +
      +         (* %relabel  m3wrapinmode m3wrapinname m3wrapintype  m3wrapindefault *)
+  PROCEDURE Name     (READONLY       str       :    TEXT    :=      ""       )
+              (* m3wrapoutcheck:throws *)
+     : NameResult RAISES {E} =
+    CONST
+      arg1name = "str";                  (* m3wrapargconst *)
+    VAR
+      arg0   : C.char_star;              (* m3wrapretvar *)
+      arg1   : C.char_star;              (* m3wrapargvar *)
+      arg2   : C.int;
+      result : RECORD
+           (*m3wrapretname  m3wraprettype*)
+                 unixPath : TEXT;
+           (*m3wrapoutname  m3wrapouttype*)
+                 checksum : CARDINAL;
+               END;
+    BEGIN
+      TRY
+        arg1 := M3toC.SharedTtoS(str);   (* m3wrapinconv *)
+        IF Text.Length(arg1) > 10 THEN   (* m3wrapincheck *)
+          RAISE E("str too long");
+        END;
+ (* m3wrapretraw           m3wrapargraw *)
+        arg0 := MessyToUnix  (arg1,   arg2);
+        result.unixPath := M3toC.CopyStoT(arg0);  (* m3wrapretconv *)
+        result.checksum := arg2;         (* m3wrapoutconv *)
+        IF result.checksum = 0 THEN      (* m3wrapoutcheck *)
+          RAISE E("invalid checksum");
+        END;
+      FINALLY
+        M3toC.FreeSharedS(str,arg1);     (* m3wrapfreearg *)
+      END;
+    END Name;
+
      +
      +

      24.5 More hints to the generator

      +

      24.5.1 Features

      + + + + +
      FeatureExampleDescription
      multiretval%m3multiretval get_box; or +%feature("modula3:multiretval") get_box;Let the denoted + function return a RECORD rather than a plain value. This +RECORD 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 must have the +multiretval feature activated, but it is explicitly requested from + the user to prevent mistakes.
      constnumeric%constnumeric(12) twelve; or +%feature("constnumeric","12") twelve;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 -generateconst +option. In future it may be generalized to other kind of values such + as strings.
      +

      24.5.2 Pragmas

      + + + + +
      PragmaExampleDescription
      unsafe%pragma(modula3) unsafe="true"; +Mark the raw interface modules as UNSAFE. This will be + necessary in many cases.
      library%pragma(modula3) library="m3fftw"; +Specifies the library name for the wrapper library to be created. It + should be distinct from the name of the library to be wrapped.
      +

      24.6 Remarks

      +
        +
      • The Modula-3 part of SWIG doesn't try to generate nicely formatted + code. Use m3pp to postprocess the Modula files, it does a very + good job here.
        • +
      +
      + + +

      25 SWIG and MzScheme

      + + +
      + +
      + +

      This section contains information on SWIG's support of MzScheme.

      +

      25.1 Creating native MzScheme structures

      +

      Example interface file:

      +
      +
      +/* define a macro for the struct creation */
+%define handle_ptr(TYPE,NAME)
+%typemap(argout) TYPE *NAME{
+    Scheme_Object *o = SWIG_NewStructFromPtr($1, $*1_mangle);
+    SWIG_APPEND_VALUE(o);
+}
+
+%typemap(in,numinputs=0) TYPE *NAME (TYPE temp) {
+    $1 = &temp;
+}
+%enddef
+
+/* setup the typemaps for the pointer to an output parameter cntrs */
+handle_ptr(struct diag_cntrs, cntrs);
+
      +
      +

      Then in scheme, you can use regular struct access procedures like

      +
      +
      +	; suppose a function created a struct foo as 
+	; (define foo (make-diag-cntrs (#x1 #x2 #x3) (make-inspector))
+	; Then you can do
+	(format "0x~x" (diag-cntrs-field1 foo))
+	(format "0x~x" (diag-cntrs-field2 foo))
+	;etc...
+
      +
      +

      That's pretty much it. It works with nested structs as well.

      +
      + +

      26 SWIG and Ocaml

      + + +
      + +
      + +

      This chapter describes SWIG's support of Ocaml. Ocaml is a + relatively recent addition to the ML family, and is a recent addition + to SWIG. It's the second compiled, typed language to be added. Ocaml + has widely acknowledged benefits for engineers, mostly derived from a + sophisticated type system, compile-time checking which eliminates + several classes of common programming errors, and good native + performance. While all of this is wonderful, there are well-written C + and C++ libraries that Ocaml users will want to take advantage of as + part of their arsenal (such as SSL and gdbm), as well as their own + mature C and C++ code. SWIG allows this code to be used in a natural, + type-safe way with Ocaml, by providing the necessary, but repetitive + glue code which creates and uses Ocaml values to communicate with C and + C++ code. In addition, SWIG also produces the needed Ocaml source that + binds variants, functions, classes, etc.

      +

      If you're not familiar with the Objective Caml language, you can + visit The Ocaml Website.

      +

      26.1 Preliminaries

      +

      SWIG 1.3 works with Ocaml 3.04 and above. Given the choice, you + should use the latest stable release. The SWIG Ocaml module has been + tested on Linux (x86,PPC,Sparc) and Cygwin on Windows. The best way to + determine whether your system will work is to compile the examples and + test-suite which come with SWIG. You can do this by running make + check from the SWIG root directory after installing SWIG. The + Ocaml module has been tested using the system's dynamic linking (the + usual -lxxx against libxxx.so, as well as with Gerd Stolpmann's +Dl package . The ocaml_dynamic and ocaml_dynamic_cpp targets in the + file Examples/Makefile illustrate how to compile and link SWIG modules + that will be loaded dynamically. This has only been tested on Linux so + far.

      +

      26.1.1 Running SWIG

      +

      The basics of getting a SWIG Ocaml module up and running can be seen + from one of SWIG's example Makefiles, but is also described here. To + build an Ocaml module, run SWIG using the -ocaml option.

      +
      +
      +%swig -ocaml example.i
+
      +
      +

      This will produce 3 files. The file example_wrap.c contains + all of the C code needed to build an Ocaml module. To build the module, + you will compile the file example_wrap.c with ocamlc + or ocamlopt to create the needed .o file. You will need to + compile the resulting .ml and .mli files as well, and do the final link + with -custom (not needed for native link).

      +

      26.1.2 Compiling the code

      +

      The O'Caml SWIG module now requires you to compile a module ( +Swig) separately. In addition to aggregating common SWIG + functionality, the Swig module contains the data structure that + represents C/C++ values. This allows easier data sharing between + modules if two or more are combined, because the type of each SWIG'ed + module's c_obj is derived from Swig.c_obj_t. This also allows SWIG to + acquire new conversions painlessly, as well as giving the user more + freedom with respect to custom typing. Use ocamlc or +ocamlopt to compile your SWIG interface like:

      +
      +
      +% swig -ocaml -co swig.mli ; swig -ocaml co swig.ml
+% ocamlc -c swig.mli ; ocamlc -c swig.ml
+% ocamlc -c -ccopt "-I/usr/include/foo" example_wrap.c
+% ocamlc -c example.mli
+% ocamlc -c example.ml
+
      +
      +

      ocamlc is aware of .c files and knows how to handle them. + Unfortunately, it does not know about .cxx, .cc, or .cpp files, so when + SWIG is invoked in C++ mode, you must:

      +
      +
      +% cp example_wrap.cxx example_wrap.cxx.c
+
      % ocamlc -c ... -ccopt -xc++ example_wrap.cxx.c
+
      % ...
+
      
+
      +
      +

      26.1.3 The camlp4 module

      +

      The camlp4 module (swigp4.ml -> swigp4.cmo) contains a simple + rewriter which makes C++ code blend more seamlessly with objective caml + code. It's use is optional, but encouraged. The source file is included + in the Lib/ocaml directory of the SWIG source distribution. You can + checkout this file with "swig -ocaml -co swigp4.ml". You + should compile the file with "ocamlc -I `camlp4 -where` -pp + 'camlp4o pa_extend.cmo q_MLast.cmo' -c swigp4.ml"

      +

      The basic principle of the module is to recognize certain non-caml + expressions and convert them for use with C++ code as interfaced by + SWIG. The camlp4 module is written to work with generated SWIG + interfaces, and probably isn't great to use with anything else.

      +

      Here are the main rewriting rules:

      + + + + + + + + + + + + + +
      InputRewritten to
      f'( ... ) as in +
      atoi'("0") or +
      _exit'(0)      		f(C_list [ ... ]) as in +
      atoi (C_list [ C_string "0" ]) or +
      _exit (C_list [ C_int 0 ])
      object -> method ( ... )(invoke object) "method" + (C_list [ ... ])
      object 'binop argument as in +
      a '+= b      		 (invoke object) "+=" argument as in +
      (invoke a) "+=" b
      Note that because camlp4 always recognizes << and + >>, they are replaced by lsl and lsr in operator names.
      'unop object as in +
      '! a      		 (invoke a) "!" C_void
      Smart pointer access like this +
      object '-> method ( args ) +
      		 (invoke (invoke object "->" C_void))
      Invoke syntax +
      object . '( ... )      		 (invoke object) "()" (C_list [ ... ])
      Array syntax +
      object '[ 10 ]      		 (invoke object) "[]" (C_int 10)
      Assignment syntax +
      let a = '10 and b = '"foo" and c = '1.0 and d = 'true      		 let + a = C_int 10 and b = C_string "foo" and c = C_double 1.0 and d = C_bool + true
      Cast syntax +
      let a = _atoi '("2") as int +
      let b = (getenv "PATH") to string +
      This works for int, string, float, bool      		 let a = get_int + (_atoi (C_string "2")) +
      let b = C_string (getenv "PATH")
      +

      26.1.4 Using your module

      +

      You can test-drive your module by building a toplevel ocaml + interpreter. Consult the ocaml manual for details.

      +

      When linking any ocaml bytecode with your module, use the -custom + option to build your functions into the primitive list. This option is + not needed when you build native code.

      +

      26.1.5 Compilation problems and compiling + with C++

      +

      As mentioned above, .cxx files need special handling to be compiled + with ocamlc. Other than that, C code that uses class + as a non-keyword, and C code that is too liberal with pointer types may + not compile under the C++ compiler. Most code meant to be compiled as + C++ will not have problems.

      +

      26.2 The low-level Ocaml/C interface

      +

      In order to provide access to overloaded functions, and provide + sensible outputs from them, all C entities are represented as members + of the c_obj type:

      +

      In the code as seen by the typemap writer, there is a value, + swig_result, that always contains the current return data. It is a + list, and must be appended with the caml_list_append function, or with + functions and macros provided by objective caml. +

      +
      +
      +type c_obj =
+    C_void
+  | C_bool of bool
+  | C_char of char
+  | C_uchar of char
+  | C_short of int
+  | C_ushort of int
+  | C_int of int
+  | C_uint of int32
+  | C_int32 of int32
+  | C_int64 of int64
+  | C_float of float
+  | C_double of float
+  | C_ptr of int64 * int64
+  | C_array of c_obj array
+  | C_list of c_obj list
+  | C_obj of (string -> c_obj -> c_obj)
+  | C_string of string
+  | C_enum of c_enum_t
+
      +
      +

      A few functions exist which generate and return these:

      +
        +
      • caml_ptr_val receives a c_obj and returns a void *.  This should be + used for all pointer purposes.
        • +
      • caml_long_val receives a c_obj and returns a long.  This should be + used for most integral purposes. +
        • +
      • caml_val_ptr receives a void * and returns a c_obj.
        • +
      • caml_val_bool receives a C int and returns a c_obj representing it's + bool value.
        • +
      • caml_val_(u)?(char|short|int|long|float|double) receives an + appropriate C value and returns a c_obj representing it.
        • +
      • caml_val_string receives a char * and returns a string value.
        • +
      • caml_val_string_len receives a char * and a length and returns a + string value.
        • +
      • caml_val_obj receives a void * and an object type and returns a + C_obj, which contains a closure giving method access.
        • +
      +

      Because of this style, a typemap can return any kind of value it + wants from a function.  This enables out typemaps and inout typemaps to + work well.  The one thing to remember about outputting values is that + you must append them to the return list with swig_result = + caml_list_append(swig_result,v).

      +

       This function will return a new list that has your element + appended. Upon return to caml space, the fnhelper function beautifies + the result. A list containing a single item degrades to only that item + (i.e. [ C_int 3 ] -> C_int 3), and a list containing more than one item + is wrapped in C_list (i.e. [ C_char 'a' ; C_char 'b' -> C_list [ C_char + 'a' ; C_char b ]).  This is in order to make return values easier to + handle when functions have only one return value, such as constructors, + and operators.  In addition, string, pointer, and object values are + interchangeable with respect to caml_ptr_val, so you can allocate + memory as caml strings and still use the resulting pointers for C + purposes, even using them to construct simple objects on. Note, though, + that foreign C++ code does not respect the garbage collector, although + the SWIG interface does.

      +

      The wild card type that you can use in lots of different ways is + C_obj. It allows you to wrap any type of thing you like as an object + using the same mechanism that the ocaml module does.  When evaluated in + caml_ptr_val, the returned value is the result of a call to the + object's "&" operator, taken as a pointer.

      +

      You should only construct values using objective caml, or using the + functions caml_val_* functions provided as static functions to a SWIG + ocaml module, as well as the caml_list_* functions. These functions + provide everything a typemap needs to produce values. In addition, + value items pass through directly, but you must make your own type + signature for a function that uses value in this way.

      +

      26.2.1 The generated module

      +

      The SWIG %module directive specifies the name of the Ocaml + module to be generated. If you specified `%module example', + then your Ocaml code will be accessible in the module Example. The + module name is always capitalized as is the ocaml convention. Note that + you must not use any Ocaml keyword to name your module. Remember that + the keywords are not the same as the C++ ones.

      +

      You can introduce extra code into the output wherever you like with + SWIG. These are the places you can introduce code:

      + + + + + + + +
      "header"This code is inserted near the beginning of the + C wrapper file, before any function definitions.
      "wrapper"This code is inserted in the function + definition section.
      "runtime"This code is inserted near the end of the C + wrapper file.
      "mli"This code is inserted into the caml interface + file. Special signatures should be inserted here.
      "ml"This code is inserted in the caml code defining the + interface to your C code. Special caml code, as well as any + initialization which should run when the module is loaded may be + inserted here.
      "classtemplate"The "classtemplate" place is special + because it describes the output SWIG will generate for class + definitions.
      +

      26.2.2 Enums

      +

      SWIG will wrap enumerations as polymorphic variants in the output + Ocaml code, as above in C_enum.  In order to support all C++-style uses + of enums, the function int_to_enum and enum_to_int are provided for + ocaml code to produce and consume these values as integers.  Other than + that, correct uses of enums will not have a problem.  Since enum labels + may overlap between enums, the enum_to_int and int_to_enum functions + take an enum type label as an argument. Example:

      +
      +
      +%module enum_test
+%{
+enum c_enum_type { a = 1, b, c = 4, d = 8 };
+%}
+enum c_enum_type { a = 1, b, c = 4, d = 8 };
+
      +
      +

      The output mli contains:

      +
      +
      +type c_enum_type = [
+  `unknown
+| `c_enum_type
+]
+type c_enum_tag = [
+  `int of int
+| `a
+| `b
+| `c
+| `d
+]
+val int_to_enum c_enum_type -> int -> c_obj
+val enum_to_int c_enum_type -> c_obj -> c_obj
+
      +
      +

      So it's possible to do this:

      +
      +
      +bash-2.05a$ ocamlmktop -custom enum_test_wrap.o enum_test.cmo -o enum_test_top
+bash-2.05a$ ./enum_test_top 
+        Objective Caml version 3.04
+
+# open Enum_test ;;
+# let x = C_enum `a ;;
+val x : Enum_test.c_obj = C_enum `a
+# enum_to_int `c_enum_type x ;;
+- : Enum_test.c_obj = C_int 1
+# int_to_enum `c_enum_type 4 ;;
+- : Enum_test.c_obj = C_enum `c
+
      +
      +

      26.2.2.1 Enum typing in Ocaml

      +

      The ocaml SWIG module now has support for loading and using multiple + SWIG modules at the same time. This enhances modularity, but presents + problems when used with a language which assumes that each module's + types are complete at compile time. In order to achieve total soundness + enum types are now isolated per-module. The type issue matters when + values are shared between functions imported from different modules. + You must convert values to master values using the swig_val function + before sharing them with another module.

      +

      26.2.3 Arrays

      +

      26.2.3.1 Simple types of bounded arrays

      +

      SWIG has support for array types, but you generally will need to + provide a typemap to handle them. You can currently roll your own, or + expand some of the macros provided (but not included by default) with + the SWIG distribution.

      +

      By including "carray.i", you will get access to some macros that + help you create typemaps for array types fairly easily.

      +

      %make_simple_array_typemap is the easiest way to get access + to arrays of simple types with known bounds in your code, but this only + works for arrays whose bounds are completely specified.

      +

      26.2.3.2 Complex and unbounded arrays

      +

      Unfortunately, unbounded arrays and pointers can't be handled in a + completely general way by SWIG, because the end-condition of such an + array can't be predicted. In some cases, it will be by consent (e.g. an + array of four or more chars), sometimes by explicit length (char + *buffer, int len), and sometimes by sentinel value (0,-1,etc.). SWIG + can't predict which of these methods will be used in the array, so you + have to specify it for yourself in the form of a typemap.

      +

      26.2.3.3 Using an object

      +

      It's possible to use C++ to your advantage by creating a simple + object that provides access to your array. This may be more desirable + in some cases, since the object can provide bounds checking, etc., that + prevents crashes.

      +

      Consider writing an object when the ending condition of your array + is complex, such as using a required sentinel, etc.

      +

      26.2.3.4 Example typemap for a function + taking float * and int

      +

      This is a simple example in typemap for an array of float, + where the length of the array is specified as an extra parameter. Other + such typemaps will work similarly. In the example, the function + printfloats is called with a float array, and specified length. The + actual length reported in the len argument is the length of the array + passed from ocaml, making passing an array into this type of function + convenient.

      + + + + + +
      +
      tarray.i
      +
      +
      +%module tarray
+%{
+#include <stdio.h>
+
+void printfloats( float *tab, int len ) {
+	int i;
+
+	for( i = 0; i < len; i++ ) {
+		printf( "%f ", tab[i] );
+	}
+
+	printf( "\n" );  
+}
+%}
+
+%typemap(in) (float *tab, int len) {
+    int i;
+    /* $*1_type */
+    $2 = caml_array_len($input);
+    $1 = ($*1_type *)malloc( $2 * sizeof( float ) );
+    for( i = 0; i < $2; i++ ) {
+        $1[i] = caml_double_val(caml_array_nth($input,i));
+    }
+}
+
+void printfloats( float *tab, int len );
+
      +
      Sample Run
      +
      +# open Tarray ;;
+# _printfloats (C_array [| C_double 1.0 ; C_double 3.0 ; C_double 5.6666 |]) ;;
+1.000000 3.000000 5.666600
+- : Tarray.c_obj = C_void
+
      +
      +

      26.2.4 C++ Classes

      +

      C++ classes, along with structs and unions are represented by C_obj + (string -> c_obj -> c_obj) wrapped closures.  These objects contain a + method list, and a type, which allow them to be used like C++ objects. + When passed into typemaps that use pointers, they degrade to pointers + through their "&" method.  Every method an object has is represented as + a string in the object's method table, and each method table exists in + memory only once.  In addition to any other operators an object might + have, certain builtin ones are provided by SWIG: (all of these take no + arguments (C_void))

      + + + + + + + + + +
      "~"Delete this object
      "&"Return an ordinary C_ptr value representing this + object's address
      "sizeof"If enabled with ("sizeof"="1") on the module + node, return the object's size in char.
      ":methods"Returns a list of strings containing the + names of the methods this object contains
      ":classof"Returns the name of the class this object + belongs to.
      ":parents"Returns a list of all direct parent classes + which have been wrapped by SWIG.
      "::[parent-class]"Returns a view of the object as the + indicated parent class. This is mainly used internally by the SWIG + module, but may be useful to client programs.
      "[member-variable]"Each member variable is wrapped as a + method with an optional parameter. Called with one argument, the member + variable is set to the value of the argument. With zero arguments, the + value is returned.
      +

      Note that this string belongs to the wrapper object, and not the + underlying pointer, so using create_[x]_from_ptr alters the returned + value for the same object.

      +

      26.2.4.1 STL vector and string Example

      +

      Standard typemaps are now provided for STL vector and string. More + are in the works. STL strings are passed just like normal strings, and + returned as strings. STL string references don't mutate the original + string, (which might be surprising), because Ocaml strings are mutable + but have fixed length. Instead, use multiple returns, as in the + argout_ref example.

      + + + + +
      +
      example.i
      +
      +
      +%module example
+%{
+#include "example.h"
+%}
+
+%include <stl.i>
+
+namespace std {
+        %template(StringVector) std::vector < string >;
+};
+
+%include "example.h"
+
      +
      This example is in Examples/ocaml/stl +
      +

      Since there's a makefile in that directory, the example is easy to + build.

      +

      Here's a sample transcript of an interactive session using a string + vector after making a toplevel (make toplevel). This example uses the + camlp4 module.

      +
      +
      +bash-2.05a$ ./example_top 
+        Objective Caml version 3.06
+
+        Camlp4 Parsing version 3.06
+
+# open Swig ;;
+# open Example ;;
+# let x = new_StringVector '() ;;
+val x : Example.c_obj = C_obj <fun>
+# x -> ":methods" () ;;
+- : Example.c_obj =
+C_list
+ [C_string "nop"; C_string "size"; C_string "empty"; C_string "clear";
+  C_string "push_back"; C_string "[]"; C_string "="; C_string "set";
+  C_string "~"; C_string "&"; C_string ":parents"; C_string ":classof";
+  C_string ":methods"]
+# x -> push_back ("foo") ;;
+- : Example.c_obj = C_void
+# x -> push_back ("bar") ;;
+- : Example.c_obj = C_void
+# x -> push_back ("baz") ;;
+- : Example.c_obj = C_void
+# x '[1] ;;
+- : Example.c_obj = C_string "bar"
+# x -> set (1,"spam") ;;
+- : Example.c_obj = C_void
+# x '[1] ;;
+- : Example.c_obj = C_string "spam"
+# for i = 0 to (x -> size() as int) - 1 do 
+    print_endline ((x '[i to int]) as string) 
+  done ;;
+foo
+bar
+baz
+- : unit = ()
+# 
+
      +
      +

      26.2.4.2 C++ Class Example

      +

      Here's a simple example using Trolltech's Qt Library:

      + + + +
      +
      qt.i
      +
      +
      +%module qt
+%{
+#include <qapplication.h>
+#include <qpushbutton.h>
+%}
+class QApplication {
+public:
+        QApplication( int argc, char **argv );
+        void setMainWidget( QWidget *widget );
+        void exec();
+};
+
+class QPushButton {
+public:
+        QPushButton( char *str, QWidget *w );
+        void resize( int x, int y );
+        void show();
+};
+
      +
      +

      26.2.4.3 Compiling the example

      +
      +
      +bash-2.05a$ QTPATH=/your/qt/path
+bash-2.05a$ for file in swig.mli swig.ml swigp4.ml ; do swig -ocaml -co $file ; done
+bash-2.05a$ ocamlc -c swig.mli ; ocamlc -c swig.ml
+bash-2.05a$ ocamlc -I `camlp4 -where` -pp "camlp4o pa_extend.cmo q_MLast.cmo" -c swigp4.ml
+bash-2.05a$ swig -ocaml -c++ -I$QTPATH/include  qt.i
+bash-2.05a$ mv qt_wrap.cxx qt_wrap.c
+bash-2.05a$ ocamlc -c -ccopt -xc++ -ccopt -g -g -ccopt -I$QTPATH/include qt_wrap.c 
+bash-2.05a$ ocamlc -c qt.mli
+bash-2.05a$ ocamlc -c qt.ml
+bash-2.05a$ ocamlmktop -custom swig.cmo -I `camlp4 -where` \
+  camlp4o.cma swigp4.cmo qt_wrap.o qt.cmo -o qt_top -cclib \
+  -L$QTPATH/lib -cclib -lqt
+
      +
      +

      26.2.4.4 Sample Session

      +
      +
      +bash-2.05a$ ./qt_top 
+        Objective Caml version 3.06
+
+        Camlp4 Parsing version 3.06
+
+# open Swig ;;
+# open Qt ;;
+# let a = new_QApplication '(0,0) ;;
+val a : Qt.c_obj = C_obj <fun>
+# let hello = new_QPushButton '("hi",0) ;;
+val hello : Qt.c_obj = C_obj <fun>
+# hello -> resize (100,30) ;;
+- : Qt.c_obj = C_void
+# hello -> show () ;;
+- : Qt.c_obj = C_void
+# a -> exec () ;;
+
      +
      +

      Assuming you have a working installation of QT, you will see a + window containing the string "hi" in a button.

      +

      26.2.5 Director Classes

      +

      26.2.5.1 Director Introduction

      +

      Director classes are classes which allow Ocaml code to override the + public methods of a C++ object. This facility allows the user to use + C++ libraries that require a derived class to provide application + specific functionality in the context of an application or utility + framework.

      +

      You can turn on director classes by using an optional module + argument like this:

      +
      +
      +%module(directors="1")
+
+...
+
+// Turn on the director class for a specific class like this:
+%feature("director")
+class foo {
+  ...
+};
+
      +
      +

      26.2.5.2 Overriding Methods in Ocaml

      +

      Because the Ocaml language module treats C++ method calls as calls + to a certain function, all you need to do is to define the function + that will handle the method calls in terms of the public methods of the + object, and any other relevant information. The function +new_derived_object uses a stub class to call your methods in place + of the ones provided by the underlying implementation. The object you + receive is the underlying object, so you are free to call any methods + you want from within your derived method. Note that calls to the + underlying object do not invoke Ocaml code. You need to handle that + yourself.

      +

      new_derived_object receives your function, the function + that creates the underlying object, and any constructor arguments, and + provides an object that you can use in any usual way. When C++ code + calls one of the object's methods, the object invokes the Ocaml + function as if it had been invoked from Ocaml, allowing any method + definitions to override the C++ ones.

      +

      In this example, I'll examine the objective caml code involved in + providing an overloaded class. This example is contained in + Examples/ocaml/shapes.

      +

      26.2.5.3 Director Usage Example

      + + + +
      +
      example_prog.ml
      +
      +
      +open Swig
+open Example
+
+...
+
+let triangle_class pts ob meth args =
+  match meth with
+      "cover" ->
+        (match args with
+             C_list [ x_arg ; y_arg ] ->
+	     let xa = x_arg as float
+	     and ya = y_arg as float in
+	       (point_in_triangle pts xa ya) to bool
+           | _ -> raise (Failure "cover needs two double arguments."))
+    | _ -> (invoke ob) meth args ;;
+
+let triangle =
+  new_derived_object 
+    new_shape
+    (triangle_class ((0.0,0.0),(0.5,1.0),(1.0,0.0)))
+    '() ;;
+
+let _ = _draw_shape_coverage '(triangle, C_int 60, C_int 20) ;;
+
      +
      +

      This is the meat of what you need to do. The actual "class" + definition containing the overloaded method is defined in the function + triangle_class. This is a lot like the class definitions emitted by + SWIG, if you look at example.ml, which is generated when SWIG consumes + example.i. Basically, you are given the arguments as a c_obj and the + method name as a string, and you must intercept the method you are + interested in and provide whatever return value you need. Bear in mind + that the underlying C++ code needs the right return type, or an + exception will be thrown. This exception will generally be Failure, or + NotObject. You must call other ocaml methods that you rely on yourself. + Due to the way directors are implemented, method calls on your object + from with ocaml code will always invoke C++ methods even if they are + overridden in ocaml.

      +

      In the example, the draw_shape_coverage function plots the indicated + number of points as either covered (x) or uncovered ( ) + between 0 and 1 on the X and Y axes. Your shape implementation can + provide any coverage map it likes, as long as it responds to the + "cover" method call with a boolean return (the underlying method + returns bool). This might allow a tricky shape implementation, such as + a boolean combination, to be expressed in a more effortless style in + ocaml, while leaving the "engine" part of the program in C++.

      +

      26.2.5.4 Creating director objects

      +

      The definition of the actual object triangle can be described this + way:

      +
      +
      +let triangle =
+  new_derived_object 
+    new_shape
+    (triangle_class ((0.0,0.0),(0.5,1.0),(1.0,0.0)))
+    '()
+
      +
      +

      The first argument to new_derived_object, new_shape is the + method which returns a shape instance. This function will be invoked + with the third argument will be appended to the argument list [ C_void + ]. In the example, the actual argument list is sent as (C_list [ C_void + ; C_void ]). The augmented constructor for a director class needs the + first argument to determine whether it is being constructed as a + derived object, or as an object of the indicated type only (in this + case shape). The Second argument is a closure that will be + added to the final C_obj.

      +

      The actual object passed to the self parameter of the director + object will be a C_director_core, containing a c_obj option ref and a + c_obj. The c_obj provided is the same object that will be returned from + new_derived object, that is, the object exposing the overridden + methods. The other part is an option ref that will have its value + extracted before becoming the ob parameter of your class + closure. This ref will contain None if the C++ object + underlying is ever destroyed, and will consequently trigger an + exception when any method is called on the object after that point (the + actual raise is from an inner function used by new_derived_object, and + throws NotObject). This prevents a deleted C++ object from causing a + core dump, as long as the object is destroyed properly.

      +

      26.2.5.5 Typemaps for directors, +directorin, directorout, directorargout

      +

      Special typemaps exist for use with directors, the directorin, + directorout, directorargout are used in place of in, out, + argout typemaps, except that their direction is reversed. They + provide for you to provide argout values, as well as a function return + value in the same way you provide function arguments, and to receive + arguments the same way you normally receive function returns.

      +

      26.2.5.6 directorin typemap

      +

      The directorin typemap is used when you will receive + arguments from a call made by C++ code to you, therefore, values will + be translated from C++ to ocaml. You must provide some valid C_obj + value. This is the value your ocaml code receives when you are called. + In general, a simple directorin typemap can use the same body + as a simple out typemap.

      +

      26.2.5.7 directorout typemap

      +

      The directorout typemap is used when you will send an + argument from your code back to the C++ caller. That is; directorout + specifies a function return conversion. You can usually use the same + body as an in typemap for the same type, except when there are + special requirements for object ownership, etc.

      +

      26.2.5.8 directorargout typemap

      +

      C++ allows function arguments which are by pointer (*) and by + reference (&) to receive a value from the called function, as well as + sending one there. Sometimes, this is the main purpose of the argument + given. directorargout typemaps allow your caml code to emulate + this by specifying additional return values to be put into the output + parameters. The SWIG ocaml module is a bit loose in order to make code + easier to write. In this case, your return to the caller must be a list + containing the normal function return first, followed by any argout + values in order. These argout values will be taken from the list and + assigned to the values to be returned to C++ through directorargout + typemaps. In the event that you don't specify all of the necessary + values, integral values will read zero, and struct or object returns + have undefined results.

      +

      26.2.6 Exceptions

      +

      Catching exceptions is now supported using SWIG's %exception + feature. A simple but not too useful example is provided by the + throw_exception testcase in Examples/test-suite. You can provide your + own exceptions, too.

      +
      +

      27 SWIG and Octave

      + + +
      + +
      + +

      Octave is a high-level language intended for numerical programming + that is mostly compatible with MATLAB. More information can be found at + www.octave.org.

      +

      This chapter is intended to give an introduction to using the + module. You should also read the SWIG documentation that is not + specific to Octave. Also, there are a dozen or so examples in the + Examples/octave directory, and hundreds in the test suite + (Examples/test-suite and Examples/test-suite/octave).

      +

      27.1 Preliminaries

      +

      The current SWIG implemention is based on Octave 2.9.12. Support for + other versions (in particular the recent 3.0) has not been tested, nor + has support for any OS other than Linux.

      +

      27.2 Running SWIG

      +

      Let's start with a very simple SWIG interface file:

      +
      +
      %module example
+%{
+#include "example.h"
+%}
+int gcd(int x, int y);
+extern double Foo;
      +
      +

      To build an Octave module, run SWIG using the -octave + option. The -c++ option is required (for now) as Octave itself + is written in C++ and thus the wrapper code must also be.

      +
      +
      $ swig -octave -c++ example.i
      +
      +

      This creates a C/C++ source file example_wrap.cxx. The + generated C++ source file contains the low-level wrappers that need to + be compiled and linked with the rest of your C/C++ application (in this + case, the gcd implementation) to create an extension module.

      +

      The swig command line has a number of options you can use, like to + redirect it's output. Use swig --help to learn about these.

      +

      27.2.1 Compiling a dynamic module

      +

      Octave modules are DLLs/shared objects having the ".oct" suffix. + Building an oct file is usually done with the mkoctfile command (either + within Octave itself, or from the shell). For example,

      +
      +
      +$ swig -octave -c++ example.i -o example_wrap.cxx
+$ mkoctfile example_wrap.cxx example.c
+
      +
      +

      where example.c is the file containing the gcd() implementation.

      +

      mkoctfile can also be used to extract the build parameters required + to invoke the compiler and linker yourself. See the Octave manual and + mkoctfile man page.

      +

      mkoctfile will produce example.oct, which contains the compiled + extension module. Loading it into Octave is then a matter of invoking

      +
      +
      octave:1> example
      +
      +

      27.2.2 Using your module

      +

      Assuming all goes well, you will be able to do this: +

      +
      +
      $ octave -q
+octave:1> example
+octave:2> example.gcd(4,6)
+ans =  2
+octave:3> example.cvar.Foo
+ans =  3
+octave:4> example.cvar.Foo=4;
+octave:5> example.cvar.Foo
+ans =  4
      +
      +

      27.3 A tour of basic C/C++ wrapping

      +

      27.3.1 Modules

      +

      The SWIG module directive specifies the name of the Octave module. + If you specify `module example', then in Octave everything in the + module will be accessible under "example", as in the above example. + When choosing a module name, make sure you don't use the same name as a + built-in Octave command or standard module name.

      +

      When Octave is asked to invoke example, it will try to find + the .m or .oct file that defines the function "example". It will thusly + find example.oct, that upon loading will register all of the module's + symbols.

      +

      Giving this function a parameter "global" will cause it to load all + symbols into the global namespace in addition to the example + namespace. For example:

      +
      +
      $ octave -q
+octave:1> example("global")
+octave:2> gcd(4,6)
+ans =  2
+octave:3> cvar.Foo
+ans =  3
+octave:4> cvar.Foo=4;
+octave:5> cvar.Foo
+ans =  4 
+
      +
      +

      It is also possible to rename the module namespace with an + assignment, as in: +

      +
      octave:1> example;
+octave:2> c=example;
+octave:3> c.gcd(10,4)
+ans =  2
      +

      +

      All global variables are put into the cvar namespace object. This is + accessible either as my_module.cvar, or just cvar (if + the module is imported into the global namespace).

      +

      One can also rename it by simple assignment, e.g.,

      +
      +
      +octave:1> some_vars = cvar;
+
      +
      +

      27.3.2 Functions

      +

      Global functions are wrapped as new Octave built-in functions. For + example,

      +
      +
      %module example
+int fact(int n);
      +
      +

      creates a built-in function example.fact(n) that works + exactly like you think it does:

      +
      +
      octave:1> example.fact(4)
+24
      +
      +

      27.3.3 Global variables

      +

      Global variables are a little special in Octave. Given a global + variable:

      +
      +
      %module example
+extern double Foo;
+
      +
      +

      To expose variables, SWIG actually generates two functions, to get + and set the value. In this case, Foo_set and Foo_set would be + generated. SWIG then automatically calls these functions when you get + and set the variable-- in the former case creating a local copy in the + interpreter of the C variables, and in the latter case copying an + interpreter variables onto the C variable.

      +
      +
      octave:1> example;
+octave:2> c=example.cvar.Foo
+c =  3
+octave:3> example.cvar.Foo=4;
+octave:4> c
+c =  3
+octave:5> example.cvar.Foo
+ans =  4
      +
      +

      If a variable is marked with the %immutable directive then any + attempts to set this variable will cause an Octave error. Given a + global variable:

      +
      +
      %module example
+%immutable;
+extern double Foo;
+%mutable;
+
      +
      +

      SWIG will allow the the reading of Foo but when a set + attempt is made, an error function will be called.

      +
      +
      octave:1> example
+octave:2> example.Foo=4
+error: attempt to set immutable member variable
+error: assignment failed, or no method for `swig_type = scalar'
+error: evaluating assignment expression near line 2, column 12
      +
      +

      It is possible to add new functions or variables to the module. This + also allows the user to rename/remove existing functions and constants + (but not linked variables, mutable or immutable). Therefore users are + recommended to be careful when doing so.

      +
      +
      octave:1> example;
+octave:2> example.PI=3.142;
+octave:3> example.PI
+ans =  3.1420
      +
      +

      27.3.4 Constants and enums

      +

      Because Octave doesn't really have the concept of constants, C/C++ + constants are not really constant in Octave. They are actually just a + copy of the value into the Octave interpreter. Therefore they can be + changed just as any other value. For example given some constants:

      +
      +
      %module example
+%constant int ICONST=42;
+#define    SCONST      "Hello World"
+enum Days{SUNDAY,MONDAY,TUESDAY,WEDNESDAY,THURSDAY,FRIDAY,SATURDAY};
+
      +
      +

      This is 'effectively' converted into the following Octave code:

      +
      +
      example.ICONST=42
+example.SCONST="Hello World"
+example.SUNDAY=0
+....
      +
      +

      27.3.5 Pointers

      +

      C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no + problem working with incomplete type information. Given a wrapping of + the <file.h> interface: C/C++ pointers are fully supported by SWIG. + Furthermore, SWIG has no problem working with incomplete type + information. Given a wrapping of the <file.h> interface:

      +
      +
      %module example
+FILE *fopen(const char *filename, const char *mode);
+int fputs(const char *, FILE *);
+int fclose(FILE *);
+
      +
      +

      When wrapped, you will be able to use the functions in a natural way + from Octave. For example:

      +
      +
      +octave:1> example;
+octave:2> f=example.fopen("w","junk");
+octave:3> example.fputs("Hello world",f);
+octave:4> example.fclose(f);
+
      +
      +

      Simply printing the value of a wrapped C++ type will print it's + typename. E.g.,

      +
      +
      octave:1> example;
+octave:2> f=example.fopen("junk","w");
+octave:3> f
+f =
+
+{
+  _p_FILE, ptr = 0x9b0cd00
+}
      +
      +

      As the user of the pointer, you are responsible for freeing it, or + closing any resources associated with it (just as you would in a C + program). This does not apply so strictly to classes and structs (see + below).

      +
      +
      octave:1> example;
+octave:2> f=example.fopen("not there","r");
+error: value on right hand side of assignment is undefined
+error: evaluating assignment expression near line 2, column 2
      +
      +

      27.3.6 Structures and C++ classes

      +

      SWIG wraps C structures and C++ classes by using a special Octave + type called a swig_ref. A swig_ref contains a + reference to one or more instances of C/C++ objects, or just the type + information for an object. For each wrapped structure and class, a +swig_ref will be exposed that has the name of the type. When + invoked as a function, it creates a new object of its type and returns + a swig_ref that points to that instance. This provides a very + natural interface. For example,

      +
      +
      struct Point{
+  int x,y;
+};
+
      +
      +

      is used as follows:

      +
      +
      octave:1> example;
+octave:2> p=example.Point();
+octave:3> p.x=3;
+octave:4> p.y=5;
+octave:5> p.x, p.y
+ans =  3
+ans =  5 
+
      +
      +

      In C++, invoking the type object in this way calls the object's + constructor. swig_ref objects can also be acquired by having a + wrapped function return a pointer, reference, or value of a + non-primitive type.

      +

      The swig_ref type handles indexing operations such that usage maps + closely to what you would have in C/C++. Structure members are accessed + as in the above example, by calling set and get methods for C++ + variables. Methods also work as expected. For example, code wrapped in + the following way

      +
      +
      class Point{
+public:
+  int x,y;
+  Point(int _x,int _y) : x(_x),y(_y) {}
+  double distance(const Point& rhs) {
+    return sqrt(pow(x-rhs.x,2)+pow(y-rhs.y,2));
+  }
+  void set(int _x,int _y) {
+    x=_x; y=_y;
+  }
+};
+
      +
      +

      can be used from Octave like this

      +
      +
      octave:1> example;
+octave:2> p1=example.Point(3,5);
+octave:3> p2=example.Point(1,2);
+octave:4> p1.distance(p2)
+ans =  3.6056
+
      +
      +

      By using the swig_this() and swig_type() + functions, one can discover the pointers to and types of the underlying + C/C++ object.

      +
      +
      +octave:5> swig_this(p1)
+ans = 162504808
+octave:6> swig_type(p1)
+ans = Point
+
      +
      +

      Note that swig_ref is a reference-counted pointer to a + C/C++ object/type, and as such has pass-by-reference semantics. For + example if one has a allocated a single object but has two swig_ref +'s pointing to it, modifying the object through either of them will + change the single allocated object. This differs from the usual + pass-by-value (copy-on-write) semantics that Octave maintains for + built-in types. For example, in the following snippet, modifying b + does not modify a,

      +
      +
      +octave:7> a=struct('x',4)
+a =
+{
+  x =  4
+}
+
+octave:8> b=a
+b =
+{
+  x =  4
+}
+
+octave:9> b.y=4
+b =
+{
+  x =  4
+  y =  4
+}
+
+octave:10> a
+a =
+{
+  x =  4
+}
+
      +
      +

      However, when dealing with wrapped objects, one gets the behavior

      +
      +
      +octave:2> a=Point(3,5)
+a =
+
+{
+  Point, ptr = 0x9afbbb0
+}
+
+octave:3> b=a
+b =
+
+{
+  Point, ptr = 0x9afbbb0
+}
+
+octave:4> b.set(2,1);
+octave:5> b.x, b.y
+ans =  2
+ans =  1
+octave:6> a.x, a.y
+ans =  2
+ans =  1
+
      +
      +

      Depending on the ownership setting of a swig_ref, it may + call C++ destructors when its reference count goes to zero. See the + section on memory management below for details.

      +

      27.3.7 C++ inheritance

      +

      Single and multiple inheritance are fully supported. The +swig_ref type carries type information along with any C++ object + pointer it holds. This information contains the full class hierarchy. + When an indexing operation (such as a method invocation) occurs, the + tree is walked to find a match in the current class as well as any of + its bases. The lookup is then cached in the swig_ref.

      +

      27.3.8 C++ overloaded functions

      +

      Overloaded functions are supported, and handled as in other modules. + That is, each overload is wrapped separately (under internal names), + and a dispatch function is also emitted under the external/visible + name. The dispatch function selects which overload to call (if any) + based on the passed arguments. typecheck typemaps are used to + analyze each argument, as well as assign precedence. See the chapter on + typemaps for details.

      +

      27.3.9 C++ operators

      +

      C++ operator overloading is supported, in a way similar to other + modules. The swig_ref type supports all unary and binary + operators between itself and all other types that exist in the system + at module load time. When an operator is used (where one of the + operands is a swig_ref), the runtime routes the call to either + a member function of the given object, or to a global function whose + named is derived from the types of the operands (either both or just + the lhs or rhs).

      +

      For example, if a and b are SWIG variables in + Octave, a+b becomes a.__add(b). The wrapper is then + free to implement __add to do whatever it wants. A wrapper may define + the __add function manually, %rename some other function to + it, or %rename a C++ operator to it.

      +

      By default the C++ operators are renamed to their corresponding + Octave operators. So without doing any work, the following interface

      +
      +
      +%inline {
+struct A {
+  int value;
+  A(int _value) : value(_value) {}
+  A operator+ (const A& x) {
+    return A(value+x.value);
+  }
+};
+}
+
      +
      +

      is usable from Octave like this:

      +
      +
      +a=A(2), b=A(3), c=a+b
+assert(c.value==5);
+
      +
      +

      Octave operators are mapped in the following way:

      +
      +
      +__brace      a{args}
+__brace_asgn a{args} = rhs
+__paren      a(args)
+__paren_asgn a(args) = rhs
+__str        generates string rep
+__not        !a
+__uplus      +a
+__uminus     -a
+__transpose  a.'
+__hermitian  a'
+__incr       a++
+__decr       a--
+__add        a + b
+__sub        a - b
+__mul        a * b
+__div        a / b
+__pow        a ^ b
+__ldiv       a \ b
+__lshift     a <<b
+__rshift     a >> b
+__lt         a  <b
+__le         a  <= b
+__eq         a == b
+__ge         a >= b
+__gt         a > b
+__ne         a != b
+__el_mul     a .* b
+__el_div     a ./ b
+__el_pow     a .^ b
+__el_ldiv    a .\ b
+__el_and     a & b
+__el_or      a | b
+
      +
      +

      On the C++ side, the default mappings are as follows:

      +
      +
      +%rename(__add)       *::operator+;
+%rename(__add)       *::operator+();
+%rename(__add)       *::operator+() const;
+%rename(__sub)       *::operator-;
+%rename(__uminus)    *::operator-();
+%rename(__uminus)    *::operator-() const;
+%rename(__mul)       *::operator*;
+%rename(__div)       *::operator/;
+%rename(__mod)       *::operator%;
+%rename(__lshift)    *::operator<
+
+>;
+%rename(__el_and)    *::operator&&;
+%rename(__el_or)     *::operator||;
+%rename(__xor)       *::operator^;
+%rename(__invert)    *::operator~;
+%rename(__lt)        *::operator
+
+;
+%rename(__ge)        *::operator>=;
+%rename(__eq)        *::operator==;
+%rename(__ne)        *::operator!=;
+%rename(__not)       *::operator!;
+%rename(__incr)      *::operator++;
+%rename(__decr)      *::operator--;
+%rename(__paren)     *::operator();
+%rename(__brace)     *::operator[];
+
      +
      +

      27.3.10 Class extension with %extend

      +

      The %extend directive works the same as in other modules.

      +

      You can use it to define special behavior, like for example defining + Octave operators not mapped to C++ operators, or defining certain + Octave mechanisms such as how an object prints. For example, the +octave_value::{is_string,string_value,print} functions are routed + to a special method __str that can be defined inside an + %extend.

      +
      +
      +%extend A {
+string __str() {
+  stringstream sout;
+  sout<<$self->value;
+  return sout.str();
+}
+}
+
      +
      +

      Then in Octave one gets,

      +
      +
      +octave:1> a=A(4);
+octave:2> a
+a = 4
+octave:3> printf("%s\n",a);
+4
+octave:4> a.__str()
+4
+
      +
      +

      27.3.11 C++ templates

      +

      C++ class and function templates are fully supported as in other + modules, in that the %template directive may used to create explicit + instantiations of templated types. For example, function templates can + be instantiated as follows:

      +
      +
      %module example
+%inline {
+ template<class __scalar>
+   __scalar mul(__scalar a,__scalar b) {
+   return a*b;
+ }
+}
+%include <std_complex.i>
+%template(mul) mul<std::complex<double> >
+%template(mul) mul<double>
+
      +
      +

      and then used from Octave

      +
      +
      +octave:1> mul(4,3)
+ans =  12
+octave:2> mul(4.2,3.6)
+ans =  15.120
+octave:3> mul(3+4i,10+2i)
+ans =  22 + 46i
+
      +
      +

      Similarly, class templates can be instantiated as in the following + example,

      +
      +
      %module example
+%include <std_complex.i>
+%include <std_string.i>
+%inline {
+  #include <sstream>
+  template<class __scalar> class sum {
+    __scalar s;
+  public:
+    sum(__scalar _s=0) : s(_s) {}
+    sum& add(__scalar _s) {
+      s+=_s;
+      return *this;
+    }
+    std::string __str() const {
+      std::stringstream sout;
+      sout<<s;
+      return sout.str();
+    }
+  };
+}
+%template(sum_complex) sum<std::complex<double> >;
+%template(sum_double) sum<double>;
+
      +
      +

      and then used from Octave

      +
      +
      +octave:2> a=sum_complex(2+3i);
+octave:3> a.add(2)
+ans =
+
+(4,3)
+octave:4> a.add(3+i)
+ans =
+
+(7,4)
+
      +
      +

      27.3.12 C++ Smart Pointers

      +

      C++ smart pointers are fully supported as in other modules.

      +

      27.3.13 Directors (calling Octave from C++ + code)

      +

      There is full support for SWIG Directors, which permits Octave code + to subclass C++ classes, and implement their virtual methods.

      +

      Octave has no direct support for object oriented programming, + however the swig_ref type provides some of this support. You + can manufacture a swig_ref using the subclass + function (provided by the SWIG/Octave runtime).

      +

      For example,

      +
      +
      +octave:1> a=subclass();
+octave:2> a.my_var = 4;
+octave:3> a.my_method = @(self) printf("my_var = ",self.my_var);
+octave:4> a.my_method();
+my_var = 4
+
      +
      +

      subclass() can also be used to subclass one or more C++ + types. Suppose you have an interface defined by

      +
      +
      +%inline {
+class A {
+public:
+  virtual my_method() {
+    printf("c-side routine called\n");
+  }
+};
+void call_your_method(A& a) {
+  a.my_method();
+}
+}
+
      +
      +

      Then from Octave you can say:

      +
      +
      +octave:1> B=@() subclass(A(),@my_method);
+octave:2> function my_method(self)
+octave:3>   printf("octave-side routine called\n");
+octave:4> end
+octave:5> call_your_method(B());
+octave-side routine called
+
      +
      +

      or more concisely,

      +
      +
      +octave:1> B=@() subclass(A(),'my_method',@(self) printf("octave-side routine called\n"));
+octave:2> call_your_method(B());
+octave-side routine called
+
      +
      +

      Note that you have to enable directors via the %feature directive + (see other modules for this).

      +

      subclass() will accept any number of C++ bases or other +subclass()'ed objects, (string,octave_value) pairs, and +function_handles. In the first case, these are taken as base + classes; in the second case, as named members (either variables or + functions, depending on whether the given value is a function handle); + in the third case, as member functions whose name is taken from the + given function handle. E.g.,

      +
      +
      +octave:1> B=@(some_var=2) subclass(A(),'some_var',some_var,@some_func,'another_func',@(self) do_stuff())
+
      +
      +

      You can also assign non-C++ member variables and functions after + construct time. There is no support for non-C++ static members.

      +

      There is limited support for explicitly referencing C++ bases. So, + in the example above, we could have

      +
      +
      +octave:1> B=@() subclass(A(),@my_method);
+octave:2> function my_method(self)
+octave:3>   self.A.my_method();
+octave:4>   printf("octave-side routine called\n");
+octave:5> end
+octave:6> call_your_method(B());
+c-side routine called
+octave-side routine called
+
      +
      +

      27.3.14 Threads

      +

      The use of threads in wrapped Director code is not supported; i.e., + an Octave-side implementation of a C++ class must be called from the + Octave interpreter's thread. Anything fancier (apartment/queue model, + whatever) is left to the user. Without anything fancier, this amounts + to the limitation that Octave must drive the module... like, for + example, an optimization package that calls Octave to evaluate an + objective function.

      +

      27.3.15 Memory management

      +

      As noted above, swig_ref represents a reference counted + pointer to a C/C++-side object. It also contains a flag indicating + whether Octave or the C/C++ code owns the object. If Octave owns it, + any destructors will be called when the reference count reaches zero. + If the C/C++ side owns the object, then destructors will not be called + when the reference count goes to zero.

      +

      For example,

      +
      +%inline {
+class A {
+public:
+  A() { printf("A constructing\n"); }
+  ~A() { printf("A destructing\n"); }
+};
+}
+
      +

      +

      Would produce this behavior in Octave:

      +
      +
      +octave:1> a=A();
+A constructing
+octave:2> b=a;
+octave:3> clear a;
+octave:4> b=4;
+A destructing
+
      +
      +

      The %newobject directive may be used to control this behavior for + pointers returned from functions.

      +

      In the case where one wishes for the C++ side to own an object that + was created in Octave (especially a Director object), one can use the + __disown() method to invert this logic. Then letting the Octave + reference count go to zero will not destroy the object, but destroying + the object will invalidate the Octave-side object if it still exists + (and call destructors of other C++ bases in the case of multiple + inheritance/subclass()'ing).

      +

      27.3.16 STL support

      +

      This is some skeleton support for various STL containers.

      +

      27.3.17 Matrix typemaps

      +

      Octave provides a rich set of classes for dealing with matrices. + Currently there are no built-in typemaps to deal with those. However, + these are relatively straight forward for users to add themselves (see + the docs on typemaps). Without much work (a single typemap decl-- say, + 5 lines of code in the interface file), it would be possible to have a + function

      +
      +
      +double my_det(const double* mat,int m,int n);
+
      +
      +

      that is accessed from Octave as,

      +
      +
      +octave:1> my_det(rand(4));
+ans = -0.18388
+
      +
      +
      +

      28 SWIG and Perl5

      + + +
      + +
      + +

      Caution: This chapter is under repair!

      +

      This chapter describes SWIG's support of Perl5. Although the Perl5 + module is one of the earliest SWIG modules, it has continued to evolve + and has been improved greatly with the help of SWIG users. For the best + results, it is recommended that SWIG be used with Perl5.003 or later. + Earlier versions are problematic and SWIG generated extensions may not + compile or run correctly.

      +

      28.1 Overview

      +

      To build Perl extension modules, SWIG uses a layered approach. At + the lowest level, simple procedural wrappers are generated for + functions, classes, methods, and other declarations in the input file. + Then, for structures and classes, an optional collection of Perl proxy + classes can be generated in order to provide a more natural object + oriented Perl interface. These proxy classes simply build upon the + low-level interface.

      +

      In describing the Perl interface, this chapter begins by covering + the essentials. First, the problem of configuration, compiling, and + installing Perl modules is discussed. Next, the low-level procedural + interface is presented. Finally, proxy classes are described. Advanced + customization features, typemaps, and other options are found near the + end of the chapter.

      +

      28.2 Preliminaries

      +

      To build a Perl5 module, run Swig using the -perl option as + follows :

      +
      +
      +swig -perl example.i
+
+
      +
      +

      This produces two files. The first file, example_wrap.c + contains all of the C code needed to build a Perl5 module. The second + file, example.pm contains supporting Perl code needed to + properly load the module.

      +

      To build the module, you will need to compile the file +example_wrap.c and link it with the rest of your program.

      +

      28.2.1 Getting the right header files

      +

      In order to compile, SWIG extensions need the following Perl5 header + files :

      +
      +
      +#include "Extern.h"
+#include "perl.h"
+#include "XSUB.h"
+
      +
      +

      These are typically located in a directory like this

      +
      +
      +/usr/lib/perl5/5.00503/i386-linux/CORE
+
      +
      +

      The SWIG configuration script automatically tries to locate this + directory so that it can compile examples. However, if you need to find + out where the directory is loaded, an easy way to find out is to run + Perl itself.

      +
      +
      +% perl -e 'use Config; print $Config{archlib};'
+/usr/lib/perl5/5.00503/i386-linux
+
      +
      +

      28.2.2 Compiling a dynamic module

      +

      The preferred approach to building an extension module is to compile + it into a shared object file or DLL. To do this, you will need to + compile your program using commands like this (shown for Linux):

      +
      +
      +$ swig -perl example.i
+% gcc example.c
+% gcc -c example_wrap.c -I/usr/lib/perl5/5.00503/i386-linux/CORE -Dbool=char
+% gcc -shared example.o example_wrap.o -o example.so
+
      +
      +

      The exact compiler options vary from platform to platform. SWIG + tries to guess the right options when it is installed. Therefore, you + may want to start with one of the examples in the +SWIG/Examples/perl5 directory. If that doesn't work, you will need + to read the man-pages for your compiler and linker to get the right set + of options. You might also check the +SWIG Wiki for additional information.

      +

      When linking the module, the name of the shared object file must + match the module name used in the SWIG interface file. If you used ` +%module example', then the target should be named `example.so +', `example.sl', or the appropriate dynamic module name on your + system.

      +

      28.2.3 Building a dynamic module with + MakeMaker

      +

      It is also possible to use Perl to build dynamically loadable + modules for you using the MakeMaker utility. To do this, write a Perl + script such as the following :

      +
      +
      +# File : Makefile.PL
+use ExtUtils::MakeMaker;
+WriteMakefile(
+	`NAME'    => `example',                  # Name of package
+	`LIBS'    => [`-lm'],                    # Name of custom libraries
+	`OBJECT'  => `example.o example_wrap.o'  # Object files
+);
+
+
      +
      +

      Now, to build a module, simply follow these steps :

      +
      +
      +% perl Makefile.PL
+% make
+% make install
+
      +
      +

      If you are planning to distribute a SWIG-generated module, this is + the preferred approach to compilation. More information about MakeMaker + can be found in "Programming Perl, 2nd ed." by Larry Wall, Tom + Christiansen, and Randal Schwartz.

      +

      28.2.4 Building a static version of Perl

      +

      If you machine does not support dynamic loading or if you've tried + to use it without success, you can build a new version of the Perl + interpreter with your SWIG extensions added to it. To build a static + extension, you first need to invoke SWIG as follows :

      +
      +
      +% swig -perl -static example.i
+
      +
      +

      By default SWIG includes code for dynamic loading, but the +-static option takes it out.

      +

      Next, you will need to supply a main() function that + initializes your extension and starts the Perl interpreter. While, this + may sound daunting, SWIG can do this for you automatically as follows :

      +
      +
      +%module example
+
+%inline %{
+extern double My_variable;
+extern int fact(int);
+%}
+
+// Include code for rebuilding Perl
+%include <perlmain.i>
+
      +
      +

      The same thing can be accomplished by running SWIG as follows :

      +
      +
      +% swig -perl -static -lperlmain.i example.i
+
      +
      +

      The perlmain.i file inserts Perl's main() function + into the wrapper code and automatically initializes the SWIG generated + module. If you just want to make a quick a dirty module, this may be + the easiest way. By default, the perlmain.i code does not + initialize any other Perl extensions. If you need to use other + packages, you will need to modify it appropriately. You can do this by + just copying perlmain.i out of the SWIG library, placing it in + your own directory, and modifying it to suit your purposes.

      +

      To build your new Perl executable, follow the exact same procedure + as for a dynamic module, but change the link line to something like + this:

      +
      +
      +% gcc example.o example_wrap.o -L/usr/lib/perl5/5.00503/i386-linux/CORE \
+	-lperl -lsocket -lnsl -lm -o myperl
+
      +
      +

      This will produce a new version of Perl called myperl. It + should be functionality identical to Perl with your C/C++ extension + added to it. Depending on your machine, you may need to link with + additional libraries such as -lsocket, -lnsl, -ldl, etc.

      +

      28.2.5 Using the module

      +

      To use the module, simply use the Perl use statement. If + all goes well, you will be able to do this:

      +
      +
      +$ perl
+use example;
+print example::fact(4),"\n";
+24
+
      +
      +

      A common error received by first-time users is the following:

      +
      +
      +use example;
+Can't locate example.pm in @INC (@INC contains: /usr/lib/perl5/5.00503/i386-lin
+ux /usr/lib/perl5/5.00503 /usr/lib/perl5/site_perl/5.005/i386-linux /usr/lib/pe
+rl5/site_perl/5.005 .) at - line 1.
+BEGIN failed--compilation aborted at - line 1.
+
      +
      +

      This error is almost caused when the name of the shared object file + you created doesn't match the module name you specified with the +%module directive.

      +

      A somewhat related, but slightly different error is this:

      +
      +
      +use example;
+Can't find 'boot_example' symbol in ./example.so
+ at - line 1
+BEGIN failed--compilation aborted at - line 1.
+
      +
      +

      This error is generated because Perl can't locate the module + bootstrap function in the SWIG extension module. This could be caused + by a mismatch between the module name and the shared library name. + However, another possible cause is forgetting to link the + SWIG-generated wrapper code with the rest of your application when you + linked the extension module.

      +

      Another common error is the following:

      +
      +
      +use example;
+Can't load './example.so' for module example: ./example.so: 
+undefined symbol: Foo at /usr/lib/perl5/5.00503/i386-linux/DynaLoader.pm line 169.
+
+ at - line 1
+BEGIN failed--compilation aborted at - line 1.
+
      +
      +

      This error usually indicates that you forgot to include some object + files or libraries in the linking of the shared library file. Make sure + you compile both the SWIG wrapper file and your original program into a + shared library file. Make sure you pass all of the required libraries + to the linker.

      +

      Sometimes unresolved symbols occur because a wrapper has been + created for a function that doesn't actually exist in a library. This + usually occurs when a header file includes a declaration for a function + that was never actually implemented or it was removed from a library + without updating the header file. To fix this, you can either edit the + SWIG input file to remove the offending declaration or you can use the +%ignore directive to ignore the declaration. Better yet, update the + header file so that it doesn't have an undefined declaration.

      +

      Finally, suppose that your extension module is linked with another + library like this:

      +
      +
      +$ gcc -shared example.o example_wrap.o -L/home/beazley/projects/lib -lfoo \
+      -o example.so
+
      +
      +

      If the foo library is compiled as a shared library, you + might get the following error when you try to use your module:

      +
      +
      +use example;
+Can't load './example.so' for module example: libfoo.so: cannot open shared object file: 
+No such file or directory at /usr/lib/perl5/5.00503/i386-linux/DynaLoader.pm line 169.
+
+ at - line 1
+BEGIN failed--compilation aborted at - line 1.
+>>>                 
+
      +
      +

      This error is generated because the dynamic linker can't locate the +libfoo.so library. When shared libraries are loaded, the system + normally only checks a few standard locations such as /usr/lib + and /usr/local/lib. To get the loader to look in other + locations, there are several things you can do. First, you can + recompile your extension module with extra path information. For + example, on Linux you can do this:

      +
      +
      +$ gcc -shared example.o example_wrap.o -L/home/beazley/projects/lib -lfoo \
+      -Xlinker -rpath /home/beazley/projects/lib \
+      -o example.so
+
      +
      +

      Alternatively, you can set the LD_LIBRARY_PATH environment + variable to include the directory with your shared libraries. If + setting LD_LIBRARY_PATH, be aware that setting this variable + can introduce a noticeable performance impact on all other applications + that you run. To set it only for Perl, you might want to do this + instead:

      +
      +
      +$ env LD_LIBRARY_PATH=/home/beazley/projects/lib perl
+
      +
      +

      Finally, you can use a command such as ldconfig (Linux) or +crle (Solaris) to add additional search paths to the default system + configuration (this requires root access and you will need to read the + man pages).

      +

      28.2.6 Compilation problems and compiling + with C++

      +

      Compilation of C++ extensions has traditionally been a tricky + problem. Since the Perl interpreter is written in C, you need to take + steps to make sure C++ is properly initialized and that modules are + compiled correctly.

      +

      On most machines, C++ extension modules should be linked using the + C++ compiler. For example:

      +
      +
      +% swig -c++ -perl example.i
+% g++ -c example.cxx
+% g++ -c example_wrap.cxx -I/usr/lib/perl5/5.00503/i386-linux/CORE
+% g++ -shared example.o example_wrap.o -o example.so
+
      +
      +

      In addition to this, you may need to include additional library + files to make it work. For example, if you are using the Sun C++ + compiler on Solaris, you often need to add an extra library -lCrun + like this:

      +
      +
      +% swig -c++ -perl example.i
+% g++ -c example.cxx
+% g++ -c example_wrap.cxx -I/usr/lib/perl5/5.00503/i386-linux/CORE
+% g++ -shared example.o example_wrap.o -o example.so -lCrun
+
      +
      +

      Of course, the names of the extra libraries are completely + non-portable---you will probably need to do some experimentation.

      +

      Another possible compile problem comes from recent versions of Perl + (5.8.0) and the GNU tools. If you see errors having to do with + _crypt_struct, that means _GNU_SOURCE is not defined and it needs to + be. So you should compile the wrapper like:

      +
      +
      +% g++ -c example_wrap.cxx -I/usr/lib/perl/5.8.0/CORE -D_GNU_SOURCE
+
      +
      +

      -D_GNU_SOURCE is also included in the Perl ccflags, which can be + found by running

      +
      +
      +% perl -e 'use Config; print $Config{ccflags};'
+
      +
      +

      So you could also compile the wrapper like

      +
      +
      +% g++ -c example_wrap.cxx -I/usr/lib/perl/5.8.0/CORE \
+`perl -e 'use Config; print $Config{ccflags}'`
+
      +
      +

      Sometimes people have suggested that it is necessary to relink the + Perl interpreter using the C++ compiler to make C++ extension modules + work. In the experience of this author, this has never actually + appeared to be necessary on most platforms. Relinking the interpreter + with C++ really only includes the special run-time libraries described + above---as long as you link your extension modules with these + libraries, it should not be necessary to rebuild Perl.

      +

      If you aren't entirely sure about the linking of a C++ extension, + you might look at an existing C++ program. On many Unix machines, the +ldd command will list library dependencies. This should give you + some clues about what you might have to include when you link your + extension module. For example, notice the first line of output here:

      +
      +
      +$ ldd swig
+        libstdc++-libc6.1-1.so.2 => /usr/lib/libstdc++-libc6.1-1.so.2 (0x40019000)
+        libm.so.6 => /lib/libm.so.6 (0x4005b000)
+        libc.so.6 => /lib/libc.so.6 (0x40077000)
+        /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
+$
+
      +
      +

      If linking wasn't enough of a problem, another major complication of + C++ is that it does not define any sort of standard for binary linking + of libraries. This means that C++ code compiled by different compilers + will not link together properly as libraries nor is the memory layout + of classes and data structures implemented in any kind of portable + manner. In a monolithic C++ program, this problem may be unnoticed. + However, in Perl, it is possible for different extension modules to be + compiled with different C++ compilers. As long as these modules are + self-contained, this probably won't matter. However, if these modules + start sharing data, you will need to take steps to avoid segmentation + faults and other erratic program behavior. Also, be aware that certain + C++ features, especially RTTI, can behave strangely when working with + multiple modules.

      +

      It should be noted that you may get a lot of error messages about + the `bool' datatype when compiling a C++ Perl module. If you + experience this problem, you can try the following :

      +
        +
      • Use -DHAS_BOOL when compiling the SWIG wrapper code
        • +
      • Or use -Dbool=char when compiling.
        • +
      +

      Finally, recent versions of Perl (5.8.0) have namespace conflict + problems. Perl defines a bunch of short macros to make the Perl API + function names shorter. For example, in + /usr/lib/perl/5.8.0/CORE/embed.h there is a line:

      +
      +
      +#define do_open Perl_do_open
+
      +
      +

      The problem is, in the <iostream> header from GNU libstdc++v3 there + is a private function named do_open. If <iostream> is included after + the perl headers, then the Perl macro causes the iostream do_open to be + renamed, which causes compile errors. Hopefully in the future Perl will + support a PERL_NO_SHORT_NAMES flag, but for now the only solution is to + undef the macros that conflict. Lib/perl5/noembed.h in the SWIG source + has a list of macros that are known to conflict with either standard + headers or other headers. But if you get macro type conflicts from + other macros not included in Lib/perl5/noembed.h while compiling the + wrapper, you will have to find the macro that conflicts and add an + #undef into the .i file. Please report any conflicting macros you find + to swig-user mailing list.

      +

      28.2.7 Compiling for 64-bit platforms

      +

      On platforms that support 64-bit applications (Solaris, Irix, etc.), + special care is required when building extension modules. On these + machines, 64-bit applications are compiled and linked using a different + set of compiler/linker options. In addition, it is not generally + possible to mix 32-bit and 64-bit code together in the same + application.

      +

      To utilize 64-bits, the Perl executable will need to be recompiled + as a 64-bit application. In addition, all libraries, wrapper code, and + every other part of your application will need to be compiled for + 64-bits. If you plan to use other third-party extension modules, they + will also have to be recompiled as 64-bit extensions.

      +

      If you are wrapping commercial software for which you have no source + code, you will be forced to use the same linking standard as used by + that software. This may prevent the use of 64-bit extensions. It may + also introduce problems on platforms that support more than one linking + standard (e.g., -o32 and -n32 on Irix).

      +

      28.3 Building Perl Extensions under Windows

      +

      Building a SWIG extension to Perl under Windows is roughly similar + to the process used with Unix. Normally, you will want to produce a DLL + that can be loaded into the Perl interpreter. This section assumes you + are using SWIG with Microsoft Visual C++ although the procedure may be + similar with other compilers.

      +

      28.3.1 Running SWIG from Developer Studio

      +

      If you are developing your application within Microsoft developer + studio, SWIG can be invoked as a custom build option. The process + roughly requires these steps :

      +
        +
      • Open up a new workspace and use the AppWizard to select a DLL + project.
        • +
      • Add both the SWIG interface file (the .i file), any supporting C + files, and the name of the wrapper file that will be created by SWIG + (ie. example_wrap.c). Note : If using C++, choose a different + suffix for the wrapper file such as example_wrap.cxx. Don't + worry if the wrapper file doesn't exist yet--Developer studio will keep + a reference to it around.
        • +
      • Select the SWIG interface file and go to the settings menu. Under + settings, select the "Custom Build" option.
        • +
      • Enter "SWIG" in the description field.
        • +
      • Enter "swig -perl5 -o $(ProjDir)\$(InputName)_wrap.cxx + $(InputPath)" in the "Build command(s) field"
        • +
      • Enter "$(ProjDir)\$(InputName)_wrap.cxx" in the "Output + files(s) field".
        • +
      • Next, select the settings for the entire project and go to + "C++:Preprocessor". Add the include directories for your Perl 5 + installation under "Additional include directories".
        • +
      • Define the symbols WIN32 and MSWIN32 under preprocessor options. If + using the ActiveWare port, also define the symbol PERL_OBJECT. Note + that all extensions to the ActiveWare port must be compiled with the + C++ compiler since Perl has been encapsulated in a C++ class.
        • +
      • Finally, select the settings for the entire project and go to "Link + Options". Add the Perl library file to your link libraries. For example + "perl.lib". Also, set the name of the output file to match the name of + your Perl module (ie. example.dll).
        • +
      • Build your project.
        • +
      +

      Now, assuming you made it this far, SWIG will be automatically + invoked when you build your project. Any changes made to the interface + file will result in SWIG being automatically invoked to produce a new + version of the wrapper file. To run your new Perl extension, simply run + Perl and use the use command as normal. For example :

      +
      +
      +DOS > perl
+use example;
+$a = example::fact(4);
+print "$a\n";
+
+
      +
      +

      28.3.2 Using other compilers

      +

      SWIG is known to work with Cygwin and may work with other compilers + on Windows. For general hints and suggestions refer to the +Windows chapter.

      +

      28.4 The low-level interface

      +

      At its core, the Perl module uses a simple low-level interface to C + function, variables, constants, and classes. This low-level interface + can be used to control your application. However, it is also used to + construct more user-friendly proxy classes as described in the next + section.

      +

      28.4.1 Functions

      +

      C functions are converted into new Perl built-in commands (or + subroutines). For example:

      +
      +
      +%module example
+int fact(int a);
+...
+
      +
      +

      Now, in Perl:

      +
      +
      +use example;
+$a = &example::fact(2);
+
      +
      +

      28.4.2 Global variables

      +

      Global variables are handled using Perl's magic variable mechanism. + SWIG generates a pair of functions that intercept read/write operations + and attaches them to a Perl variable with the same name as the C global + variable. Thus, an interface like this

      +
      +
      +%module example;
+...
+double Spam;
+...
+
      +
      +

      is accessed as follows :

      +
      +
      +use example;
+print $example::Spam,"\n";
+$example::Spam = $example::Spam + 4
+# ... etc ...
+
+
      +
      +

      If a variable is declared as const, it is wrapped as a + read-only variable. Attempts to modify its value will result in an + error.

      +

      To make ordinary variables read-only, you can also use the +%immutable directive. For example:

      +
      +
      +%{
+extern char *path;
+%}
+%immutable;
+extern char *path;
+%mutable;
+
      +
      +

      The %immutable directive stays in effect until it is + explicitly disabled or cleared using %mutable. See the +Creating read-only variables section for further details.

      +

      It is also possible to tag a specific variable as read-only like + this:

      +
      +
      +%{
+extern char *path;
+%}
+%immutable path; 
+...
+...
+extern char *path;       // Declared later in the input
+
      +
      +

      28.4.3 Constants

      +

      By default, constants are wrapped as read-only Perl variables. For + example:

      +
      +
      +%module example
+
+#define FOO 42
+
      +
      +

      In Perl:

      +
      +
      +use example;
+print $example::FOO,"\n";    # OK
+$example::FOO = 2;           # Error
+
      +
      +

      Alternatively, if you use swig's -const option, constants + are wrapped such that the leading $ isn't required (by using a constant + subroutine), which usually gives a more natural Perl interface, for + example:

      +
      +
      +use example;
+print example::FOO,"\n";
+
      +
      +

      28.4.4 Pointers

      +

      SWIG represents pointers as blessed references. A blessed reference + is the same as a Perl reference except that it has additional + information attached to it indicating what kind of reference it is. + That is, if you have a C declaration like this :

      +
      +
      +Matrix *new_Matrix(int n, int m);
+
      +
      +

      The module returns a value generated as follows:

      +
      +
      +$ptr = new_Matrix(int n, int m);     # Save pointer return result
+bless $ptr, "p_Matrix";              # Bless it as a pointer to Matrix
+
      +
      +

      SWIG uses the "blessing" to check the datatype of various pointers. + In the event of a mismatch, an error or warning message is generated.

      +

      To check to see if a value is the NULL pointer, use the +defined() command :

      +
      +
      +if (defined($ptr)) {
+	print "Not a NULL pointer.";
+} else {
+	print "Is a NULL pointer.";
+}
+
+
      +
      +

      To create a NULL pointer, you should pass the undef value + to a function.

      +

      The "value" of a Perl reference is not the same as the underlying C + pointer that SWIG wrapper functions return. Suppose that $a + and $b are two references that point to the same C object. In + general, $a and $b will be different--since they are + different references. Thus, it is a mistake to check the equality of +$a and $b to check the equality of two C pointers. The + correct method to check equality of C pointers is to dereference them + as follows :

      +
      +
      +if ($$a == $$b) {
+	print "a and b point to the same thing in C";
+} else {
+	print "a and b point to different objects.";
+}
+
+
      +
      +

      As much as you might be inclined to modify a pointer value directly + from Perl, don't. Manipulating pointer values is architecture dependent + and could cause your program to crash. Similarly, don't try to manually + cast a pointer to a new type by reblessing a pointer. This may not work + like you expect and it is particularly dangerous when casting C++ + objects. If you need to cast a pointer or change its value, consider + writing some helper functions instead. For example:

      +
      +
      +%inline %{
+/* C-style cast */
+Bar *FooToBar(Foo *f) {
+   return (Bar *) f;
+}
+
+/* C++-style cast */
+Foo *BarToFoo(Bar *b) {
+   return dynamic_cast<Foo*>(b);
+}
+
+Foo *IncrFoo(Foo *f, int i) {
+    return f+i;
+}
+%}
+
      +
      +

      Also, if working with C++, you should always try to use the new C++ + style casts. For example, in the above code, the C-style cast may + return a bogus result whereas as the C++-style cast will return +NULL if the conversion can't be performed.

      +

      Compatibility Note: In earlier versions, SWIG tried to + preserve the same pointer naming conventions as XS and xsubpp. + Given the advancement of the SWIG typesystem and the growing + differences between SWIG and XS, this is no longer supported.

      +

      28.4.5 Structures

      +

      Access to the contents of a structure are provided through a set of + low-level accessor functions as described in the "SWIG Basics" chapter. + For example,

      +
      +
      +struct Vector {
+	double x,y,z;
+};
+
      +
      +

      gets mapped into the following collection of accessor functions:

      +
      +
      +struct Vector *new_Vector();
+void           delete_Vector(Vector *v);
+double         Vector_x_get(Vector *obj)
+void           Vector_x_set(Vector *obj, double x)
+double         Vector_y_get(Vector *obj)
+void           Vector_y_set(Vector *obj, double y)
+double         Vector_z_get(Vector *obj)
+void           Vector_z_set(Vector *obj, double z)
+
+
      +
      +

      These functions are then used to access structure data from Perl as + follows:

      +
      +
      +$v = example::new_Vector();
+print example::Vector_x_get($v),"\n";    # Get x component
+example::Vector_x_set($v,7.8);          # Change x component
+
      +
      +

      Similar access is provided for unions and the data members of C++ + classes.

      +

      const members of a structure are read-only. Data members + can also be forced to be read-only using the %immutable + directive. For example:

      +
      +
      +struct Foo {
+   ...
+   %immutable;
+   int x;        /* Read-only members */
+   char *name;
+   %mutable;
+   ...
+};
+
      +
      +

      When char * members of a structure are wrapped, the + contents are assumed to be dynamically allocated using malloc + or new (depending on whether or not SWIG is run with the -c++ + option). When the structure member is set, the old contents will be + released and a new value created. If this is not the behavior you want, + you will have to use a typemap (described later).

      +

      Array members are normally wrapped as read-only. For example,

      +
      +
      +struct Foo {
+   int  x[50];
+};
+
      +
      +

      produces a single accessor function like this:

      +
      +
      +int *Foo_x_get(Foo *self) {
+    return self->x;
+};
+
      +
      +

      If you want to set an array member, you will need to supply a + "memberin" typemap described later in this chapter. As a special case, + SWIG does generate code to set array members of type char + (allowing you to store a Python string in the structure).

      +

      When structure members are wrapped, they are handled as pointers. + For example,

      +
      +
      +struct Foo {
+   ...
+};
+
+struct Bar {
+   Foo f;
+};
+
      +
      +

      generates accessor functions such as this:

      +
      +
      +Foo *Bar_f_get(Bar *b) {
+    return &b->f;
+}
+
+void Bar_f_set(Bar *b, Foo *val) {
+    b->f = *val;
+}
+
      +
      +

      28.4.6 C++ classes

      +

      C++ classes are wrapped by building a set of low level accessor + functions. Consider the following class :

      +
      +
      +class List {
+public:
+  List();
+  ~List();
+  int  search(char *item);
+  void insert(char *item);
+  void remove(char *item);
+  char *get(int n);
+  int  length;
+static void print(List *l);
+};
+
      +
      +

      When wrapped by SWIG, the following functions are created :

      +
      +
      +List    *new_List();
+void     delete_List(List *l);
+int      List_search(List *l, char *item);
+void     List_insert(List *l, char *item);
+void     List_remove(List *l, char *item);
+char    *List_get(List *l, int n);
+int      List_length_get(List *l);
+void     List_length_set(List *l, int n);
+void     List_print(List *l);
+
+
      +
      +

      In Perl, these functions are used in a straightforward manner:

      +
      +
      +use example;
+$l = example::new_List();
+example::List_insert($l,"Ale");
+example::List_insert($l,"Stout");
+example::List_insert($l,"Lager")
+example::List_print($l)
+Lager
+Stout
+Ale
+print example::List_length_get($l),"\n";
+3
+
      +
      +

      At this low level, C++ objects are really just typed pointers. + Member functions are accessed by calling a C-like wrapper with an + instance pointer as the first argument. Although this interface is + fairly primitive, it provides direct access to C++ objects. A higher + level interface using Perl proxy classes can be built using these + low-level accessors. This is described shortly.

      +

      28.4.7 C++ classes and type-checking

      +

      The SWIG type-checker is fully aware of C++ inheritance. Therefore, + if you have classes like this

      +
      +
      +class Foo {
+...
+};
+
+class Bar : public Foo {
+...
+};
+
      +
      +

      and a function

      +
      +
      +void spam(Foo *f);
+
      +
      +

      then the function spam() accepts Foo * or a + pointer to any class derived from Foo. If necessary, the + type-checker also adjusts the value of the pointer (as is necessary + when multiple inheritance is used).

      +

      28.4.8 C++ overloaded functions

      +

      If you have a C++ program with overloaded functions or methods, you + will need to disambiguate those methods using %rename. For + example:

      +
      +
      +/* Forward renaming declarations */
+%rename(foo_i) foo(int); 
+%rename(foo_d) foo(double);
+...
+void foo(int);           // Becomes 'foo_i'
+void foo(char *c);       // Stays 'foo' (not renamed)
+
+class Spam {
+public:
+   void foo(int);      // Becomes 'foo_i'
+   void foo(double);   // Becomes 'foo_d'
+   ...
+};
+
      +
      +

      Now, in Perl, the methods are accessed as follows:

      +
      +
      +use example;
+example::foo_i(3);
+$s = example::new_Spam();
+example::Spam_foo_i($s,3);
+example::Spam_foo_d($s,3.14);
+
      +
      +

      Please refer to the "SWIG Basics" chapter for more information.

      +

      28.4.9 Operators

      +

      As of version 1.3.27 SWIG automatically renames the most common C++ + operators, and maps them into the perl module with the proper 'use + overload ...' so you don't need to do any work.

      +

      The following C++ operators are currently supported by the Perl + module:

      +
        +
      • operator++
        • +
      • operator--
        • +
      • operator+
        • +
      • operator-
        • +
      • operator*
        • +
      • operator/
        • +
      • operator==
        • +
      • operator!=
        • +
      • operator%
        • +
      • operator>
        • +
      • operator<
        • +
      • operator and
        • +
      • operator or
        • +
      +

      28.4.10 Modules and packages

      +

      When you create a SWIG extension, everything gets placed into a + single Perl module. The name of the module is determined by the +%module directive. To use the module, do the following :

      +
      +
      +% perl5
+use example;                      # load the example module
+print example::fact(4),"\n"       # Call a function in it
+24
+
      +
      +

      Usually, a module consists of a collection of code that is contained + within a single file. A package, on the other hand, is the Perl + equivalent of a namespace. A package is a lot like a module, except + that it is independent of files. Any number of files may be part of the + same package--or a package may be broken up into a collection of + modules if you prefer to think about it in this way.

      +

      SWIG installs its functions into a package with the same name as the + module.

      +

      Incompatible Change: previous versions of SWIG enabled you to + change the name of the package by using the -package option, this + feature has been removed in order to properly support modules that used + nested namespaces, e.g. Foo::Bar::Baz. To give your module a nested + namespace simply provide the fully qualified name in your %module + directive:

      +
      +
      +%module "Foo::Bar::Baz"
+
      +
      +

      NOTE: the double quotes are necessary.

      +

      Using the package option of the %module directive + allows you to specify what Perl namespace that the module will be + living in when installed. This is useful in the situation where a + module maintainer wants to split a large module into smaller pieces to + make maintenance easier, but doesn't want to have that affect the + module name used by applications. So for example, if I wanted to split +XML::Xerces into XML::Xerces::SAX, etc. , but I wanted all + the applications to be able to access the classes using the +XML::Xerces namespace I could use:

      +
      +
      +%module(package="XML::Xerces") "XML::Xerces::SAX
+
      +
      +

      And now all the applications could use the class +XML::Xerces::SAXParser. Without the package directive + splitting the module would force applications to use the class +XML::Xerces::SAX::SAXParser. This could break compatibility for + existing applications that are already using the class under the name +XML::Xerces::SAXParser.

      + + +

      28.5 Input and output parameters

      +

      A common problem in some C programs is handling parameters passed as + simple pointers. For example:

      +
      +
      +void add(int x, int y, int *result) {
+   *result = x + y;
+}
+
      +
      +

      or perhaps

      +
      +
      +int sub(int *x, int *y) {
+   return *x+*y;
+}
+
      +
      +

      The easiest way to handle these situations is to use the +typemaps.i file. For example:

      +
      +
      +%module example
+%include "typemaps.i"
+
+void add(int, int, int *OUTPUT);
+int  sub(int *INPUT, int *INPUT);
+
      +
      +

      In Perl, this allows you to pass simple values. For example:

      +
      +
      +$a = example::add(3,4);
+print "$a\n";
+7
+$b = example::sub(7,4);
+print "$b\n";
+3
+
      +
      +

      Notice how the INPUT parameters allow integer values to be + passed instead of pointers and how the OUTPUT parameter + creates a return result.

      +

      If you don't want to use the names INPUT or OUTPUT +, use the %apply directive. For example:

      +
      +
      +%module example
+%include "typemaps.i"
+
+%apply int *OUTPUT { int *result };
+%apply int *INPUT  { int *x, int *y};
+
+void add(int x, int y, int *result);
+int  sub(int *x, int *y);
+
      +
      +

      If a function mutates one of its parameters like this,

      +
      +
      +void negate(int *x) {
+   *x = -(*x);
+}
+
      +
      +

      you can use INOUT like this:

      +
      +
      +%include "typemaps.i"
+...
+void negate(int *INOUT);
+
      +
      +

      In Perl, a mutated parameter shows up as a return value. For + example:

      +
      +
      +$a = example::negate(3);
+print "$a\n";
+-3
+
      +
      +

      The most common use of these special typemap rules is to handle + functions that return more than one value. For example, sometimes a + function returns a result as well as a special error code:

      +
      +
      +/* send message, return number of bytes sent, along with success code */
+int send_message(char *text, int len, int *success);
+
      +
      +

      To wrap such a function, simply use the OUTPUT rule above. + For example:

      +
      +
      +%module example
+%include "typemaps.i"
+%apply int *OUTPUT { int *success };
+...
+int send_message(char *text, int *success);
+
      +
      +

      When used in Perl, the function will return multiple values.

      +
      +
      +($bytes, $success) = example::send_message("Hello World");
+
      +
      +

      Another common use of multiple return values are in query functions. + For example:

      +
      +
      +void get_dimensions(Matrix *m, int *rows, int *columns);
+
      +
      +

      To wrap this, you might use the following:

      +
      +
      +%module example
+%include "typemaps.i"
+%apply int *OUTPUT { int *rows, int *columns };
+...
+void get_dimensions(Matrix *m, int *rows, *columns);
+
      +
      +

      Now, in Perl:

      +
      +
      +($r,$c) = example::get_dimensions($m);
+
      +
      +

      In certain cases, it is possible to treat Perl references as C + pointers. To do this, use the REFERENCE typemap. For example:

      +
      +
      +%module example
+%include "typemaps.i"
+
+void add(int x, int y, int *REFERENCE);
+
      +
      +

      In Perl:

      +
      +
      +use example;
+$c = 0.0;
+example::add(3,4,\$c);
+print "$c\n";
+7
+
      +
      +

      Note: The REFERENCE feature is only currently + supported for numeric types (integers and floating point).

      +

      28.6 Exception handling

      +

      The SWIG %exception directive can be used to create a + user-definable exception handler for converting exceptions in your + C/C++ program into Perl exceptions. The chapter on customization + features contains more details, but suppose you have a C++ class like + the following :

      +
      +
      +class RangeError {};   // Used for an exception
+
+class DoubleArray {
+  private:
+    int n;
+    double *ptr;
+  public:
+    // Create a new array of fixed size
+    DoubleArray(int size) {
+      ptr = new double[size];
+      n = size;
+    }
+    // Destroy an array
+    ~DoubleArray() {
+       delete ptr;
+    }
+    // Return the length of the array
+    int   length() {
+      return n;
+    }
+
+    // Get an item from the array and perform bounds checking.
+    double getitem(int i) {
+      if ((i >= 0) && (i < n))
+        return ptr[i];
+      else
+        throw RangeError();
+    }
+
+    // Set an item in the array and perform bounds checking.
+    void setitem(int i, double val) {
+      if ((i >= 0) && (i < n))
+        ptr[i] = val;
+      else {
+        throw RangeError();
+      }
+    }
+  };
+
      +
      +

      Since several methods in this class can throw an exception for an + out-of-bounds access, you might want to catch this in the Perl + extension by writing the following in an interface file:

      +
      +
      +%exception {
+  try {
+    $action
+  }
+  catch (RangeError) {
+    croak("Array index out-of-bounds");
+  }
+}
+
+class DoubleArray {
+...
+};
+
      +
      +

      The exception handling code is inserted directly into generated + wrapper functions. The $action variable is replaced with the + C/C++ code being executed by the wrapper. When an exception handler is + defined, errors can be caught and used to gracefully generate a Perl + error instead of forcing the entire program to terminate with an + uncaught error.

      +

      As shown, the exception handling code will be added to every wrapper + function. Since this is somewhat inefficient. You might consider + refining the exception handler to only apply to specific methods like + this:

      +
      +
      +%exception getitem {
+  try {
+    $action
+  }
+  catch (RangeError) {
+    croak("Array index out-of-bounds");
+  }
+}
+
+%exception setitem {
+  try {
+    $action
+  }
+  catch (RangeError) {
+    croak("Array index out-of-bounds");
+  }
+}
+
      +
      +

      In this case, the exception handler is only attached to methods and + functions named getitem and setitem.

      +

      If you had a lot of different methods, you can avoid extra typing by + using a macro. For example:

      +
      +
      +%define RANGE_ERROR
+{
+  try {
+    $action
+  }
+  catch (RangeError) {
+    croak("Array index out-of-bounds");
+  }
+}
+%enddef
+
+%exception getitem RANGE_ERROR;
+%exception setitem RANGE_ERROR;
+
      +
      +

      Since SWIG's exception handling is user-definable, you are not + limited to C++ exception handling. See the chapter on " +Customization features" for more examples.

      +

      Compatibility note: In SWIG1.1, exceptions were defined using + the older %except directive:

      +
      +
      +%except(python) {
+  try {
+    $function
+  }
+  catch (RangeError) {
+    croak("Array index out-of-bounds");
+  }
+}
+
      +
      +

      This is still supported, but it is deprecated. The newer +%exception directive provides the same functionality, but it has + additional capabilities that make it more powerful.

      +

      28.7 Remapping datatypes with typemaps

      +

      This section describes how you can modify SWIG's default wrapping + behavior for various C/C++ datatypes using the %typemap + directive. This is an advanced topic that assumes familiarity with the + Perl C API as well as the material in the "Typemaps +" chapter.

      +

      Before proceeding, it should be stressed that typemaps are not + a required part of using SWIG---the default wrapping behavior is enough + in most cases. Typemaps are only used if you want to change some aspect + of the primitive C-Perl interface.

      +

      28.7.1 A simple typemap example

      +

      A typemap is nothing more than a code generation rule that is + attached to a specific C datatype. For example, to convert integers + from Perl to C, you might define a typemap like this:

      +
      +
      +%module example
+
+%typemap(in) int {
+	$1 = (int) SvIV($input);
+	printf("Received an integer : %d\n", $1);
+}
+...
+%inline %{
+extern int fact(int n);
+%}
+
+
      +
      +

      Typemaps are always associated with some specific aspect of code + generation. In this case, the "in" method refers to the conversion of + input arguments to C/C++. The datatype int is the datatype to + which the typemap will be applied. The supplied C code is used to + convert values. In this code a number of special variable prefaced by a + $ are used. The $1 variable is placeholder for a + local variable of type int. The $input variable is + the input object (usually a SV *).

      +

      When this example is used in Perl5, it will operate as follows :

      +
      +
      +use example;
+$n = example::fact(6);
+print "$n\n";
+...
+
+Output :
+Received an integer : 6
+720
+
      +
      +

      The application of a typemap to specific datatypes and argument + names involves more than simple text-matching--typemaps are fully + integrated into the SWIG type-system. When you define a typemap for +int, that typemap applies to int and qualified variations + such as const int. In addition, the typemap system follows +typedef declarations. For example:

      +
      +
      +%typemap(in) int n {
+	$1 = (int) SvIV($input);
+	printf("n = %d\n",$1);
+}
+%inline %{
+typedef int Integer;
+extern int fact(Integer n);    // Above typemap is applied
+%}
+
      +
      +

      It should be noted that the matching of typedef only occurs + in one direction. If you defined a typemap for Integer, it is + not applied to arguments of type int.

      +

      Typemaps can also be defined for groups of consecutive arguments. + For example:

      +
      +
      +%typemap(in) (char *str, unsigned len) {
+    $1 = SvPV($input,$2);
+};
+
+int count(char c, char *str, unsigned len);
+
      +
      +

      When a multi-argument typemap is defined, the arguments are always + handled as a single Perl object. This allows the function to be used + like this (notice how the length parameter is omitted):

      +
      +
      +example::count("e","Hello World");
+1
+>>>
+
      +
      +

      28.7.2 Perl5 typemaps

      +

      The previous section illustrated an "in" typemap for converting Perl + objects to C. A variety of different typemap methods are defined by the + Perl module. For example, to convert a C integer back into a Perl + object, you might define an "out" typemap like this:

      +
      +
      +%typemap(out) int {
+    $result = sv_newmortal();
+    set_setiv($result, (IV) $1);
+    argvi++;
+}
+
      +
      +

      The following typemap methods are available:

      +

      %typemap(in)

      +
      Converts Perl5 object to input function arguments.
      +

      %typemap(out)

      +
      Converts function return value to a Perl5 value.
      +

      %typemap(varin)

      +
      Converts a Perl5 object to a global variable.
      +

      %typemap(varout)

      +
      Converts a global variable to a Perl5 object.
      +

      %typemap(freearg)

      +
      Cleans up a function argument after a function call
      +

      %typemap(argout)

      +
      Output argument handling
      +

      %typemap(ret)

      +
      Clean up return value from a function.
      +

      %typemap(memberin)

      +
      Setting of C++ member data (all languages).
      +

      %typemap(memberout)

      +
      Return of C++ member data (all languages).
      +

      %typemap(check)

      +
      Check value of input parameter.
      +

      28.7.3 Typemap variables

      +

      Within typemap code, a number of special variables prefaced with a +$ may appear. A full list of variables can be found in the " +Typemaps" chapter. This is a list of the most common variables:

      +

      $1

      +
      A C local variable corresponding to the actual type + specified in the %typemap directive. For input values, this is + a C local variable that's supposed to hold an argument value. For + output values, this is the raw result that's supposed to be returned to + Perl.
      +

      $input

      +
      A Perl object holding the value of an argument of + variable value.
      +

      $result

      +
      A Perl object that holds the result to be returned + to Perl.
      +

      $1_name

      +
      The parameter name that was matched.
      +

      $1_type

      +
      The actual C datatype matched by the typemap.
      +

      $1_ltype

      +
      An assignable version of the datatype matched by + the typemap (a type that can appear on the left-hand-side of a C + assignment operation). This type is stripped of qualifiers and may be + an altered version of $1_type. All arguments and local + variables in wrapper functions are declared using this type so that + their values can be properly assigned.
      +

      $symname

      +
      The Perl name of the wrapper function being + created.
      +

      28.7.4 Useful functions

      +

      When writing typemaps, it is necessary to work directly with Perl5 + objects. This, unfortunately, can be a daunting task. Consult the + "perlguts" man-page for all of the really ugly details. A short summary + of commonly used functions is provided here for reference. It should be + stressed that SWIG can be used quite effectively without knowing any of + these details--especially now that there are typemap libraries that can + already been written.

      +

      Perl Integer Functions

      +
      +
      +int   SvIV(SV *);
+void  sv_setiv(SV *sv, IV value);
+SV   *newSViv(IV value);
+int   SvIOK(SV *);
+
      +
      +

      Perl Floating Point Functions

      +
      +
      +double SvNV(SV *);
+void   sv_setnv(SV *, double value);
+SV    *newSVnv(double value);
+int    SvNOK(SV *);
+
      +
      +

      Perl String Functions

      +
      +
      +char     *SvPV(SV *, STRLEN len);
+void      sv_setpv(SV *, char *val);
+void      sv_setpvn(SV *, char *val, STRLEN len);
+SV       *newSVpv(char *value, STRLEN len);
+int       SvPOK(SV *);
+void      sv_catpv(SV *, char *);
+void      sv_catpvn(SV *, char *, STRLEN);
+
      +
      +

      Perl References

      +
      +
      +void      sv_setref_pv(SV *, char *, void *ptr);
+int       sv_isobject(SV *);
+SV       *SvRV(SV *);
+int       sv_isa(SV *, char *0;
+
      +
      +

      28.8 Typemap Examples

      +

      This section includes a few examples of typemaps. For more examples, + you might look at the files "perl5.swg" and "typemaps.i +" in the SWIG library.

      +

      28.8.1 Converting a Perl5 array to a char + **

      +

      A common problem in many C programs is the processing of command + line arguments, which are usually passed in an array of NULL terminated + strings. The following SWIG interface file allows a Perl5 array + reference to be used as a char ** datatype.

      +
      +
      +%module argv
+
+// This tells SWIG to treat char ** as a special case
+%typemap(in) char ** {
+	AV *tempav;
+	I32 len;
+	int i;
+	SV  **tv;
+	if (!SvROK($input))
+	    croak("Argument $argnum is not a reference.");
+        if (SvTYPE(SvRV($input)) != SVt_PVAV)
+	    croak("Argument $argnum is not an array.");
+        tempav = (AV*)SvRV($input);
+	len = av_len(tempav);
+	$1 = (char **) malloc((len+2)*sizeof(char *));
+	for (i = 0; i <= len; i++) {
+	    tv = av_fetch(tempav, i, 0);	
+	    $1[i] = (char *) SvPV(*tv,PL_na);
+        }
+	$1[i] = NULL;
+};
+
+// This cleans up the char ** array after the function call
+%typemap(freearg) char ** {
+	free($1);
+}
+
+// Creates a new Perl array and places a NULL-terminated char ** into it
+%typemap(out) char ** {
+	AV *myav;
+	SV **svs;
+	int i = 0,len = 0;
+	/* Figure out how many elements we have */
+	while ($1[len])
+	   len++;
+	svs = (SV **) malloc(len*sizeof(SV *));
+	for (i = 0; i < len ; i++) {
+	    svs[i] = sv_newmortal();
+	    sv_setpv((SV*)svs[i],$1[i]);
+	};
+	myav =	av_make(len,svs);
+	free(svs);
+        $result = newRV_noinc((SV*)myav);
+        sv_2mortal($result);
+        argvi++;
+}
+
+// Now a few test functions
+%inline %{
+int print_args(char **argv) {
+    int i = 0;
+    while (argv[i]) {
+         printf("argv[%d] = %s\n", i,argv[i]);
+         i++;
+    }
+    return i;
+}
+
+// Returns a char ** list 
+char **get_args() {
+    static char *values[] = { "Dave", "Mike", "Susan", "John", "Michelle", 0};
+    return &values[0];
+}
+%}
+
+
      +
      +

      When this module is compiled, the wrapped C functions can be used in + a Perl script as follows :

      +
      +
      +use argv;
+@a = ("Dave", "Mike", "John", "Mary");           # Create an array of strings
+argv::print_args(\@a);                           # Pass it to our C function
+$b = argv::get_args();                           # Get array of strings from C
+print @$b,"\n";                                  # Print it out
+
      +
      +

      28.8.2 Return values

      +

      Return values are placed on the argument stack of each wrapper + function. The current value of the argument stack pointer is contained + in a variable argvi. Whenever a new output value is added, it + is critical that this value be incremented. For multiple output values, + the final value of argvi should be the total number of output + values.

      +

      The total number of return values should not exceed the number of + input values unless you explicitly extend the argument stack. This can + be done using the EXTEND() macro as in :

      +
      +
      +%typemap(argout) int *OUTPUT {
+	if (argvi >= items) {            
+		EXTEND(sp,1);              /* Extend the stack by 1 object */
+	}
+	$result = sv_newmortal();
+	sv_setiv($target,(IV) *($1));
+	argvi++;
+}
+
      +
      +

      28.8.3 Returning values from arguments

      +

      Sometimes it is desirable for a function to return a value in one of + its arguments. This example describes the implementation of the +OUTPUT typemap.

      +
      +
      +%module return
+
+// This tells SWIG to treat an double * argument with name 'OutDouble' as
+// an output value.  
+
+%typemap(argout) double *OUTPUT {
+	$result = sv_newmortal();
+	sv_setnv($result, *$input);
+	argvi++;                     /* Increment return count -- important! */
+}
+
+// We don't care what the input value is. Ignore, but set to a temporary variable
+
+%typemap(in,numinputs=0) double *OUTPUT(double junk) {
+	$1 = &junk;
+}
+
+// Now a function to test it
+%{
+/* Returns the first two input arguments */
+int multout(double a, double b, double *out1, double *out2) {
+	*out1 = a;
+	*out2 = b;
+	return 0;
+};
+%}
+
+// If we name both parameters OutDouble both will be output
+
+int multout(double a, double b, double *OUTPUT, double *OUTPUT);
+...
+
      +
      +

      When this function is called, the output arguments are appended to + the stack used to return results. This shows up an array in Perl. For + example :

      +
      +
      +@r = multout(7,13);
+print "multout(7,13) = @r\n";
+($x,$y) = multout(7,13);
+
      +
      +

      28.8.4 Accessing array structure members

      +

      Consider the following data structure :

      +
      +
      +#define SIZE  8
+typedef struct {
+    int   values[SIZE];
+    ...
+} Foo;
+
+
      +
      +

      By default, SWIG doesn't know how to the handle the values structure + member it's an array, not a pointer. In this case, SWIG makes the array + member read-only. Reading will simply return a pointer to the first + item in the array. To make the member writable, a "memberin" typemap + can be used.

      +
      +
      +%typemap(memberin) int [SIZE] {
+    int i;
+    for (i = 0; i < SIZE; i++) {
+        $1[i] = $input[i];
+    }
+}
+
+
      +
      +

      Whenever a int [SIZE] member is encountered in a structure + or class, this typemap provides a safe mechanism for setting its value.

      +

      As in the previous example, the typemap can be generalized for any + dimension. For example:

      +
      +
      +%typemap(memberin) int [ANY] {
+   int i;
+   for (i = 0; i < $1_dim0; i++) {
+      $1[i] = $input[i];
+   }
+}
+
      +
      +

      When setting structure members, the input object is always assumed + to be a C array of values that have already been converted from the + target language. Because of this, the memberin typemap is + almost always combined with the use of an "in" typemap. For example, + the "in" typemap in the previous section would be used to convert an +int[] array to C whereas the "memberin" typemap would be used to + copy the converted array into a C data structure.

      +

      28.8.5 Turning Perl references into C + pointers

      +

      A frequent confusion on the SWIG mailing list is errors caused by + the mixing of Perl references and C pointers. For example, suppose you + have a C function that modifies its arguments like this :

      +
      +
      +void add(double a, double b, double *c) {
+	*c = a + b;
+}
+
      +
      +

      A common misinterpretation of this function is the following Perl + script :

      +
      +
      +# Perl script
+$a = 3.5;
+$b = 7.5;
+$c = 0.0;          # Output value
+add($a,$b,\$c);    # Place result in c (Except that it doesn't work)
+
      +
      +

      To make this work with a reference, you can use a typemap such as + this:

      +
      +
      +%typemap(in) double * (double dvalue) {
+  SV* tempsv;
+  if (!SvROK($input)) {
+    croak("expected a reference\n");
+  }
+  tempsv = SvRV($input);
+  if ((!SvNOK(tempsv)) && (!SvIOK(tempsv))) {
+    croak("expected a double reference\n");
+  }
+  dvalue = SvNV(tempsv);
+  $1 = &dvalue;
+}
+
+%typemap(argout) double * {
+  SV *tempsv;
+  tempsv = SvRV($input);
+  sv_setnv(tempsv, *$1);
+}
+
      +
      +

      Now, if you place this before the add function, you can do this :

      +
      +
      +$a = 3.5;
+$b = 7.5;
+$c = 0.0;
+add($a,$b,\$c);            # Now it works!
+print "$c\n";
+
+
      +
      +

      28.8.6 Pointer handling

      +

      Occasionally, it might be necessary to convert pointer values that + have been stored using the SWIG typed-pointer representation. To + convert a pointer from Perl to C, the following function is used:

      +

      int SWIG_ConvertPtr(SV *obj, void **ptr, swig_type_info *ty, int + flags)

      +
      Converts a Perl object obj to a C pointer. + The result of the conversion is placed into the pointer located at +ptr. ty is a SWIG type descriptor structure. flags + is used to handle error checking and other aspects of conversion. +flags is currently undefined and reserved for future expansion. + Returns 0 on success and -1 on error.
      +

      void *SWIG_MakePtr(SV *obj, void *ptr, swig_type_info *ty, int + flags)

      +
      Creates a new Perl pointer object. obj is + a Perl SV that has been initialized to hold the result, ptr is + the pointer to convert, ty is the SWIG type descriptor + structure that describes the type, and flags is a flag that + controls properties of the conversion. flags is currently + undefined and reserved.
      +

      Both of these functions require the use of a special SWIG + type-descriptor structure. This structure contains information about + the mangled name of the datatype, type-equivalence information, as well + as information about converting pointer values under C++ inheritance. + For a type of Foo *, the type descriptor structure is usually + accessed as follows:

      +
      +
      +Foo *f;
+if (SWIG_ConvertPtr($input, (void **) &f, SWIGTYPE_p_Foo, 0) == -1) return NULL;
+
+SV *sv = sv_newmortal();
+SWIG_MakePtr(sv, f, SWIGTYPE_p_Foo, 0);
+
      +
      +

      In a typemap, the type descriptor should always be accessed using + the special typemap variable $1_descriptor. For example:

      +
      +
      +%typemap(in) Foo * {
+   if ((SWIG_ConvertPtr($input,(void **) &$1, $1_descriptor,0)) == -1) return NULL;
+}
+
      +
      +

      If necessary, the descriptor for any type can be obtained using the +$descriptor() macro in a typemap. For example:

      +
      +
      +%typemap(in) Foo * {
+   if ((SWIG_ConvertPtr($input,(void **) &$1, $descriptor(Foo *), 0)) == -1) return NULL;
+}
+
      +
      +

      28.9 Proxy classes

      +

      Out of date. Needs update.

      +

      Using the low-level procedural interface, SWIG can also construct a + high-level object oriented interface to C structures and C++ classes. + This is done by constructing a Perl proxy class (also known as a shadow + class) that provides an OO wrapper to the underlying code. This section + describes the implementation details of the proxy interface.

      +

      28.9.1 Preliminaries

      +

      Proxy classes, are generated by default. If you want to turn them + off, use the -noproxy command line option. For example:

      +
      +
      +$ swig -c++ -perl -noproxy example.i
+
      +
      +

      When proxy classes are used, SWIG moves all of the low-level + procedural wrappers to another package name. By default, this package + is named 'modulec' where 'module' is the name of the module you + provided with the %module directive. Then, in place of the + original module, SWIG creates a collection of high-level Perl wrappers. + In your scripts, you will use these high level wrappers. The wrappers, + in turn, interact with the low-level procedural module.

      +

      28.9.2 Structure and class wrappers

      +

      Suppose you have the following SWIG interface file :

      +
      +
      +%module example
+struct Vector {
+	Vector(double x, double y, double z);
+	~Vector();
+	double x,y,z;
+};
+
+
      +
      +

      When wrapped, SWIG creates the following set of low-level accessor + functions as described in previous sections.

      +
      +
      +Vector *new_Vector(double x, double y, double z);
+void    delete_Vector(Vector *v);
+double  Vector_x_get(Vector *v);
+double  Vector_x_set(Vector *v, double value);
+double  Vector_y_get(Vector *v);
+double  Vector_y_set(Vector *v, double value);
+double  Vector_z_get(Vector *v);
+double  Vector_z_set(Vector *v, double value);
+
+
      +
      +

      However, when proxy classes are enabled, these accessor functions + are wrapped inside a Perl class like this:

      +
      +
      +package example::Vector;
+@ISA = qw( example );
+%OWNER = ();
+%BLESSEDMEMBERS = ();
+
+sub new () {
+    my $self = shift;
+    my @args = @_;
+    $self = vectorc::new_Vector(@args);
+    return undef if (!defined($self));
+    bless $self, "example::Vector";
+    $OWNER{$self} = 1;
+    my %retval;
+    tie %retval, "example::Vector", $self;
+    return bless \%retval,"Vector";
+}
+
+sub DESTROY {
+    return unless $_[0]->isa('HASH');
+    my $self = tied(%{$_[0]});
+    delete $ITERATORS{$self};
+    if (exists $OWNER{$self}) {
+	 examplec::delete_Vector($self));
+	 delete $OWNER{$self};
+}
+
+sub FETCH {
+    my ($self,$field) = @_;
+    my $member_func = "vectorc::Vector_${field}_get";
+    my $val = &$member_func($self);
+    if (exists $BLESSEDMEMBERS{$field}) {
+        return undef if (!defined($val));
+        my %retval;
+        tie %retval,$BLESSEDMEMBERS{$field},$val;
+        return bless \%retval, $BLESSEDMEMBERS{$field};
+    }
+    return $val;
+}
+
+sub STORE {
+    my ($self,$field,$newval) = @_;
+    my $member_func = "vectorc::Vector_${field}_set";
+    if (exists $BLESSEDMEMBERS{$field}) {
+        &$member_func($self,tied(%{$newval}));
+    } else {
+        &$member_func($self,$newval);
+    }
+}
+
      +
      +

      Each structure or class is mapped into a Perl package of the same + name. The C++ constructors and destructors are mapped into constructors + and destructors for the package and are always named "new" and + "DESTROY". The constructor always returns a tied hash table. This hash + table is used to access the member variables of a structure in addition + to being able to invoke member functions. The %OWNER and +%BLESSEDMEMBERS hash tables are used internally and described + shortly.

      +

      To use our new proxy class we can simply do the following:

      +
      +
      +# Perl code using Vector class
+$v = new Vector(2,3,4);
+$w = Vector->new(-1,-2,-3);
+
+# Assignment of a single member
+$v->{x} = 7.5;
+
+# Assignment of all members
+%$v = ( x=>3,
+	 y=>9,
+	 z=>-2);
+
+# Reading members
+$x = $v->{x};
+
+# Destruction
+$v->DESTROY();
+
+
      +
      +

      28.9.3 Object Ownership

      +

      In order for proxy classes to work properly, it is necessary for + Perl to manage some mechanism of object ownership. Here's the crux of + the problem---suppose you had a function like this :

      +
      +
      +Vector *Vector_get(Vector *v, int index) {
+	return &v[i];
+}
+
      +
      +

      This function takes a Vector pointer and returns a pointer to + another Vector. Such a function might be used to manage arrays or lists + of vectors (in C). Now contrast this function with the constructor for + a Vector object :

      +
      +
      +Vector *new_Vector(double x, double y, double z) {
+	Vector *v;
+	v = new Vector(x,y,z);        // Call C++ constructor
+	return v;
+}
+
      +
      +

      Both functions return a Vector, but the constructor is returning a + brand-new Vector while the other function is returning a Vector that + was already created (hopefully). In Perl, both vectors will be + indistinguishable---clearly a problem considering that we would + probably like the newly created Vector to be destroyed when we are done + with it.

      +

      To manage these problems, each class contains two methods that + access an internal hash table called %OWNER. This hash keeps a + list of all of the objects that Perl knows that it has created. This + happens in two cases: (1) when the constructor has been called, and (2) + when a function implicitly creates a new object (as is done when SWIG + needs to return a complex datatype by value). When the destructor is + invoked, the Perl proxy class module checks the %OWNER hash to + see if Perl created the object. If so, the C/C++ destructor is invoked. + If not, we simply destroy the Perl object and leave the underlying C + object alone (under the assumption that someone else must have created + it).

      +

      This scheme works remarkably well in practice but it isn't + foolproof. In fact, it will fail if you create a new C object in Perl, + pass it on to a C function that remembers the object, and then destroy + the corresponding Perl object (this situation turns out to come up + frequently when constructing objects like linked lists and trees). When + C takes possession of an object, you can change Perl's ownership by + simply deleting the object from the %OWNER hash. This is done + using the DISOWN method.

      +
      +
      +# Perl code to change ownership of an object
+$v = new Vector(x,y,z);
+$v->DISOWN();     
+
      +
      +

      To acquire ownership of an object, the ACQUIRE method can + be used.

      +
      +
      +# Given Perl ownership of a file
+$u = Vector_get($v);
+$u->ACQUIRE();
+
+
      +
      +

      As always, a little care is in order. SWIG does not provide + reference counting, garbage collection, or advanced features one might + find in sophisticated languages.

      +

      28.9.4 Nested Objects

      +

      Suppose that we have a new object that looks like this :

      +
      +
      +struct Particle {
+	Vector r;
+	Vector v;
+	Vector f;
+	int	type;
+}
+
+
      +
      +

      In this case, the members of the structure are complex objects that + have already been encapsulated in a Perl proxy class. To handle these + correctly, we use the %BLESSEDMEMBERS hash which would look + like this (along with some supporting code) :

      +
      +
      +package Particle;
+...
+%BLESSEDMEMBERS = (
+	r => `Vector',
+	v => `Vector',
+	f => `Vector',
+);
+
+
      +
      +

      When fetching members from the structure, %BLESSEDMEMBERS + is checked. If the requested field is present, we create a tied-hash + table and return it. If not, we just return the corresponding member + unmodified.

      +

      This implementation allows us to operate on nested structures as + follows :

      +
      +
      +# Perl access of nested structure
+$p = new Particle();
+$p->{f}->{x} = 0.0;
+%${$p->{v}} = ( x=>0, y=>0, z=>0);         
+
      +
      +

      28.9.5 Proxy Functions

      +

      When functions take arguments involving a complex object, it is + sometimes necessary to write a proxy function. For example :

      +
      +
      +double dot_product(Vector *v1, Vector *v2);
+
      +
      +

      Since Vector is an object already wrapped into a proxy class, we + need to modify this function to accept arguments that are given in the + form of tied hash tables. This is done by creating a Perl function like + this :

      +
      +
      +sub dot_product {
+    my @args = @_;
+    $args[0] = tied(%{$args[0]});         # Get the real pointer values
+    $args[1] = tied(%{$args[1]});
+    my $result = vectorc::dot_product(@args);
+    return $result;
+}
+
      +
      +

      This function replaces the original function, but operates in an + identical manner.

      +

      28.9.6 Inheritance

      +

      Simple C++ inheritance is handled using the Perl @ISA array + in each class package. For example, if you have the following interface + file :

      +
      +
      +// shapes.i
+// SWIG interface file for shapes class
+%module shapes
+%{
+#include "shapes.h"
+%}
+
+class Shape {
+public:
+	virtual double area() = 0;
+	virtual double perimeter() = 0;
+	void    set_location(double x, double y);
+};
+class Circle : public Shape {
+public:
+	Circle(double radius);
+	~Circle();
+	double area();
+	double perimeter();
+};
+class Square : public Shape {
+public:
+	Square(double size);
+	~Square();
+	double area();
+	double perimeter();
+}
+
+
      +
      +

      The resulting, Perl wrapper class will create the following code :

      +
      +
      +Package Shape;
+@ISA = (shapes);
+...
+Package Circle;
+@ISA = (shapes Shape);
+...
+Package Square;
+@ISA = (shapes Shape);
+
+
      +
      +

      The @ISA array determines where to look for methods of a + particular class. In this case, both the Circle and Square + classes inherit functions from Shape so we'll want to look in + the Shape base class for them. All classes also inherit from + the top-level module shapes. This is because certain common + operations needed to implement proxy classes are implemented only once + and reused in the wrapper code for various classes and structures.

      +

      Since SWIG proxy classes are implemented in Perl, it is easy to + subclass from any SWIG generated class. To do this, simply put the name + of a SWIG class in the @ISA array for your new class. However, + be forewarned that this is not a trivial problem. In particular, + inheritance of data members is extremely tricky (and I'm not even sure + if it really works).

      +

      28.9.7 Modifying the proxy methods

      +

      It is possible to override the SWIG generated proxy/shadow methods, + using %feature("shadow"). It works like all the other +%feature directives. Here is a simple example showing how to add + some Perl debug code to the constructor:

      +
      +
      +/* Let's make the constructor of the class Square more verbose */
+%feature("shadow") Square(double w)
+%{
+  sub new {
+    my $pkg = shift;
+    my $self = examplec::new_Square(@_);
+    print STDERR "Constructed an @{[ref($self)]}\n";
+    bless $self, $pkg if defined($self);
+  }
+%}
+
+class Square {
+public:
+  Square(double w);
+  ...
+};
+
      +
      +

      28.10 Adding additional Perl code

      +

      If writing support code in C isn't enough, it is also possible to + write code in Perl. This code gets inserted in to the .pm file + created by SWIG. One use of Perl code might be to supply a high-level + interface to certain functions. For example:

      +
      +
      +void set_transform(Image *im, double x[4][4]);
+
+...
+/* Rewrite the high level interface to set_transform */
+%perlcode %{
+sub set_transform
+{
+  my ($im, $x) = @_;
+  my $a = new_mat44();
+  for (my $i = 0; $i < 4, $i++)
+  {
+    for (my $j = 0; $j < 4, $j++)
+    {
+      mat44_set($a, $i, $j, $x->[i][j])
+      }
+  }
+  example.set_transform($im, $a);
+  free_mat44($a);
+}
+%}
+
      +
      +

      In this example, set_transform() provides a high-level Perl + interface built on top of low-level helper functions. For example, this + code now seems to work:

      +
      +
      +my $a =
+  [[1,0,0,0],
+   [0,1,0,0],
+   [0,0,1,0],
+   [0,0,0,1]];
+set_transform($im, $a);
+
      +
      + + +

      29 SWIG and PHP

      + + +
      + +
      + +

      SWIG supports generating wrappers for PHP5. Support for PHP4 has + been removed as of SWIG 1.3.37. The PHP developers are no longer making + new PHP4 releases, and won't even be patching critical security issues + after 2008-08-08, so it doesn't make much sense for SWIG to continue to + support PHP4 at this point. If you need to continue to use PHP4, stick + with SWIG 1.3.36.

      +

      In this chapter, we discuss SWIG's support of PHP. The PHP module + was extensively rewritten in release 1.3.26, and support for generating + OO wrappers for PHP5 was added in 1.3.30. The PHP module works fairly + well, but currently does not implement all the features available in + some of the other languages.

      +

      In order to use this module, you will need to have a copy of the + PHP5 include files to compile the SWIG generated files. If you + installed PHP from a binary package, you may need to install a + "php-dev" or "php-devel" package for these to be installed. You can + find out where these files are by running php-config --includes +. To use the built PHP module you will need either the php binary or the + Apache php module. If you want to build your extension into php + directly, you will need the complete PHP source tree available.

      +

      29.1 Generating PHP Extensions

      +

      To build a PHP extension, run swig using the -php option as + follows:

      +
      +
      +swig -php example.i
+
      +
      +

      This will produce 3 files example_wrap.c, php_example.h and + example.php. The first file, example_wrap.c contains all of + the C code needed to build a PHP extension. The second file, +php_example.h contains the header information needed if you wish to + statically link the extension into the php interpreter. The third file, + example.php 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 PHP5 class wrappers.

      +

      Swig can generate PHP extensions from C++ libraries as well when + given the -c++ option. The support for C++ is discussed in + more detail in section 27.2.6.

      +

      The usual (and recommended) way is to build the extension as a + separate dynamically loaded module (which is supported by all modern + operating systems). You can then specify that this be loaded + automatically in php.ini or load it explicitly for any script + which needs it.

      +

      It is also possible to rebuild PHP from source so that your module + is statically linked into the php executable/library. This is a lot + more work, and also requires a full rebuild of PHP to update your + module, and it doesn't play nicely with package system. We don't + recommend this approach, or provide explicit support for it.

      +

      29.1.1 Building a loadable extension

      +

      To build your module as a dynamically loadable extension, use + compilation commands like these (if you aren't using GCC, the commands + will be different, and there may be some variation between platforms - + these commands should at least work for Linux though):

      +
      +
      +	gcc `php-config --includes` -fpic -c example_wrap.c
+	gcc -shared example_wrap.o -o example.so
+
      +
      +

      29.1.2 Using PHP Extensions

      +

      To test the extension from a PHP script, you need to load it first. + You can load it for every script by adding this line the [PHP] + section of php.ini:

      +
      +
      +	extension=/path/to/modulename.so
+
      +
      +

      Alternatively, you can load it explicitly only for scripts which + need it by adding this line:

      +
      +
      +	dl("/path/to/modulename.so");	// Load the module
+
      +
      +

      to the start of each PHP file. SWIG also generates a php module, + which attempts to do the dl() call for you:

      +
      +
      +	include("example.php");
+
      +
      +

      29.2 Basic PHP interface

      +

      It is important to understand that PHP uses a single global + namespace into which all symbols from extension modules are loaded. It + is quite possible for names of symbols in one extension module to clash + with other symbols unless care is taken to %rename them.

      +

      29.2.1 Constants

      +

      These work in much the same way as in C/C++, constants can be + defined by using either the normal C pre-processor declarations, or the + %constant SWIG directive. These will then be available from + your PHP script as a PHP constant, (i.e. no dollar sign is needed to + access them.) For example, with a swig interface file like this,

      +
      +
      +%module example
+
+#define PI 3.14159
+
+%constant int E  = 2.71828
+
      +
      +

      you can access the constants in your php script like this,

      +
      +
      +include("example.php");
+
+echo "PI = " . PI . "\n";
+
+echo "E = " . E . "\n";
+
+
      +
      +

      There are two peculiarities with using constants in PHP. The first + is that if you try to use an undeclared constant, it will evaluate to a + string set to the constant's name. For example,

      +
      +
      +%module example
+
+#define EASY_TO_MISPELL	0
+
      +
      +

      accessed incorrectly in PHP,

      +
      +
      +include("example.php");
+
+if(EASY_TO_MISPEL) {
+	....
+} else {
+	....
+}
+
+
      +
      +

      will issue a warning about the undeclared constant, but will then + evaluate it and turn it into a string ('EASY_TO_MISPEL'), which + evaluates to true, rather than the value of the constant which would be + false. This is a feature!

      +

      The second 'feature' is that although constants are case sensitive + (by default), you cannot declare a constant twice with alternative + cases. E.g.,

      +
      +
      +%module example
+
+#define TEST	Hello
+#define Test	World
+
      +
      +

      accessed from PHP,

      +
      +
      +include("example.php");
+
+echo TEST, Test;
+
      +
      +

      will output "Hello Test" rather than "Hello World". This is because + internally, all constants are stored in a hash table by their lower + case name, so 'TEST' and 'Test' will map to the same hash element + ('Test'). But, because we declared them case sensitive, the Zend engine + will test if the case matches with the case the constant was declared + with first.

      +

      So, in the example above, the TEST constant was declared first, and + will be stored under the hash element 'test'. The 'Test' constant will + also map to the same hash element 'test', but will not overwrite it. + When called from the script, the TEST constant will again be mapped to + the hash element 'test' so the constant will be retrieved. The case + will then be checked, and will match up, so the value ('Hello') will be + returned. When 'Test' is evaluated, it will also map to the same hash + element 'test'. The same constant will be retrieved, this time though + the case check will fail as 'Test' != 'TEST'. So PHP will assume that + Test is a undeclared constant, and as explained above, will return it + as a string set to the constant name ('Test'). Hence the script above + will print 'Hello Test'. If they were declared non-case sensitive, the + output would be 'Hello Hello', as both point to the same value, without + the case test taking place. ( Apologies, this paragraph needs rewriting + to make some sense. )

      +

      29.2.2 Global Variables

      +

      Because PHP does not provide a mechanism to intercept access and + assignment of global variables, global variables are supported through + the use of automatically generated accessor functions.

      +
      +
      +%module example;
+
+%inline %{
+  double seki = 2;
+  void print_seki() {
+    zend_printf("seki is now %f\n",seki);
+  }
+%}
+
      +
      +

      is accessed as follows:

      +
      +
      +include("example.php");
+print seki_get();
+seki_set( seki_get() * 2);	# The C variable is now 4.
+print seki_get();
+
      +
      +

      SWIG supports global variables of all C datatypes including pointers + and complex objects. Additional types can be supported by using the +varinit typemap.

      +

      SWIG honors the %immutable modifier by not generating code + for the _set method. This provides read-only access to the + variable from the php script. Attempting to access the _set + method will result in a php fatal error because the function is + undefined.

      +

      At this time SWIG does not support custom accessor methods.

      +

      29.2.3 Functions

      +

      C functions are converted into PHP functions. Default/optional + arguments are also allowed. An interface file like this :

      +
      +
      +%module example
+int foo(int a);
+double bar(double, double b = 3.0);
+...
+
      +
      +

      Will be accessed in PHP like this :

      +
      +
      +include("example.php");
+$a = foo(2);
+$b = bar(3.5, -1.5);
+$c = bar(3.5);		# Use default argument for 2nd parameter
+
+
      +
      + +

      29.2.4 Overloading

      +

      Although PHP does not support overloading functions natively, swig + will generate dispatch functions which will use %typecheck + typemaps to allow overloading. This dispatch function's operation and + precedence is described in +Wrapping Overloaded Functions and Methods.

      + + +

      29.2.5 Pointers and References

      +

      Pointers to C/C++ objects are represented as PHP resources, rather + like MySQL connection handles.

      +

      There are multiple ways to wrap pointers to simple types. Given the + following C method:

      +
      +
      +  void add( int *in1, int *in2, int *result);
+
      +
      +

      One can include cpointer.i to generate PHP wrappers to +int *.

      +
      +
      +%module example
+%include "cpointer.i"
+%pointer_functions(int,intp)
+
+void add( int *in1, int *in2, int *result);
+
      +
      +

      This will result in the following usage in PHP:

      +
      +
      +<?php
+
+include("example.php");
+
+$in1=copy_intp(3);
+$in2=copy_intp(5);
+$result=new_intp();
+
+add( $in1, $in2, $result );
+
+echo "The sum " . intp_value($in1) . " + " . intp_value($in2) . " = " . intp_value( $result) . "\n";
+?>
+
      +
      +

      An alternative would be to use the include typemaps.i which + defines named typemaps for INPUT, OUTPUT and INOUT variables. One needs + to either %apply the appropriate typemap or adjust the + parameter names as appropriate.

      +
      +
      +%module example
+%include "typemaps.i"
+
+void add( int *INPUT, int *INPUT, int *OUTPUT);
+
+
      +
      +

      This will result in the following usage in PHP:

      +
      +
      +<?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";
+?>
+
      +
      +

      Because PHP has a native concept of reference, it may seem more + natural to the PHP developer to use references to pass pointers. To + enable this, one needs to include phppointers.i which defines + the named typemap REFERENCE.

      +
      +
      +%module example
+%include "phppointers.i"
+
+void add( int *REF, int *REF, int *REF);
+
+
      +
      +

      This will result in the following usage in PHP:

      +
      +
      +<?php
+
+include("example.php");
+
+$in1 = 3;
+$in2 = 5;
+$result = 0;
+add(&$in1,&$in2,&$result);
+
+echo "The sum $in1 + $in2 = $result\n";
+?>
+
      +
      +

      It is important to note that a php variable which is NULL when + passed by reference would end up passing a NULL pointer into the + function. In PHP, an unassigned variable (i.e. where the first + reference to the variable is not an assignment) is NULL. In the above + example, if any of the three variables had not been assigned, a NULL + pointer would have been passed into add. Depending on the + implementation of the function, this may or may not be a good thing.

      +

      We chose to allow passing NULL pointers into functions because that + is sometimes required in C libraries. A NULL pointer can be created in + PHP in a number of ways: by using unset on an existing + variable, or assigning NULL to a variable.

      +

      29.2.6 Structures and C++ classes

      +

      SWIG defaults to wrapping C++ structs and classes with PHP classes + unless "-noproxy" is specified. For PHP5, a PHP wrapper class is + generated which calls a set of flat functions wrapping the C++ class.

      +

      This interface file

      +
      +
      +%module vector
+
+class Vector {
+public:
+	double x,y,z;
+	Vector();
+	~Vector();
+	double magnitude();
+};
+
+struct Complex {
+ double re, im;
+};
+
      +
      +

      Would be used in the following way from PHP5:

      +
      +
      +<?php
+  require "vector.php";
+
+  $v = new Vector();
+  $v->x = 3;
+  $v->y = 4;
+  $v->z = 5;
+
+  echo "Magnitude of ($v->x,$v->y,$v->z) = " . $v->magnitude() . "\n";
+
+  $v = NULL;   # destructor called.
+
+  $c = new Complex();
+
+  $c->re = 0;
+  $c->im = 0;
+
+  # $c destructor called when $c goes out of scope.
+?>
+
      +
      +

      Member variables and methods are accessed using the -> + operator.

      +

      29.2.6.1 Using -noproxy

      +

      The -noproxy option flattens the object structure and + generates collections of named functions (these are the functions which + the PHP5 class wrappers call). The above example results in the + following PHP functions:

      +
      +
      +new_Vector();
+Vector_x_set($obj,$d);
+Vector_x_get($obj);
+Vector_y_set($obj,$d);
+Vector_y_get($obj);
+Vector_z_set($obj,$d);
+Vector_z_get($obj);
+Vector_magnitude($obj);
+new_Complex();
+Complex_re_set($obj,$d);
+Complex_re_get($obj);
+Complex_im_set($obj,$d);
+Complex_im_get($obj);
+
      +
      +

      29.2.6.2 Constructors and Destructors

      +

      The constructor is called when new Object() (or +new_Object() if using -noproxy) is used to create an + instance of the object. If multiple constructors are defined for an + object, function overloading will be used to determine which + constructor to execute.

      +

      Because PHP uses reference counting to manage resources, simple + assignment of one variable to another such as:

      +
      +
      +$ref = $v;
+
      +
      +

      causes the symbol $ref to refer to the same underlying + object as $v. This does not result in a call to the C++ copy + constructor or copy assignment operator.

      +

      One can force execution of the copy constructor by using:

      +
      +
      +$o_copy = new Object($o);
+
      +
      +

      Destructors are automatically called when all variables referencing + the instance are reassigned or go out of scope. The destructor is not + available to be called manually. To force a destructor to be called the + programmer can either reassign the variable or call unset($v)

      +

      29.2.6.3 Static Member Variables

      +

      Static member variables in C++ are not wrapped as such in PHP as it + does not appear to be possible to intercept accesses to such variables. + Therefore, static member variables are wrapped using a class function + with the same name, which returns the current value of the class + variable. For example

      +
      +
      +%module example
+
+class Ko {
+	static int threats;
+};
+
+
      +
      +

      would be accessed in PHP as,

      +
      +
      +include("example.php");
+
+echo "There has now been " . Ko::threats() . " threats\n";
+
+
      +
      +

      To set the static member variable, pass the value as the argument to + the class function, e.g.

      +
      +
      +
+Ko::threats(10);
+
+echo "There has now been " . Ko::threats() . " threats\n";
+
+
      +
      +

      29.2.6.4 Static Member Functions

      +

      Static member functions are supported in PHP using the +class::function() syntax. For example

      +
      +
      +%module example
+class Ko {
+  static void threats();
+};
+
      +
      would be executed in PHP as,
      +
      +include("example.php");
+Ko::threats();
+
      +
      +

      29.2.7 PHP Pragmas, Startup and Shutdown + code

      +

      To place PHP code in the generated "example.php" file one can use + the code pragma. The code is inserted after loading the shared + object.

      +
      +
      +%module example
+%pragma(php) code="
+# This code is inserted into example.php
+echo \"example.php execution\\n\";
+"
+
      +
      +

      Results in the following in "example.php"

      +
      +
      +# This code is inserted into example.php
+echo "example.php execution\n";
+
      +
      +

      The include pragma is a short cut to add include statements + to the example.php file.

      +
      +
      +%module example
+%pragma(php) code="
+include \"include.php\";
+"
+%pragma(php) include="include.php"   // equivalent.
+
      +
      +

      The phpinfo pragma inserts code in the PHP_MINFO_FUNCTION + which is called from PHP's phpinfo() function.

      +
      +
      +%module example;
+%pragma(php) phpinfo="
+  zend_printf("An example of PHP support through SWIG\n");
+  php_info_print_table_start();
+  php_info_print_table_header(2, \"Directive\", \"Value\");
+  php_info_print_table_row(2, \"Example support\", \"enabled\");
+  php_info_print_table_end();
+"
+
      +
      +

      To insert code into the PHP_MINIT_FUNCTION, one can use + either %init or %minit.

      +
      +
      +%module example;
+%init {
+  zend_printf("Inserted into PHP_MINIT_FUNCTION\n");
+}
+%minit {
+  zend_printf("Inserted into PHP_MINIT_FUNCTION\n");
+}
+
      +
      +

      To insert code into the PHP_MSHUTDOWN_FUNCTION, one can use + either %init or %minit.

      +
      +
      +%module example;
+%mshutdown {
+  zend_printf("Inserted into PHP_MSHUTDOWN_FUNCTION\n");
+}
+
      +
      +

      The %rinit and %rshutdown statements insert code + into the request init and shutdown code respectively.

      +

      29.3 Cross language polymorphism

      +

      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.

      +

      This arrangement is asymmetric in the sense that no corresponding + mechanism exists to pass method calls down the inheritance chain from + C++ to PHP. In particular, if a C++ class has been extended in PHP (by + extending the proxy class), these extensions will not be visible from + C++ code. Virtual method calls from C++ are thus not able access the + lowest implementation in the inheritance chain.

      +

      Changes have been made to SWIG 1.3.18 to address this problem and + make the relationship between C++ classes and proxy classes more + symmetric. To achieve this goal, new classes called directors are + introduced at the bottom of the C++ inheritance chain. Support for + generating PHP classes has been added in SWIG 1.3.40. The job of the + directors is to route method calls correctly, either to C++ + implementations higher in the inheritance chain or to PHP + implementations lower in the inheritance chain. The upshot is that C++ + classes can be extended in PHP and from C++ these extensions look + exactly like native C++ classes. Neither C++ code nor PHP code needs to + know where a particular method is implemented: the combination of proxy + classes, director classes, and C wrapper functions takes care of all + the cross-language method routing transparently.

      +

      29.3.1 Enabling directors

      +

      The director feature is disabled by default. To use directors you + must make two changes to the interface file. First, add the "directors" + option to the %module directive, like this:

      +
      +
      +%module(directors="1") modulename
+
      +
      +

      Without this option no director code will be generated. Second, you + must use the %feature("director") directive to tell SWIG which classes + and methods should get directors. The %feature directive can be applied + globally, to specific classes, and to specific methods, like this:

      +
      +
      +// generate directors for all classes that have virtual methods
+%feature("director");         
+
+// generate directors for all virtual methods in class Foo
+%feature("director") Foo;      
+
+// generate a director for just Foo::bar()
+%feature("director") Foo::bar; 
+
      +
      +

      You can use the %feature("nodirector") directive to turn off + directors for specific classes or methods. So for example,

      +
      +
      +%feature("director") Foo;
+%feature("nodirector") Foo::bar;
+
      +
      +

      will generate directors for all virtual methods of class Foo except + bar().

      +

      Directors can also be generated implicitly through inheritance. In + the following, class Bar will get a director class that handles the + methods one() and two() (but not three()):

      +
      +
      +%feature("director") Foo;
+class Foo {
+public:
+    Foo(int foo);
+    virtual void one();
+    virtual void two();
+};
+
+class Bar: public Foo {
+public:
+    virtual void three();
+};
+
      +
      +

      then at the PHP side you can define

      +
      +
      +require("mymodule.php");
+
+class MyFoo extends Foo {
+  function one() {
+     print "one from php\n";
+  }
+}
+
      +
      +

      29.3.2 Director classes

      +

      For each class that has directors enabled, SWIG generates a new + class that derives from both the class in question and a special +Swig::Director 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.

      +

      For simplicity let's ignore the Swig::Director class and + refer to the original C++ class as the director's base class. By + default, a director class extends all virtual methods in the + inheritance chain of its base class (see the preceding section for how + to modify this behavior). Thus all virtual method calls, whether they + originate in C++ or in PHP via proxy classes, eventually end up in at + the implementation in the director class. The job of the director + methods is to route these method calls to the appropriate place in the + inheritance chain. By "appropriate place" we mean the method that would + have been called if the C++ base class and its extensions in PHP were + seamlessly integrated. That seamless integration is exactly what the + director classes provide, transparently skipping over all the messy + extension API glue that binds the two languages together.

      +

      In reality, the "appropriate place" is one of only two + possibilities: C++ or PHP. Once this decision is made, the rest is + fairly easy. If the correct implementation is in C++, then the lowest + implementation of the method in the C++ inheritance chain is called + explicitly. If the correct implementation is in PHP, the Zend API is + used to call the method of the underlying PHP object (after which the + usual virtual method resolution in PHP automatically finds the right + implementation).

      +

      Now how does the director decide which language should handle the + method call? The basic rule is to handle the method in PHP, unless + there's a good reason not to. The reason for this is simple: PHP has + the most "extended" implementation of the method. This assertion is + guaranteed, since at a minimum the PHP proxy class implements the + method. If the method in question has been extended by a class derived + from the proxy class, that extended implementation will execute exactly + as it should. If not, the proxy class will route the method call into a + C wrapper function, expecting that the method will be resolved in C++. + The wrapper will call the virtual method of the C++ instance, and since + the director extends this the call will end up right back in the + director method. Now comes the "good reason not to" part. If the + director method were to blindly call the PHP method again, it would get + stuck in an infinite loop. We avoid this situation by adding special + code to the C wrapper function that tells the director method to not do + this. The C wrapper function compares the called and the declaring + class name of the given method. If these are not the same, then the C + wrapper function tells the director to resolve the method by calling up + the C++ inheritance chain, preventing an infinite loop.

      +

      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 ->_cPtr. This is exactly what happens without + directors and is true even if directors are enabled for the particular + class in question. When a class derived 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 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++ + so there is no need for the extra overhead involved with routing the + calls through PHP.

      +

      29.3.3 Ownership and object destruction

      +

      Memory management issues are slightly more complicated with + directors than for proxy classes alone. PHP instances hold a pointer to + the associated C++ director object, and the director in turn holds a + pointer back to the PHP object. By default, proxy classes own their C++ + director object and take care of deleting it when they are garbage + collected.

      +

      This relationship can be reversed by calling the special +->thisown property of the proxy class. After setting this property + to 0, the director class no longer destroys the PHP object. + Assuming no outstanding references to the PHP object remain, the PHP + object will be destroyed at the same time. This is a good thing, since + directors and proxies refer to each other and so must be created and + destroyed together. Destroying one without destroying the other will + likely cause your program to segfault.

      +

      Here is an example:

      +
      +
      +class Foo {
+public:
+    ...
+};
+class FooContainer {
+public:
+    void addFoo(Foo *);
+    ...
+};
+
      +
      +
      +
      +$c = new FooContainer();
+$a = new Foo();
+$a->thisown = 0;
+$c->addFoo($a);
+
      +
      +

      In this example, we are assuming that FooContainer will take care of + deleting all the Foo pointers it contains at some point.

      +

      29.3.4 Exception unrolling

      +

      With directors routing method calls to PHP, and proxies routing them + to C++, the handling of exceptions is an important concern. By default, + the directors ignore exceptions that occur during method calls that are + resolved in PHP. To handle such exceptions correctly, it is necessary + to temporarily translate them into C++ exceptions. This can be done + with the %feature("director:except") directive. The following code + should suffice in most cases:

      +
      +
      +%feature("director:except") {
+    if ($error == FAILURE) {
+        throw Swig::DirectorMethodException();
+    }
+}
+
      +
      +

      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. + Currently no information about the PHP error is stored in the + Swig::DirectorMethodException object, but this will likely change in + the future.

      +

      It may be the case that a method call originates in PHP, travels up + to C++ through a proxy class, and then back into PHP via a director + method. If an exception occurs in PHP at this point, it would be nice + for that exception to find its way back to the original caller. This + can be done by combining a normal %exception directive with the +director:except handler shown above. Here is an example of a + suitable exception handler:

      +
      +
      +%exception {
+    try { $action }
+    catch (Swig::DirectorException &e) { SWIG_fail; }
+}
+
      +
      +

      The class Swig::DirectorException used in this example is actually a + base class of Swig::DirectorMethodException, so it will trap this + exception. Because the PHP error state is still set when + Swig::DirectorMethodException is thrown, PHP will register the + exception as soon as the C wrapper function returns.

      +

      29.3.5 Overhead and code bloat

      +

      Enabling directors for a class will generate a new director method + for every virtual method in the class' inheritance chain. This alone + can generate a lot of code bloat for large hierarchies. Method + arguments that require complex conversions to and from target language + types can result in large director methods. For this reason it is + recommended that you selectively enable directors only for specific + classes that are likely to be extended in PHP and used in C++.

      +

      Compared to classes that do not use directors, the call routing in + the director methods does add some overhead. In particular, at least + one dynamic cast and one extra function call occurs per method call + from PHP. Relative to the speed of PHP execution this is probably + completely negligible. For worst case routing, a method call that + ultimately resolves in C++ may take one extra detour through PHP in + order to ensure that the method does not have an extended PHP + implementation. This could result in a noticeable overhead in some + cases.

      +

      Although directors make it natural to mix native C++ objects with + PHP objects (as director objects) via a common base class pointer, one + should be aware of the obvious fact that method calls to PHP objects + will be much slower than calls to C++ objects. This situation can be + optimized by selectively enabling director methods (using the %feature + directive) for only those methods that are likely to be extended in + PHP.

      +

      29.3.6 Typemaps

      +

      Typemaps for input and output of most of the basic types from + director classes have been written. These are roughly the reverse of + the usual input and output typemaps used by the wrapper code. The + typemap operation names are 'directorin', 'directorout', and + 'directorargout'. The director code does not currently use any of the + other kinds of typemaps. It is not clear at this point which kinds are + appropriate and need to be supported.

      +

      29.3.7 Miscellaneous

      +

      Director typemaps for STL classes are mostly in place, and hence you + should be able to use std::string, etc., as you would any other type.

      +
      +

      30 SWIG and Pike

      + + +
      + +
      + +

      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.

      +

      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 "SWIG Basics" + chapter. +

      +

      30.1 Preliminaries

      +

      30.1.1 Running SWIG

      +

      Suppose that you defined a SWIG module such as the following:

      +
      +
      %module example
+
      
+
      %{
+
      #include "example.h"
+
      %}
+
      
+
      int fact(int n);
+
      +
      +

      To build a C extension module for Pike, run SWIG using the -pike + option :

      +
      +
      $ swig -pike example.i
+
      +
      +

      If you're building a C++ extension, be sure to add the -c++ + option:

      +
      +
      $ swig -c++ -pike example.i
+
      +
      +

      This creates a single source file named example_wrap.c (or +example_wrap.cxx, if you ran SWIG with the -c++ 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.

      +

      The name of the wrapper file is derived from the name of the input + file. For example, if the input file is example.i, the name of + the wrapper file is example_wrap.c. To change this, you can + use the -o option:

      +
      +
      $ swig -pike -o pseudonym.c example.i
+
      +
      +

      30.1.2 Getting the right header files

      +

      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

      +
      +
      /usr/local/pike/7.4.10/include/pike
+
      +
      +

      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 global.h, +program.h and so on.

      +

      30.1.3 Using your module

      +

      To use your module, simply use Pike's import statement:

      +
      +
      +$ pike
+Pike v7.4 release 10 running Hilfe v3.5 (Incremental Pike Frontend)
+> import example;
+> fact(4);
+(1) Result: 24
+
      +
      +

      30.2 Basic C/C++ Mapping

      +

      30.2.1 Modules

      +

      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 %module directive doesn't really have any + significance.

      +

      30.2.2 Functions

      +

      Global functions are wrapped as new Pike built-in functions. For + example,

      +
      +
      +%module example
+
+int fact(int n);
+
      +
      +

      creates a new built-in function example.fact(n) that works + exactly as you'd expect it to:

      +
      +
      +> import example;
+> fact(4);
+(1) Result: 24
+
      +
      +

      30.2.3 Global variables

      +

      Global variables are currently wrapped as a pair of of functions, + one to get the current value of the variable and another to set it. For + example, the declaration

      +
      +
      +%module example
+
+double Foo;
+
      +
      +

      will result in two functions, Foo_get() and Foo_set() +:

      +
      +
      +> import example;
+> Foo_get();
+(1) Result: 3.000000
+> Foo_set(3.14159);
+(2) Result: 0
+> Foo_get();
+(3) Result: 3.141590
+
      +
      +

      30.2.4 Constants and enumerated types

      +

      Enumerated types in C/C++ declarations are wrapped as Pike + constants, not as Pike enums.

      +

      30.2.5 Constructors and Destructors

      +

      Constructors are wrapped as create() methods, and + destructors are wrapped as destroy() methods, for Pike + classes.

      +

      30.2.6 Static Members

      +

      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:

      +
      +
      +class Shape
+{
+public:
+    static void print();
+    static int nshapes;
+};
+
      +
      +

      SWIG will generate a Shape_print() method that invokes the + static Shape::print() member function, as well as a pair of + methods, Shape_nshapes_get() and Shape_nshapes_set(), + to get and set the value of Shape::nshapes.

      +
      +

      31 SWIG and Python

      + + +
      + +
      + +

      Caution: This chapter is under repair!

      +

      This chapter describes SWIG's support of Python. SWIG is compatible + with most recent Python versions including Python 3.0 and Python 2.6, + as well as older versions dating back to Python 2.0. For the best + results, consider using Python 2.3 or newer.

      +

      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 "SWIG Basics" + chapter.

      +

      31.1 Overview

      +

      To build Python extension modules, SWIG uses a layered approach in + which parts of the extension module are defined in C and other parts + are defined in Python. The C layer contains low-level wrappers whereas + Python code is used to define high-level features.

      +

      This layered approach recognizes the fact that certain aspects of + extension building are better accomplished in each language (instead of + trying to do everything in C or C++). Furthermore, by generating code + in both languages, you get a lot more flexibility since you can enhance + the extension module with support code in either language.

      +

      In describing the Python interface, this chapter starts by covering + the basics of configuration, compiling, and installing Python modules. + Next, the Python interface to common C and C++ programming features is + described. Advanced customization features such as typemaps are then + described followed by a discussion of low-level implementation details.

      +

      31.2 Preliminaries

      +

      31.2.1 Running SWIG

      +

      Suppose that you defined a SWIG module such as the following:

      +
      +
      +/* File: example.i */
+%module example
+
+%{
+#define SWIG_FILE_WITH_INIT
+#include "example.h"
+%}
+
+int fact(int n);
+
      +
      +

      The #define SWIG_FILE_WITH_INIT line inserts a macro that + specifies that the resulting C file should be built as a python + extension, inserting the module init code. This .i + file wraps the following simple C file:

      +
      +
      +/* File: example.c */
+
+#include "example.h"
+
+int fact(int n) {
+    if (n < 0){ /* This should probably return an error, but this is simpler */
+        return 0;
+    }
+    if (n == 0) {
+        return 1;
+    }
+    else {
+        /* testing for overflow would be a good idea here */
+        return n * fact(n-1);
+    }
+}
+
+
      +
      +

      With the header file:

      +
      +
      +/* File: example.h */
+
+int fact(int n);
+
      +
      +

      To build a Python module, run SWIG using the -python + option:

      +
      +
      +$ swig -python example.i
+
      +
      +

      If building a C++ extension, add the -c++ option:

      +
      +
      +$ swig -c++ -python example.i
+
      +
      +

      This creates two different files; a C/C++ source file +example_wrap.c or example_wrap.cxx and a Python source + file example.py. The generated C 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. The Python source + file contains high-level support code. This is the file that you will + import to use the module.

      +

      The name of the wrapper file is derived from the name of the input + file. For example, if the input file is example.i, the name of + the wrapper file is example_wrap.c. To change this, you can + use the -o option. The name of the Python file is derived from + the module name specified with %module. If the module name is +example, then a file example.py is created.

      +

      The following sections have further practical examples and details + on how you might go about compiling and using the generated files.

      +

      31.2.2 Using distutils

      +

      The preferred approach to building an extension module for python is + to compile it with distutils, which comes with all recent versions of + python (Distutils Docs +).

      +

      Distutils takes care of making sure that your extension is built + with all the correct flags, headers, etc. for the version of Python it + is run with. Distutils will compile your extension into a shared object + file or DLL (.so on Linux, .pyd on Windows, etc). In + addition, distutils can handle installing your package into + site-packages, if that is desired. A configuration file (conventionally + called: setup.py) describes the extension (and related python + modules). The distutils will then generate all the right compiler + directives to build it for you.

      +

      Here is a sample setup.py file for the above example:

      +
      +
      +#!/usr/bin/env python
+
+"""
+setup.py file for SWIG example
+"""
+
+from distutils.core import setup, Extension
+
+
+example_module = Extension('_example',
+                           sources=['example_wrap.c', 'example.c'],
+                           )
+
+setup (name = 'example',
+       version = '0.1',
+       author      = "SWIG Docs",
+       description = """Simple swig example from docs""",
+       ext_modules = [example_module],
+       py_modules = ["example"],
+       )
+
      +
      +

      In this example, the line: example_module = Extension(....) + creates an Extension module object, defining the name as _example +, and using the source code files: example_wrap.c, generated by + swig, and example.c, your original c source. The swig (and + other python extension modules) tradition is for the compiled extension + to have the name of the python portion, prefixed by an underscore. If + the name of your python module is "example.py", then the name + of the corresponding object file will be"_example.so"

      +

      The setup call then sets up distutils to build your + package, defining some meta data, and passing in your extension module + object. Once this is saved as setup.py, you can build your + extension with these commands:

      +
      +
      +$ swig -python example.i
+$ python setup.py build_ext --inplace
+
      +
      +

      And a .so, or .pyd or... will be created for you. It will build a + version that matches the python that you run the command with. Taking + apart the command line:

      +
        +
      • python -- the version of python you want to build for
        • +
      • setup.py -- the name of your setup script (it can be + called anything, but setup.py is the tradition)
        • +
      • build_ext -- telling distutils to build extensions
        • +
      • --inplace -- this tells distutils to put the extension lib + in the current dir. Otherwise, it will put it inside a build hierarchy, + and you'd have to move it to use it.
        • +
      +

      The distutils have many other features, consult the python distutils + docs for details.

      +

      This same approach works on all platforms if the appropriate + compiler is installed. (it can even build extensions to the standard + Windows Python using MingGW)

      +

      31.2.3 Hand compiling a dynamic module

      +

      While the preferred approach to building an extension module is to + use the distutils, some people like to integrate building extensions + with a larger build system, and thus may wish to compile their modules + without the distutils. To do this, you need to compile your program + using commands like this (shown for Linux):

      +
      +
      +$ swig -python example.i
+$ gcc -O2 -fPIC -c example.c
+$ gcc -O2 -fPIC -c example_wrap.c -I/usr/local/include/python2.5
+$ gcc -shared example.o example_wrap.o -o _example.so
+
      +
      +

      The exact commands for doing this vary from platform to platform. + However, SWIG tries to guess the right options when it is installed. + Therefore, you may want to start with one of the examples in the +SWIG/Examples/python directory. If that doesn't work, you will need + to read the man-pages for your compiler and linker to get the right set + of options. You might also check the +SWIG Wiki for additional information.

      +

      When linking the module, the name of the output file has to match + the name of the module prefixed by an underscore. If the name of + your module is "example", then the name of the corresponding + object file should be "_example.so" or "_examplemodule.so +". The name of the module is specified using the %module + directive or the -module command line option.

      +

      Compatibility Note: In SWIG-1.3.13 and earlier releases, + module names did not include the leading underscore. This is because + modules were normally created as C-only extensions without the extra + Python support file (instead, creating Python code was supported as an + optional feature). This has been changed in SWIG-1.3.14 and is + consistent with other Python extension modules. For example, the +socket module actually consists of two files; socket.py + and _socket.so. Many other built-in Python modules follow a + similar convention.

      +

      31.2.4 Static linking

      +

      An alternative approach to dynamic linking is to rebuild the Python + interpreter with your extension module added to it. In the past, this + approach was sometimes necessary due to limitations in dynamic loading + support on certain machines. However, the situation has improved + greatly over the last few years and you should not consider this + approach unless there is really no other option.

      +

      The usual procedure for adding a new module to Python involves + finding the Python source, adding an entry to the Modules/Setup + file, and rebuilding the interpreter using the Python Makefile. + However, newer Python versions have changed the build process. You may + need to edit the 'setup.py' file in the Python distribution instead.

      +

      In earlier versions of SWIG, the embed.i library file could + be used to rebuild the interpreter. For example:

      +
      +
      +%module example
+
+%inline %{
+extern int fact(int);
+extern int mod(int, int);
+extern double My_variable;
+%}
+
+%include "embed.i"       // Include code for a static version of Python
+
+
      +
      +

      The embed.i library file includes supporting code that + contains everything needed to rebuild Python. To rebuild the + interpreter, you simply do something like this:

      +
      +
      +$ swig -python example.i
+$ gcc example.c example_wrap.c \
+        -Xlinker -export-dynamic \
+        -DHAVE_CONFIG_H -I/usr/local/include/python2.1 \
+	-I/usr/local/lib/python2.1/config \
+	-L/usr/local/lib/python2.1/config -lpython2.1 -lm -ldl \
+	-o mypython
+
+
      +
      +

      You will need to supply the same libraries that were used to build + Python the first time. This may include system libraries such as +-lsocket, -lnsl, and -lpthread. Assuming this + actually works, the new version of Python should be identical to the + default version except that your extension module will be a built-in + part of the interpreter.

      +

      Comment: In practice, you should probably try to avoid static + linking if possible. Some programmers may be inclined to use static + linking in the interest of getting better performance. However, the + performance gained by static linking tends to be rather minimal in most + situations (and quite frankly not worth the extra hassle in the opinion + of this author).

      +

      Compatibility note: The embed.i library file is + deprecated and has not been maintained for several years. Even though + it appears to "work" with Python 2.1, no future support is guaranteed. + If using static linking, you might want to rely on a different approach + (perhaps using distutils).

      +

      31.2.5 Using your module

      +

      To use your module, simply use the Python import statement. + If all goes well, you will be able to this:

      +
      +
      +$ python
+>>> import example
+>>> example.fact(4)
+24
+>>>
+
      +
      +

      A common error received by first-time users is the following:

      +
      +
      +>>> import example
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+  File "example.py", line 2, in ?
+    import _example
+ImportError: No module named _example
+
      +
      +

      If you get this message, it means that you either forgot to compile + the wrapper code into an extension module or you didn't give the + extension module the right name. Make sure that you compiled the + wrappers into a module called _example.so. And don't forget + the leading underscore (_).

      +

      Another possible error is the following:

      +
      +
      +>>> import example
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+ImportError: dynamic module does not define init function (init_example)
+>>>                                                               
+
      +
      +

      This error is almost always caused when a bad name is given to the + shared object file. For example, if you created a file example.so + instead of _example.so you would get this error. + Alternatively, this error could arise if the name of the module is + inconsistent with the module name supplied with the %module + directive. Double-check the interface to make sure the module name and + the shared object filename match. Another possible cause of this error + is forgetting to link the SWIG-generated wrapper code with the rest of + your application when creating the extension module.

      +

      Another common error is something similar to the following:

      +
      +
      +Traceback (most recent call last):
+  File "example.py", line 3, in ?
+    import example
+ImportError: ./_example.so: undefined symbol: fact
+
      +
      +

      This error usually indicates that you forgot to include some object + files or libraries in the linking of the shared library file. Make sure + you compile both the SWIG wrapper file and your original program into a + shared library file. Make sure you pass all of the required libraries + to the linker.

      +

      Sometimes unresolved symbols occur because a wrapper has been + created for a function that doesn't actually exist in a library. This + usually occurs when a header file includes a declaration for a function + that was never actually implemented or it was removed from a library + without updating the header file. To fix this, you can either edit the + SWIG input file to remove the offending declaration or you can use the +%ignore directive to ignore the declaration.

      +

      Finally, suppose that your extension module is linked with another + library like this:

      +
      +
      +$ gcc -shared example.o example_wrap.o -L/home/beazley/projects/lib -lfoo \
+      -o _example.so
+
      +
      +

      If the foo library is compiled as a shared library, you + might encounter the following problem when you try to use your module:

      +
      +
      +>>> import example
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+ImportError: libfoo.so: cannot open shared object file: No such file or directory
+>>>                 
+
      +
      +

      This error is generated because the dynamic linker can't locate the +libfoo.so library. When shared libraries are loaded, the system + normally only checks a few standard locations such as /usr/lib + and /usr/local/lib. To fix this problem, there are several + things you can do. First, you can recompile your extension module with + extra path information. For example, on Linux you can do this:

      +
      +
      +$ gcc -shared example.o example_wrap.o -L/home/beazley/projects/lib -lfoo \
+      -Xlinker -rpath /home/beazley/projects/lib  \
+      -o _example.so
+
      +
      +

      Alternatively, you can set the LD_LIBRARY_PATH environment + variable to include the directory with your shared libraries. If + setting LD_LIBRARY_PATH, be aware that setting this variable + can introduce a noticeable performance impact on all other applications + that you run. To set it only for Python, you might want to do this + instead:

      +
      +
      +$ env LD_LIBRARY_PATH=/home/beazley/projects/lib python
+
      +
      +

      Finally, you can use a command such as ldconfig (Linux) or +crle (Solaris) to add additional search paths to the default system + configuration (this requires root access and you will need to read the + man pages).

      +

      31.2.6 Compilation of C++ extensions

      +

      Compilation of C++ extensions has traditionally been a tricky + problem. Since the Python interpreter is written in C, you need to take + steps to make sure C++ is properly initialized and that modules are + compiled correctly. This should be a non-issue if you're using + distutils, as it takes care of all that for you. The following is + included for historical reasons, and in case you need to compile on + your own.

      +

      On most machines, C++ extension modules should be linked using the + C++ compiler. For example:

      +
      +
      +$ swig -c++ -python example.i
+$ g++ -O2 -fPIC -c example.cxx
+$ g++ -O2 -fPIC -c example_wrap.cxx -I/usr/local/include/python2.5
+$ g++ -shared example.o example_wrap.o -o _example.so
+
      +
      +

      The -fPIC option tells GCC to generate position-independent code + (PIC) which is required for most architectures (it's not vital on x86, + but still a good idea as it allows code pages from the library to be + shared between processes). Other compilers may need a different option + specified instead of -fPIC.

      +

      In addition to this, you may need to include additional library + files to make it work. For example, if you are using the Sun C++ + compiler on Solaris, you often need to add an extra library -lCrun + like this:

      +
      +
      +$ swig -c++ -python example.i
+$ CC -c example.cxx
+$ CC -c example_wrap.cxx -I/usr/local/include/python2.5
+$ CC -G example.o example_wrap.o -L/opt/SUNWspro/lib -o _example.so -lCrun
+
      +
      +

      Of course, the extra libraries to use are completely + non-portable---you will probably need to do some experimentation.

      +

      Sometimes people have suggested that it is necessary to relink the + Python interpreter using the C++ compiler to make C++ extension modules + work. In the experience of this author, this has never actually + appeared to be necessary. Relinking the interpreter with C++ really + only includes the special run-time libraries described above---as long + as you link your extension modules with these libraries, it should not + be necessary to rebuild Python.

      +

      If you aren't entirely sure about the linking of a C++ extension, + you might look at an existing C++ program. On many Unix machines, the +ldd command will list library dependencies. This should give you + some clues about what you might have to include when you link your + extension module. For example:

      +
      +
      +$ ldd swig
+        libstdc++-libc6.1-1.so.2 => /usr/lib/libstdc++-libc6.1-1.so.2 (0x40019000)
+        libm.so.6 => /lib/libm.so.6 (0x4005b000)
+        libc.so.6 => /lib/libc.so.6 (0x40077000)
+        /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
+
      +
      +

      As a final complication, a major weakness of C++ is that it does not + define any sort of standard for binary linking of libraries. This means + that C++ code compiled by different compilers will not link together + properly as libraries nor is the memory layout of classes and data + structures implemented in any kind of portable manner. In a monolithic + C++ program, this problem may be unnoticed. However, in Python, it is + possible for different extension modules to be compiled with different + C++ compilers. As long as these modules are self-contained, this + probably won't matter. However, if these modules start sharing data, + you will need to take steps to avoid segmentation faults and other + erratic program behavior. If working with lots of software components, + you might want to investigate using a more formal standard such as COM.

      +

      31.2.7 Compiling for 64-bit platforms

      +

      On platforms that support 64-bit applications (Solaris, Irix, etc.), + special care is required when building extension modules. On these + machines, 64-bit applications are compiled and linked using a different + set of compiler/linker options. In addition, it is not generally + possible to mix 32-bit and 64-bit code together in the same + application.

      +

      To utilize 64-bits, the Python executable will need to be recompiled + as a 64-bit application. In addition, all libraries, wrapper code, and + every other part of your application will need to be compiled for + 64-bits. If you plan to use other third-party extension modules, they + will also have to be recompiled as 64-bit extensions.

      +

      If you are wrapping commercial software for which you have no source + code, you will be forced to use the same linking standard as used by + that software. This may prevent the use of 64-bit extensions. It may + also introduce problems on platforms that support more than one linking + standard (e.g., -o32 and -n32 on Irix).

      +

      On the Linux x86_64 platform (Opteron or EM64T), besides of the + required compiler option -fPIC discussed above, you will need to be + careful about the libraries you link with or the library path you use. + In general, a Linux distribution will have two set of libraries, one + for native x86_64 programs (under /usr/lib64), and another for 32 bits + compatibility (under /usr/lib). Also, the compiler options -m32 and + -m64 allow you to choose the desired binary format for your python + extension.

      +

      31.2.8 Building Python Extensions under + Windows

      +

      Building a SWIG extension to Python under Windows is roughly similar + to the process used with Unix. Using the distutils, it is essentially + identical. If you have the same version of the MS compiler that Python + was built with (the python2.4 and python2.5 distributed by python.org + are built with Visual Studio 2003), the standard python setup.py + build should just work.

      +

      As of python2.5, the distutils support building extensions with + MingGW out of the box. Following the instruction here: +Building Python extensions for Windows with only free tools should + get you started.

      +

      If you need to build it on your own, the following notes are + provided:

      +

      You will need to create a DLL that can be loaded into the + interpreter. This section briefly describes the use of SWIG with + Microsoft Visual C++. As a starting point, many of SWIG's examples + include project files. You might want to take a quick look at these in + addition to reading this section.

      +

      In Developer Studio, SWIG should be invoked as a custom build + option. This is usually done as follows:

      +
        +
      • Open up a new workspace and use the AppWizard to select a DLL + project.
        • +
      • Add both the SWIG interface file (the .i file), any supporting C + files, and the name of the wrapper file that will be created by SWIG + (ie. example_wrap.c). Note : If using C++, choose a different + suffix for the wrapper file such as example_wrap.cxx. Don't + worry if the wrapper file doesn't exist yet--Developer Studio keeps a + reference to it.
        • +
      • Select the SWIG interface file and go to the settings menu. Under + settings, select the "Custom Build" option.
        • +
      • Enter "SWIG" in the description field.
        • +
      • Enter "swig -python -o $(ProjDir)\$(InputName)_wrap.c + $(InputPath)" in the "Build command(s) field"
        • +
      • Enter "$(ProjDir)\$(InputName)_wrap.c" in the "Output + files(s) field".
        • +
      • Next, select the settings for the entire project and go to + "C++:Preprocessor". Add the include directories for your Python + installation under "Additional include directories".
        • +
      • Define the symbol __WIN32__ under preprocessor options.
        • +
      • Finally, select the settings for the entire project and go to "Link + Options". Add the Python library file to your link libraries. For + example "python21.lib". Also, set the name of the output file to match + the name of your Python module, ie. _example.pyd - Note that + _example.dll also worked with Python-2.4 and earlier.
        • +
      • Build your project.
        • +
      +

      If all went well, SWIG will be automatically invoked whenever you + build your project. Any changes made to the interface file will result + in SWIG being automatically executed to produce a new version of the + wrapper file.

      +

      To run your new Python extension, simply run Python and use the +import command as normal. For example :

      +
      +
      +$ python
+>>> import example
+>>> print example.fact(4)
+24
+>>>
+
      +
      +

      If you get an ImportError exception when importing the + module, you may have forgotten to include additional library files when + you built your module. If you get an access violation or some kind of + general protection fault immediately upon import, you have a more + serious problem. This is often caused by linking your extension module + against the wrong set of Win32 debug or thread libraries. You will have + to fiddle around with the build options of project to try and track + this down.

      +

      Some users have reported success in building extension modules using + Cygwin and other compilers. However, the problem of building usable + DLLs with these compilers tends to be rather problematic. For the + latest information, you may want to consult the + SWIG Wiki.

      +

      31.3 A tour of basic C/C++ wrapping

      +

      By default, SWIG tries to build a very natural Python interface to + your C/C++ code. Functions are wrapped as functions, classes are + wrapped as classes, and so forth. This section briefly covers the + essential aspects of this wrapping.

      +

      31.3.1 Modules

      +

      The SWIG %module directive specifies the name of the Python + module. If you specify `%module example', then everything is + wrapped into a Python 'example' module. Underneath the covers, + this module consists of a Python source file example.py and a + low-level extension module _example.so. When choosing a module + name, make sure you don't use the same name as a built-in Python + command or standard module name.

      +

      31.3.2 Functions

      +

      Global functions are wrapped as new Python built-in functions. For + example,

      +
      +
      +%module example
+int fact(int n);
+
      +
      +

      creates a built-in function example.fact(n) that works + exactly like you think it does:

      +
      +
      +>>> import example
+>>> print example.fact(4)
+24
+>>>
+
      +
      +

      31.3.3 Global variables

      +

      C/C++ global variables are fully supported by SWIG. However, the + underlying mechanism is somewhat different than you might expect due to + the way that Python assignment works. When you type the following in + Python

      +
      +
      +a = 3.4
+
      +
      +

      "a" becomes a name for an object containing the value 3.4. If you + later type

      +
      +
      +b = a
+
      +
      +

      then "a" and "b" are both names for the object containing the value + 3.4. Thus, there is only one object containing 3.4 and "a" and "b" are + both names that refer to it. This is quite different than C where a + variable name refers to a memory location in which a value is stored + (and assignment copies data into that location). Because of this, there + is no direct way to map variable assignment in C to variable assignment + in Python.

      +

      To provide access to C global variables, SWIG creates a special + object called `cvar' that is added to each SWIG generated + module. Global variables are then accessed as attributes of this + object. For example, consider this interface

      +
      +
      +// SWIG interface file with global variables
+%module example
+...
+%inline %{
+extern int My_variable;
+extern double density;
+%}
+...
+
      +
      +

      Now look at the Python interface:

      +
      +
      +>>> import example
+>>> # Print out value of a C global variable
+>>> print example.cvar.My_variable
+4
+>>> # Set the value of a C global variable
+>>> example.cvar.density = 0.8442
+>>> # Use in a math operation
+>>> example.cvar.density = example.cvar.density*1.10
+
      +
      +

      If you make an error in variable assignment, you will receive an + error message. For example:

      +
      +
      +>>> example.cvar.density = "Hello"
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+TypeError: C variable 'density (double )'
+>>> 
+
      +
      +

      If a variable is declared as const, it is wrapped as a + read-only variable. Attempts to modify its value will result in an + error.

      +

      To make ordinary variables read-only, you can use the %immutable + directive. For example:

      +
      +
      +%{
+extern char *path;
+%}
+%immutable;
+extern char *path;
+%mutable;
+
      +
      +

      The %immutable directive stays in effect until it is + explicitly disabled or cleared using %mutable. See the +Creating read-only variables section for further details.

      +

      If you just want to make a specific variable immutable, supply a + declaration name. For example:

      +
      +
      +%{
+extern char *path;
+%}
+%immutable path;
+...
+extern char *path;      // Read-only (due to %immutable)
+
      +
      +

      If you would like to access variables using a name other than " +cvar", it can be changed using the -globals option :

      +
      +
      +$ swig -python -globals myvar example.i
+
      +
      +

      Some care is in order when importing multiple SWIG modules. If you + use the "from <file> import *" style of importing, you will + get a name clash on the variable `cvar' and you will only be + able to access global variables from the last module loaded. To prevent + this, you might consider renaming cvar or making it private to + the module by giving it a name that starts with a leading underscore. + SWIG does not create cvar if there are no global variables in + a module.

      +

      31.3.4 Constants and enums

      +

      C/C++ constants are installed as Python objects containing the + appropriate value. To create a constant, use #define, enum +, or the %constant directive. For example:

      +
      +
      +#define PI 3.14159
+#define VERSION "1.0"
+
+enum Beverage { ALE, LAGER, STOUT, PILSNER };
+
+%constant int FOO = 42;
+%constant const char *path = "/usr/local";
+
      +
      +

      For enums, make sure that the definition of the enumeration actually + appears in a header file or in the wrapper file somehow---if you just + stick an enum in a SWIG interface without also telling the C compiler + about it, the wrapper code won't compile.

      +

      Note: declarations declared as const are wrapped as + read-only variables and will be accessed using the cvar object + described in the previous section. They are not wrapped as constants. + For further discussion about this, see the SWIG Basics + chapter.

      +

      Constants are not guaranteed to remain constant in Python---the name + of the constant could be accidentally reassigned to refer to some other + object. Unfortunately, there is no easy way for SWIG to generate code + that prevents this. You will just have to be careful.

      +

      31.3.5 Pointers

      +

      C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no + problem working with incomplete type information. Here is a rather + simple interface:

      +
      +
      +%module example
+
+FILE *fopen(const char *filename, const char *mode);
+int fputs(const char *, FILE *);
+int fclose(FILE *);
+
      +
      +

      When wrapped, you will be able to use the functions in a natural way + from Python. For example:

      +
      +
      +>>> import example
+>>> f = example.fopen("junk","w")
+>>> example.fputs("Hello World\n", f)
+>>> example.fclose(f)
+
      +
      +

      If this makes you uneasy, rest assured that there is no deep magic + involved. Underneath the covers, pointers to C/C++ objects are simply + represented as opaque values using an especial python container object:

      +
      +
      +>>> print f
+<Swig Object at _08a71808_p_FILE>
+
      +
      +

      This pointer value can be freely passed around to different C + functions that expect to receive an object of type FILE *. The + only thing you can't do is dereference the pointer from Python. Of + course, that isn't much of a concern in this example.

      +

      In older versions of Swig (1.3.22 or older), pointers were + represented using a plain string object. If you have an old package + that still requires that representation, or you just feel nostalgic, + you can always retrieve it by casting the pointer object to a string:

      +
      +
      +>>> print str(f)
+_c0671108_p_FILE
+
      +
      +

      Also, if you need to pass the raw pointer value to some external + python library, you can do it by casting the pointer object to an + integer:

      +
      +
      +>>> print int(f)
+135833352
+
      +
      +

      However, the inverse operation is not possible, i.e., you can't + build a Swig pointer object from a raw integer value.

      +

      Note also that the '0' or NULL pointer is always represented by +None, no matter what type swig is addressing. In the previous + example, you can call:

      +
      +
      +>>> example.fclose(None)
+
      +
      +

      and that will be equivalent to the following, but not really useful, + C code:

      +
      +
      +FILE *f = NULL;
+fclose(f);
+
      +
      +

      As much as you might be inclined to modify a pointer value directly + from Python, don't. The hexadecimal encoding is not necessarily the + same as the logical memory address of the underlying object. Instead it + is the raw byte encoding of the pointer value. The encoding will vary + depending on the native byte-ordering of the platform (i.e., big-endian + vs. little-endian). Similarly, don't try to manually cast a pointer to + a new type by simply replacing the type-string. This may not work like + you expect, it is particularly dangerous when casting C++ objects. If + you need to cast a pointer or change its value, consider writing some + helper functions instead. For example:

      +
      +
      +%inline %{
+/* C-style cast */
+Bar *FooToBar(Foo *f) {
+   return (Bar *) f;
+}
+
+/* C++-style cast */
+Foo *BarToFoo(Bar *b) {
+   return dynamic_cast<Foo*>(b);
+}
+
+Foo *IncrFoo(Foo *f, int i) {
+    return f+i;
+}
+%}
+
      +
      +

      Also, if working with C++, you should always try to use the new C++ + style casts. For example, in the above code, the C-style cast may + return a bogus result whereas as the C++-style cast will return +None if the conversion can't be performed.

      +

      31.3.6 Structures

      +

      If you wrap a C structure, it is wrapped by a Python class. This + provides a very natural interface. For example,

      +
      +
      +struct Vector {
+	double x,y,z;
+};
+
+
      +
      +

      is used as follows:

      +
      +
      +>>> v = example.Vector()
+>>> v.x = 3.5
+>>> v.y = 7.2
+>>> print v.x, v.y, v.z
+7.8 -4.5 0.0
+>>> 
+
      +
      +

      Similar access is provided for unions and the data members of C++ + classes.

      +

      If you print out the value of v in the above example, you + will see something like this:

      +
      +
      +>>> print v
+<C Vector instance at _18e31408_p_Vector>
+
      +
      +

      This object is actually a Python instance that has been wrapped + around a pointer to the low-level C structure. This instance doesn't + actually do anything--it just serves as a proxy. The pointer to the C + object can be found in the the .this attribute. For example:

      +
      +
      +>>> print v.this
+_18e31408_p_Vector
+>>>
+
      +
      +

      Further details about the Python proxy class are covered a little + later.

      +

      const members of a structure are read-only. Data members + can also be forced to be read-only using the %immutable + directive. For example:

      +
      +
      +struct Foo {
+   ...
+   %immutable;
+   int x;        /* Read-only members */
+   char *name;
+   %mutable;
+   ...
+};
+
      +
      +

      When char * members of a structure are wrapped, the + contents are assumed to be dynamically allocated using malloc + or new (depending on whether or not SWIG is run with the -c++ + option). When the structure member is set, the old contents will be + released and a new value created. If this is not the behavior you want, + you will have to use a typemap (described later).

      +

      If a structure contains arrays, access to those arrays is managed + through pointers. For example, consider this:

      +
      +
      +struct Bar {
+    int  x[16];
+};
+
      +
      +

      If accessed in Python, you will see behavior like this:

      +
      +
      +>>> b = example.Bar()
+>>> print b.x
+_801861a4_p_int
+>>> 
+
      +
      +

      This pointer can be passed around to functions that expect to + receive an int * (just like C). You can also set the value of + an array member using another pointer. For example:

      +
      +
      +>>> c = example.Bar()
+>>> c.x = b.x             # Copy contents of b.x to c.x
+
      +
      +

      For array assignment, SWIG copies the entire contents of the array + starting with the data pointed to by b.x. In this example, 16 + integers would be copied. Like C, SWIG makes no assumptions about + bounds checking---if you pass a bad pointer, you may get a segmentation + fault or access violation.

      +

      When a member of a structure is itself a structure, it is handled as + a pointer. For example, suppose you have two structures like this:

      +
      +
      +struct Foo {
+   int a;
+};
+
+struct Bar {
+   Foo f;
+};
+
      +
      +

      Now, suppose that you access the f attribute of Bar + like this:

      +
      +
      +>>> b = Bar()
+>>> x = b.f
+
      +
      +

      In this case, x is a pointer that points to the Foo + that is inside b. This is the same value as generated by this + C code:

      +
      +
      +Bar b;
+Foo *x = &b->f;       /* Points inside b */
+
      +
      +

      Because the pointer points inside the structure, you can modify the + contents and everything works just like you would expect. For example:

      +
      +
      +>>> b = Bar()
+>>> b.f.a = 3               # Modify attribute of structure member
+>>> x = b.f                   
+>>> x.a = 3                 # Modifies the same structure
+
      +
      +

      31.3.7 C++ classes

      +

      C++ classes are wrapped by Python classes as well. For example, if + you have this class,

      +
      +
      +class List {
+public:
+  List();
+  ~List();
+  int  search(char *item);
+  void insert(char *item);
+  void remove(char *item);
+  char *get(int n);
+  int  length;
+};
+
      +
      +

      you can use it in Python like this:

      +
      +
      +>>> l = example.List()
+>>> l.insert("Ale")
+>>> l.insert("Stout")
+>>> l.insert("Lager")
+>>> l.get(1)
+'Stout'
+>>> print l.length
+3
+>>>
+
      +
      +

      Class data members are accessed in the same manner as C structures.

      +

      Static class members present a special problem for Python. Prior to + Python-2.2, Python classes had no support for static methods and no + version of Python supports static member variables in a manner that + SWIG can utilize. Therefore, SWIG generates wrappers that try to work + around some of these issues. To illustrate, suppose you have a class + like this:

      +
      +
      +class Spam {
+public:
+   static void foo();
+   static int bar;
+
+};
+
      +
      +

      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
+
      +
      +

      The first two methods of access are supported in all versions of + Python. The last technique is only available in Python-2.2 and later + versions.

      +

      Static member variables are currently accessed as global variables. + This means, they are accessed through cvar like this:

      +
      +
      +>>> print example.cvar.Spam_bar
+7
+
      +
      +

      31.3.8 C++ inheritance

      +

      SWIG is fully aware of issues related to C++ inheritance. Therefore, + if you have classes like this

      +
      +
      +class Foo {
+...
+};
+
+class Bar : public Foo {
+...
+};
+
      +
      +

      those classes are wrapped into a hierarchy of Python classes that + reflect the same inheritance structure. All of the usual Python utility + functions work normally:

      +
      +
      +>>> b = Bar()
+>>> instance(b,Foo)
+1
+>>> issubclass(Bar,Foo)
+1
+>>> issubclass(Foo,Bar)
+0
+
      +
      +

      Furthermore, if you have functions like this

      +
      +
      +void spam(Foo *f);
+
      +
      +

      then the function spam() accepts Foo * or a + pointer to any class derived from Foo.

      +

      It is safe to use multiple inheritance with SWIG.

      +

      31.3.9 Pointers, references, values, and + arrays

      +

      In C++, there are many different ways a function might receive and + manipulate objects. For example:

      +
      +
      +void spam1(Foo *x);      // Pass by pointer
+void spam2(Foo &x);      // Pass by reference
+void spam3(const Foo &x);// Pass by const reference
+void spam4(Foo x);       // Pass by value
+void spam5(Foo x[]);     // Array of objects
+
      +
      +

      In Python, there is no detailed distinction like this--specifically, + there are only "objects". There are no pointers, references, arrays, + and so forth. Because of this, SWIG unifies all of these types together + in the wrapper code. For instance, if you actually had the above + functions, it is perfectly legal to do this:

      +
      +
      +>>> f = Foo()           # Create a Foo
+>>> spam1(f)            # Ok. Pointer
+>>> spam2(f)            # Ok. Reference
+>>> spam3(f)            # Ok. Const reference
+>>> spam4(f)            # Ok. Value.
+>>> spam5(f)            # Ok. Array (1 element)
+
      +
      +

      Similar behavior occurs for return values. For example, if you had + functions like this,

      +
      +
      +Foo *spam6();
+Foo &spam7();
+Foo  spam8();
+const Foo &spam9();
+
      +
      +

      then all three functions will return a pointer to some Foo + object. Since the third function (spam8) returns a value, newly + allocated memory is used to hold the result and a pointer is returned + (Python will release this memory when the return value is garbage + collected). The fourth case (spam9) which returns a const reference, in + most of the cases will be treated as a returning value, and it will + follow the same allocation/deallocation process.

      +

      31.3.10 C++ overloaded functions

      +

      C++ overloaded functions, methods, and constructors are mostly + supported by SWIG. For example, if you have two functions like this:

      +
      +
      +void foo(int);
+void foo(char *c);
+
      +
      +

      You can use them in Python in a straightforward manner:

      +
      +
      +>>> foo(3)           # foo(int)
+>>> foo("Hello")     # foo(char *c)
+
      +
      +

      Similarly, if you have a class like this,

      +
      +
      +class Foo {
+public:
+    Foo();
+    Foo(const Foo &);
+    ...
+};
+
      +
      +

      you can write Python code like this:

      +
      +
      +>>> f = Foo()          # Create a Foo
+>>> g = Foo(f)         # Copy f
+
      +
      +

      Overloading support is not quite as flexible as in C++. Sometimes + there are methods that SWIG can't disambiguate. For example:

      +
      +
      +void spam(int);
+void spam(short);
+
      +
      +

      or

      +
      +
      +void foo(Bar *b);
+void foo(Bar &b);
+
      +
      +

      If declarations such as these appear, you will get a warning message + like this:

      +
      +
      +example.i:12: Warning(509): Overloaded spam(short) is shadowed by spam(int)
+at example.i:11.
+
      +
      +

      To fix this, you either need to ignore or rename one of the methods. + For example:

      +
      +
      +%rename(spam_short) spam(short);
+...
+void spam(int);    
+void spam(short);   // Accessed as spam_short
+
      +
      +

      or

      +
      +
      +%ignore spam(short);
+...
+void spam(int);    
+void spam(short);   // Ignored
+
      +
      +

      SWIG resolves overloaded functions and methods using a + disambiguation scheme that ranks and sorts declarations according to a + set of type-precedence rules. The order in which declarations appear in + the input does not matter except in situations where ambiguity + arises--in this case, the first declaration takes precedence.

      +

      Please refer to the "SWIG and C++" chapter for more information + about overloading.

      +

      31.3.11 C++ operators

      +

      Certain C++ overloaded operators can be handled automatically by + SWIG. For example, consider a class like this:

      +
      +
      +class Complex {
+private:
+  double rpart, ipart;
+public:
+  Complex(double r = 0, double i = 0) : rpart(r), ipart(i) { }
+  Complex(const Complex &c) : rpart(c.rpart), ipart(c.ipart) { }
+  Complex &operator=(const Complex &c);
+
+  Complex operator+=(const Complex &c) const;
+  Complex operator+(const Complex &c) const;
+  Complex operator-(const Complex &c) const;
+  Complex operator*(const Complex &c) const;
+  Complex operator-() const;
+  
+  double re() const { return rpart; }
+  double im() const { return ipart; }
+};
+
      +
      +

      When wrapped, it works like you expect:

      +
      +
      +>>> c = Complex(3,4)
+>>> d = Complex(7,8)
+>>> e = c + d
+>>> e.re()
+10.0
+>>> e.im()
+12.0
+>>> c += d
+>>> c.re()
+10.0
+>>> c.im()
+12.0
+
+
      +
      +

      One restriction with operator overloading support is that SWIG is + not able to fully handle operators that aren't defined as part of the + class. For example, if you had code like this

      +
      +
      +class Complex {
+...
+friend Complex operator+(double, const Complex &c);
+...
+};
+
      +
      +

      then SWIG ignores it and issues a warning. You can still wrap the + operator, but you may have to encapsulate it in a special function. For + example:

      +
      +
      +%rename(Complex_add_dc) operator+(double, const Complex &);
+
      +
      +

      There are ways to make this operator appear as part of the class + using the %extend directive. Keep reading.

      +

      Also, be aware that certain operators don't map cleanly to Python. + For instance, overloaded assignment operators don't map to Python + semantics and will be ignored.

      +

      31.3.12 C++ namespaces

      +

      SWIG is aware of C++ namespaces, but namespace names do not appear + in the module nor do namespaces result in a module that is broken up + into submodules or packages. For example, if you have a file like this,

      +
      +
      +%module example
+
+namespace foo {
+   int fact(int n);
+   struct Vector {
+       double x,y,z;
+   };
+};
+
      +
      +

      it works in Python as follows:

      +
      +
      +>>> import example
+>>> example.fact(3)
+6
+>>> v = example.Vector()
+>>> v.x = 3.4
+>>> print v.y
+0.0
+>>>
+
      +
      +

      If your program has more than one namespace, name conflicts (if any) + can be resolved using %rename For example:

      +
      +
      +%rename(Bar_spam) Bar::spam;
+
+namespace Foo {
+    int spam();
+}
+
+namespace Bar {
+    int spam();
+}
+
      +
      +

      If you have more than one namespace and your want to keep their + symbols separate, consider wrapping them as separate SWIG modules. For + example, make the module name the same as the namespace and create + extension modules for each namespace separately. If your program + utilizes thousands of small deeply nested namespaces each with + identical symbol names, well, then you get what you deserve.

      +

      31.3.13 C++ templates

      +

      C++ templates don't present a huge problem for SWIG. However, in + order to create wrappers, you have to tell SWIG to create wrappers for + a particular template instantiation. To do this, you use the +%template directive. For example:

      +
      +
      +%module example
+%{
+#include "pair.h"
+%}
+
+template<class T1, class T2>
+struct pair {
+   typedef T1 first_type;
+   typedef T2 second_type;
+   T1 first;
+   T2 second;
+   pair();
+   pair(const T1&, const T2&);
+  ~pair();
+};
+
+%template(pairii) pair<int,int>;
+
      +
      +

      In Python:

      +
      +
      +>>> import example
+>>> p = example.pairii(3,4)
+>>> p.first
+3
+>>> p.second
+4
+
      +
      +

      Obviously, there is more to template wrapping than shown in this + example. More details can be found in the SWIG and + C++ chapter. Some more complicated examples will appear later.

      +

      31.3.14 C++ Smart Pointers

      +

      In certain C++ programs, it is common to use classes that have been + wrapped by so-called "smart pointers." Generally, this involves the use + of a template class that implements operator->() like this:

      +
      +
      +template<class T> class SmartPtr {
+   ...
+   T *operator->();
+   ...
+}
+
      +
      +

      Then, if you have a class like this,

      +
      +
      +class Foo {
+public:
+     int x;
+     int bar();
+};
+
      +
      +

      A smart pointer would be used in C++ as follows:

      +
      +
      +SmartPtr<Foo> p = CreateFoo();   // Created somehow (not shown)
+...
+p->x = 3;                        // Foo::x
+int y = p->bar();                // Foo::bar
+
      +
      +

      To wrap this in Python, simply tell SWIG about the SmartPtr + class and the low-level Foo object. Make sure you instantiate +SmartPtr using %template if necessary. For example:

      +
      +
      +%module example
+...
+%template(SmartPtrFoo) SmartPtr<Foo>;
+...
+
      +
      +

      Now, in Python, everything should just "work":

      +
      +
      +>>> p = example.CreateFoo()          # Create a smart-pointer somehow
+>>> p.x = 3                          # Foo::x
+>>> p.bar()                          # Foo::bar
+
      +
      +

      If you ever need to access the underlying pointer returned by +operator->() itself, simply use the __deref__() method. + For example:

      +
      +
      +>>> f = p.__deref__()     # Returns underlying Foo *
+
      +
      +

      31.3.15 C++ Reference Counted Objects + (ref/unref)

      +

      Another usual idiom in C++ is the use of reference counted objects. + Consider for example:

      +
      +class RCObj  {
+  // implement the ref counting mechanism
+  int add_ref();
+  int del_ref();
+  int ref_count();
+
+public:
+  virtual ~RCObj() = 0;
+
+  int ref() const {
+    return add_ref();
+  }
+
+  int unref() const   {
+    if (ref_count() == 0 || del_ref() == 0 ) {
+	delete this;
+	return 0;
+      } 
+    return ref_count();
+  }
+};
+
+
+class A : RCObj {
+public:
+  A();
+  int foo();
+};
+
+
+class B {
+  A *_a;
+
+public:
+  B(A *a) : _a(a) { 
+    a->ref(); 
+  }
+
+  ~B() { 
+    a->unref(); 
+  }
+};
+
+int main() {
+  A *a  = new A();
+  a->ref();           // 'a' is ref here
+
+  B *b1 = new B(a);   // 'a' is ref here
+  if (1 + 1 == 2) {
+    B *b2 = new B(a); // 'a' is ref here
+    delete b2;        // 'a' is unref, but not deleted   
+  }
+
+  delete b1;          // 'a' is unref, but not deleted   
+  a->unref();         // 'a' is unref and deleted
+}
+
      +

      +

      In the example above, the 'A' class instance 'a' is a reference + counted object, which can't be deleted arbitrarily since it is shared + between the objects 'b1' and 'b2'. 'A' is derived from an Reference + Counted Object 'RCObj', which implements the ref/unref idiom.

      +

      To tell SWIG that 'RCObj' and all its derived classes are reference + counted objects, you use the "ref" and "unref" features, or %ref + and %unref directives (since 1.3.28). For example:

      +
      +
      +%module example
+...
+
+%feature("ref")   RCObj "$this->ref();"
+%feature("unref") RCObj "$this->unref();"
+
+%include "rcobj.h"
+%include "A.h"
+...
+
      +
      or, using the directive form:
      +
      +%module example
+...
+
+%ref   RCObj "$this->ref();"
+%unref RCObj "$this->unref();"
+
+%include "rcobj.h"
+%include "A.h"
+...
+
      +
      +

      where the code passed to the "ref" and "unref" features will be + executed as needed whenever a new object is passed to python, or when + python tries to release the shadow object instance, respectively.

      +

      In the python side, the use of a reference counted object is not + different than any other regular instance:

      +
      +
      +def create_A():
+  a = A()         # SWIG ref 'a' (new object is passed to python)
+  b1 = B(a)       # C++  ref 'a'
+  if 1 + 1 == 2:
+     b2 = B(a)    # C++ ref 'a'
+  return a        # 'b1' and 'b2' are released, C++ unref 'a' twice
+
+a = create_A()   
+exit              # 'a' is released, SWIG unref 'a'
+
      +
      +

      Note that the user doesn't explicitly need to call 'a->ref()' nor + 'a->unref()' (as neither 'delete a'). Instead, SWIG take cares of + executing the "ref" and "unref" codes as needed. If the user doesn't + specify the "ref/unref" features, SWIG will produce a code equivalent + to define them as:

      +
      +
      +%feature("ref")   ""
+%feature("unref") "delete $this;"
+
      +
      +

      In other words, SWIG will not do anything special when a new object + is passed to python, and it will always 'delete' the object when python + releases the proxy instance.

      +

      31.4 Further details on the Python class + interface

      +

      In the previous section, a high-level view of Python wrapping was + presented. A key component of this wrapping is that structures and + classes are wrapped by Python proxy classes. This provides a very + natural Python interface and allows SWIG to support a number of + advanced features such as operator overloading. However, a number of + low-level details were omitted. This section provides a brief overview + of how the proxy classes work.

      +

      31.4.1 Proxy classes

      +

      In the "SWIG basics" and +"SWIG and C++" chapters, details of low-level structure and class + wrapping are described. To summarize those chapters, if you have a + class like this

      +
      +
      +class Foo {
+public:
+     int x;
+     int spam(int);
+     ...
+
      +
      +

      then SWIG transforms it into a set of low-level procedural wrappers. + For example:

      +
      +
      +Foo *new_Foo() {
+    return new Foo();
+}
+void delete_Foo(Foo *f) {
+    delete f;
+}
+int Foo_x_get(Foo *f) {
+    return f->x;
+}
+void Foo_x_set(Foo *f, int value) {
+    f->x = value;
+}
+int Foo_spam(Foo *f, int arg1) {
+    return f->spam(arg1);
+}
+
      +
      +

      These wrappers can be found in the low-level extension module (e.g., + _example).

      +

      Using these wrappers, SWIG generates a high-level Python proxy class + (also known as a shadow class) like this (shown for Python 2.2):

      +
      +
      +import _example
+
+class Foo(object):
+     def __init__(self):
+         self.this = _example.new_Foo()
+         self.thisown = 1
+     def __del__(self):
+         if self.thisown:
+               _example.delete_Foo(self.this)
+     def spam(self,arg1):
+         return _example.Foo_spam(self.this,arg1)
+     x = property(_example.Foo_x_get, _example.Foo_x_set)
+
      +
      +

      This class merely holds a pointer to the underlying C++ object ( +.this) and dispatches methods and member variable access to that + object using the low-level accessor functions. From a user's point of + view, it makes the class work normally:

      +
      +
      +>>> f = example.Foo()
+>>> f.x = 3
+>>> y = f.spam(5)
+
      +
      +

      The fact that the class has been wrapped by a real Python class + offers certain advantages. For instance, you can attach new Python + methods to the class and you can even inherit from it (something not + supported by Python built-in types until Python 2.2).

      +

      31.4.2 Memory management

      +

      Associated with proxy object, is an ownership flag .thisown + The value of this flag determines who is responsible for deleting the + underlying C++ object. If set to 1, the Python interpreter will destroy + the C++ object when the proxy class is garbage collected. If set to 0 + (or if the attribute is missing), then the destruction of the proxy + class has no effect on the C++ object.

      +

      When an object is created by a constructor or returned by value, + Python automatically takes ownership of the result. For example:

      +
      +
      +class Foo {
+public:
+    Foo();
+    Foo bar();
+};
+
      +
      +

      In Python:

      +
      +
      +>>> f = Foo()
+>>> f.thisown
+1
+>>> g = f.bar()
+>>> g.thisown
+1
+
      +
      +

      On the other hand, when pointers are returned to Python, there is + often no way to know where they came from. Therefore, the ownership is + set to zero. For example:

      +
      +
      +class Foo {
+public:
+    ...
+    Foo *spam();
+    ...
+};
+
      +
      +
      +
      +>>> f = Foo()
+>>> s = f.spam()
+>>> print s.thisown
+0
+>>>
+
      +
      +

      This behavior is especially important for classes that act as + containers. For example, if a method returns a pointer to an object + that is contained inside another object, you definitely don't want + Python to assume ownership and destroy it!

      +

      A good way to indicate that ownership should be set for a returned + pointer is to use the %newobject directive.

      +

      Related to containers, ownership issues can arise whenever an object + is assigned to a member or global variable. For example, consider this + interface:

      +
      +
      +%module example
+
+struct Foo {
+    int  value;
+    Foo  *next;
+};
+
+Foo *head = 0;
+
      +
      +

      When wrapped in Python, careful observation will reveal that + ownership changes whenever an object is assigned to a global variable. + For example:

      +
      +
      +>>> f = example.Foo()
+>>> f.thisown
+1
+>>> example.cvar.head = f           
+>>> f.thisown
+0
+>>>
+
      +
      +

      In this case, C is now holding a reference to the object---you + probably don't want Python to destroy it. Similarly, this occurs for + members. For example:

      +
      +
      +>>> f = example.Foo()
+>>> g = example.Foo()
+>>> f.thisown
+1
+>>> g.thisown
+1
+>>> f.next = g
+>>> g.thisown
+0
+>>>
+
      +
      +

      For the most part, memory management issues remain hidden. However, + there are occasionally situations where you might have to manually + change the ownership of an object. For instance, consider code like + this:

      +
      +
      +class Node {
+   Object *value;
+public:
+   void set_value(Object *v) { value = v; }
+   ...
+};
+
      +
      +

      Now, consider the following Python code:

      +
      +
      +>>> v = Object()           # Create an object
+>>> n = Node()             # Create a node
+>>> n.set_value(v)         # Set value
+>>> v.thisown
+1
+>>> del v
+
      +
      +

      In this case, the object n is holding a reference to v + internally. However, SWIG has no way to know that this has occurred. + Therefore, Python still thinks that it has ownership of the object. + Should the proxy object be destroyed, then the C++ destructor will be + invoked and n will be holding a stale-pointer. If you're + lucky, you will only get a segmentation fault.

      +

      To work around this, it is always possible to flip the ownership + flag. For example,

      +
      +
      +>>> v.thisown = 0
+
      +
      +

      It is also possible to deal with situations like this using + typemaps--an advanced topic discussed later.

      +

      31.4.3 Python 2.2 and classic classes

      +

      SWIG makes every attempt to preserve backwards compatibility with + older versions of Python to the extent that it is possible. However, in + Python-2.2, an entirely new type of class system was introduced. This + new-style class system offers many enhancements including static member + functions, properties (managed attributes), and class methods. Details + about all of these changes can be found on +www.python.org and is not repeated here.

      +

      To address differences between Python versions, SWIG currently emits + dual-mode proxy class wrappers. In Python-2.2 and newer releases, these + wrappers encapsulate C++ objects in new-style classes that take + advantage of new features (static methods and properties). However, if + these very same wrappers are imported into an older version of Python, + old-style classes are used instead.

      +

      This dual-nature of the wrapper code means that you can create + extension modules with SWIG and those modules will work with all + versions of Python ranging from Python-1.4 to the very latest release. + Moreover, the wrappers take advantage of Python-2.2 features when + available.

      +

      For the most part, the interface presented to users is the same + regardless of what version of Python is used. The only incompatibility + lies in the handling of static member functions. In Python-2.2, they + can be accessed via the class itself. In Python-2.1 and earlier, they + have to be accessed as a global function or through an instance (see + the earlier section).

      +

      31.5 Cross language polymorphism

      +

      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.

      +

      This arrangement is asymmetric in the sense that no corresponding + mechanism exists to pass method calls down the inheritance chain from + C++ to Python. In particular, if a C++ class has been extended in + Python (by extending the proxy class), these extensions will not be + visible from C++ code. Virtual method calls from C++ are thus not able + access the lowest implementation in the inheritance chain.

      +

      Changes have been made to SWIG 1.3.18 to address this problem and + make the relationship between C++ classes and proxy classes more + symmetric. To achieve this goal, new classes called directors are + introduced at the bottom of the C++ inheritance chain. The job of the + directors is to route method calls correctly, either to C++ + implementations higher in the inheritance chain or to Python + implementations lower in the inheritance chain. The upshot is that C++ + classes can be extended in Python and from C++ these extensions look + exactly like native C++ classes. Neither C++ code nor Python code needs + to know where a particular method is implemented: the combination of + proxy classes, director classes, and C wrapper functions takes care of + all the cross-language method routing transparently.

      +

      31.5.1 Enabling directors

      +

      The director feature is disabled by default. To use directors you + must make two changes to the interface file. First, add the "directors" + option to the %module directive, like this:

      +
      +
      +%module(directors="1") modulename
+
      +
      +

      Without this option no director code will be generated. Second, you + must use the %feature("director") directive to tell SWIG which classes + and methods should get directors. The %feature directive can be applied + globally, to specific classes, and to specific methods, like this:

      +
      +
      +// generate directors for all classes that have virtual methods
+%feature("director");         
+
+// generate directors for all virtual methods in class Foo
+%feature("director") Foo;      
+
+// generate a director for just Foo::bar()
+%feature("director") Foo::bar; 
+
      +
      +

      You can use the %feature("nodirector") directive to turn off + directors for specific classes or methods. So for example,

      +
      +
      +%feature("director") Foo;
+%feature("nodirector") Foo::bar;
+
      +
      +

      will generate directors for all virtual methods of class Foo except + bar().

      +

      Directors can also be generated implicitly through inheritance. In + the following, class Bar will get a director class that handles the + methods one() and two() (but not three()):

      +
      +
      +%feature("director") Foo;
+class Foo {
+public:
+    Foo(int foo);
+    virtual void one();
+    virtual void two();
+};
+
+class Bar: public Foo {
+public:
+    virtual void three();
+};
+
      +
      +

      then at the python side you can define

      +
      +
      +import mymodule
+
+class MyFoo(mymodule.Foo):
+  def __init__(self, foo):
+     mymodule.Foo(self, foo)  
+
+  def one(self):
+     print "one from python"
+
      +
      +

      31.5.2 Director classes

      +

      For each class that has directors enabled, SWIG generates a new + class that derives from both the class in question and a special +Swig::Director class. These new classes, referred to as director + classes, can be loosely thought of as the C++ equivalent of the Python + proxy classes. The director classes store a pointer to their underlying + Python object and handle various issues related to object ownership. + Indeed, this is quite similar to the "this" and "thisown" members of + the Python proxy classes.

      +

      For simplicity let's ignore the Swig::Director class and + refer to the original C++ class as the director's base class. By + default, a director class extends all virtual methods in the + inheritance chain of its base class (see the preceding section for how + to modify this behavior). Thus all virtual method calls, whether they + originate in C++ or in Python via proxy classes, eventually end up in + at the implementation in the director class. The job of the director + methods is to route these method calls to the appropriate place in the + inheritance chain. By "appropriate place" we mean the method that would + have been called if the C++ base class and its extensions in Python + were seamlessly integrated. That seamless integration is exactly what + the director classes provide, transparently skipping over all the messy + extension API glue that binds the two languages together.

      +

      In reality, the "appropriate place" is one of only two + possibilities: C++ or Python. Once this decision is made, the rest is + fairly easy. If the correct implementation is in C++, then the lowest + implementation of the method in the C++ inheritance chain is called + explicitly. If the correct implementation is in Python, the Python API + is used to call the method of the underlying Python object (after which + the usual virtual method resolution in Python automatically finds the + right implementation).

      +

      Now how does the director decide which language should handle the + method call? The basic rule is to handle the method in Python, unless + there's a good reason not to. The reason for this is simple: Python has + the most "extended" implementation of the method. This assertion is + guaranteed, since at a minimum the Python proxy class implements the + method. If the method in question has been extended by a class derived + from the proxy class, that extended implementation will execute exactly + as it should. If not, the proxy class will route the method call into a + C wrapper function, expecting that the method will be resolved in C++. + The wrapper will call the virtual method of the C++ instance, and since + the director extends this the call will end up right back in the + director method. Now comes the "good reason not to" part. If the + director method were to blindly call the Python method again, it would + get stuck in an infinite loop. We avoid this situation by adding + special code to the C wrapper function that tells the director method + to not do this. The C wrapper function compares the pointer to the + Python object that called the wrapper function to the pointer stored by + the director. If these are the same, then the C wrapper function tells + the director to resolve the method by calling up the C++ inheritance + chain, preventing an infinite loop.

      +

      One more point needs to be made about the relationship between + director classes and proxy classes. When a proxy class instance is + created in Python, SWIG creates an instance of the original C++ class + and assigns it to .this. This is exactly what happens without + directors and is true even if directors are enabled for the particular + class in question. When a class derived 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 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++ + so there is no need for the extra overhead involved with routing the + calls through Python.

      +

      31.5.3 Ownership and object destruction

      +

      Memory management issues are slightly more complicated with + directors than for proxy classes alone. Python instances hold a pointer + to the associated C++ director object, and the director in turn holds a + pointer back to the Python object. By default, proxy classes own their + C++ director object and take care of deleting it when they are garbage + collected.

      +

      This relationship can be reversed by calling the special +__disown__() method of the proxy class. After calling this method, + the .thisown flag is set to zero, and the director class + increments the reference count of the Python object. When the director + class is deleted it decrements the reference count. Assuming no + outstanding references to the Python object remain, the Python object + will be destroyed at the same time. This is a good thing, since + directors and proxies refer to each other and so must be created and + destroyed together. Destroying one without destroying the other will + likely cause your program to segfault.

      +

      To help ensure that no references to the Python object remain after + calling __disown__(), this method returns a weak reference to + the Python object. Weak references are only available in Python + versions 2.1 and higher, so for older versions you must explicitly + delete all references. Here is an example:

      +
      +
      +class Foo {
+public:
+    ...
+};
+class FooContainer {
+public:
+    void addFoo(Foo *);
+    ...
+};
+
      +
      +
      +
      +>>> c = FooContainer()
+>>> a = Foo().__disown()__
+>>> c.addFoo(a)
+>>> b = Foo()
+>>> b = b.__disown()__
+>>> c.addFoo(b)
+>>> c.addFoo(Foo().__disown()__)
+
      +
      +

      In this example, we are assuming that FooContainer will take care of + deleting all the Foo pointers it contains at some point. Note that no + hard references to the Foo objects remain in Python.

      +

      31.5.4 Exception unrolling

      +

      With directors routing method calls to Python, and proxies routing + them to C++, the handling of exceptions is an important concern. By + default, the directors ignore exceptions that occur during method calls + that are resolved in Python. To handle such exceptions correctly, it is + necessary to temporarily translate them into C++ exceptions. This can + be done with the %feature("director:except") directive. The following + code should suffice in most cases:

      +
      +
      +%feature("director:except") {
+    if ($error != NULL) {
+        throw Swig::DirectorMethodException();
+    }
+}
+
      +
      +

      This code will check the Python error state after each method call + from a director into Python, and throw a C++ exception if an error + occurred. This exception can be caught in C++ to implement an error + handler. Currently no information about the Python error is stored in + the Swig::DirectorMethodException object, but this will likely change + in the future.

      +

      It may be the case that a method call originates in Python, travels + up to C++ through a proxy class, and then back into Python via a + director method. If an exception occurs in Python at this point, it + would be nice for that exception to find its way back to the original + caller. This can be done by combining a normal %exception directive + with the director:except handler shown above. Here is an + example of a suitable exception handler:

      +
      +
      +%exception {
+    try { $action }
+    catch (Swig::DirectorException &e) { SWIG_fail; }
+}
+
      +
      +

      The class Swig::DirectorException used in this example is actually a + base class of Swig::DirectorMethodException, so it will trap this + exception. Because the Python error state is still set when + Swig::DirectorMethodException is thrown, Python will register the + exception as soon as the C wrapper function returns.

      +

      31.5.5 Overhead and code bloat

      +

      Enabling directors for a class will generate a new director method + for every virtual method in the class' inheritance chain. This alone + can generate a lot of code bloat for large hierarchies. Method + arguments that require complex conversions to and from target language + types can result in large director methods. For this reason it is + recommended that you selectively enable directors only for specific + classes that are likely to be extended in Python and used in C++.

      +

      Compared to classes that do not use directors, the call routing in + the director methods does add some overhead. In particular, at least + one dynamic cast and one extra function call occurs per method call + from Python. Relative to the speed of Python execution this is probably + completely negligible. For worst case routing, a method call that + ultimately resolves in C++ may take one extra detour through Python in + order to ensure that the method does not have an extended Python + implementation. This could result in a noticeable overhead in some + cases.

      +

      Although directors make it natural to mix native C++ objects with + Python objects (as director objects) via a common base class pointer, + one should be aware of the obvious fact that method calls to Python + objects will be much slower than calls to C++ objects. This situation + can be optimized by selectively enabling director methods (using the + %feature directive) for only those methods that are likely to be + extended in Python.

      +

      31.5.6 Typemaps

      +

      Typemaps for input and output of most of the basic types from + director classes have been written. These are roughly the reverse of + the usual input and output typemaps used by the wrapper code. The + typemap operation names are 'directorin', 'directorout', and + 'directorargout'. The director code does not currently use any of the + other kinds of typemaps. It is not clear at this point which kinds are + appropriate and need to be supported.

      +

      31.5.7 Miscellaneous

      +

      Director typemaps for STL classes are in place, and hence you should + be able to use std::vector, std::string, etc., as you would any other + type.

      +

      Note: The director typemaps for return types based in const + references, such as

      +
      +class Foo {
+…
+    virtual const int& bar();
+…
+};
+
      +

      +

      will work only for simple call scenarios. Usually the resulting code + is neither thread or reentrant safe. Hence, the user is advised to + avoid returning const references in director methods. For example, the + user could modify the method interface to use lvalue return types, + wherever possible, for example

      +
      +
      +class Foo {
+…
+    virtual int bar();
+…
+};
+
      +
      +

      If that is not possible, the user should avoid enabling the director + feature for reentrant, recursive or threaded member methods that return + const references.

      +

      31.6 Common customization features

      +

      The last section presented the absolute basics of C/C++ wrapping. If + you do nothing but feed SWIG a header file, you will get an interface + that mimics the behavior described. However, sometimes this isn't + enough to produce a nice module. Certain types of functionality might + be missing or the interface to certain functions might be awkward. This + section describes some common SWIG features that are used to improve + your the interface to an extension module.

      +

      31.6.1 C/C++ helper functions

      +

      Sometimes when you create a module, it is missing certain bits of + functionality. For example, if you had a function like this

      +
      +
      +void set_transform(Image *im, double m[4][4]);
+
      +
      +

      it would be accessible from Python, but there may be no easy way to + call it. For example, you might get errors like this:

      +
      +
      +>>> a = [
+...   [1,0,0,0],
+...   [0,1,0,0],
+...   [0,0,1,0],
+...   [0,0,0,1]]
+>>> set_transform(im,a)
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+TypeError: Type error. Expected _p_a_4__double
+
      +
      +

      The problem here is that there is no easy way to construct and + manipulate a suitable double [4][4] value to use. To fix this, + you can write some extra C helper functions. Just use the %inline + directive. For example:

      +
      +
      +%inline %{
+/* Note: double[4][4] is equivalent to a pointer to an array double (*)[4] */
+double (*new_mat44())[4] {
+   return (double (*)[4]) malloc(16*sizeof(double));
+}
+void free_mat44(double (*x)[4]) {
+   free(x);
+}
+void mat44_set(double x[4][4], int i, int j, double v) {
+   x[i][j] = v;
+}
+double mat44_get(double x[4][4], int i, int j) {
+   return x[i][j];
+}
+%}
+
      +
      +

      From Python, you could then write code like this:

      +
      +
      +>>> a = new_mat44()
+>>> mat44_set(a,0,0,1.0)
+>>> mat44_set(a,1,1,1.0)
+>>> mat44_set(a,2,2,1.0)
+...
+>>> set_transform(im,a)
+>>>
+
      +
      +

      Admittedly, this is not the most elegant looking approach. However, + it works and it wasn't too hard to implement. It is possible to clean + this up using Python code, typemaps, and other customization features + as covered in later sections.

      +

      31.6.2 Adding additional Python code

      +

      If writing support code in C isn't enough, it is also possible to + write code in Python. This code gets inserted in to the .py + file created by SWIG. One use of Python code might be to supply a + high-level interface to certain functions. For example:

      +
      +
      +void set_transform(Image *im, double x[4][4]);
+
+...
+/* Rewrite the high level interface to set_transform */
+%pythoncode %{
+def set_transform(im,x):
+   a = new_mat44()
+   for i in range(4):
+       for j in range(4):
+           mat44_set(a,i,j,x[i][j])
+   _example.set_transform(im,a)
+   free_mat44(a)
+%}
+
      +
      +

      In this example, set_transform() provides a high-level + Python interface built on top of low-level helper functions. For + example, this code now seems to work:

      +
      +
      +>>> a = [
+...   [1,0,0,0],
+...   [0,1,0,0],
+...   [0,0,1,0],
+...   [0,0,0,1]]
+>>> set_transform(im,a)
+>>>
+
      +
      +

      Admittedly, this whole scheme for wrapping the two-dimension array + argument is rather ad-hoc. Besides, shouldn't a Python list or a + Numeric Python array just work normally? We'll get to those examples + soon enough. For now, think of this example as an illustration of what + can be done without having to rely on any of the more advanced + customization features.

      +

      Sometimes you may want to replace or modify the wrapper function that + SWIG creates in the proxy .py file. The Python module in SWIG + provides some features that enable you do do this. First, to entirely + replace a proxy function you can use %feature("shadow"). For + example:

      +
      +
      +%module example
+
+// Rewrite bar() python code
+
+%feature("shadow") Foo::bar(int) %{
+def bar(*args):
+    #do something before
+    $action
+    #do something after
+%}
+    
+class Foo {
+public:
+    int bar(int x);
+}
+
      +
      +

      where $action will be replaced by the call to the C/C++ + proper method.

      +

      Often the proxy function created by SWIG is fine, but you simply + want to add code to it without touching the rest of the generated + function body. For these cases SWIG provides the pythonprepend + and pythonappend features which do exactly as their names + suggest. The pythonprepend feature will insert its value at + the beginning of the proxy function, and pythonappend will + insert code at the end of the proxy, just before the return statement.

      +
      +
      +%module example
+
+// Add python code to bar() 
+
+%feature("pythonprepend") Foo::bar(int) %{
+   #do something before C++ call
+%}
+
+%feature("pythonappend") Foo::bar(int) %{
+   #do something after C++ call
+%}
+
+    
+class Foo {
+public:
+    int bar(int x);
+}
+
      +
      +

      Notes: Usually the pythonappend and pythonprepend + features are safer to use than the shadow feature. Also, from + SWIG version 1.3.28 you can use the directive forms %pythonappend + and %pythonprepend as follows:

      +
      +
      +%module example
+
+// Add python code to bar() 
+
+%pythonprepend Foo::bar(int) %{
+   #do something before C++ call
+%}
+
+%pythonappend Foo::bar(int) %{
+   #do something after C++ call
+%}
+
+    
+class Foo {
+public:
+    int bar(int x);
+}
+
      +
      +

      31.6.3 Class extension with %extend

      +

      One of the more interesting features of SWIG is that it can extend + structures and classes with new methods--at least in the Python + interface. Here is a simple example:

      +
      +
      +%module example
+%{
+#include "someheader.h"
+%}
+
+struct Vector {
+   double x,y,z;
+};
+
+%extend Vector {
+   char *__str__() {
+       static char tmp[1024];
+       sprintf(tmp,"Vector(%g,%g,%g)", $self->x,$self->y,$self->z);
+       return tmp;
+   }
+   Vector(double x, double y, double z) {
+       Vector *v = (Vector *) malloc(sizeof(Vector));
+       v->x = x;
+       v->y = y;
+       v->z = z;
+       return v;
+   }
+};
+
      +
      +

      Now, in Python

      +
      +
      +>>> v = example.Vector(2,3,4)
+>>> print v
+Vector(2,3,4)
+>>>
+
      +
      +

      %extend can be used for many more tasks than this. For + example, if you wanted to overload a Python operator, you might do + this:

      +
      +
      +%extend Vector {
+    Vector __add__(Vector *other) {
+         Vector v;
+         v.x = $self->x + other->x;
+         v.y = $self->y + other->y;
+         v.z = $self->z + other->z;
+         return v;
+    }
+};
+
      +
      +

      Use it like this:

      +
      +
      +>>> import example
+>>> v = example.Vector(2,3,4)
+>>> w = example.Vector(10,11,12)
+>>> print v+w
+Vector(12,14,16)
+>>> 
+
      +
      +

      %extend works with both C and C++ code. It does not modify + the underlying object in any way---the extensions only show up in the + Python interface.

      +

      31.6.4 Exception handling with %exception

      +

      If a C or C++ function throws an error, you may want to convert that + error into a Python exception. To do this, you can use the +%exception directive. %exception simply lets you rewrite + part of the generated wrapper code to include an error check.

      +

      In C, a function often indicates an error by returning a status code + (a negative number or a NULL pointer perhaps). Here is a simple example + of how you might handle that:

      +
      +
      +%exception malloc {
+  $action
+  if (!result) {
+     PyErr_SetString(PyExc_MemoryError,"Not enough memory");
+     return NULL;
+  }
+}
+void *malloc(size_t nbytes);
+
      +
      +

      In Python,

      +
      +
      +>>> a = example.malloc(2000000000)
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+MemoryError: Not enough memory
+>>>
+
      +
      +

      If a library provides some kind of general error handling framework, + you can also use that. For example:

      +
      +
      +%exception {
+   $action
+   if (err_occurred()) {
+      PyErr_SetString(PyExc_RuntimeError, err_message());
+      return NULL;
+   }
+}
+
      +
      +

      No declaration name is given to %exception, it is applied + to all wrapper functions.

      +

      C++ exceptions are also easy to handle. For example, you can write + code like this:

      +
      +
      +%exception getitem {
+   try {
+      $action
+   } catch (std::out_of_range &e) {
+      PyErr_SetString(PyExc_IndexError, const_cast<char*>(e.what()));
+      return NULL;
+   }
+}
+
+class Base {
+public:
+     Foo *getitem(int index);      // Exception handled added
+     ...
+};
+
      +
      +

      When raising a Python exception from C, use the +PyErr_SetString() function as shown above. The following exception + types can be used as the first argument.

      +
      +
      +PyExc_ArithmeticError
+PyExc_AssertionError
+PyExc_AttributeError
+PyExc_EnvironmentError
+PyExc_EOFError
+PyExc_Exception
+PyExc_FloatingPointError
+PyExc_ImportError
+PyExc_IndexError
+PyExc_IOError
+PyExc_KeyError
+PyExc_KeyboardInterrupt
+PyExc_LookupError
+PyExc_MemoryError
+PyExc_NameError
+PyExc_NotImplementedError
+PyExc_OSError
+PyExc_OverflowError
+PyExc_RuntimeError
+PyExc_StandardError
+PyExc_SyntaxError
+PyExc_SystemError
+PyExc_TypeError
+PyExc_UnicodeError
+PyExc_ValueError
+PyExc_ZeroDivisionError
+
      +
      +

      The language-independent exception.i library file can also + be used to raise exceptions. See the SWIG Library + chapter.

      +

      31.7 Tips and techniques

      +

      Although SWIG is largely automatic, there are certain types of + wrapping problems that require additional user input. Examples include + dealing with output parameters, strings, binary data, and arrays. This + chapter discusses the common techniques for solving these problems.

      +

      31.7.1 Input and output parameters

      +

      A common problem in some C programs is handling parameters passed as + simple pointers. For example:

      +
      +
      +void add(int x, int y, int *result) {
+   *result = x + y;
+}
+
      +
      +

      or perhaps

      +
      +
      +int sub(int *x, int *y) {
+   return *x-*y;
+}
+
      +
      +

      The easiest way to handle these situations is to use the +typemaps.i file. For example:

      +
      +
      +%module example
+%include "typemaps.i"
+
+void add(int, int, int *OUTPUT);
+int  sub(int *INPUT, int *INPUT);
+
      +
      +

      In Python, this allows you to pass simple values. For example:

      +
      +
      +>>> a = add(3,4)
+>>> print a
+7
+>>> b = sub(7,4)
+>>> print b
+3
+>>>
+
      +
      +

      Notice how the INPUT parameters allow integer values to be + passed instead of pointers and how the OUTPUT parameter + creates a return result.

      +

      If you don't want to use the names INPUT or OUTPUT +, use the %apply directive. For example:

      +
      +
      +%module example
+%include "typemaps.i"
+
+%apply int *OUTPUT { int *result };
+%apply int *INPUT  { int *x, int *y};
+
+void add(int x, int y, int *result);
+int  sub(int *x, int *y);
+
      +
      +

      If a function mutates one of its parameters like this,

      +
      +
      +void negate(int *x) {
+   *x = -(*x);
+}
+
      +
      +

      you can use INOUT like this:

      +
      +
      +%include "typemaps.i"
+...
+void negate(int *INOUT);
+
      +
      +

      In Python, a mutated parameter shows up as a return value. For + example:

      +
      +
      +>>> a = negate(3)
+>>> print a
+-3
+>>>
+
      +
      +

      Note: Since most primitive Python objects are immutable, it is not + possible to perform in-place modification of a Python object passed as + a parameter.

      +

      The most common use of these special typemap rules is to handle + functions that return more than one value. For example, sometimes a + function returns a result as well as a special error code:

      +
      +
      +/* send message, return number of bytes sent, along with success code */
+int send_message(char *text, int len, int *success);
+
      +
      +

      To wrap such a function, simply use the OUTPUT rule above. + For example:

      +
      +
      +%module example
+%include "typemaps.i"
+%apply int *OUTPUT { int *success };
+...
+int send_message(char *text, int *success);
+
      +
      +

      When used in Python, the function will return multiple values.

      +
      +
      +bytes, success = send_message("Hello World")
+if not success:
+    print "Whoa!"
+else:
+    print "Sent", bytes
+
      +
      +

      Another common use of multiple return values are in query functions. + For example:

      +
      +
      +void get_dimensions(Matrix *m, int *rows, int *columns);
+
      +
      +

      To wrap this, you might use the following:

      +
      +
      +%module example
+%include "typemaps.i"
+%apply int *OUTPUT { int *rows, int *columns };
+...
+void get_dimensions(Matrix *m, int *rows, *columns);
+
      +
      +

      Now, in Python:

      +
      +
      +>>> r,c = get_dimensions(m)
+
      +
      +

      Be aware that the primary purpose of the typemaps.i file is + to support primitive datatypes. Writing a function like this

      +
      +
      +void foo(Bar *OUTPUT);
+
      +
      +

      may not have the intended effect since typemaps.i does not + define an OUTPUT rule for Bar.

      +

      31.7.2 Simple pointers

      +

      If you must work with simple pointers such as int * or +double * and you don't want to use typemaps.i, consider + using the cpointer.i library file. For example:

      +
      +
      +%module example
+%include "cpointer.i"
+
+%inline %{
+extern void add(int x, int y, int *result);
+%}
+
+%pointer_functions(int, intp);
+
      +
      +

      The %pointer_functions(type,name) macro generates five + helper functions that can be used to create, destroy, copy, assign, and + dereference a pointer. In this case, the functions are as follows:

      +
      +
      +int  *new_intp();
+int  *copy_intp(int *x);
+void  delete_intp(int *x);
+void  intp_assign(int *x, int value);
+int   intp_value(int *x);
+
      +
      +

      In Python, you would use the functions like this:

      +
      +
      +>>> result = new_intp()
+>>> print result
+_108fea8_p_int
+>>> add(3,4,result)
+>>> print intp_value(result)
+7
+>>>
+
      +
      +

      If you replace %pointer_functions() by +%pointer_class(type,name), the interface is more class-like.

      +
      +
      +>>> result = intp()
+>>> add(3,4,result)
+>>> print result.value()
+7
+
      +
      +

      See the SWIG Library chapter for further + details.

      +

      31.7.3 Unbounded C Arrays

      +

      Sometimes a C function expects an array to be passed as a pointer. + For example,

      +
      +
      +int sumitems(int *first, int nitems) {
+    int i, sum = 0;
+    for (i = 0; i < nitems; i++) {
+        sum += first[i];
+    }
+    return sum;
+}
+
      +
      +

      To wrap this into Python, you need to pass an array pointer as the + first argument. A simple way to do this is to use the carrays.i + library file. For example:

      +
      +
      +%include "carrays.i"
+%array_class(int, intArray);
+
      +
      +

      The %array_class(type, name) macro creates wrappers for an + unbounded array object that can be passed around as a simple pointer + like int * or double *. For instance, you will be + able to do this in Python:

      +
      +
      +>>> a = intArray(10000000)         # Array of 10-million integers
+>>> for i in xrange(10000):        # Set some values
+...     a[i] = i
+>>> sumitems(a,10000)
+49995000
+>>>
+
      +
      +

      The array "object" created by %array_class() does not + encapsulate pointers inside a special array object. In fact, there is + no bounds checking or safety of any kind (just like in C). Because of + this, the arrays created by this library are extremely low-level + indeed. You can't iterate over them nor can you even query their + length. In fact, any valid memory address can be accessed if you want + (negative indices, indices beyond the end of the array, etc.). Needless + to say, this approach is not going to suit all applications. On the + other hand, this low-level approach is extremely efficient and well + suited for applications in which you need to create buffers, package + binary data, etc.

      +

      31.7.4 String handling

      +

      If a C function has an argument of char *, then a Python + string can be passed as input. For example:

      +
      +
      +// C
+void foo(char *s);
+
      +
      +
      +# Python
+>>> foo("Hello")
+
      +
      +

      When a Python string is passed as a parameter, the C function + receives a pointer to the raw data contained in the string. Since + Python strings are immutable, it is illegal for your program to change + the value. In fact, doing so will probably crash the Python + interpreter.

      +

      If your program modifies the input parameter or uses it to return + data, consider using the cstring.i library file described in + the SWIG Library chapter.

      +

      When functions return a char *, it is assumed to be a + NULL-terminated string. Data is copied into a new Python string and + returned.

      +

      If your program needs to work with binary data, you can use a + typemap to expand a Python string into a pointer/length argument pair. + As luck would have it, just such a typemap is already defined. Just do + this:

      +
      +
      +%apply (char *STRING, int LENGTH) { (char *data, int size) };
+...
+int parity(char *data, int size, int initial);
+
      +
      +

      Now in Python:

      +
      +
      +>>> parity("e\x09ffss\x00\x00\x01\nx", 0)
+
      +
      +

      If you need to return binary data, you might use the cstring.i + library file. The cdata.i library can also be used to extra + binary data from arbitrary pointers.

      +

      31.7.5 Arrays

      +

      31.7.6 String arrays

      +

      31.7.7 STL wrappers

      +

      31.8 Typemaps

      +

      This section describes how you can modify SWIG's default wrapping + behavior for various C/C++ datatypes using the %typemap + directive. This is an advanced topic that assumes familiarity with the + Python C API as well as the material in the " +Typemaps" chapter.

      +

      Before proceeding, it should be stressed that typemaps are not a + required part of using SWIG---the default wrapping behavior is enough + in most cases. Typemaps are only used if you want to change some aspect + of the primitive C-Python interface or if you want to elevate your guru + status.

      +

      31.8.1 What is a typemap?

      +

      A typemap is nothing more than a code generation rule that is + attached to a specific C datatype. For example, to convert integers + from Python to C, you might define a typemap like this:

      +
      +
      +%module example
+
+%typemap(in) int {
+	$1 = (int) PyLong_AsLong($input);
+	printf("Received an integer : %d\n",$1);
+}
+%inline %{
+extern int fact(int n);
+%}
+
      +
      +

      Typemaps are always associated with some specific aspect of code + generation. In this case, the "in" method refers to the conversion of + input arguments to C/C++. The datatype int is the datatype to + which the typemap will be applied. The supplied C code is used to + convert values. In this code a number of special variable prefaced by a + $ are used. The $1 variable is placeholder for a + local variable of type int. The $input variable is + the input object of type PyObject *.

      +

      When this example is compiled into a Python module, it operates as + follows:

      +
      +
      +>>> from example import *
+>>> fact(6)
+Received an integer : 6
+720
+
      +
      +

      In this example, the typemap is applied to all occurrences of the +int datatype. You can refine this by supplying an optional + parameter name. For example:

      +
      +
      +%module example
+
+%typemap(in) int nonnegative {
+	$1 = (int) PyLong_AsLong($input);
+        if ($1 < 0) {
+           PyErr_SetString(PyExc_ValueError,"Expected a nonnegative value.");
+           return NULL;
+        }
+}
+%inline %{
+extern int fact(int nonnegative);
+%}
+
      +
      +

      In this case, the typemap code is only attached to arguments that + exactly match int nonnegative.

      +

      The application of a typemap to specific datatypes and argument + names involves more than simple text-matching--typemaps are fully + integrated into the SWIG C++ type-system. When you define a typemap for + int, that typemap applies to int and qualified + variations such as const int. In addition, the typemap system + follows typedef declarations. For example:

      +
      +
      +%typemap(in) int n {
+	$1 = (int) PyLong_AsLong($input);
+	printf("n = %d\n",$1);
+}
+%inline %{
+typedef int Integer;
+extern int fact(Integer n);    // Above typemap is applied
+%}
+
      +
      +

      Typemaps can also be defined for groups of consecutive arguments. + For example:

      +
      +
      +%typemap(in) (char *str, int len) {
+    $1 = PyString_AsString($input);
+    $2 = PyString_Size($input);
+};
+
+int count(char c, char *str, int len);
+
      +
      +

      When a multi-argument typemap is defined, the arguments are always + handled as a single Python object. This allows the function to be used + like this (notice how the length parameter is omitted):

      +
      +
      +>>> example.count('e','Hello World')
+1
+>>>
+
      +
      +

      31.8.2 Python typemaps

      +

      The previous section illustrated an "in" typemap for converting + Python objects to C. A variety of different typemap methods are defined + by the Python module. For example, to convert a C integer back into a + Python object, you might define an "out" typemap like this:

      +
      +
      +%typemap(out) int {
+    $result = PyInt_FromLong((long) $1);
+}
+
      +
      +

      A detailed list of available methods can be found in the " +Typemaps" chapter.

      +

      However, the best source of typemap information (and examples) is + probably the Python module itself. In fact, all of SWIG's default type + handling is defined by typemaps. You can view these typemaps by looking + at the files in the SWIG library. Just take into account that in the + latest versions of swig (1.3.22+), the library files are not very + pristine clear for the casual reader, as they used to be. The extensive + use of macros and other ugly techniques in the latest version produce a + very powerful and consistent python typemap library, but at the cost of + simplicity and pedagogic value.

      +

      To learn how to write a simple or your first typemap, you better + take a look at the SWIG library version 1.3.20 or so.

      +

      31.8.3 Typemap variables

      +

      Within typemap code, a number of special variables prefaced with a +$ may appear. A full list of variables can be found in the " +Typemaps" chapter. This is a list of the most common variables:

      +

      $1

      +
      A C local variable corresponding to the actual type + specified in the %typemap directive. For input values, this is + a C local variable that's supposed to hold an argument value. For + output values, this is the raw result that's supposed to be returned to + Python.
      +

      $input

      +
      A PyObject * holding a raw Python object + with an argument or variable value.
      +

      $result

      +
      A PyObject * that holds the result to be + returned to Python.
      +

      $1_name

      +
      The parameter name that was matched.
      +

      $1_type

      +
      The actual C datatype matched by the typemap.
      +

      $1_ltype

      +
      An assignable version of the datatype matched by + the typemap (a type that can appear on the left-hand-side of a C + assignment operation). This type is stripped of qualifiers and may be + an altered version of $1_type. All arguments and local + variables in wrapper functions are declared using this type so that + their values can be properly assigned.
      +

      $symname

      +
      The Python name of the wrapper function being + created.
      +

      31.8.4 Useful Python Functions

      +

      When you write a typemap, you usually have to work directly with + Python objects. The following functions may prove to be useful.

      +

      Python Integer Functions

      +
      +
      +PyObject *PyInt_FromLong(long l);
+long      PyInt_AsLong(PyObject *);
+int       PyInt_Check(PyObject *);
+
      +
      +

      Python Floating Point Functions

      +
      +
      +PyObject *PyFloat_FromDouble(double);
+double    PyFloat_AsDouble(PyObject *);
+int       PyFloat_Check(PyObject *);
+
      +
      +

      Python String Functions

      +
      +
      +PyObject *PyString_FromString(char *);
+PyObject *PyString_FromStringAndSize(char *, lint len);
+int       PyString_Size(PyObject *);
+char     *PyString_AsString(PyObject *);
+int       PyString_Check(PyObject *);
+
      +
      +

      Python List Functions

      +
      +
      +PyObject *PyList_New(int size);
+int       PyList_Size(PyObject *list);
+PyObject *PyList_GetItem(PyObject *list, int i);
+int       PyList_SetItem(PyObject *list, int i, PyObject *item);
+int       PyList_Insert(PyObject *list, int i, PyObject *item);
+int       PyList_Append(PyObject *list, PyObject *item);
+PyObject *PyList_GetSlice(PyObject *list, int i, int j);
+int       PyList_SetSlice(PyObject *list, int i, int , PyObject *list2);
+int       PyList_Sort(PyObject *list);
+int       PyList_Reverse(PyObject *list);
+PyObject *PyList_AsTuple(PyObject *list);
+int       PyList_Check(PyObject *);
+
      +
      +

      Python Tuple Functions

      +
      +
      +PyObject *PyTuple_New(int size);
+int       PyTuple_Size(PyObject *);
+PyObject *PyTuple_GetItem(PyObject *, int i);
+int       PyTuple_SetItem(PyObject *, int i, PyObject *item);
+PyObject *PyTuple_GetSlice(PyObject *t, int i, int j);
+int       PyTuple_Check(PyObject *);
+
      +
      +

      Python Dictionary Functions

      +
      +
      +PyObject *PyDict_New();
+int       PyDict_Check(PyObject *);
+int       PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val);
+int       PyDict_SetItemString(PyObject *p, const char *key, PyObject *val);
+int       PyDict_DelItem(PyObject *p, PyObject *key);
+int       PyDict_DelItemString(PyObject *p, char *key);
+PyObject* PyDict_Keys(PyObject *p);
+PyObject* PyDict_Values(PyObject *p);
+PyObject* PyDict_GetItem(PyObject *p, PyObject *key);
+PyObject* PyDict_GetItemString(PyObject *p, const char *key);
+int       PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue);
+Py_ssize_t PyDict_Size(PyObject *p);
+int       PyDict_Update(PyObject *a, PyObject *b);
+int       PyDict_Merge(PyObject *a, PyObject *b, int override);
+PyObject* PyDict_Items(PyObject *p);
+
      +
      +

      Python File Conversion Functions

      +
      +
      +PyObject *PyFile_FromFile(FILE *f);
+FILE     *PyFile_AsFile(PyObject *);
+int       PyFile_Check(PyObject *);
+
      +
      +

      Abstract Object Interface

      +
      +
      +write me
+
      +
      +

      31.9 Typemap Examples

      +

      This section includes a few examples of typemaps. For more examples, + you might look at the files "python.swg" and "typemaps.i +" in the SWIG library.

      +

      31.9.1 Converting Python list to a char **

      +

      A common problem in many C programs is the processing of command + line arguments, which are usually passed in an array of NULL terminated + strings. The following SWIG interface file allows a Python list object + to be used as a char ** object.

      +
      +
      +%module argv
+
+// This tells SWIG to treat char ** as a special case
+%typemap(in) char ** {
+  /* Check if is a list */
+  if (PyList_Check($input)) {
+    int size = PyList_Size($input);
+    int i = 0;
+    $1 = (char **) malloc((size+1)*sizeof(char *));
+    for (i = 0; i < size; i++) {
+      PyObject *o = PyList_GetItem($input,i);
+      if (PyString_Check(o))
+	$1[i] = PyString_AsString(PyList_GetItem($input,i));
+      else {
+	PyErr_SetString(PyExc_TypeError,"list must contain strings");
+	free($1);
+	return NULL;
+      }
+    }
+    $1[i] = 0;
+  } else {
+    PyErr_SetString(PyExc_TypeError,"not a list");
+    return NULL;
+  }
+}
+
+// This cleans up the char ** array we malloc'd before the function call
+%typemap(freearg) char ** {
+  free((char *) $1);
+}
+
+// Now a test function
+%inline %{
+int print_args(char **argv) {
+    int i = 0;
+    while (argv[i]) {
+         printf("argv[%d] = %s\n", i,argv[i]);
+         i++;
+    }
+    return i;
+}
+%}
+
+
      +
      +

      When this module is compiled, the wrapped C function now operates as + follows :

      +
      +
      +>>> from argv import *
+>>> print_args(["Dave","Mike","Mary","Jane","John"])
+argv[0] = Dave
+argv[1] = Mike
+argv[2] = Mary
+argv[3] = Jane
+argv[4] = John
+5
+
      +
      +

      In the example, two different typemaps are used. The "in" typemap is + used to receive an input argument and convert it to a C array. Since + dynamic memory allocation is used to allocate memory for the array, the + "freearg" typemap is used to later release this memory after the + execution of the C function.

      +

      31.9.2 Expanding a Python object into + multiple arguments

      +

      Suppose that you had a collection of C functions with arguments such + as the following:

      +
      +
      +int foo(int argc, char **argv);
+
      +
      +

      In the previous example, a typemap was written to pass a Python list + as the char **argv. This allows the function to be used from + Python as follows:

      +
      +
      +>>> foo(4, ["foo","bar","spam","1"])
+
      +
      +

      Although this works, it's a little awkward to specify the argument + count. To fix this, a multi-argument typemap can be defined. This is + not very difficult--you only have to make slight modifications to the + previous example:

      +
      +
      +%typemap(in) (int argc, char **argv) {
+  /* Check if is a list */
+  if (PyList_Check($input)) {
+    int i;
+    $1 = PyList_Size($input);
+    $2 = (char **) malloc(($1+1)*sizeof(char *));
+    for (i = 0; i < $1; i++) {
+      PyObject *o = PyList_GetItem($input,i);
+      if (PyString_Check(o))
+	$2[i] = PyString_AsString(PyList_GetItem($input,i));
+      else {
+	PyErr_SetString(PyExc_TypeError,"list must contain strings");
+	free($2);
+	return NULL;
+      }
+    }
+    $2[i] = 0;
+  } else {
+    PyErr_SetString(PyExc_TypeError,"not a list");
+    return NULL;
+  }
+}
+
+%typemap(freearg) (int argc, char **argv) {
+  free((char *) $2);
+}
+
      +
      +

      When writing a multiple-argument typemap, each of the types is + referenced by a variable such as $1 or $2. The + typemap code simply fills in the appropriate values from the supplied + Python object.

      +

      With the above typemap in place, you will find it no longer + necessary to supply the argument count. This is automatically set by + the typemap code. For example:

      +
      +
      +>>> foo(["foo","bar","spam","1"])
+
      +
      +

      31.9.3 Using typemaps to return arguments

      +

      A common problem in some C programs is that values may be returned + in arguments rather than in the return value of a function. For + example:

      +
      +
      +/* Returns a status value and two values in out1 and out2 */
+int spam(double a, double b, double *out1, double *out2) {
+	... Do a bunch of stuff ...
+	*out1 = result1;
+	*out2 = result2;
+	return status;
+};
+
+
      +
      +

      A typemap can be used to handle this case as follows :

      +
      +
      +%module outarg
+
+// This tells SWIG to treat an double * argument with name 'OutValue' as
+// an output value.  We'll append the value to the current result which 
+// is guaranteed to be a List object by SWIG.
+
+%typemap(argout) double *OutValue {
+    PyObject *o, *o2, *o3;
+    o = PyFloat_FromDouble(*$1);
+    if ((!$result) || ($result == Py_None)) {
+        $result = o;
+    } else {
+        if (!PyTuple_Check($result)) {
+            PyObject *o2 = $result;
+            $result = PyTuple_New(1);
+            PyTuple_SetItem(target,0,o2);
+        }
+        o3 = PyTuple_New(1);
+        PyTuple_SetItem(o3,0,o);
+        o2 = $result;
+        $result = PySequence_Concat(o2,o3);
+        Py_DECREF(o2);
+        Py_DECREF(o3);
+    }
+}
+
+int spam(double a, double b, double *OutValue, double *OutValue);
+
+
      +
      +

      The typemap works as follows. First, a check is made to see if any + previous result exists. If so, it is turned into a tuple and the new + output value is concatenated to it. Otherwise, the result is returned + normally. For the sample function spam(), there are three + output values--meaning that the function will return a 3-tuple of the + results.

      +

      As written, the function must accept 4 arguments as input values, + last two being pointers to doubles. If these arguments are only used to + hold output values (and have no meaningful input value), an additional + typemap can be written. For example:

      +
      +
      +%typemap(in,numinputs=0) double *OutValue(double temp) {
+    $1 = &temp;
+}
+
+
      +
      +

      By specifying numinputs=0, the input value is ignored. However, + since the argument still has to be set to some meaningful value before + calling C, it is set to point to a local variable temp. When + the function stores its output value, it will simply be placed in this + local variable. As a result, the function can now be used as follows:

      +
      +
      +>>> a = spam(4,5)
+>>> print a
+(0, 2.45, 5.0)
+>>> x,y,z = spam(4,5)
+>>>
+
      +
      +

      31.9.4 Mapping Python tuples into small + arrays

      +

      In some applications, it is sometimes desirable to pass small arrays + of numbers as arguments. For example :

      +
      +
      +extern void set_direction(double a[4]);       // Set direction vector
+
      +
      +

      This too, can be handled used typemaps as follows :

      +
      +
      +// Grab a 4 element array as a Python 4-tuple
+%typemap(in) double[4](double temp[4]) {   // temp[4] becomes a local variable
+  int i;
+  if (PyTuple_Check($input)) {
+    if (!PyArg_ParseTuple($input,"dddd",temp,temp+1,temp+2,temp+3)) {
+      PyErr_SetString(PyExc_TypeError,"tuple must have 4 elements");
+      return NULL;
+    }
+    $1 = &temp[0];
+  } else {
+    PyErr_SetString(PyExc_TypeError,"expected a tuple.");
+    return NULL;
+  }
+}
+
+
      +
      +

      This allows our set_direction function to be called from + Python as follows :

      +
      +
      +>>> set_direction((0.5,0.0,1.0,-0.25))
+
      +
      +

      Since our mapping copies the contents of a Python tuple into a C + array, such an approach would not be recommended for huge arrays, but + for small structures, this approach works fine.

      +

      31.9.5 Mapping sequences to C arrays

      +

      Suppose that you wanted to generalize the previous example to handle + C arrays of different sizes. To do this, you might write a typemap as + follows:

      +
      +
      +// Map a Python sequence into any sized C double array
+%typemap(in) double[ANY](double temp[$1_dim0]) {
+  int i;
+  if (!PySequence_Check($input)) {
+      PyErr_SetString(PyExc_TypeError,"Expecting a sequence");
+      return NULL;
+  }
+  if (PyObject_Length($input) != $1_dim0) {
+      PyErr_SetString(PyExc_ValueError,"Expecting a sequence with $1_dim0 elements");
+      return NULL;
+  }
+  for (i =0; i < $1_dim0; i++) {
+      PyObject *o = PySequence_GetItem($input,i);
+      if (!PyFloat_Check(o)) {
+         Py_XDECREF(o);
+         PyErr_SetString(PyExc_ValueError,"Expecting a sequence of floats");
+         return NULL;
+      }
+      temp[i] = PyFloat_AsDouble(o);
+      Py_DECREF(o);
+  }
+  $1 = &temp[0];
+}
+
      +
      +

      In this case, the variable $1_dim0 is expanded to match the + array dimensions actually used in the C code. This allows the typemap + to be applied to types such as:

      +
      +
      +void foo(double x[10]);
+void bar(double a[4], double b[8]);
+
      +
      +

      Since the above typemap code gets inserted into every wrapper + function where used, it might make sense to use a helper function + instead. This will greatly reduce the amount of wrapper code. For + example:

      +
      +
      +%{
+static int convert_darray(PyObject *input, double *ptr, int size) {
+  int i;
+  if (!PySequence_Check(input)) {
+      PyErr_SetString(PyExc_TypeError,"Expecting a sequence");
+      return 0;
+  }
+  if (PyObject_Length(input) != size) {
+      PyErr_SetString(PyExc_ValueError,"Sequence size mismatch");
+      return 0;
+  }
+  for (i =0; i < size; i++) {
+      PyObject *o = PySequence_GetItem(input,i);
+      if (!PyFloat_Check(o)) {
+         Py_XDECREF(o);
+         PyErr_SetString(PyExc_ValueError,"Expecting a sequence of floats");
+         return 0;
+      }
+      ptr[i] = PyFloat_AsDouble(o);
+      Py_DECREF(o);
+  }
+  return 1;
+}
+%}
+
+%typemap(in) double [ANY](double temp[$1_dim0]) {
+   if (!convert_darray($input,temp,$1_dim0))) {
+      return NULL;
+   }
+   $1 = &temp[0];
+}
+
      +
      +

      31.9.6 Pointer handling

      +

      Occasionally, it might be necessary to convert pointer values that + have been stored using the SWIG typed-pointer representation. Since + there are several ways in which pointers can be represented, the + following two functions are used to safely perform this conversion:

      +

      int SWIG_ConvertPtr(PyObject *obj, void **ptr, swig_type_info + *ty, int flags)

      +
      Converts a Python object obj to a C + pointer. The result of the conversion is placed into the pointer + located at ptr. ty is a SWIG type descriptor + structure. flags is used to handle error checking and other + aspects of conversion. It is the bitwise-or of several flag values + including SWIG_POINTER_EXCEPTION and SWIG_POINTER_DISOWN +. The first flag makes the function raise an exception on type error. + The second flag additionally steals ownership of an object. Returns 0 + on success and -1 on error.
      +

      PyObject *SWIG_NewPointerObj(void *ptr, swig_type_info *ty, int + own)

      +
      Creates a new Python pointer object. ptr + is the pointer to convert, ty is the SWIG type descriptor + structure that describes the type, and own is a flag that + indicates whether or not Python should take ownership of the pointer.
      +

      Both of these functions require the use of a special SWIG + type-descriptor structure. This structure contains information about + the mangled name of the datatype, type-equivalence information, as well + as information about converting pointer values under C++ inheritance. + For a type of Foo *, the type descriptor structure is usually + accessed as follows:

      +
      +
      +Foo *f;
+if (SWIG_ConvertPtr($input, (void **) &f, SWIGTYPE_p_Foo, SWIG_POINTER_EXCEPTION) == -1)
+  return NULL;
+
+PyObject *obj;
+obj = SWIG_NewPointerObj(f, SWIGTYPE_p_Foo, 0);
+
      +
      +

      In a typemap, the type descriptor should always be accessed using + the special typemap variable $1_descriptor. For example:

      +
      +
      +%typemap(in) Foo * {
+if ((SWIG_ConvertPtr($input,(void **) &$1, $1_descriptor,SWIG_POINTER_EXCEPTION)) == -1)
+  return NULL;
+}
+
      +
      +

      If necessary, the descriptor for any type can be obtained using the +$descriptor() macro in a typemap. For example:

      +
      +
      +%typemap(in) Foo * {
+if ((SWIG_ConvertPtr($input,(void **) &$1, $descriptor(Foo *), 
+                                               SWIG_POINTER_EXCEPTION)) == -1)
+  return NULL;
+}
+
      +
      +

      Although the pointer handling functions are primarily intended for + manipulating low-level pointers, both functions are fully aware of + Python proxy classes. Specifically, SWIG_ConvertPtr() will + retrieve a pointer from any object that has a this attribute. + In addition, SWIG_NewPointerObj() can automatically generate a + proxy class object (if applicable).

      +

      31.10 Docstring Features

      +

      Using docstrings in Python code is becoming more and more important + and more tools are coming on the scene that take advantage of them, + everything from full-blown documentation generators to class browsers + and popup call-tips in Python-aware IDEs. Given the way that SWIG + generates the proxy code by default, your users will normally get + something like "function_name(*args)" in the popup calltip of + their IDE which is next to useless when the real function prototype + might be something like this:

      +
      +
      +bool function_name(int x, int y, Foo* foo=NULL, Bar* bar=NULL);
+
      +
      +

      The features described in this section make it easy for you to add + docstrings to your modules, functions and methods that can then be used + by the various tools out there to make the programming experience of + your users much simpler.

      +

      31.10.1 Module docstring

      +

      Python allows a docstring at the beginning of the .py file + before any other statements, and it is typically used to give a general + description of the entire module. SWIG supports this by setting an + option of the %module directive. For example:

      +
      +
      +%module(docstring="This is the example module's docstring") example
+
      +
      +

      When you have more than just a line or so then you can retain the + easy readability of the %module directive by using a macro. + For example:

      +
      +
      +%define DOCSTRING
+"The `XmlResource` class allows program resources defining menus, 
+layout of controls on a panel, etc. to be loaded from an XML file."
+%enddef
+
+%module(docstring=DOCSTRING) xrc
+
      +
      +

      31.10.2 %feature("autodoc")

      +

      As alluded to above SWIG will generate all the function and method + proxy wrappers with just "*args" (or "*args, **kwargs" if the -keyword + option is used) for a parameter list and will then sort out the + individual parameters in the C wrapper code. This is nice and simple + for the wrapper code, but makes it difficult to be programmer and tool + friendly as anyone looking at the .py file will not be able to + find out anything about the parameters that the functions accept.

      +

      But since SWIG does know everything about the function it is possible + to generate a docstring containing the parameter types, names and + default values. Since many of the docstring tools are adopting a + standard of recognizing if the first thing in the docstring is a + function prototype then using that instead of what they found from + introspection, then life is good once more.

      +

      SWIG's Python module provides support for the "autodoc" feature, + which when attached to a node in the parse tree will cause a docstring + to be generated that includes the name of the function, parameter + names, default values if any, and return type if any. There are also + three options for autodoc controlled by the value given to the feature, + described below.

      +

      31.10.2.1 %feature("autodoc", "0")

      +

      When the "0" option is given then the types of the parameters will + not be included in the autodoc string. For example, given this + function prototype:

      +
      +
      +%feature("autodoc", "0");
+bool function_name(int x, int y, Foo* foo=NULL, Bar* bar=NULL);
+
      +
      +

      Then Python code like this will be generated:

      +
      +
      +def function_name(*args, **kwargs):
+    """function_name(x, y, foo=None, bar=None) -> bool"""
+    ...
+
      +
      +

      31.10.2.2 %feature("autodoc", "1")

      +

      When the "1" option is used then the parameter types will + be used in the autodoc string. In addition, an attempt is made to + simplify the type name such that it makes more sense to the Python + user. Pointer, reference and const info is removed, %rename's + are evaluated, etc. (This is not always successful, but works most of + the time. See the next section for what to do when it doesn't.) Given + the example above, then turning on the parameter types with the "1" + option will result in Python code like this:

      +
      +
      +def function_name(*args, **kwargs):
+    """function_name(int x, int y, Foo foo=None, Bar bar=None) -> bool"""
+    ...
+
      +
      +

      31.10.2.3 %feature("autodoc", "docstring")

      +

      Finally, there are times when the automatically generated autodoc + string will make no sense for a Python programmer, particularly when a + typemap is involved. So if you give an explicit value for the autodoc + feature then that string will be used in place of the automatically + generated string. For example:

      +
      +
      +%feature("autodoc", "GetPosition() -> (x, y)") GetPosition;
+void GetPosition(int* OUTPUT, int* OUTPUT);
+
      +
      +

      31.10.3 %feature("docstring")

      +

      In addition to the autodoc strings described above, you can also + attach any arbitrary descriptive text to a node in the parse tree with + the "docstring" feature. When the proxy module is generated then any + docstring associated with classes, function or methods are output. If + an item already has an autodoc string then it is combined with the + docstring and they are output together. If the docstring is all on a + single line then it is output like this::

      +
      +
      +"""This is the docstring"""
+
      +
      +

      Otherwise, to aid readability it is output like this:

      +
      +
      +"""
+This is a multi-line docstring
+with more than one line.
+"""
+
      +
      +

      31.11 Python Packages

      +

      Using the package option of the %module directive + allows you to specify what Python package that the module will be + living in when installed.

      +
      +
      +%module(package="wx") xrc
+
      +
      +

      This is useful when the .i file is %imported by + another .i file. By default SWIG will assume that the importer + is able to find the importee with just the module name, but if they + live in separate Python packages then that won't work. However if the + importee specifies what its package is with the %module option + then the Python code generated for the importer will use that package + name when importing the other module and also in base class + declarations, etc. if the package name is different than its own.

      +

      31.12 Python 3 Support

      +

      SWIG is able to support Python 3.0. The wrapper code generated by + SWIG can be compiled with both Python 2.x or 3.0. Further more, by + passing the -py3 command line option to SWIG, wrapper code + with some Python 3 specific features can be generated (see below + subsections for details of these features). The -py3 option + also disables some incompatible features for Python 3, such as +-classic.

      +

      There is a list of known-to-be-broken features in Python 3:

      +
        +
      • No more support for FILE* typemaps, because PyFile_AsFile has been + dropped in Python 3.
        • +
      • The -apply command line option is removed and generating + code using apply() is no longer supported.
        • +
      +

      The following are Python 3.0 new features that are currently + supported by SWIG.

      +

      31.12.1 Function annotation

      +

      The -py3 option will enable function annotation support. + When used SWIG is able to generate proxy method definitions like this:

      +
      +
      +  def foo(self, bar : "int" = 0) -> "void" : ...
+
      +
      +

      Also, even if without passing SWIG the -py3 option, the + parameter list still could be generated:

      +
      +
      +  def foo(self, bar = 0): ...
+
      +
      +

      But for overloaded function or method, the parameter list would + fallback to *args or self, *args, and **kwargs + may be append depend on whether you enabled the keyword argument. This + fallback is due to all overloaded functions share the same function in + SWIG generated proxy class.

      +

      For detailed usage of function annotation, see PEP 3107.

      +

      31.12.2 Buffer interface

      +

      Buffer protocols were revised in Python 3. SWIG also gains a series + of new typemaps to support buffer interfaces. These typemap macros are + defined in pybuffer.i, which must be included in order to use + them. By using these typemaps, your wrapped function will be able to + accept any Python object that exposes a suitable buffer interface.

      +

      For example, the get_path() function puts the path string + into the memory pointed to by its argument:

      +
      +
      +void get_path(char *s);
+
      +
      +

      Then you can write a typemap like this: (the following example is + applied to both Python 3.0 and 2.6, since the bytearray type + is backported to 2.6.

      +
      +
      +%include <pybuffer.i>
+%pybuffer_mutable_string(char *str);
+void get_path(char *s);
+
      +
      +

      And then on the Python side the wrapped get_path could be + used in this way:

      +
      +
      +>>> p = bytearray(10)
+>>> get_path(p)
+>>> print(p)
+bytearray(b'/Foo/Bar/\x00')
+
      +
      +

      The macros defined in pybuffer.i are similar to those in +cstring.i:

      +

      %pybuffer_mutable_binary(parm, size_parm)

      +
      +

      The macro can be used to generate a typemap which maps a buffer of + an object to a pointer provided by parm and a size argument + provided by size_parm. For example:

      +
      +
      +%pybuffer_mutable_binary(char *str, size_t size);
+...
+int snprintf(char *str, size_t size, const char *format, ...);
+
      +
      +

      In Python:

      +
      +
      +>>> buf = bytearray(6)
+>>> snprintf(buf, "Hello world!")
+>>> print(buf)
+bytearray(b'Hello\x00')
+>>> 
+
      +
      +

      %pybuffer_mutable_string(parm)

      +
      +

      This typemap macro requires the buffer to be a zero terminated + string, and maps the pointer of the buffer to parm. For + example:

      +
      +
      +%pybuffer_mutable_string(char *str);
+...
+size_t make_upper(char *str);
+
      +
      +

      In Python:

      +
      +
      +>>> buf = bytearray(b'foo\x00')
+>>> make_upper(buf)
+>>> print(buf)
+bytearray(b'FOO\x00')
+>>>
+
      +
      +

      Both %pybuffer_mutable_binary and +%pybuffer_mutable_string require the provided buffer to be mutable, + eg. they can accept a bytearray type but can't accept an + immutable byte type.

      +
      +

      %pybuffer_binary(parm, size_parm)

      +
      +

      This macro maps an object's buffer to a pointer parm and a + size size_parm. It is similar to %pybuffer_mutable_binary +, except the %pybuffer_binary an accept both mutable and + immutable buffers. As a result, the wrapped function should not modify + the buffer.

      +
      +

      %pybuffer_string(parm)

      +
      +

      This macro maps an object's buffer as a string pointer parm +. It is similar to %pybuffer_mutable_string but the buffer + could be both mutable and immutable. And your function should not + modify the buffer.

      +
      +

      31.12.3 Abstract base classes

      +

      By including pyabc.i and using the -py3 command + line option when calling SWIG, the proxy classes of the STL containers + will automatically gain an appropriate abstract base class. For + example, the following SWIG interface:

      +
      +
      +%include <pyabc.i>
+%include <std_map.i>
+%include <std_list.i>
+
+namespace std {
+  %template(Mapii) map<int, int>;
+  %template(IntList) list<int>;
+}
+
      +
      +

      will generate a Python proxy class Mapii inheriting from +collections.MutableMap and a proxy class IntList + inheriting from collections.MutableSequence.

      +

      pyabc.i also provides a macro %pythonabc that + could be used to define an abstract base class for your own C++ class:

      +
      +
      +%pythonabc(MySet, collections.MutableSet);
+
      +
      +

      For details of abstract base class, please see PEP 3119.

      + + + + + + + + +
      +

      32 SWIG and Ruby

      + + +
      + +
      + +

      This chapter describes SWIG's support of Ruby.

      +

      32.1 Preliminaries

      +

      SWIG 1.3 is known to work with Ruby versions 1.6 and later. Given + the choice, you should use the latest stable version of Ruby. You + should also determine if your system supports shared libraries and + dynamic loading. SWIG will work with or without dynamic loading, but + the compilation process will vary.

      +

      This chapter covers most SWIG features, but in less depth than is + found in earlier chapters. At the very least, make sure you also read + the "SWIG Basics" chapter. It is also assumed that + the reader has a basic understanding of Ruby.

      +

      32.1.1 Running SWIG

      +

      To build a Ruby module, run SWIG using the -ruby option:

      +
      +
      $ swig -ruby example.i
+
      +
      +

      If building a C++ extension, add the -c++ option:

      +
      +
      $ swig -c++ -ruby example.i
+
      +
      +

      This creates a file example_wrap.c (example_wrap.cxx + if compiling a C++ extension) that contains all of the code needed to + build a Ruby extension module. To finish building the module, you need + to compile this file and link it with the rest of your program.

      +

      32.1.2 Getting the right header files

      +

      In order to compile the wrapper code, the compiler needs the +ruby.h header file. This file is usually contained in a directory + such as

      +
      +
      /usr/lib/ruby/1.8/x86_64-linux-gnu/ruby.h
+
      /usr/local/lib/ruby/1.6/i686-linux/ruby.h
+
      +
      +

      The exact location may vary on your machine, but the above location + is typical. If you are not entirely sure where Ruby is installed, you + can run Ruby to find out. For example:

      +
      +
      $ ruby -e 'puts $:.join("\n")'
+
      /usr/local/lib/ruby/site_ruby/1.6 /usr/local/lib/ruby/site_ruby/1.6/i686-linux
+
      /usr/local/lib/ruby/site_ruby /usr/local/lib/ruby/1.6 /usr/local/lib/ruby/1.6/i686-linux .
+
      +
      +

      32.1.3 Compiling a dynamic module

      +

      Ruby extension modules are typically compiled into shared libraries + that the interpreter loads dynamically at runtime. Since the exact + commands for doing this vary from platform to platform, your best bet + is to follow the steps described in the README.EXT file from + the Ruby distribution:

      +
        +
      1. +

        Create a file called extconf.rb that looks like the + following:

        +
        +
        require 'mkmf'
+
        create_makefile('example')
+
        +
        2. +
      2. +

        Type the following to build the extension:

        +
        +
        $ ruby extconf.rb
+
        $ make
+
        $ make install
+
        +
        3. +
      +

      Of course, there is the problem that mkmf does not work correctly on + all platforms, e.g, HPUX. If you need to add your own make rules to the + file that extconf.rb produces, you can add this:

      +
      +
      open("Makefile", "a") { |mf|
+
       puts <<EOM
+
       # Your make rules go here
+
       EOM
+
      }
+
      +
      +

      to the end of the extconf.rb file. If for some reason you + don't want to use the standard approach, you'll need to determine the + correct compiler and linker flags for your build platform. For example, + a typical sequence of commands for the Linux operating system would + look something like this:

      +
      +
      $ swig -ruby example.i
+
      $ gcc -c example.c
+
      $ gcc -c example_wrap.c -I/usr/local/lib/ruby/1.6/i686-linux 
+
      $ gcc -shared example.o example_wrap.o -o example.so
+
      +
      +

      For other platforms it may be necessary to compile with the +-fPIC option to generate position-independent code. If in doubt, + consult the manual pages for your compiler and linker to determine the + correct set of options. You might also check the +SWIG Wiki for additional information.

      +

      32.1.4 Using your module

      +

      Ruby module names must be capitalized, but the convention for + Ruby feature names is to use lowercase names. So, for example, + the Etc extension module is imported by requiring the etc + feature:

      +
      +
      # The feature name begins with a lowercase letter...
+
      require 'etc'
+
      
+
      # ... but the module name begins with an uppercase letter
+
      puts "Your login name: #{Etc.getlogin}"
+
      +
      +

      To stay consistent with this practice, you should always specify a + lowercase module name with SWIG's %module directive. SWIG + will automatically correct the resulting Ruby module name for your + extension. So for example, a SWIG interface file that begins with:

      +
      +
      %module example
+
      +
      +

      will result in an extension module using the feature name "example" + and Ruby module name "Example".

      +

      32.1.5 Static linking

      +

      An alternative approach to dynamic linking is to rebuild the Ruby + interpreter with your extension module added to it. In the past, this + approach was sometimes necessary due to limitations in dynamic loading + support on certain machines. However, the situation has improved + greatly over the last few years and you should not consider this + approach unless there is really no other option.

      +

      The usual procedure for adding a new module to Ruby involves finding + the Ruby source, adding an entry to the ext/Setup file, adding + your directory to the list of extensions in the file, and finally + rebuilding Ruby.

      +

      32.1.6 Compilation of C++ extensions

      +

      On most machines, C++ extension modules should be linked using the + C++ compiler. For example:

      +
      +
      $ swig -c++ -ruby example.i
+
      $ g++ -c example.cxx
+
      $ g++ -c example_wrap.cxx -I/usr/local/lib/ruby/1.6/i686-linux
+
      $ g++ -shared example.o example_wrap.o -o example.so
+
      +
      +

      If you've written an extconf.rb script to automatically + generate a Makefile for your C++ extension module, keep in + mind that (as of this writing) Ruby still uses gcc and not +g++ as its linker. As a result, the required C++ runtime library + support will not be automatically linked into your extension module and + it may fail to load on some platforms. A workaround for this problem is + use the mkmf module's append_library() method to add + one of the C++ runtime libraries to the list of libraries linked into + your extension, e.g.

      +
      +
      require 'mkmf'
+
      $libs = append_library($libs, "supc++")
+
      create_makefile('example')
+
      +
      +

      32.2 Building Ruby Extensions under Windows + 95/NT

      +

      Building a SWIG extension to Ruby under Windows 95/NT is roughly + similar to the process used with Unix. Normally, you will want to + produce a DLL that can be loaded into the Ruby interpreter. For all + recent versions of Ruby, the procedure described above (i.e. using an +extconf.rb script) will work with Windows as well; you should be + able to build your code into a DLL by typing:

      +
      +
      C:\swigtest> ruby extconf.rb
+
      C:\swigtest> nmake
+
      C:\swigtest> nmake install
+
      +
      +

      The remainder of this section covers the process of compiling + SWIG-generated Ruby extensions with Microsoft Visual C++ 6 (i.e. within + the Developer Studio IDE, instead of using the command line tools). In + order to build extensions, you may need to download the source + distribution to the Ruby package, as you will need the Ruby header + files.

      +

      32.2.1 Running SWIG from Developer Studio

      +

      If you are developing your application within Microsoft developer + studio, SWIG can be invoked as a custom build option. The process + roughly follows these steps :

      +
        +
      • Open up a new workspace and use the AppWizard to select a DLL + project.
        • +
      • Add both the SWIG interface file (the .i file), any supporting C + files, and the name of the wrapper file that will be created by SWIG + (i.e. example_wrap.c). Note : If using C++, choose a different + suffix for the wrapper file such as example_wrap.cxx. Don't + worry if the wrapper file doesn't exist yet--Developer Studio will keep + a reference to it around.
        • +
      • Select the SWIG interface file and go to the settings menu. Under + settings, select the "Custom Build" option.
        • +
      • Enter "SWIG" in the description field.
        • +
      • Enter "swig -ruby -o $(ProjDir)\$(InputName)_wrap.c + $(InputPath)" in the "Build command(s) field". You may have to + include the path to swig.exe.
        • +
      • Enter "$(ProjDir)\$(InputName)_wrap.c" in the "Output + files(s) field".
        • +
      • Next, select the settings for the entire project and go to the + C/C++ tab and select the Preprocessor category. Add NT=1 to the + Preprocessor definitions. This must be set else you will get + compilation errors. Also add IMPORT to the preprocessor definitions, + else you may get runtime errors. Also add the include directories for + your Ruby installation under "Additional include directories".
        • +
      • Next, select the settings for the entire project and go to the Link + tab and select the General category. Set the name of the output file to + match the name of your Ruby module (i.e.. example.dll). Next add the + Ruby library file to your link libraries under Object/Library modules. + For example "mswin32-ruby16.lib. You also need to add the path to the + library under the Input tab - Additional library path.
        • +
      • Build your project.
        • +
      +

      Now, assuming all went well, SWIG will be automatically invoked when + you build your project. Any changes made to the interface file will + result in SWIG being automatically invoked to produce a new version of + the wrapper file. To run your new Ruby extension, simply run Ruby and + use the require command as normal. For example if you have + this ruby file run.rb:

      +
      +
      # file: run.rb
+
      require 'Example'
+
      
+
      # Call a c function
+
      print "Foo = ", Example.Foo, "\n"
+
      +
      +

      Ensure the dll just built is in your path or current directory, then + run the Ruby script from the DOS/Command prompt:

      +
      +
      C:\swigtest> ruby run.rb
+
      Foo = 3.0
+
      +
      +

      32.3 The Ruby-to-C/C++ Mapping

      +

      This section describes the basics of how SWIG maps C or C++ + declarations in your SWIG interface files to Ruby constructs.

      +

      32.3.1 Modules

      +

      The SWIG %module directive specifies the name of the Ruby + module. If you specify:

      +
      +
      %module example
      +
      +

      then everything is wrapped into a Ruby module named Example + that is nested directly under the global module. You can specify a more + deeply nested module by specifying the fully-qualified module name in + quotes, e.g.

      +
      +
      %module "foo::bar::spam"
      +
      +

      An alternate method of specifying a nested module name is to use the + + -prefix option on the SWIG command line. The prefix that you specify + with this option will be prepended to the module name specified with + the + + %module directive in your SWIG interface file. So for example, this + declaration at the top of your SWIG interface file: +

      +
      +
      %module "foo::bar::spam"
      +
      +

      will result in a nested module name of + + Foo::Bar::Spam, but you can achieve the + + same effect by specifying: +

      +
      +
      %module spam
      +
      +

      and then running SWIG with the + + -prefix command line option: +

      +
      +
      $ swig -ruby -prefix "foo::bar::" example.i
      +
      +

      Starting with SWIG 1.3.20, you can also choose to wrap everything + into the global module by specifying the -globalmodule option + on the SWIG command line, i.e.

      +
      +
      $ swig -ruby -globalmodule example.i
      +
      +

      Note that this does not relieve you of the requirement of specifying + the SWIG module name with the %module directive (or the +-module command-line option) as described earlier.

      +

      When choosing a module name, do not use the same name as a built-in + Ruby command or standard module name, as the results may be + unpredictable. Similarly, if you're using the -globalmodule + option to wrap everything into the global module, take care that the + names of your constants, classes and methods don't conflict with any of + Ruby's built-in names.

      +

      32.3.2 Functions

      +

      Global functions are wrapped as Ruby module methods. For example, + given the SWIG interface file example.i:

      +
      +
      %module example
+
      
+
      int fact(int n);
+
      +
      +

      and C source file example.c:

      +
      +
      int fact(int n) {
+
       if (n == 0)
+
       return 1;
+
       return (n * fact(n-1));
+
      }
+
      +
      +

      SWIG will generate a method fact in the Example module + that can be used like so:

      +
      +
      $ irb
+
      irb(main):001:0> require 'example'
+
      true
+
      irb(main):002:0> Example.fact(4)
+
      24
+
      +
      +

      32.3.3 Variable Linking

      +

      C/C++ global variables are wrapped as a pair of singleton methods + for the module: one to get the value of the global variable and one to + set it. For example, the following SWIG interface file declares two + global variables:

      +
      +
      // SWIG interface file with global variables
+
      %module example
+
      ...
+
      %inline %{
+
      extern int variable1;
+
      extern double Variable2;
+
      %}
+
      ...
+
      +
      +

      Now look at the Ruby interface:

      +
      +
      $ irb
+
      irb(main):001:0> require 'Example'
+
      true
+
      irb(main):002:0> Example.variable1 = 2
+
      2
+
      irb(main):003:0> Example.Variable2 = 4 * 10.3
+
      41.2
+
      irb(main):004:0> Example.Variable2
+
      41.2
+
      +
      +

      If you make an error in variable assignment, you will receive an + error message. For example:

      +
      +
      irb(main):005:0> Example.Variable2 = "hello"
+
      TypeError: no implicit conversion to float from string
+
      from (irb):5:in `Variable2='
+
      from (irb):5
+
      +
      +

      If a variable is declared as const, it is wrapped as a + read-only variable. Attempts to modify its value will result in an + error.

      +

      To make ordinary variables read-only, you can also use the +%immutable directive. For example:

      +
      +
      %immutable;
+
      %inline %{
+
      extern char *path;
+
      %}
+
      %mutable;
+
      +
      +

      The %immutable directive stays in effect until it is + explicitly disabled using %mutable.

      +

      32.3.4 Constants

      +

      C/C++ constants are wrapped as module constants initialized to the + appropriate value. To create a constant, use #define or the +%constant directive. For example:

      +
      +
      #define PI 3.14159
+
      #define VERSION "1.0"
+
      
+
      %constant int FOO = 42;
+
      %constant const char *path = "/usr/local";
+
      
+
      const int BAR = 32;
+
      +
      +

      Remember to use the :: operator in Ruby to get at these constant + values, e.g.

      +
      +
      $ irb
+
      irb(main):001:0> require 'Example'
+
      true
+
      irb(main):002:0> Example::PI
+
      3.14159
+
      +
      +

      32.3.5 Pointers

      +

      "Opaque" pointers to arbitrary C/C++ types (i.e. types that aren't + explicitly declared in your SWIG interface file) are wrapped as data + objects. So, for example, consider a SWIG interface file containing + only the declarations:

      +
      +
      Foo *get_foo();
+
      void set_foo(Foo *foo);
+
      +
      +

      For this case, the get_foo() method returns an instance of an + internally generated Ruby class:

      +
      +
      irb(main):001:0> foo = Example::get_foo()
+
      #<SWIG::TYPE_p_Foo:0x402b1654>
+
      +
      +

      A NULL pointer is always represented by the Ruby nil + object.

      +

      32.3.6 Structures

      +

      C/C++ structs are wrapped as Ruby classes, with accessor methods + (i.e. "getters" and "setters") for all of the struct members. For + example, this struct declaration:

      +
      +
      struct Vector {
+
       double x, y;
+
      };
+
      +
      +

      gets wrapped as a Vector class, with Ruby instance methods +x, x=, y and y=. These methods can be + used to access structure data from Ruby as follows:

      +
      +
      $ irb
+
      irb(main):001:0> require 'Example'
+
      true
+
      irb(main):002:0> f = Example::Vector.new
+
      #<Example::Vector:0x4020b268>
+
      irb(main):003:0> f.x = 10
+
      nil
+
      irb(main):004:0> f.x
+
      10.0
+
      +
      +

      Similar access is provided for unions and the public data members of + C++ classes.

      +

      const members of a structure are read-only. Data members can + also be forced to be read-only using the %immutable directive + (in C++, private may also be used). For example:

      +
      +
      struct Foo {
+
       ...
+
       %immutable;
+
       int x; /* Read-only members */
+
       char *name;
+
       %mutable;
+
       ...
+
      };
+
      +
      +

      When char * members of a structure are wrapped, the + contents are assumed to be dynamically allocated using malloc + or new (depending on whether or not SWIG is run with the +-c++ option). When the structure member is set, the old contents + will be released and a new value created. If this is not the behavior + you want, you will have to use a typemap (described shortly).

      +

      Array members are normally wrapped as read-only. For example, this + code:

      +
      +
      struct Foo {
+
       int x[50];
+
      };
+
      +
      +

      produces a single accessor function like this:

      +
      +
      int *Foo_x_get(Foo *self) {
+
       return self->x;
+
      };
+
      +
      +

      If you want to set an array member, you will need to supply a + "memberin" typemap described in the +section on typemaps. As a special case, SWIG does generate code to + set array members of type char (allowing you to store a Ruby + string in the structure).

      +

      When structure members are wrapped, they are handled as pointers. For + example,

      +
      +
      struct Foo {
+
       ...
+
      };
+
      
+
      struct Bar {
+
       Foo f;
+
      };
+
      +
      +

      generates accessor functions such as this:

      +
      +
      Foo *Bar_f_get(Bar *b) {
+
       return &b->f;
+
      }
+
      
+
      void Bar_f_set(Bar *b, Foo *val) {
+
       b->f = *val;
+
      }
+
      +
      +

      32.3.7 C++ classes

      +

      Like structs, C++ classes are wrapped by creating a new Ruby class + of the same name with accessor methods for the public class member + data. Additionally, public member functions for the class are wrapped + as Ruby instance methods, and public static member functions are + wrapped as Ruby singleton methods. So, given the C++ class declaration:

      +
      +
      class List {
+
      public:
+
       List();
+
       ~List();
+
       int search(char *item);
+
       void insert(char *item);
+
       void remove(char *item);
+
       char *get(int n);
+
       int length;
+
       static void print(List *l);
+
      };
+
      +
      +

      SWIG would create a List class with:

      +
        +
      • instance methods search, insert, remove, and + get;
        • +
      • instance methods length and length= (to get and set + the value of the length data member); and,
        • +
      • a print singleton method for the class.
        • +
      +

      In Ruby, these functions are used as follows:

      +
      +
      require 'Example'
+
      
+
      l = Example::List.new
+
      
+
      l.insert("Ale")
+
      l.insert("Stout")
+
      l.insert("Lager")
+
      Example.print(l)
+
      l.length()
+
      ----- produces the following output 
+
      Lager
+
      Stout
+
      Ale
+
      3
+
      +
      +

      32.3.8 C++ Inheritance

      +

      The SWIG type-checker is fully aware of C++ inheritance. Therefore, + if you have classes like this:

      +
      +
      class Parent {
+
       ...
+
      };
+
      
+
      class Child : public Parent {
+
       ...
+
      };
+
      +
      +

      those classes are wrapped into a hierarchy of Ruby classes that + reflect the same inheritance structure. All of the usual Ruby utility + methods work normally:

      +
      +
      irb(main):001:0> c = Child.new
+
      #<Bar:0x4016efd4>
+
      irb(main):002:0> c.instance_of? Child
+
      true
+
      irb(main):003:0> b.instance_of? Parent
+
      false
+
      irb(main):004:0> b.is_a? Child
+
      true
+
      irb(main):005:0> b.is_a? Parent
+
      true
+
      irb(main):006:0> Child < Parent
+
      true
+
      irb(main):007:0> Child > Parent
+
      false
+
      +
      +

      Furthermore, if you have a function like this:

      +
      +
      void spam(Parent *f);
+
      +
      +

      then the function spam() accepts Parent* or a + pointer to any class derived from Parent.

      +

      Until recently, the Ruby module for SWIG didn't support multiple + inheritance, and this is still the default behavior. This doesn't mean + that you can't wrap C++ classes which inherit from multiple base + classes; it simply means that only the first base class listed + in the class declaration is considered, and any additional base classes + are ignored. As an example, consider a SWIG interface file with a + declaration like this:

      +
      +
      class Derived : public Base1, public Base2
+
      {
+
       ...
+
      };
+
      +
      +

      For this case, the resulting Ruby class (Derived) will only + consider Base1 as its superclass. It won't inherit any of +Base2's member functions or data and it won't recognize Base2 + as an "ancestor" of Derived (i.e. the is_a? + relationship would fail). When SWIG processes this interface file, + you'll see a warning message like:

      +
      +
      example.i:5: Warning(802): Warning for Derived: Base Base2 ignored.
+
      Multiple inheritance is not supported in Ruby.
+
      +
      +

      Starting with SWIG 1.3.20, the Ruby module for SWIG provides limited + support for multiple inheritance. Because the approach for dealing with + multiple inheritance introduces some limitations, this is an optional + feature that you can activate with the -minherit command-line + option:

      +
      +
      $ swig -c++ -ruby -minherit example.i
      +
      +

      Using our previous example, if your SWIG interface file contains a + declaration like this:

      +
      +
      class Derived : public Base1, public Base2
+
      {
+
       ...
+
      };
+
      +
      +

      and you run SWIG with the -minherit command-line option, + then you will end up with a Ruby class Derived that appears to + "inherit" the member data and functions from both Base1 and +Base2. What actually happens is that three different top-level + classes are created, with Ruby's Object class as their + superclass. Each of these classes defines a nested module named +Impl, and it's in these nested Impl modules that the + actual instance methods for the classes are defined, i.e.

      +
      +
      class Base1
+
       module Impl
+
       # Define Base1 methods here
+
       end
+
       include Impl
+
      end
+
      
+
      class Base2
+
       module Impl
+
       # Define Base2 methods here
+
       end
+
       include Impl
+
      end
+
      
+
      class Derived
+
       module Impl
+
       include Base1::Impl
+
       include Base2::Impl
+
       # Define Derived methods here
+
       end
+
       include Impl
+
      end
+
      +
      +

      Observe that after the nested Impl module for a class is + defined, it is mixed-in to the class itself. Also observe that the +Derived::Impl module first mixes-in its base classes' Impl + modules, thus "inheriting" all of their behavior.

      +

      The primary drawback is that, unlike the default mode of operation, + neither Base1 nor Base2 is a true superclass of +Derived anymore:

      +
      +
      obj = Derived.new
+
      obj.is_a? Base1 # this will return false...
+
      obj.is_a? Base2 # ... and so will this
+
      +
      +

      In most cases, this is not a serious problem since objects of type +Derived will otherwise behave as though they inherit from both +Base1 and Base2 (i.e. they exhibit +"Duck Typing").

      +

      32.3.9 C++ Overloaded Functions

      +

      C++ overloaded functions, methods, and constructors are mostly + supported by SWIG. For example, if you have two functions like this:

      +
      +
      void foo(int);
+
      void foo(char *c);
+
      +
      +

      You can use them in Ruby in a straightforward manner:

      +
      +
      irb(main):001:0> foo(3) # foo(int)
+
      irb(main):002:0> foo("Hello") # foo(char *c)
+
      +
      +

      Similarly, if you have a class like this,

      +
      +
      class Foo {
+
      public:
+
       Foo();
+
       Foo(const Foo &);
+
       ...
+
      };
+
      +
      +

      you can write Ruby code like this:

      +
      +
      irb(main):001:0> f = Foo.new # Create a Foo
+
      irb(main):002:0> g = Foo.new(f) # Copy f
+
      +
      +

      Overloading support is not quite as flexible as in C++. Sometimes + there are methods that SWIG can't disambiguate. For example:

      +
      +
      void spam(int);
+
      void spam(short);
+
      +
      +

      or

      +
      +
      void foo(Bar *b);
+
      void foo(Bar &b);
+
      +
      +

      If declarations such as these appear, you will get a warning message + like this:

      +
      +
      example.i:12: Warning(509): Overloaded spam(short) is shadowed by spam(int)
+
      at example.i:11.
+
      +
      +

      To fix this, you either need to ignore or rename one of the methods. + For example:

      +
      +
      %rename(spam_short) spam(short);
+
      ...
+
      void spam(int); 
+
      void spam(short); // Accessed as spam_short
+
      +
      +

      or

      +
      +
      %ignore spam(short);
+
      ...
+
      void spam(int); 
+
      void spam(short); // Ignored
+
      +
      +

      SWIG resolves overloaded functions and methods using a + disambiguation scheme that ranks and sorts declarations according to a + set of type-precedence rules. The order in which declarations appear in + the input does not matter except in situations where ambiguity + arises--in this case, the first declaration takes precedence.

      +

      Please refer to the "SWIG and C++" chapter + for more information about overloading.

      +

      32.3.10 C++ Operators

      +

      For the most part, overloaded operators are handled automatically by + SWIG and do not require any special treatment on your part. So if your + class declares an overloaded addition operator, e.g.

      +
      +
      class Complex {
+
       ...
+
       Complex operator+(Complex &);
+
       ...
+
      };
+
      +
      +

      the resulting Ruby class will also support the addition (+) method + correctly.

      +

      For cases where SWIG's built-in support is not sufficient, C++ + operators can be wrapped using the %rename directive + (available on SWIG 1.3.10 and later releases). All you need to do is + give the operator the name of a valid Ruby identifier. For example:

      +
      +
      %rename(add_complex) operator+(Complex &, Complex &);
+
      ...
+
      Complex operator+(Complex &, Complex &);
+
      +
      +

      Now, in Ruby, you can do this:

      +
      +
      a = Example::Complex.new(2, 3)
+
      b = Example::Complex.new(4, -1)
+
      c = Example.add_complex(a, b)
+
      +
      +

      More details about wrapping C++ operators into Ruby operators is + discussed in the section on + operator overloading.

      +

      32.3.11 C++ namespaces

      +

      SWIG is aware of C++ namespaces, but namespace names do not appear + in the module nor do namespaces result in a module that is broken up + into submodules or packages. For example, if you have a file like this,

      +
      +
      %module example
+
      
+
      namespace foo {
+
       int fact(int n);
+
       struct Vector {
+
       double x,y,z;
+
       };
+
      };
+
      +
      +

      it works in Ruby as follows:

      +
      +
      irb(main):001:0> require 'example'
+
      true
+
      irb(main):002:0> Example.fact(3)
+
      6
+
      irb(main):003:0> v = Example::Vector.new
+
      #<Example::Vector:0x4016f4d4>
+
      irb(main):004:0> v.x = 3.4
+
      3.4
+
      irb(main):004:0> v.y
+
      0.0
+
      +
      +

      If your program has more than one namespace, name conflicts (if any) + can be resolved using %rename For example:

      +
      +
      %rename(Bar_spam) Bar::spam;
+
      
+
      namespace Foo {
+
       int spam();
+
      }
+
      
+
      namespace Bar {
+
       int spam();
+
      }
+
      +
      +

      If you have more than one namespace and your want to keep their + symbols separate, consider wrapping them as separate SWIG modules. For + example, make the module name the same as the namespace and create + extension modules for each namespace separately. If your program + utilizes thousands of small deeply nested namespaces each with + identical symbol names, well, then you get what you deserve.

      +

      32.3.12 C++ templates

      +

      C++ templates don't present a huge problem for SWIG. However, in + order to create wrappers, you have to tell SWIG to create wrappers for + a particular template instantiation. To do this, you use the +%template directive. For example:

      +
      +
      %module example
+
      
+
      %{
+
      #include "pair.h"
+
      %}
+
      
+
      template<class T1, class T2>
+
      struct pair {
+
       typedef T1 first_type;
+
       typedef T2 second_type;
+
       T1 first;
+
       T2 second;
+
       pair();
+
       pair(const T1&, const T2&);
+
       ~pair();
+
      };
+
      
+
      %template(Pairii) pair<int,int>;
+
      +
      +

      In Ruby:

      +
      +
      irb(main):001:0> require 'example'
+
      true
+
      irb(main):002:0> p = Example::Pairii.new(3, 4)
+
      #<Example:Pairii:0x4016f4df>
+
      irb(main):003:0> p.first
+
      3
+
      irb(main):004:0> p.second
+
      4
+
      +
      +

      32.3.13 C++ Standard Template Library + (STL)

      +

      On a related note, the standard SWIG library contains a number of + modules that provide typemaps for standard C++ library classes (such as + std::pair, std::string and std::vector). + These library modules don't provide wrappers around the templates + themselves, but they do make it convenient for users of your extension + module to pass Ruby objects (such as arrays and strings) to wrapped C++ + code that expects instances of standard C++ templates. For example, + suppose the C++ library you're wrapping has a function that expects a + vector of floats:

      +
      +
      %module example
+
      
+
      float sum(const std::vector<float>& values);
+
      +
      +

      Rather than go through the hassle of writing an "in" typemap to + convert an array of Ruby numbers into a std::vector<float>, you can + just use the std_vector.i module from the standard SWIG + library:

      +
      +
      %module example
+
      
+
      %include std_vector.i
+
      float sum(const std::vector<float>& values);
+
      +
      +

      Ruby's STL wrappings provide additional methods to make them behave + more similarly to Ruby's native classes.

      +

      Thus, you can do, for example:

      +
      +
      v = IntVector.new
+
+
      v << 2
+
+
      v << 3
+
      v << 4
+
      v.each { |x| puts x }
+
      
+
+
      => 2
+
      
+
+3
+
      
+
+4
+
      v.delete_if { |x| x == 3 }
+
      
+
+=> [2,4]
      +
      +

      The SWIG Ruby module provides also the ability for all the STL + containers to carry around Ruby native objects (Fixnum, Classes, etc) + making them act almost like Ruby's own Array, Hash, etc.   To do that, + you need to define a container that contains a swig::GC_VALUE, like:

      +
      %module nativevector +
      +
      %{ +
      std::vector< swig::GC_VALUE > NativeVector; +
      %} +
      +
      %template(NativeVector) std::vector< swig::GC_VALUE >; +
      +
      +

      This vector can then contain any Ruby object, making them almost + identical to Ruby's own Array class.

      +
      + +require 'nativevector' +
      + + include NativeVector +
      +
      + + v = NativeVector.new +
      + + v << 1 +
      + + v << [1,2] +
      + + v << 'hello' +
      +
      + + class A; end +
      +
      + + v << A.new +
      +
      + + puts v +
      + + => [1, [1,2], 'hello', #<A:0x245325>]
      +
      +

      Obviously, there is a lot more to template wrapping than shown in + these examples. More details can be found in the +SWIG and C++ chapter.

      +

      32.3.14 C++ STL Functors

      +

      Some containers in the STL allow you to modify their default behavior + by using so called functors or function objects.  Functors are often + just a very simple struct with + + operator() redefined or an actual C/C++ function.  This allows you, for + example, to always keep the sort order of a STL container to your + liking.

      +

      The Ruby STL mappings allows you to modify those containers that + support functors using Ruby procs or methods, instead.  Currently, this + includes + + std::set, + + set::map, + + std::multiset and + + std::multimap.

      +

      The functors in swig are called + + swig::UnaryFunction and + + swig::BinaryFunction. +
      For C++ predicates (ie. functors that must return bool as a result) + + swig::UnaryPredicate and + + swig::BinaryPredicate are provided.

      +

      As an example, if given this swig file:

      +
      %module intset; +
      +
      %include <std_set.i> +
      +
      %typemap(IntSet)  std::set< int, swig::BinaryPredicate >;
      +

      You can then use the set from Ruby with or without a proc object as a + predicate:

      +
      require 'intset' +
      include Intset +
      +
      # Default sorting behavior defined in C++ +
      a = IntSet.new +
      a << 1 +
      a << 2 +
      a << 3 +
      a +
      + + =>  [1,2,3] +
      +
      # Custom sorting behavior defined by a Ruby proc
      + +b = IntSet.new( proc { |a,b| a > b } ) +
      b << 1 +
      b << 2 +
      b << 3 +
      b +
      + + =>  [3,2,1]
      +

      32.3.15 C++ STL Iterators

      +

      The STL is well known for the use of iterators.  There are a number + of iterators possible with different properties, but in general there + are two main categories: const iterators and non-const iterators.  The + const iterators can access and not modify the values they point at, + while the non-const iterators can both read and modify the values.

      +

      The Ruby STL wrappings support both type of iterators by using a + proxy class in-between.  This proxy class is + + swig::Iterator or swig::ConstIterator.  Derived from them are template + classes that need to be initialized with the actual iterator for the + container you are wrapping and often times with the beginning and + ending points of the iteration range. 

      +

      The SWIG STL library already provides typemaps to all the standard + containers to do this wrapping automatically for you, but if you have + your own STL-like iterator, you will need to write your own typemap for + them.  For out typemaps, the special functions + + make_const_iterator and + + make_nonconst_iterator are provided.

      +

      These can be used either like:

      +
      make_const_iterator( + iterator, rubyclass ); +
      make_const_iterator( iterator, iterator_begin, iterator_end, + rubyclass );
      +

      The iterators support a + + next() and + + previous() member function to just change the iterator without + returning anything.   + +previous() should obviously only be used for bidirectional iterators. +  You can also advance the iterator multiple steps by using standard + math operations like + + +=.

      +

      The value the iterator points at can be accessed with + + value() -- this is equivalent to dereferencing it with + + *i.   For non-const iterators, a + + value=() function is also provided which allows you to change the value + pointed by the iterator.  This is equivalent to the C++ construct of + dereferencing and assignment, like + + *i = something. 

      +

      Thus, given say a vector class of doubles defined as:

      +
      + +%module doublevector +
      + +
      %include std_vector.i +
      + +
      %template(DoubleVector) std::vector<double>;
      +

      Its iterator can then be used from Ruby like:

      +
      require + 'doublevector' +
      include Doublevector +
      +
      v = DoubleVector.new +
      v << 1 +
      v << 2 +
      v << 3 +
      +
      # +
      # an elaborate and less efficient way of doing v.map! { |x| x+2 } +
      # +
      i = v.begin +
      e = v.end +
      while i != e +
        val = i.value +
        val += 2 +
        i.value = val +
        i.next +
      end +
      i +
      + + >> [3, 4, 5 ]
      +
      +

      If you'd rather have STL classes without any iterators, you should + define + + -DSWIG_NO_EXPORT_ITERATOR_METHODS when running swig.

      +

      32.3.16 C++ Smart Pointers

      +

      In certain C++ programs, it is common to use classes that have been + wrapped by so-called "smart pointers." Generally, this involves the use + of a template class that implements operator->() like this:

      +
      +
      template<class T> class SmartPtr {
+
       ...
+
       T *operator->();
+
       ...
+
      }
+
      +
      +

      Then, if you have a class like this,

      +
      +
      class Foo {
+
      public:
+
       int x;
+
       int bar();
+
      };
+
      +
      +

      A smart pointer would be used in C++ as follows:

      +
      +
      SmartPtr<Foo> p = CreateFoo(); // Created somehow (not shown)
+
      ...
+
      p->x = 3; // Foo::x
+
      int y = p->bar(); // Foo::bar
+
      +
      +

      To wrap this in Ruby, simply tell SWIG about the SmartPtr + class and the low-level Foo object. Make sure you instantiate +SmartPtr using %template if necessary. For example:

      +
      +
      %module example
+
      ...
+
      %template(SmartPtrFoo) SmartPtr<Foo>;
+
      ...
+
      +
      +

      Now, in Ruby, everything should just "work":

      +
      +
      irb(main):001:0> p = Example::CreateFoo() # Create a smart-pointer somehow
+
      #<Example::SmartPtrFoo:0x4016f4df>
+
      irb(main):002:0> p.x = 3 # Foo::x
+
      3
+
      irb(main):003:0> p.bar() # Foo::bar
+
      +
      +

      If you ever need to access the underlying pointer returned by +operator->() itself, simply use the __deref__() method. + For example:

      +
      +
      irb(main):004:0> f = p.__deref__() # Returns underlying Foo *
+
      +
      +

      32.3.17 Cross-Language Polymorphism

      +

      SWIG's Ruby module supports cross-language polymorphism (a.k.a. the + "directors" feature) similar to that for SWIG's Python module. Rather + than duplicate the information presented in the Python + chapter, this section just notes the differences that you need to be + aware of when using this feature with Ruby.

      +

      32.3.17.1 Exception Unrolling

      +

      Whenever a C++ director class routes one of its virtual member + function calls to a Ruby instance method, there's always the + possibility that an exception will be raised in the Ruby code. By + default, those exceptions are ignored, which simply means that the + exception will be exposed to the Ruby interpreter. If you would like to + change this behavior, you can use the %feature("director:except") + directive to indicate what action should be taken when a Ruby exception + is raised. The following code should suffice in most cases:

      +
      +
      %feature("director:except") {
+
       throw Swig::DirectorMethodException($error);
+
      }
+
      +
      +

      When this feature is activated, the call to the Ruby instance method + is "wrapped" using the rb_rescue2() function from Ruby's C + API. If any Ruby exception is raised, it will be caught here and a C++ + exception is raised in its place.

      +

      32.4 Naming

      +

      Ruby has several common naming conventions. Constants are generally + in upper case, module and class names are in camel case and methods are + in lower case with underscores. For example:

      +
      +
        +
      • MATH::PI is a constant name
        • +
      • MyClass is a class name
        • +
      • my_method is a method name
        • +
      +
      +

      Prior to version 1.3.28, SWIG did not support these Ruby conventions. + The only modifications it made to names was to capitalize the first + letter of constants (which includes module and class names).

      +

      SWIG 1.3.28 introduces the new -autorename command line parameter. + When this parameter is specified, SWIG will automatically change + constant, class and method names to conform with the standard Ruby + naming conventions. For example:

      +
      +
      $ swig -ruby -autorename example.i
+
      +
      +

      To disable renaming use the -noautorename command line option.

      +

      Since this change significantly changes the wrapper code generated by + SWIG, it is turned off by default in SWIG 1.3.28. However, it is + planned to become the default option in future releases.

      +

      32.4.1 Defining Aliases

      +

      It's a fairly common practice in the Ruby built-ins and standard + library to provide aliases for method names. For example, + Array#size is an alias for Array#length. If you would + like to provide an alias for one of your class' instance methods, one + approach is to use SWIG's %extend directive to add a new + method of the aliased name that calls the original function. For + example:

      +
      +
      class MyArray {
+
      public:
+
       // Construct an empty array
+
       MyArray();
+
       
+
       // Return the size of this array
+
       size_t length() const;
+
      };
+
      
+
      %extend MyArray {
+
       // MyArray#size is an alias for MyArray#length
+
       size_t size() const {
+
       return $self->length();
+
       }
+
      }
+
      +
      +

      A better solution is to use the %alias directive (unique to + SWIG's Ruby module). The previous example could then be rewritten as:

      +
      +
      // MyArray#size is an alias for MyArray#length
+
      %alias MyArray::length "size";
+
      
+
      class MyArray {
+
      public:
+
       // Construct an empty array
+
       MyArray();
+
       
+
       // Return the size of this array
+
       size_t length() const;
+
      };
+
      
+
      +
      +

      Multiple aliases can be associated with a method by providing a + comma-separated list of aliases to the %alias directive, e.g.

      +
      +
      %alias MyArray::length "amount,quantity,size";
      +
      +

      From an end-user's standpoint, there's no functional difference + between these two approaches; i.e. they should get the same result from + calling either MyArray#size or MyArray#length. + However, when the %alias directive is used, SWIG doesn't need + to generate all of the wrapper code that's usually associated with + added methods like our MyArray::size() example.

      +

      Note that the %alias directive is implemented using SWIG's + "features" mechanism and so the same name matching rules used for other + kinds of features apply (see the chapter on +"Customization Features") for more details).

      +

      32.4.2 Predicate Methods

      +

      Ruby methods that return a boolean value and end in a question mark + are known as predicate methods. Examples of predicate methods in + standard Ruby classes include Array#empty? (which returns +true for an array containing no elements) and + Object#instance_of? (which returns true if the object is + an instance of the specified class). For consistency with Ruby + conventions, methods that return boolean values should be marked as + predicate methods.

      +

      One cumbersome solution to this problem is to rename the method + (using SWIG's %rename directive) and provide a custom typemap + that converts the function's actual return type to Ruby's true + or false. For example:

      +
      +
      %rename("is_it_safe?") is_it_safe();
+
      
+
      %typemap(out) int is_it_safe 
+
       "$result = ($1 != 0) ? Qtrue : Qfalse;";
+
      
+
      int is_it_safe();
+
      
+
      +
      +

      A better solution is to use the %predicate directive + (unique to SWIG's Ruby module) to designate a method as a predicate + method. For the previous example, this would look like:

      +
      +
      %predicate is_it_safe();
+
      
+
      int is_it_safe();
+
      
+
      +
      +

      This method would be invoked from Ruby code like this:

      +
      +
      irb(main):001:0> Example::is_it_safe?
+
      true
+
      
+
      +
      +

      The %predicate directive is implemented using SWIG's + "features" mechanism and so the same name matching rules used for other + kinds of features apply (see the chapter on +"Customization Features") for more details).

      +

      32.4.3 Bang Methods

      +

      Ruby methods that modify an object in-place and end in an + exclamation mark are known as bang methods. An example of a bang method + is Array#sort! which changes the ordering of items in an + array. Contrast this with Array#sort, which returns a copy of + the array with the items sorted instead of modifying the original + array. For consistency with Ruby conventions, methods that modify + objects in place should be marked as bang methods.

      +

      Bang methods can be marked using the %bang directive which + is unique to the Ruby module and was introduced in SWIG 1.3.28. For + example:

      +
      +
      %bang sort!(arr);
+
      
+
      int sort(int arr[]);
      +
      +

      This method would be invoked from Ruby code like this:

      +
      +
      irb(main):001:0> Example::sort!(arr)
      +
      +

      The %bang directive is implemented using SWIG's "features" + mechanism and so the same name matching rules used for other kinds of + features apply (see the chapter on +"Customization Features") for more details).

      +

      32.4.4 Getters and Setters

      +

      Often times a C++ library will expose properties through getter and + setter methods. For example:

      +
      +
      class Foo {
+
      	Foo() {}
+
      
+
       int getValue() { return value_; }
+
      
+
       void setValue(int value) { value_ = value; }
+
      
+
      private:
+
       int value_;
+
      };
      +
      +

      By default, SWIG will expose these methods to Ruby as get_value + and set_value. However, it more natural for these methods to + be exposed in Ruby as value and value=. That allows + the methods to be used like this:

      +
      +
      irb(main):001:0> foo = Foo.new()
+
      irb(main):002:0> foo.value = 5
+
      irb(main):003:0> puts foo.value
      +
      +

      This can be done by using the %rename directive:

      +
      +
      %rename("value") Foo::getValue();
+
      %rename("value=") Foo::setValue(int value);
+
      +
      +

       

      +

      32.5 Input and output parameters

      +

      A common problem in some C programs is handling parameters passed as + simple pointers. For example:

      +
      +
      void add(int x, int y, int *result) {
+
       *result = x + y;
+
      }
+
      or
+
      int sub(int *x, int *y) {
+
       return *x-*y;
+
      }
+
      +
      +

      The easiest way to handle these situations is to use the +typemaps.i file. For example:

      +
      +
      %module Example
+
      %include "typemaps.i"
+
      
+
      void add(int, int, int *OUTPUT);
+
      int sub(int *INPUT, int *INPUT);
+
      +
      +

      In Ruby, this allows you to pass simple values. For example:

      +
      +
      a = Example.add(3,4)
+
      puts a
+
      7
+
      b = Example.sub(7,4)
+
      puts b
+
      3
+
      +
      +

      Notice how the INPUT parameters allow integer values to be + passed instead of pointers and how the OUTPUT parameter + creates a return result.

      +

      If you don't want to use the names INPUT or OUTPUT, + use the %apply directive. For example:

      +
      +
      %module Example
+
      %include "typemaps.i"
+
      
+
      %apply int *OUTPUT { int *result };
+
      %apply int *INPUT { int *x, int *y};
+
      
+
      void add(int x, int y, int *result);
+
      int sub(int *x, int *y);
+
      +
      +

      If a function mutates one of its parameters like this,

      +
      +
      void negate(int *x) {
+
       *x = -(*x);
+
      }
+
      +
      +

      you can use INOUT like this:

      +
      +
      %include "typemaps.i"
+
      ...
+
      void negate(int *INOUT);
+
      +
      +

      In Ruby, a mutated parameter shows up as a return value. For example:

      +
      +
      a = Example.negate(3)
+
      print a
+
      -3
+
      
+
      +
      +

      The most common use of these special typemap rules is to handle + functions that return more than one value. For example, sometimes a + function returns a result as well as a special error code:

      +
      +
      /* send message, return number of bytes sent, success code, and error_code */
+
      int send_message(char *text, int *success, int *error_code);
+
      +
      +

      To wrap such a function, simply use the OUTPUT rule above. + For example:

      +
      +
      %module example
+
      %include "typemaps.i"
+
      ...
+
      int send_message(char *, int *OUTPUT, int *OUTPUT);
+
      +
      +

      When used in Ruby, the function will return an array of multiple + values.

      +
      +
      bytes, success, error_code = send_message("Hello World")
+
      if not success
+
       print "error #{error_code} : in send_message"
+
      else
+
       print "Sent", bytes
+
      end
+
      +
      +

      Another way to access multiple return values is to use the +%apply rule. In the following example, the parameters rows and + columns are related to SWIG as OUTPUT values through the use + of %apply

      +
      +
      %module Example
+
      %include "typemaps.i"
+
      %apply int *OUTPUT { int *rows, int *columns };
+
      ...
+
      void get_dimensions(Matrix *m, int *rows, int*columns);
+
      +
      +

      In Ruby:

      +
      +
      r, c = Example.get_dimensions(m)
+
      +
      +

      32.6 Exception handling

      +

      32.6.1 Using the %exception directive

      +

      The SWIG %exception directive can be used to define a + user-definable exception handler that can convert C/C++ errors into + Ruby exceptions. The chapter on Customization + Features contains more details, but suppose you have a C++ class + like the following :

      +
      +
      class DoubleArray {
+
       private:
+
       int n;
+
       double *ptr;
+
       public:
+
       // Create a new array of fixed size
+
       DoubleArray(int size) {
+
       ptr = new double[size];
+
       n = size;
+
       }
+
      
+
       // Destroy an array
+
       ~DoubleArray() {
+
       delete ptr;
+
       } 
+
      
+
       // Return the length of the array
+
       int length() {
+
       return n;
+
       }
+
      
+
       // Get an array item and perform bounds checking.
+
       double getitem(int i) {
+
       if ((i >= 0) && (i < n))
+
       return ptr[i];
+
       else
+
       throw RangeError();
+
       }
+
      
+
       // Set an array item and perform bounds checking.
+
       void setitem(int i, double val) {
+
       if ((i >= 0) && (i < n))
+
       ptr[i] = val;
+
       else {
+
       throw RangeError();
+
       }
+
       }
+
       };
+
      +
      +

      Since several methods in this class can throw an exception for an + out-of-bounds access, you might want to catch this in the Ruby + extension by writing the following in an interface file:

      +
      +
      %exception {
+
       try {
+
       $action
+
       }
+
       catch (const RangeError&) {
+
       static VALUE cpperror = rb_define_class("CPPError", rb_eStandardError);
+
       rb_raise(cpperror, "Range error.");
+
       }
+
      }
+
      
+
      class DoubleArray {
+
       ...
+
      };
+
      +
      +

      The exception handling code is inserted directly into generated + wrapper functions. When an exception handler is defined, errors can be + caught and used to gracefully raise a Ruby exception instead of forcing + the entire program to terminate with an uncaught error.

      +

      As shown, the exception handling code will be added to every wrapper + function. Because this is somewhat inefficient, you might consider + refining the exception handler to only apply to specific methods like + this:

      +
      +
      %exception getitem {
+
       try {
+
       $action
+
       }
+
       catch (const RangeError&) {
+
       static VALUE cpperror = rb_define_class("CPPError", rb_eStandardError);
+
       rb_raise(cpperror, "Range error in getitem.");
+
       }
+
      }
+
      
+
      %exception setitem {
+
       try {
+
       $action
+
       }
+
       catch (const RangeError&) {
+
       static VALUE cpperror = rb_define_class("CPPError", rb_eStandardError);
+
       rb_raise(cpperror, "Range error in setitem.");
+
       }
+
      }
+
      +
      +

      In this case, the exception handler is only attached to methods and + functions named getitem and setitem.

      +

      Since SWIG's exception handling is user-definable, you are not + limited to C++ exception handling. See the chapter on +Customization Features for more examples.

      +

      32.6.2 Handling Ruby Blocks

      +

      One of the highlights of Ruby and most of its standard library is the + use of blocks, which allow the easy creation of continuations and other + niceties.  Blocks in ruby are also often used to simplify the passing + of many arguments to a class.

      +

      In order to make your class constructor support blocks, you can take + advantage of the %exception directive, which will get run after the C++ + class' constructor was called. 

      +

      For example, this yields the class over after its construction: +

      +
      +
      class Window
+
      {
+
      public:
+
       Window(int x, int y, int w, int h);
+
      // .... other methods here ....
+
      };
+
      
+
      // Add support for yielding self in the Class' constructor.
+
      %exception Window::Window {
+
       $action
+
       if (rb_block_given_p()) {
+
       rb_yield(self);
+
       }
+
      }
      +
      +

      Then, in ruby, it can be used like:

      +
      +Window.new(0,0,360,480) { |w| +
          w.color = Fltk::RED +
          w.border = false +
      + + }
      +
      +

      For other methods, you can usually use a dummy parameter with a + special in typemap, like:

      +
      // +
      // original function was: +
      // +
      // void func(int x); +
      +
      %typemap(in,numinputs=0) int RUBY_YIELD_SELF { +
           if ( !rb_block_given_p() ) +
                  rb_raise("No block given"); +
           return rb_yield(self); +
      } +
      +
      %extend { +
              void func(int x, int RUBY_YIELD_SELF ); +
      }
      +

      For more information on typemaps, see Typemaps +.

      +

      32.6.3 Raising exceptions

      +

      There are three ways to raise exceptions from C++ code to Ruby.

      +

      The first way is to use SWIG_exception(int code, const char *msg) +. The following table shows the mappings from SWIG error codes to Ruby + exceptions:

      +
      + + + + + + + + + + + + + + + + +
      +SWIG_MemoryError
      +rb_eNoMemError
      +SWIG_IOError
      +rb_eIOError
      +SWIG_RuntimeError
      +rb_eRuntimeError
      +SWIG_IndexError
      +rb_eIndexError
      +SWIG_TypeError
      +rb_eTypeError
      +SWIG_DivisionByZero
      +rb_eZeroDivError
      +SWIG_OverflowError
      +rb_eRangeError
      +SWIG_SyntaxError
      +rb_eSyntaxError
      +SWIG_ValueError
      +rb_eArgError
      +SWIG_SystemError
      +rb_eFatal
      +SWIG_AttributeError
      +rb_eRuntimeError
      +SWIG_NullReferenceError
      +rb_eNullReferenceError*
      +SWIG_ObjectPreviouslyDeletedError
      		 +
      rb_eObjectPreviouslyDeleted*
      +SWIG_UnknownError
      +rb_eRuntimeError
      +* These error classes are created by SWIG and are not built-in Ruby + exception classes
      +
      +

      The second way to raise errors is to use SWIG_Raise(obj, type, + desc). Obj is a C++ instance of an exception class, type is a + string specifying the type of exception (for example, "MyError") and + desc is the SWIG description of the exception class. For example:

      +
      + %raise(SWIG_NewPointerObj(e, SWIGTYPE_p_AssertionFailedException, 0), + ":AssertionFailedException", SWIGTYPE_p_AssertionFailedException);
      +

      This is useful when you want to pass the current exception object + directly to Ruby, particularly when the object is an instance of class + marked as an %exceptionclass (see the next section for more + information).

      +

      Last, you can raise an exception by directly calling Ruby's C api. + This is done by invoking the rb_raise() function. The first + argument passed to rb_raise() is the exception type. You can + raise a custom exception type or one of the built-in Ruby exception + types.

      +

      32.6.4 Exception classes

      +

      Starting with SWIG 1.3.28, the Ruby module supports the +%exceptionclass directive, which is used to identify C++ classes + that are used as exceptions. Classes that are marked with the +%exceptionclass directive are exposed in Ruby as child classes of +rb_eRuntimeError. This allows C++ exceptions to be directly mapped + to Ruby exceptions, providing for a more natural integration between + C++ code and Ruby code.

      +
      +
      	%exceptionclass CustomError;
+
      	
+
      	%inline %{
+
      	class CustomError { };
+
      	
+
      	class Foo { 
+
      	public:
+
      	void test() { throw CustomError; }
+
      	};
+
      	}
+
      +
      +

      From Ruby you can now call this method like this:

      +
      +
      foo = Foo.new
+
      begin
+
       foo.test()
+
      rescue CustomError => e
+
       puts "Caught custom error"
+
      end
      +
      +

      For another example look at swig/Examples/ruby/exception_class. +

      +

      32.7 Typemaps

      +

      This section describes how you can modify SWIG's default wrapping + behavior for various C/C++ datatypes using the %typemap + directive. This is an advanced topic that assumes familiarity with the + Ruby C API as well as the material in the "Typemaps +" chapter. 

      +

      Before proceeding, it should be stressed that typemaps are not a + required part of using SWIG---the default wrapping behavior is enough + in most cases. Typemaps are only used if you want to change some aspect + of the primitive C-Ruby interface.

      +

      32.7.1 What is a typemap?

      +

      A typemap is nothing more than a code generation rule that is + attached to a specific C datatype. The general form of this declaration + is as follows ( parts enclosed in [...] are optional ):    

      +
      + +%typemap( method [, modifiers...] ) typelist code;
      +

      method is a simply a name that specifies what kind of + typemap is being defined. It is usually a name like "in", +"out", or "argout" (or its director variations). The + purpose of these methods is described later.

      +

      modifiers is an optional comma separated list of +name="value" values. These are sometimes to attach extra + information to a typemap and is often target-language dependent.

      +

      typelist is a list of the C++ type patterns that the + typemap will match. The general form of this list is as follows:

      +
      +
      typelist : typepattern [, typepattern, typepattern, ... ] ;
+
      
+
      typepattern : type [ (parms) ]
+
       | type name [ (parms) ]
+
       | ( typelist ) [ (parms) ]
+
      +
      +

      Each type pattern is either a simple type, a simple type and + argument name, or a list of types in the case of multi-argument + typemaps. In addition, each type pattern can be parameterized with a + list of temporary variables (parms). The purpose of these variables + will be explained shortly.

      +

      code specifies the C code used in the typemap. It can take + any one of the following forms:

      +
      +
      code : { ... }
+
       | " ... "
+
       | %{ ... %}
+
      +
      +

      For example, to convert integers from Ruby to C, you might define a + typemap like this:

      +
      +
      %module example
+
      
+
      %typemap(in) int {
+
       $1 = (int) NUM2INT($input);
+
       printf("Received an integer : %d\n",$1);
+
      }
+
      
+
      %inline %{
+
      extern int fact(int n);
+
      %}
+
      +
      +

      Typemaps are always associated with some specific aspect of code + generation. In this case, the "in" method refers to the conversion of + input arguments to C/C++. The datatype int is the datatype to + which the typemap will be applied. The supplied C code is used to + convert values. In this code a number of special variables prefaced by + a $ are used. The $1 variable is placeholder for a + local variable of type int. The $input variable is + the input Ruby object.

      +

      When this example is compiled into a Ruby module, the following + sample code:

      +
      +
      require 'example'
+
      
+
      puts Example.fact(6)
+
      +
      +

      prints the result:

      +
      +
      Received an integer : 6
+
      720
+
      +
      +

      In this example, the typemap is applied to all occurrences of the +int datatype. You can refine this by supplying an optional + parameter name. For example:

      +
      +
      %module example
+
      
+
      %typemap(in) int n {
+
       $1 = (int) NUM2INT($input);
+
       printf("n = %d\n",$1);
+
      }
+
      
+
      %inline %{
+
      extern int fact(int n);
+
      %}
+
      +
      +

      In this case, the typemap code is only attached to arguments that + exactly match "int n".

      +

      The application of a typemap to specific datatypes and argument names + involves more than simple text-matching--typemaps are fully integrated + into the SWIG type-system. When you define a typemap for int, + that typemap applies to int and qualified variations such as +const int. In addition, the typemap system follows typedef + declarations. For example:

      +
      +
      %typemap(in) int n {
+
       $1 = (int) NUM2INT($input);
+
       printf("n = %d\n",$1);
+
      }
+
      
+
      typedef int Integer;
+
      extern int fact(Integer n); // Above typemap is applied
+
      +
      +

      However, the matching of typedef only occurs in one + direction. If you defined a typemap for Integer, it is not + applied to arguments of type int.

      +

      Typemaps can also be defined for groups of consecutive arguments. For + example:

      +
      +
      %typemap(in) (char *str, int len) {
+
       $1 = STR2CSTR($input);
+
       $2 = (int) RSTRING($input)->len;
+
      };
+
      
+
      int count(char c, char *str, int len);
+
      +
      +

      When a multi-argument typemap is defined, the arguments are always + handled as a single Ruby object. This allows the function count + to be used as follows (notice how the length parameter is omitted):

      +
      +
      puts Example.count('o','Hello World')
+
      2
+
      +
      +

      32.7.2 Typemap scope

      +

      Once defined, a typemap remains in effect for all of the + declarations that follow. A typemap may be redefined for different + sections of an input file. For example:

      +
      +
      // typemap1
+
      %typemap(in) int {
+
      ...
+
      }
+
      
+
      int fact(int); // typemap1
+
      int gcd(int x, int y); // typemap1
+
      
+
      // typemap2
+
      %typemap(in) int {
+
      ...
+
      }
+
      
+
      int isprime(int); // typemap2
+
      +
      +

      One exception to the typemap scoping rules pertains to the +%extend declaration. %extend is used to attach new + declarations to a class or structure definition. Because of this, all + of the declarations in an %extend block are subject to the + typemap rules that are in effect at the point where the class itself is + defined. For example:

      +
      +
      class Foo {
+
       ...
+
      };
+
      
+
      %typemap(in) int {
+
       ...
+
      }
+
      
+
      %extend Foo {
+
       int blah(int x); // typemap has no effect. Declaration is attached to Foo which 
+
       // appears before the %typemap declaration.
+
      };
+
      +
      +

      32.7.3 Copying a typemap

      +

      A typemap is copied by using assignment. For example:

      +
      +
      %typemap(in) Integer = int;
+
      +
      +

      or this:

      +
      +
      %typemap(in) Integer, Number, int32_t = int;
+
      +
      +

      Types are often managed by a collection of different typemaps. For + example:

      +
      +
      %typemap(in) int { ... }
+
      %typemap(out) int { ... }
+
      %typemap(varin) int { ... }
+
      %typemap(varout) int { ... }
+
      +
      +

      To copy all of these typemaps to a new type, use %apply. + For example:

      +
      +
      %apply int { Integer }; // Copy all int typemaps to Integer
+
      %apply int { Integer, Number }; // Copy all int typemaps to both Integer and Number
+
      +
      +

      The patterns for %apply follow the same rules as for +%typemap. For example:

      +
      +
      %apply int *output { Integer *output }; // Typemap with name
+
      %apply (char *buf, int len) { (char *buffer, int size) }; // Multiple arguments
+
      +
      +

      32.7.4 Deleting a typemap

      +

      A typemap can be deleted by simply defining no code. For example:

      +
      +
      %typemap(in) int; // Clears typemap for int
+
      %typemap(in) int, long, short; // Clears typemap for int, long, short
+
      %typemap(in) int *output; 
+
      +
      +

      The %clear directive clears all typemaps for a given type. + For example:

      +
      +
      %clear int; // Removes all types for int
+
      %clear int *output, long *output;
+
      +
      +

      Note: Since SWIG's default behavior is defined by typemaps, + clearing a fundamental type like int will make that type + unusable unless you also define a new set of typemaps immediately after + the clear operation.

      +

      32.7.5 Placement of + typemaps

      +

      Typemap declarations can be declared in the global scope, within a + C++ namespace, and within a C++ class. For example:

      +
      +
      %typemap(in) int {
+
       ...
+
      }
+
      
+
      namespace std {
+
       class string;
+
       %typemap(in) string {
+
       ...
+
       }
+
      }
+
      
+
      class Bar {
+
      public:
+
       typedef const int & const_reference;
+
       %typemap(out) const_reference {
+
       ...
+
       }
+
      };
+
      +
      +

      When a typemap appears inside a namespace or class, it stays in + effect until the end of the SWIG input (just like before). However, the + typemap takes the local scope into account. Therefore, this code

      +
      +
      namespace std {
+
       class string;
+
       %typemap(in) string {
+
       ...
+
       }
+
      }
+
      +
      +

      is really defining a typemap for the type std::string. You + could have code like this:

      +
      +
      namespace std {
+
       class string;
+
       %typemap(in) string { /* std::string */
+
       ...
+
       }
+
      }
+
      
+
      namespace Foo {
+
       class string;
+
       %typemap(in) string { /* Foo::string */
+
       ...
+
       }
+
      }
+
      +
      +

      In this case, there are two completely distinct typemaps that apply + to two completely different types (std::string and +Foo::string).

      +

      It should be noted that for scoping to work, SWIG has to know that +string is a typename defined within a particular namespace. In this + example, this is done using the class declaration class string + .

      +

      32.7.6 Ruby typemaps

      +

      The following list details all of the typemap methods that can be + used by the Ruby module:

      +

      32.7.6.1  "in" typemap

      +

      Converts Ruby objects to input function arguments. For example:

      +
      +
      %typemap(in) int {
+
       $1 = NUM2INT($input);
+
      }
+
      +
      +

      The following special variables are available:

      +
      + + + + + + + +
      $input + Input object holding value to be converted.
      $symname + Name of function/method being wrapped
      $1...n + Argument being sent to the function
      $1_name + Name of the argument (if provided)
      $1_type + The actual C datatype matched by the typemap.
      $1_ltype + The assignable version of the C datatype matched by the typemap.
      +
      +

      This is probably the most commonly redefined typemap because it can + be used to implement customized conversions.

      +

      In addition, the "in" typemap allows the number of converted + arguments to be specified. For example:

      +
      +
      // Ignored argument.
+
      %typemap(in, numinputs=0) int *out (int temp) {
+
       $1 = &temp;
+
      }
+
      +
      +

      At this time, only zero or one arguments may be converted.

      +

      32.7.6.2 "typecheck" typemap

      +

      The "typecheck" typemap is used to support overloaded functions and + methods. It merely checks an argument to see whether or not it matches + a specific type. For example:

      +
      +
      %typemap(typecheck,precedence=SWIG_TYPECHECK_INTEGER) int {
+
       $1 = FIXNUM_P($input) ? 1 : 0;
+
      }
+
      +
      +

      For typechecking, the $1 variable is always a simple integer that is + set to 1 or 0 depending on whether or not the input argument is the + correct type.

      +

      If you define new "in" typemaps and your program uses + overloaded methods, you should also define a collection of "typecheck" + typemaps. More details about this follow in a later section on + "Typemaps and Overloading."

      +

      32.7.6.3  "out" typemap

      +

      Converts return value of a C function to a Ruby object.

      +
      +
      %typemap(out) int { +
         $result = INT2NUM( $1 ); +
      } +
      +

      The following special variables are available.

      +
      + + + + + + + +
      $result + Result object returned to target language.
      $symname + Name of function/method being wrapped
      $1...n + Argument being wrapped
      $1_name + Name of the argument (if provided)
      $1_type + The actual C datatype matched by the typemap.
      $1_ltype + The assignable version of the C datatype matched by the typemap.
      +
      +
      +

      32.7.6.4 "arginit" typemap

      +

      The "arginit" typemap is used to set the initial value of a function + argument--before any conversion has occurred. This is not normally + necessary, but might be useful in highly specialized applications. For + example:

      +
      +
      // Set argument to NULL before any conversion occurs
+
      %typemap(arginit) int *data {
+
       $1 = NULL;
+
      }
+
      +
      +

      32.7.6.5 "default" typemap

      +

      The "default" typemap is used to turn an argument into a default + argument. For example:

      +
      +
      %typemap(default) int flags {
+
       $1 = DEFAULT_FLAGS;
+
      }
+
      ...
+
      int foo(int x, int y, int flags);
+
      +
      +

      The primary use of this typemap is to either change the wrapping of + default arguments or specify a default argument in a language where + they aren't supported (like C). Target languages that do not support + optional arguments, such as Java and C#, effectively ignore the value + specified by this typemap as all arguments must be given.

      +

      Once a default typemap has been applied to an argument, all + arguments that follow must have default values. See the + Default/optional arguments section for further information on + default argument wrapping.

      +

      32.7.6.6 "check" typemap

      +

      The "check" typemap is used to supply value checking code during + argument conversion. The typemap is applied after arguments + have been converted. For example:

      +
      +
      %typemap(check) int positive {
+
       if ($1 <= 0) {
+
       SWIG_exception(SWIG_ValueError,"Expected positive value.");
+
       }
+
      }
+
      +
      +

      32.7.6.7 "argout" typemap

      +

      The "argout" typemap is used to return values from arguments. This + is most commonly used to write wrappers for C/C++ functions that need + to return multiple values. The "argout" typemap is almost always + combined with an "in" typemap---possibly to ignore the input value. For + example:

      +
      +
      /* Set the input argument to point to a temporary variable */
+
      %typemap(in, numinputs=0) int *out (int temp) {
+
       $1 = &temp;
+
      }
+
      
+
      %typemap(argout, fragment="output_helper") int *out {
+
       // Append output value $1 to $result (assuming a single integer in this case)
+
       $result = output_helper( $result, INT2NUM(*$1) );
+
      }
+
      +
      +

      The following special variables are available.

      +
      + + + + +
      $result + Result object returned to target language.
      $input + The original input object passed.
      $symname + Name of function/method being wrapped.
      +
      +

      The code supplied to the "argout" typemap is always placed after the + "out" typemap. If multiple return values are used, the extra return + values are often appended to return value of the function.

      +

      Output helper is a fragment that usually defines a macro to some + function like SWIG_Ruby_AppendOutput.

      +

      See the typemaps.i library for examples.

      +

      32.7.6.8 "freearg" typemap

      +

      The "freearg" typemap is used to cleanup argument data. It is only + used when an argument might have allocated resources that need to be + cleaned up when the wrapper function exits. The "freearg" typemap + usually cleans up argument resources allocated by the "in" typemap. For + example:

      +
      +
      // Get a list of integers
+
      %typemap(in) int *items {
+
       int nitems = Length($input); 
+
       $1 = (int *) malloc(sizeof(int)*nitems);
+
      }
+
      // Free the list 
+
      %typemap(freearg) int *items {
+
       free($1);
+
      }
+
      +
      +

      The "freearg" typemap inserted at the end of the wrapper function, + just before control is returned back to the target language. This code + is also placed into a special variable $cleanup that may be + used in other typemaps whenever a wrapper function needs to abort + prematurely.

      +

      32.7.6.9 "newfree" typemap

      +

      The "newfree" typemap is used in conjunction with the %newobject + directive and is used to deallocate memory used by the return result of + a function. For example:

      +
      +
      %typemap(newfree) string * {
+
       delete $1;
+
      }
+
      %typemap(out) string * {
+
       $result = PyString_FromString($1->c_str());
+
      }
+
      ...
+
      
+
      %newobject foo;
+
      ...
+
      string *foo();
+
      +
      +

      See +Object ownership and %newobject for further details.

      +

      32.7.6.10 "memberin" typemap

      +

      The "memberin" typemap is used to copy data from an already + converted input value into a structure member. It is typically + used to handle array members and other special cases. For example:

      +
      +
      %typemap(memberin) int [4] {
+
       memmove($1, $input, 4*sizeof(int));
+
      }
+
      +
      +

      It is rarely necessary to write "memberin" typemaps---SWIG already + provides a default implementation for arrays, strings, and other + objects.

      +

      32.7.6.11 "varin" typemap

      +

      The "varin" typemap is used to convert objects in the target + language to C for the purposes of assigning to a C/C++ global variable. + This is implementation specific.

      +

      32.7.6.12 "varout" typemap

      +

      The "varout" typemap is used to convert a C/C++ object to an object + in the target language when reading a C/C++ global variable. This is + implementation specific.

      +

      32.7.6.13 "throws" typemap

      +

      The "throws" typemap is only used when SWIG parses a C++ method with + an exception specification or has the %catches feature + attached to the method. It provides a default mechanism for handling + C++ methods that have declared the exceptions they will throw. The + purpose of this typemap is to convert a C++ exception into an error or + exception in the target language. It is slightly different to the other + typemaps as it is based around the exception type rather than the type + of a parameter or variable. For example:

      +
      +
      %typemap(throws) const char * %{
+
       rb_raise(rb_eRuntimeError, $1);
+
       SWIG_fail;
+
      %}
+
      void bar() throw (const char *);
+
      +
      +

      As can be seen from the generated code below, SWIG generates an + exception handler with the catch block comprising the "throws" typemap + content.

      +
      +
      ...
+
      try {
+
       bar();
+
      }
+
      catch(char const *_e) {
+
       rb_raise(rb_eRuntimeError, _e);
+
       SWIG_fail;
+
      }
+
      ...
+
      +
      +

      Note that if your methods do not have an exception specification yet + they do throw exceptions, SWIG cannot know how to deal with them. For a + neat way to handle these, see the +Exception handling with %exception section.

      +

      32.7.6.14 directorin typemap

      +

      Converts C++ objects in director member functions to ruby objects. It + is roughly the opposite of the "in" typemap, making its typemap rule + often similar to the "out" typemap.

      +
      +
      %typemap(directorin) int { +
           $result = INT2NUM($1); +
      } +
      +

      The following special variables are available.

      +
      + + + + + + + + +
      $result + Result object returned to target language.
      $symname + Name of function/method being wrapped
      $1...n + Argument being wrapped
      $1_name + Name of the argument (if provided)
      $1_type + The actual C datatype matched by the typemap.
      $1_ltype + The assignable version of the C datatype matched by the typemap.
      this + C++ this, referring to the class itself.
      +
      +

      32.7.6.15 directorout typemap

      +

      Converts Ruby objects in director member functions to C++ objects. +  It is roughly the opposite of the "out" typemap, making its rule often + similar to the "in" typemap.

      +
      +
      %typemap(directorout) int {       +
         $result = NUM2INT($1);       +
      } +
      +

      The following special variables are available:

      +
      + + + + + + + +
      $symname + Name of function/method being wrapped
      $1...n + Argument being sent to the function
      $1_name + Name of the argument (if provided)
      $1_type + The actual C datatype matched by the typemap.
      $1_ltype + The assignable version of the C datatype matched by the typemap.
      this + C++ this, referring to the class itself.
      +
      +

      Currently, the directorout nor the out typemap support the option  + +numoutputs, but the Ruby module provides that functionality through a + %feature directive.  Thus, a function can be made to return "nothing" + if you do:

      +
      +%feature("numoutputs","0") MyClass::function;
      +

      This feature can be useful if a function returns a status code, which + you want to discard but still use the typemap to raise an exception. +

      +

      32.7.6.16 directorargout + typemap

      +

      Output argument processing in director member functions.

      +
      +%typemap(directorargout, fragment="output_helper") int { +
      $result = output_helper( $result, NUM2INT($1) );       +
      }
      +

      The following special variables are available:

      +
      + + + + + + + + +
      $result +Result that the director function returns
      $symname +name of the function/method being wrapped
      $1...n +Argument being sent to the function
      $1_name +Name of the argument (if provided)
      $1_type +The actual C datatype matched by the typemap
      $1_ltype +The assignable version of the C datatype matched by the typemap
      this +C++ this, referring to the instance of the class itself
      +
      +

      32.7.6.17 ret typemap

      +

      Cleanup of function return values

      +

      32.7.6.18 globalin typemap

      +

      Setting of C global variables

      +

      32.7.7 Typemap variables

      +

      Within a typemap, a number of special variables prefaced with a +$ may appear. A full list of variables can be found in the " +Typemaps" chapter. This is a list of the most common variables:

      +

      $1

      +
      A C local variable corresponding to the actual type + specified in the %typemap directive. For input values, this is + a C local variable that is supposed to hold an argument value. For + output values, this is the raw result that is supposed to be returned + to Ruby.
      +

      $input

      +
      A VALUE holding a raw Ruby object with an + argument or variable value.
      +

      $result

      +
      A VALUE that holds the result to be + returned to Ruby.
      +

      $1_name

      +
      The parameter name that was matched.
      +

      $1_type

      +
      The actual C datatype matched by the typemap.
      +

      $1_ltype

      +
      An assignable version of the datatype matched by the + typemap (a type that can appear on the left-hand-side of a C assignment + operation). This type is stripped of qualifiers and may be an altered + version of $1_type. All arguments and local variables in + wrapper functions are declared using this type so that their values can + be properly assigned.
      +

      $symname

      +
      The Ruby name of the wrapper function being created.
      +

      32.7.8 Useful Functions

      +

      When you write a typemap, you usually have to work directly with + Ruby objects. The following functions may prove to be useful. (These + functions plus many more can be found in +Programming Ruby, by David Thomas and Andrew Hunt.) 

      +

      In addition, we list equivalent functions that Swig defines, which + provide a language neutral conversion (these functions are defined for + each swig language supported).  If you are trying to create a swig file + that will work under multiple languages, it is recommended you stick to + the swig functions instead of the native Ruby functions.  That should + help you avoid having to rewrite a lot of typemaps across multiple + languages.

      +

      32.7.8.1 C Datatypes to Ruby Objects

      +
      + + + + + + + + +
      RUBY +Swig
      INT2NUM(long or int) +SWIG_From_int(int x) int to Fixnum or Bignum
      INT2FIX(long or int) + int to Fixnum (faster than INT2NUM)
      CHR2FIX(char) +SWIG_From_char(char x) char to Fixnum
      rb_str_new2(char*) +SWIG_FromCharPtrAndSize(char*, size_t) char* to String
      rb_float_new(double) +SWIG_From_double(double), +
      SWIG_From_float(float)      		float/double to Float
      +
      +

      32.7.8.2 Ruby Objects to C Datatypes

      +

      Here, while the Ruby versions return the value directly, the SWIG + versions do not, but return a status value to indicate success ( + +SWIG_OK). While more akward to use, this allows you to write typemaps + that report more helpful error messages, like:

      +
      +
      %typemap(in) size_t (int ok) +
        +
        ok = SWIG_AsVal_size_t($input, &$1); +
        if (!SWIG_IsOK(ok)) { +
          SWIG_exception_fail(SWIG_ArgError(ok), Ruby_Format_TypeError( + "$1_name", "$1_type","$symname", $argnum, $input )); +
         } +
      +
      }
        
      + + + + + + + + + + + + + + + +
      int NUM2INT(Numeric) +SWIG_AsVal_int(VALUE, int*)
      int FIX2INT(Numeric) +SWIG_AsVal_int(VALUE, int*)
      unsigned int NUM2UINT(Numeric)SWIG_AsVal_unsigned_SS_int(VALUE, int*)
      unsigned int FIX2UINT(Numeric)SWIG_AsVal_unsigned_SS_int(VALUE, int*)
      long NUM2LONG(Numeric) +SWIG_AsVal_long(VALUE, long*)
      long FIX2LONG(Numeric) +SWIG_AsVal_long(VALUE, long*)
      unsigned long FIX2ULONG(Numeric)SWIG_AsVal_unsigned_SS_long(VALUE, + unsigned long*)
      char NUM2CHR(Numeric or String)SWIG_AsVal_char(VALUE, int*)
      char * STR2CSTR(String) +SWIG_AsCharPtrAndSize(VALUE, char*, size_t, int* alloc)
      char * rb_str2cstr(String, + int*length)
      double NUM2DBL(Numeric) +(double) SWIG_AsVal_int(VALUE) or similar
      +
      +

      32.7.8.3 Macros for VALUE

      +

      RSTRING_LEN(str)

      +
      length of the Ruby string
      +

      RSTRING_PTR(str)

      +
      pointer to string storage
      +

      RARRAY_LEN(arr)

      +
      length of the Ruby array
      +

      RARRAY(arr)->capa

      +
      capacity of the Ruby array
      +

      RARRAY_PTR(arr)

      +
      pointer to array storage
      +

      32.7.8.4 Exceptions

      +

      void rb_raise(VALUE exception, const char *fmt, ...)

      +
      Raises an exception. The given format string fmt + and remaining arguments are interpreted as with printf().
      +

      void rb_fatal(const char *fmt, ...)

      +
      Raises a fatal exception, terminating the process. + No rescue blocks are called, but ensure blocks will be called. The + given format string fmt and remaining arguments are interpreted + as with printf().
      +

      void rb_bug(const char *fmt, ...)

      +
      Terminates the process immediately -- no handlers + of any sort will be called. The given format string fmt and + remaining arguments are interpreted as with printf(). You + should call this function only if a fatal bug has been exposed.
      +

      void rb_sys_fail(const char *msg)

      +
      Raises a platform-specific exception corresponding + to the last known system error, with the given string msg.
      +

      VALUE rb_rescue(VALUE (*body)(VALUE), VALUE args, + VALUE(*rescue)(VALUE, VALUE), VALUE rargs)

      +
      Executes body with the given args. If + a StandardError exception is raised, then execute rescue + with the given rargs.
      +

      VALUE rb_ensure(VALUE(*body)(VALUE), VALUE args, + VALUE(*ensure)(VALUE), VALUE eargs)

      +
      Executes body with the given args. + Whether or not an exception is raised, execute ensure with the + given rargs after body has completed.
      +

      VALUE rb_protect(VALUE (*body)(VALUE), VALUE args, int *result) +

      +
      Executes body with the given args and + returns nonzero in result if any exception was raised.
      +

      void rb_notimplement()

      +
      Raises a NotImpError exception to indicate + that the enclosed function is not implemented yet, or not available on + this platform.
      +

      void rb_exit(int status)

      +
      Exits Ruby with the given status. Raises a +SystemExit exception and calls registered exit functions and + finalizers.
      +

      void rb_warn(const char *fmt, ...)

      +
      Unconditionally issues a warning message to + standard error. The given format string fmt and remaining + arguments are interpreted as with printf().
      +

      void rb_warning(const char *fmt, ...)

      +
      Conditionally issues a warning message to standard + error if Ruby was invoked with the -w flag. The given format + string fmt and remaining arguments are interpreted as with +printf().
      +

      32.7.8.5 Iterators

      +

      void rb_iter_break()

      +
      Breaks out of the enclosing iterator block.
      +

      VALUE rb_each(VALUE obj)

      +
      Invokes the each method of the given + obj.
      +

      VALUE rb_yield(VALUE arg)

      +
      Transfers execution to the iterator block in the + current context, passing arg as an argument. Multiple values may + be passed in an array.
      +

      int rb_block_given_p()

      +
      Returns true if yield would + execute a block in the current context; that is, if a code block was + passed to the current method and is available to be called.
      +

      VALUE rb_iterate(VALUE (*method)(VALUE), VALUE args, VALUE + (*block)(VALUE, VALUE), VALUE arg2)

      +
      Invokes method with argument args and + block block. A yield from that method will invoke + block with the argument given to yield, and a second + argument arg2.
      +

      VALUE rb_catch(const char *tag, VALUE (*proc)(VALUE, VALUE), + VALUE value)

      +
      Equivalent to Ruby's catch.
      +

      void rb_throw(const char *tag, VALUE value)

      +
      Equivalent to Ruby's throw.
      +

      32.7.9 Typemap Examples

      +

      This section includes a few examples of typemaps. For more examples, + you might look at the examples in the Example/ruby directory.

      +

      32.7.10 Converting a Ruby array to a char **

      +

      A common problem in many C programs is the processing of command + line arguments, which are usually passed in an array of NULL + terminated strings. The following SWIG interface file allows a Ruby + Array instance to be used as a char ** object.

      +
      +
      %module argv
+
      
+
      // This tells SWIG to treat char ** as a special case
+
      %typemap(in) char ** {
+
       /* Get the length of the array */
+
       int size = RARRAY($input)->len; 
+
       int i;
+
       $1 = (char **) malloc((size+1)*sizeof(char *));
+
       /* Get the first element in memory */
+
       VALUE *ptr = RARRAY($input)->ptr; 
+
       for (i=0; i < size; i++, ptr++)
+
       /* Convert Ruby Object String to char* */
+
       $1[i]= STR2CSTR(*ptr); 
+
       $1[i]=NULL; /* End of list */
+
      }
+
      
+
      // This cleans up the char ** array created before 
+
      // the function call
+
      
+
      %typemap(freearg) char ** {
+
       free((char *) $1);
+
      }
+
      
+
      // Now a test function
+
      %inline %{
+
      int print_args(char **argv) {
+
       int i = 0;
+
       while (argv[i]) {
+
       printf("argv[%d] = %s\n", i,argv[i]);
+
       i++;
+
       }
+
       return i;
+
      }
+
      %}
+
      
+
      +
      +

      When this module is compiled, the wrapped C function now operates as + follows :

      +
      +
      require 'Argv'
+
      Argv.print_args(["Dave","Mike","Mary","Jane","John"])
+
      argv[0] = Dave
+
      argv[1] = Mike
+
      argv[2] = Mary
+
      argv[3] = Jane
+
      argv[4] = John
+
      +
      +

      In the example, two different typemaps are used. The "in" typemap is + used to receive an input argument and convert it to a C array. Since + dynamic memory allocation is used to allocate memory for the array, the + "freearg" typemap is used to later release this memory after the + execution of the C function.

      +

      32.7.11 Collecting arguments in a hash

      +

      Ruby's solution to the "keyword arguments" capability of some other + languages is to allow the programmer to pass in one or more key-value + pairs as arguments to a function. All of those key-value pairs are + collected in a single Hash argument that's presented to the + function. If it makes sense, you might want to provide similar + functionality for your Ruby interface. For example, suppose you'd like + to wrap this C function that collects information about people's vital + statistics:

      +
      +
      void setVitalStats(const char *person, int nattributes, const char **names, int *values);
+
      +
      +

      and you'd like to be able to call it from Ruby by passing in an + arbitrary number of key-value pairs as inputs, e.g.

      +
      +
      setVitalStats("Fred",
+
       'weight' => 270,
+
      	'age' => 42
+
      	)
+
      +
      +

      To make this work, you need to write a typemap that expects a Ruby +Hash as its input and somehow extracts the last three arguments ( +nattributes, names and values) needed by your C + function. Let's start with the basics:

      +
      +
      %typemap(in) (int nattributes, const char **names, const int *values)
+
       (VALUE keys_arr, int i, VALUE key, VALUE val) {
+
      }
+
      +
      +

      This %typemap directive tells SWIG that we want to match + any function declaration that has the specified types and names of + arguments somewhere in the argument list. The fact that we specified + the argument names (nattributes, names and values) + in our typemap is significant; this ensures that SWIG won't try to + apply this typemap to other functions it sees that happen to + have a similar declaration with different argument names. The arguments + that appear in the second set of parentheses (keys_arr, i +, key and val) define local variables that our typemap + will need.

      +

      Since we expect the input argument to be a Hash, let's next + add a check for that:

      +
      +
      %typemap(in) (int nattributes, const char **names, const int *values)
+
       (VALUE keys_arr, int i, VALUE key, VALUE val) {
+
       Check_Type($input, T_HASH);
+
      }
+
      +
      +

      Check_Type() is just a macro (defined in the Ruby header + files) that confirms that the input argument is of the correct type; if + it isn't, an exception will be raised.

      +

      The next task is to determine how many key-value pairs are present in + the hash; we'll assign this number to the first typemap argument ( +$1). This is a little tricky since the Ruby/C API doesn't provide a + public function for querying the size of a hash, but we can get around + that by calling the hash's size method directly and converting + its result to a C int value:

      +
      +
      %typemap(in) (int nattributes, const char **names, const int *values)
+
       (VALUE keys_arr, int i, VALUE key, VALUE val) {
+
       Check_Type($input, T_HASH);
+
       $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, NULL));
+
      }
+
      +
      +

      So now we know the number of attributes. Next we need to initialize + the second and third typemap arguments (i.e. the two C arrays) to +NULL and set the stage for extracting the keys and values from the + hash:

      +
      +
      %typemap(in) (int nattributes, const char **names, const int *values)
+
       (VALUE keys_arr, int i, VALUE key, VALUE val) {
+
       Check_Type($input, T_HASH);
+
       $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, NULL));
+
       $2 = NULL;
+
       $3 = NULL;
+
       if ($1 > 0) {
+
       $2 = (char **) malloc($1*sizeof(char *));
+
       $3 = (int *) malloc($1*sizeof(int));
+
       }      
+
      }
+
      +
      +

      There are a number of ways we could extract the keys and values from + the input hash, but the simplest approach is to first call the hash's + keys method (which returns a Ruby array of the keys) and then start + looping over the elements in that array:

      +
      +
      %typemap(in) (int nattributes, const char **names, const int *values)
+
       (VALUE keys_arr, int i, VALUE key, VALUE val) {
+
       Check_Type($input, T_HASH);
+
       $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, NULL));
+
       $2 = NULL;
+
       $3 = NULL;
+
       if ($1 > 0) {
+
       $2 = (char **) malloc($1*sizeof(char *));
+
       $3 = (int *) malloc($1*sizeof(int));
+
       keys_arr = rb_funcall($input, rb_intern("keys"), 0, NULL);
+
       for (i = 0; i < $1; i++) {
+
       }      
+
      }
+
      }
+
      +
      +

      Recall that keys_arr and i are local variables for + this typemap. For each element in the keys_arr array, we want to + get the key itself, as well as the value corresponding to that key in + the hash:

      +
      +
      %typemap(in) (int nattributes, const char **names, const int *values)
+
       (VALUE keys_arr, int i, VALUE key, VALUE val) {
+
       Check_Type($input, T_HASH);
+
       $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, NULL));
+
       $2 = NULL;
+
       $3 = NULL;
+
       if ($1 > 0) {
+
       $2 = (char **) malloc($1*sizeof(char *));
+
       $3 = (int *) malloc($1*sizeof(int));
+
       keys_arr = rb_funcall($input, rb_intern("keys"), 0, NULL);
+
       for (i = 0; i < $1; i++) {
+
       key = rb_ary_entry(keys_arr, i);
+
       val = rb_hash_aref($input, key);      
+
      }
+
      }
+
      }
+
      +
      +

      To be safe, we should again use the Check_Type() macro to + confirm that the key is a String and the value is a Fixnum +:

      +
      +
      %typemap(in) (int nattributes, const char **names, const int *values)
+
       (VALUE keys_arr, int i, VALUE key, VALUE val) {
+
       Check_Type($input, T_HASH);
+
       $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, NULL));
+
       $2 = NULL;
+
       $3 = NULL;
+
       if ($1 > 0) {
+
       $2 = (char **) malloc($1*sizeof(char *));
+
       $3 = (int *) malloc($1*sizeof(int));
+
       keys_arr = rb_funcall($input, rb_intern("keys"), 0, NULL);
+
       for (i = 0; i < $1; i++) {
+
       key = rb_ary_entry(keys_arr, i);
+
       val = rb_hash_aref($input, key);
+
       Check_Type(key, T_STRING);
+
       Check_Type(val, T_FIXNUM);      
+
      }
+
      }
+
      }
+
      +
      +

      Finally, we can convert these Ruby objects into their C equivalents + and store them in our local C arrays:

      +
      +
      %typemap(in) (int nattributes, const char **names, const int *values)
+
       (VALUE keys_arr, int i, VALUE key, VALUE val) {
+
       Check_Type($input, T_HASH);
+
       $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, NULL));
+
       $2 = NULL;
+
       $3 = NULL;
+
       if ($1 > 0) {
+
       $2 = (char **) malloc($1*sizeof(char *));
+
       $3 = (int *) malloc($1*sizeof(int));
+
       keys_arr = rb_funcall($input, rb_intern("keys"), 0, NULL);
+
       for (i = 0; i < $1; i++) {
+
       key = rb_ary_entry(keys_arr, i);
+
       val = rb_hash_aref($input, key);
+
       Check_Type(key, T_STRING);
+
       Check_Type(val, T_FIXNUM);
+
       $2[i] = STR2CSTR(key);
+
       $3[i] = NUM2INT(val);      
+
      }
+
      }
+
      }
+
      +
      +

      We're not done yet. Since we used malloc() to dynamically + allocate the memory used for the names and values + arguments, we need to provide a corresponding "freearg" typemap to free + that memory so that there is no memory leak. Fortunately, this typemap + is a lot easier to write:

      +
      +
      %typemap(freearg) (int nattributes, const char **names, const int *values) {
+
       free((void *) $2);
+
       free((void *) $3);
+
      }
+
      +
      +

      All of the code for this example, as well as a sample Ruby program + that uses the extension, can be found in the Examples/ruby/hashargs + directory of the SWIG distribution.

      +

      32.7.12 Pointer handling

      +

      Occasionally, it might be necessary to convert pointer values that + have been stored using the SWIG typed-pointer representation. Since + there are several ways in which pointers can be represented, the + following two functions are used to safely perform this conversion:

      +

      int SWIG_ConvertPtr(VALUE obj, void **ptr, swig_type_info *ty, + int flags)

      +
      Converts a Ruby object obj to a C pointer + whose address is ptr (i.e. ptr is a pointer to a + pointer). The third argument, ty, is a pointer to a SWIG type + descriptor structure. If ty is not NULL, that type + information is used to validate type compatibility and other aspects of + the type conversion. If flags is non-zero, any type errors + encountered during this validation result in a Ruby TypeError + exception being raised; if flags is zero, such type errors will + cause SWIG_ConvertPtr() to return -1 but not raise an + exception. If ty is NULL, no type-checking is + performed.
      +

      VALUE SWIG_NewPointerObj(void *ptr, swig_type_info *ty, int own) +

      +
      Creates a new Ruby pointer object. Here, ptr + is the pointer to convert, ty is the SWIG type descriptor + structure that describes the type, and own is a flag that + indicates whether or not Ruby should take ownership of the pointer + (i.e. whether Ruby should free this data when the corresponding Ruby + instance is garbage-collected).
      +

      Both of these functions require the use of a special SWIG + type-descriptor structure. This structure contains information about + the mangled name of the datatype, type-equivalence information, as well + as information about converting pointer values under C++ inheritance. + For a type of Foo *, the type descriptor structure is usually + accessed as follows:

      +
      +
      Foo *foo;
+
      SWIG_ConvertPtr($input, (void **) &foo, SWIGTYPE_p_Foo, 1);
+
      
+
      VALUE obj;
+
      obj = SWIG_NewPointerObj(f, SWIGTYPE_p_Foo, 0);
+
      +
      +

      In a typemap, the type descriptor should always be accessed using + the special typemap variable $1_descriptor. For example:

      +
      +
      %typemap(in) Foo * {
+
       SWIG_ConvertPtr($input, (void **) &$1, $1_descriptor, 1);
+
      }
+
      +
      +

      32.7.12.1 Ruby Datatype Wrapping

      +

      VALUE Data_Wrap_Struct(VALUE class, void (*mark)(void *), void + (*free)(void *), void *ptr)

      +
      Given a pointer ptr to some C data, and the + two garbage collection routines for this data (mark and free +), return a VALUE for the Ruby object.
      +

      VALUE Data_Make_Struct(VALUE class, c-type, void + (*mark)(void *), void (*free)(void *), c-type *ptr)

      +
      Allocates a new instance of a C data type c-type +, assigns it to the pointer ptr, then wraps that pointer with +Data_Wrap_Struct() as above.
      +

      Data_Get_Struct(VALUE obj, c-type, c-type *ptr) +

      +
      Retrieves the original C pointer of type c-type + from the data object obj and assigns that pointer to ptr.
      +

      32.7.13 Example: STL Vector to Ruby Array

      +

      Another use for macros and type maps is to create a Ruby array from a + STL vector of pointers. In essence, copy of all the pointers in the + vector into a Ruby array. The use of the macro is to make the typemap + so generic that any vector with pointers can use the type map. The + following is an example of how to construct this type of macro/typemap + and should give insight into constructing similar typemaps for other + STL structures:

      +
      +
      %define PTR_VECTOR_TO_RUBY_ARRAY(vectorclassname, classname)
+
      %typemap(out) vectorclassname &, const vectorclassname & {
+
       VALUE arr = rb_ary_new2($1->size());
+
       vectorclassname::iterator i = $1->begin(), iend = $1->end();
+
       for ( ; i!=iend; i++ )
+
       rb_ary_push(arr, Data_Wrap_Struct(c ## classname.klass, 0, 0, *i));
+
       $result = arr;
+
      }
+
      %typemap(out) vectorclassname, const vectorclassname {
+
       VALUE arr = rb_ary_new2($1.size());
+
       vectorclassname::iterator i = $1.begin(), iend = $1.end();
+
       for ( ; i!=iend; i++ )
+
       rb_ary_push(arr, Data_Wrap_Struct(c ## classname.klass, 0, 0, *i));
+
       $result = arr;
+
      }
+
      %enddef
+
      +
      +

      Note, that the "c ## classname.klass" is used in the + preprocessor step to determine the actual object from the class name.

      +

      To use the macro with a class Foo, the following is used:

      +
      +
      PTR_VECTOR_TO_RUBY_ARRAY(vector<foo *="">, Foo)
+
      +
      +

      It is also possible to create a STL vector of Ruby objects:

      +
      +
      %define RUBY_ARRAY_TO_PTR_VECTOR(vectorclassname, classname)
+
      %typemap(in) vectorclassname &, const vectorclassname & {
+
       Check_Type($input, T_ARRAY);
+
       vectorclassname *vec = new vectorclassname;
+
       int len = RARRAY($input)->len;
+
       for (int i=0; i!=len; i++) {
+
       VALUE inst = rb_ary_entry($input, i);
+
       //The following _should_ work but doesn't on HPUX
+
       // Check_Type(inst, T_DATA);
+
       classname *element = NULL;
+
       Data_Get_Struct(inst, classname, element);
+
       vec->push_back(element);
+
       }
+
       $1 = vec;
+
      }
+
      
+
      %typemap(freearg) vectorclassname &, const vectorclassname & {
+
       delete $1;
+
      }
+
      %enddef
+
      +
      +

      It is also possible to create a Ruby array from a vector of static + data types:

      +
      +
      %define VECTOR_TO_RUBY_ARRAY(vectorclassname, classname)
+
      %typemap(out) vectorclassname &, const vectorclassname & {
+
       VALUE arr = rb_ary_new2($1->size()); 
+
       vectorclassname::iterator i = $1->begin(), iend = $1->end();
+
       for ( ; i!=iend; i++ )
+
       rb_ary_push(arr, Data_Wrap_Struct(c ## classname.klass, 0, 0, &(*i)));
+
       $result = arr;
+
      }
+
      %typemap(out) vectorclassname, const vectorclassname {
+
       VALUE arr = rb_ary_new2($1.size()); 
+
       vectorclassname::iterator i = $1.begin(), iend = $1.end();
+
       for ( ; i!=iend; i++ )
+
       rb_ary_push(arr, Data_Wrap_Struct(c ## classname.klass, 0, 0, &(*i)));
+
       $result = arr;
+
      }
+
      %enddef
+
      +
      +
      Note that this is mostly an example of typemaps. If you want to use + the STL with ruby, you are advised to use the standard swig STL + library, which does much more than this.  Refer to the section called + the C++ Standard Template Library. +
      +

      32.8 Docstring Features

      +

      Using ri and rdoc web pages in Ruby libraries is a common practice. + Given the way that SWIG generates the extensions by default, your users + will normally not get any documentation for it, even if they run 'rdoc' + on the resulting .c or .cxx file.

      +

      The features described in this section make it easy for you to add + rdoc strings to your modules, functions and methods that can then be + read by Ruby's rdoc tool to generate html web pages, ri documentation, + Windows chm file and an .xml description.

      +

      rdoc can then be run from a console or shell window on a swig + generated file. 

      +

      For example, to generate html web pages from a C++ file, you'd do: 

      +
      + + $ rdoc -E cxx=c -f html file_wrap.cxx
      +

      To generate ri documentation from a c wrap file, you could do:

      +
      + +$ rdoc -r file_wrap.c
      +

      32.8.1 Module docstring

      +

      Ruby allows a docstring at the beginning of the file before any + other statements, and it is typically used to give a general + description of the entire module. SWIG supports this by setting an + option of the %module directive. For example:

      +
      +
      %module(docstring="This is the example module's docstring") example
+
      +
      +

      When you have more than just a line or so then you can retain the + easy readability of the %module directive by using a macro. + For example:

      +
      +
      %define DOCSTRING
+
      "The `XmlResource` class allows program resources defining menus, 
+
      layout of controls on a panel, etc. to be loaded from an XML file."
+
      %enddef
+
      
+
      %module(docstring=DOCSTRING) xrc
+
      +
      +

      32.8.2 %feature("autodoc")

      +

      Since SWIG does know everything about the function it wraps, it is + possible to generate an rdoc containing the parameter types, names and + default values. Since Ruby ships with one of the best documentation + systems of any language, it makes sense to take advantage of it.

      +

      SWIG's Ruby module provides support for the "autodoc" feature, which + when attached to a node in the parse tree will cause an rdoc comment to + be generated in the wrapper file that includes the name of the + function, parameter names, default values if any, and return type if + any. There are also several options for autodoc controlled by the value + given to the feature, described below.

      +

      32.8.2.1 %feature("autodoc", "0")

      +

      When the "0" option is given then the types of the parameters will + not be included in the autodoc string. For example, given this + function prototype:

      +
      +
      %feature("autodoc", "0");
+
      bool function_name(int x, int y, Foo* foo=NULL, Bar* bar=NULL);
+
      +
      +

      Then Ruby code like this will be generated:

      +
      +
      function_name(x, y, foo=nil, bar=nil) -> bool
+
       ...
+
      +
      +

      32.8.2.2 %feature("autodoc", "1")

      +

      When the "1" option is used then the parameter types will + be used in the rdoc string. In addition, an attempt is made to simplify + the type name such that it makes more sense to the Ruby user. Pointer, + reference and const info is removed, %rename's are evaluated, + etc. (This is not always successful, but works most of the time. See + the next section for what to do when it doesn't.) Given the example + above, then turning on the parameter types with the "1" option will + result in rdoc code like this:

      +
      +
      function_name(int x, int y, Foo foo=nil, Bar bar=nil) -> bool
+
       ...
+
      +
      +

      32.8.2.3 %feature("autodoc", "2")

      +

      When the "2" option is used then the parameter types will not be + used in the rdoc string. However, they will be listed in full after the + function.  Given the example above, then turning on the parameter types + with the "2" option will result in Ruby code like this:

      +

      32.8.2.4 %feature("autodoc", + "3")

      +

      When the "3" option is used then the function will be documented + using a combination of "1" and "2" above.  Given the example above, + then turning on the parameter types with the "2" option will result in + Ruby code like this:

      +
      +
      function_name(int x, int y, Foo foo=nil, Bar bar=nil) -> bool
+
      
+
      Parameters:
+
      	x - int
+
      	y - int
+
      	foo - Foo
+
      	bar - Bar
+
      +
      +

      32.8.2.5 %feature("autodoc", "docstring")

      +

      Finally, there are times when the automatically generated autodoc + string will make no sense for a Ruby programmer, particularly when a + typemap is involved. So if you give an explicit value for the autodoc + feature then that string will be used in place of the automatically + generated string. For example:

      +
      +
      %feature("autodoc", "GetPosition() -> (x, y)") GetPosition;
+
      void GetPosition(int* OUTPUT, int* OUTPUT);
+
      +
      +

      32.8.3 %feature("docstring")

      +

      In addition to the autodoc strings described above, you can also + attach any arbitrary descriptive text to a node in the parse tree with + the "docstring" feature. When the proxy module is generated then any + docstring associated with classes, function or methods are output. If + an item already has an autodoc string then it is combined with the + docstring and they are output together.

      +

      32.9 Advanced Topics

      +

      32.9.1 Operator overloading

      +

      SWIG allows operator overloading with, by using the %extend + or %rename commands in SWIG and the following operator names + (derived from Python):

      +
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      General
      __repr__ inspect
      __str__ to_s
      __cmp__ <=>
      __hash__ hash
      __nonzero__ nonzero?
      Callable
      __call__ call
      Collection
      __len__ length
      __getitem__ []
      __setitem__ []=
      Numeric
      __add__ +
      __sub__ -
      __mul__ *
      __div__ /
      __mod__ %
      __divmod__ divmod
      __pow__ **
      __lshift__ <<
      __rshift__ >>
      __and__ &
      __xor__ ^
      __or__ |
      __neg__ -@
      __pos__ +@
      __abs__ abs
      __invert__ ~
      __int__ to_i
      __float__ to_f
      __coerce__ coerce
      Additions in 1.3.13
      __lt__ <
      __le__ <=
      __eq__ ==
      __gt__ >
      __ge__ >=
      +
      +

      Note that although SWIG supports the __eq__ magic method + name for defining an equivalence operator, there is no separate method + for handling inequality since Ruby parses the expression a != + b as !(a == b).

      +

      32.9.2 Creating Multi-Module Packages

      +

      The chapter on Working with Modules + discusses the basics of creating multi-module extensions with SWIG, and + in particular the considerations for sharing runtime type information + among the different modules.

      +

      As an example, consider one module's interface file (shape.i +) that defines our base class:

      +
      +
      %module shape
+
      
+
      %{
+
      #include "Shape.h"
+
      %}
+
      
+
      class Shape {
+
      protected:
+
       double xpos;
+
       double ypos;
+
      protected:
+
       Shape(double x, double y);
+
      public:
+
       double getX() const;
+
       double getY() const;
+
      };
+
      +
      +

      We also have a separate interface file (circle.i) that + defines a derived class:

      +
      +
      %module circle
+
      
+
      %{
+
      #include "Shape.h"
+
      #include "Circle.h"
+
      %}
+
      
+
      // Import the base class definition from Shape module
+
      %import shape.i
+
      
+
      class Circle : public Shape {
+
      protected:
+
       double radius;
+
      public:
+
       Circle(double x, double y, double r);
+
       double getRadius() const;
+
      };
+
      +
      +

      We'll start by building the Shape extension module:

      +
      +
      $ swig -c++ -ruby shape.i
+
      +
      +

      SWIG generates a wrapper file named shape_wrap.cxx. To + compile this into a dynamically loadable extension for Ruby, prepare an + extconf.rb script using this template:

      +
      +
      require 'mkmf'
+
      
+
      # Since the SWIG runtime support library for Ruby
+
      # depends on the Ruby library, make sure it's in the list
+
      # of libraries.
+
      $libs = append_library($libs, Config::CONFIG['RUBY_INSTALL_NAME'])
+
      
+
      # Create the makefile
+
      create_makefile('shape')
+
      +
      +

      Run this script to create a Makefile and then type make + to build the shared library:

      +
      +
      $ ruby extconf.rb
+
      creating Makefile
+
      $ make
+
      g++ -fPIC -g -O2 -I. -I/usr/local/lib/ruby/1.7/i686-linux \
+
      -I. -c shape_wrap.cxx
+
      gcc -shared -L/usr/local/lib -o shape.so shape_wrap.o -L. \
+
      -lruby -lruby -lc
+
      +
      +

      Note that depending on your installation, the outputs may be + slightly different; these outputs are those for a Linux-based + development environment. The end result should be a shared library + (here, shape.so) containing the extension module code. Now + repeat this process in a separate directory for the Circle + module:

      +
        +
      1. Run SWIG to generate the wrapper code (circle_wrap.cxx);
        2. +
      2. Write an extconf.rb script that your end-users can use to + create a platform-specific Makefile for the extension;
        3. +
      3. Build the shared library for this extension by typing make +.
        4. +
      +

      Once you've built both of these extension modules, you can test them + interactively in IRB to confirm that the Shape and Circle + modules are properly loaded and initialized:

      +
      +
      $ irb
+
      irb(main):001:0> require 'shape'
+
      true
+
      irb(main):002:0> require 'circle'
+
      true
+
      irb(main):003:0> c = Circle::Circle.new(5, 5, 20)
+
      #<Circle::Circle:0xa097208>
+
      irb(main):004:0> c.kind_of? Shape::Shape
+
      true
+
      irb(main):005:0> c.getX()
+
      5.0
+
      +
      +

      32.9.3 Specifying Mixin Modules

      +

      The Ruby language doesn't support multiple inheritance, but it does + allow you to mix one or more modules into a class using Ruby's +include method. For example, if you have a Ruby class that defines + an each instance method, e.g.

      +
      +
      class Set
+
       def initialize
+
       @members = []
+
       end
+
       
+
       def each
+
       @members.each { |m| yield m }
+
       end
+
      end
+
      +
      +

      then you can mix-in Ruby's Enumerable module to easily add + a lot of functionality to your class:

      +
      +
      class Set
+
       include Enumerable
+
      def initialize
+
      @members = []
+
      end
+
      def each
+
      @members.each { |m| yield m }
+
      end
+
      end
+
      +
      +

      To get the same benefit for your SWIG-wrapped classes, you can use + the %mixin directive to specify the names of one or more + modules that should be mixed-in to a class. For the above example, the + SWIG interface specification might look like this:

      +
      +
      %mixin Set "Enumerable";
+
      
+
      class Set {
+
      public:
+
       // Constructor
+
       Set();
+
       
+
       // Iterates through set members
+
       void each();
+
      };
+
      +
      +

      Multiple modules can be mixed into a class by providing a + comma-separated list of module names to the %mixin directive, + e.g.

      +
      +
      %mixin Set "Fee,Fi,Fo,Fum";
      +
      +

      Note that the %mixin directive is implemented using SWIG's + "features" mechanism and so the same name matching rules used for other + kinds of features apply (see the chapter on +"Customization Features") for more details).

      +

      32.10 Memory Management

      +

      One of the most common issues in generating SWIG bindings for Ruby is + proper memory management. The key to proper memory management is + clearly defining whether a wrapper Ruby object owns the underlying C + struct or C++ class. There are two possibilities:

      +
        +
      • The Ruby object is responsible for freeing the C struct or C++ + object
        • +
      • The Ruby object should not free the C struct or C++ object because + it will be freed by the underlying C or C++ code
        • +
      +

      To complicate matters, object ownership may transfer from Ruby to C++ + (or vice versa) depending on what function or methods are invoked. + Clearly, developing a SWIG wrapper requires a thorough understanding of + how the underlying library manages memory.

      +

      32.10.1 Mark and Sweep Garbage Collector

      +

      Ruby uses a mark and sweep garbage collector. When the garbage + collector runs, it finds all the "root" objects, including local + variables, global variables, global constants, hardware registers and + the C stack. For each root object, the garbage collector sets its mark + flag to true and calls rb_gc_mark on the object. The job of +rb_gc_mark is to recursively mark all the objects that a Ruby + object has a reference to (ignoring those objects that have already + been marked). Those objects, in turn, may reference other objects. This + process will continue until all active objects have been "marked." + After the mark phase comes the sweep phase. In the sweep phase, all + objects that have not been marked will be garbage collected. For more + information about the Ruby garbage collector please refer to + + + http://rubygarden.org/ruby/ruby?GCAndExtensions.

      +

      The Ruby C/API provides extension developers two hooks into the + garbage collector - a "mark" function and a "sweep" function. By + default these functions are set to NULL.

      +

      If a C struct or C++ class references any other Ruby objects, then it + must provide a "mark" function. The "mark" function should identify any + referenced Ruby objects by calling the rb_gc_mark function for each + one. Unsurprisingly, this function will be called by the Ruby garbage + during the "mark" phase.

      +

      During the sweep phase, Ruby destroys any unused objects. If any + memory has been allocated in creating the underlying C struct or C++ + struct, then a "free" function must be defined that deallocates this + memory.

      +

      32.10.2 Object Ownership

      +

      As described above, memory management depends on clearly defining who + is responsible for freeing the underlying C struct or C++ class. If the + Ruby object is responsible for freeing the C++ object, then a "free" + function must be registered for the object. If the Ruby object is not + responsible for freeing the underlying memory, then a "free" function + must not be registered for the object.

      +

      For the most part, SWIG takes care of memory management issues. The + rules it uses are:

      +
        +
      • When calling a C++ object's constructor from Ruby, SWIG will assign + a "free" function thereby making the Ruby object responsible for + freeing the C++ object
        • +
      • When calling a C++ member function that returns a pointer, SWIG + will not assign a "free" function thereby making the underlying library + responsible for freeing the object.
        • +
      +

      To make this clearer, let's look at an example. Assume we have a Foo + and a Bar class.

      +
      +
      /* File "RubyOwernshipExample.h" */
+
      
+
      class Foo
+
      {
+
      public:
+
       Foo() {}
+
       ~Foo() {}
+
      };
+
      
+
      class Bar
+
      {
+
       Foo *foo_;
+
      public:
+
       Bar(): foo_(new Foo) {}
+
       ~Bar() { delete foo_; }
+
       Foo* get_foo() { return foo_; }
+
       Foo* get_new_foo() { return new Foo; }
+
       void set_foo(Foo *foo) { delete foo_; foo_ = foo; }
+
      };
+
      
+
      +
      +

      First, consider this Ruby code:

      +
      +
      foo = Foo.new
      +
      +

      In this case, the Ruby code calls the underlying Foo C++ + constructor, thus creating a new foo object. By default, SWIG + will assign the new Ruby object a "free" function. When the Ruby object + is garbage collected, the "free" function will be called. It in turn + will call Foo's destructor.

      +

      Next, consider this code:

      +
      +
      bar = Bar.new
+
      foo = bar.get_foo()
      +
      +

      In this case, the Ruby code calls a C++ member function, get_foo +. By default, SWIG will not assign the Ruby object a "free" function. + Thus, when the Ruby object is garbage collected the underlying C++ +foo object is not affected.

      +

      Unfortunately, the real world is not as simple as the examples above. + For example:

      +
      +
      bar = Bar.new
+
      foo = bar.get_new_foo()
      +
      +

      In this case, the default SWIG behavior for calling member functions + is incorrect. The Ruby object should assume ownership of the returned + object. This can be done by using the %newobject directive. See + Object ownership and %newobject for more information.

      +

      The SWIG default mappings are also incorrect in this case:

      +
      +
      foo = Foo.new
+
      bar = Bar.new
+
      bar.set_foo(foo)
      +
      +

      Without modification, this code will cause a segmentation fault. When + the Ruby foo object goes out of scope, it will free the + underlying C++ foo object. However, when the Ruby bar object + goes out of scope, it will call the C++ bar destructor which will also + free the C++ foo object. The problem is that object ownership + is transferred from the Ruby object to the C++ object when the +set_foo method is called. This can be done by using the special + DISOWN type map, which was added to the Ruby bindings in SWIG-1.3.26.

      +

      Thus, a correct SWIG interface file correct mapping for these classes + is:

      +
      +
      /* File RubyOwnershipExample.i */
+
      
+
      %module RubyOwnershipExample
+
      
+
      %{
+
      #include "RubyOwnershipExample.h"
+
      %}
+
      
+
      class Foo
+
      {
+
      public:
+
       Foo();
+
       ~Foo();
+
      };
+
      
+
      class Bar
+
      {
+
       Foo *foo_;
+
      public:
+
       Bar();
+
       ~Bar();
+
       Foo* get_foo();
+
      
+
      
+
+ %newobject get_new_foo;
+
       Foo* get_new_foo();
+
      
+
      
+
+ %apply SWIGTYPE *DISOWN {Foo *foo};
+
       void set_foo(Foo *foo);
+
      
+
+ %clear Foo *foo;
+
      };
+
      
+
      +
      +
      +

      This code can be seen in swig/examples/ruby/tracking.

      +
      +

      32.10.3 Object Tracking

      +

      The remaining parts of this section will use the class library shown + below to illustrate different memory management techniques. The class + library models a zoo and the animals it contains.

      +
      +
      %module zoo
+
      
+
      %{
+
      #include <string>
+
      #include <vector>
+
      
+
      #include "zoo.h"
+
      %}
+
      
+
      class Animal
+
      {
+
      private:
+
       typedef std::vector<Animal*> AnimalsType;
+
       typedef AnimalsType::iterator IterType;
+
      protected:
+
       AnimalsType animals;
+
      protected:
+
       std::string name_;
+
      public:
+
       // Construct an animal with this name
+
       Animal(const char* name) : name_(name) {}
+
       
+
       // Return the animal's name
+
       const char* get_name() const { return name.c_str(); }
+
      };
+
      
+
      class Zoo
+
      {
+
      protected:
+
       std::vector<animal *=""> animals;
+
       
+
      public:
+
       // Construct an empty zoo
+
       Zoo() {}
+
       
+
       /* Create a new animal. */
+
       static Animal* Zoo::create_animal(const char* name)
+
       {
+
       return new Animal(name);
+
       }
+
      
+
       // Add a new animal to the zoo
+
       void add_animal(Animal* animal) {
+
       animals.push_back(animal); 
+
       }
+
      
+
       Animal* remove_animal(size_t i) {
+
       Animal* result = this->animals[i];
+
       IterType iter = this->animals.begin();
+
       std::advance(iter, i);
+
       this->animals.erase(iter);
+
      
+
       return result;
+
       }
+
       
+
       // Return the number of animals in the zoo
+
       size_t get_num_animals() const {
+
       return animals.size(); 
+
       }
+
       
+
       // Return a pointer to the ith animal
+
       Animal* get_animal(size_t i) const {
+
       return animals[i]; 
+
       }
+
      };
+
      
+
      +
      +

      Let's say you SWIG this code and then run IRB: +

      +
      +
      $ 
+
+irb
+
      irb(main):001:0> 
+
+require 'example'
+
      => true
+
      
+
      irb(main):002:0> 
+
+tiger1 = Example::Animal.new("tiger1")
+
      => #<Example::Animal:0x2be3820>
+
      
+
      irb(main):004:0> 
+
+tiger1.get_name()
+
      => "tiger1"
+
      
+
      irb(main):003:0> 
+
+zoo = Example::Zoo.new()
+
      => #<Example::Zoo:0x2be0a60>
+
      
+
      irb(main):006:0> 
+
+zoo.add_animal(tiger)
+
      => nil
+
      
+
      irb(main):007:0> 
+
+zoo.get_num_animals()
+
      => 1
+
      
+
      irb(main):007:0> 
+
+tiger2 = zoo.remove_animal(0)
+
      => #<Example::Animal:0x2bd4a18>
+
      
+
      irb(main):008:0> 
+
+tiger2.get_name()
+
      => "tiger1"
+
      
+
      irb(main):009:0> 
+
+tiger1.equal?(tiger2)
+
      => false
+
      
+
      +
      +

      Pay particular attention to the code tiger1.equal?(tiger2). + Note that the two Ruby objects are not the same - but they reference + the same underlying C++ object. This can cause problems. For example: +

      +
      +
      irb(main):010:0> 
+
+tiger1 = nil
+
      => nil
+
      
+
      irb(main):011:0> 
+
+GC.start
+
      => nil
+
      
+
      irb(main):012:0> 
+
+tiger2.get_name()
+
      (irb):12: [BUG] Segmentation fault
+
      
+
      +
      +

      After the the garbage collector runs, as a result of our call to +GC.start, callingtiger2.get_name() causes a segmentation + fault. The problem is that when tiger1 is garbage collected, + it frees the underlying C++ object. Thus, when tiger2 calls + the get_name() method it invokes it on a destroyed object.

      +

      This problem can be avoided if SWIG enforces a one-to-one mapping + between Ruby objects and C++ classes. This can be done via the use of + the %trackobjects functionality available in SWIG-1.3.26. and + later.

      +

      When the %trackobjects is turned on, SWIG automatically + keeps track of mappings between C++ objects and Ruby objects. Note that + enabling object tracking causes a slight performance degradation. Test + results show this degradation to be about 3% to 5% when creating and + destroying 100,000 animals in a row.

      +

      Since %trackobjects is implemented as a %feature, + it uses the same name matching rules as other kinds of features (see + the chapter on "Customization Features") + . Thus it can be applied on a class-by-class basis if needed. To fix + the example above:

      +
      +
      %module example
+
      
+
      %{
+
      #include "example.h"
+
      %}
+
      
+
      
+
+/* Tell SWIG that create_animal creates a new object */
+
      
+
+%newobject Zoo::create_animal;
+
      
+
      
+
+/* Tell SWIG to keep track of mappings between C/C++ structs/classes. */
+
      
+
+%trackobjects;
+
      
+
      %include "example.h"
      +
      +

      When this code runs we see: +
      +

      +
      +
      $ 
+
+irb
+
      irb(main):001:0> 
+
+require 'example'
+
      => true
+
      
+
      irb(main):002:0> 
+
+tiger1 = Example::Animal.new("tiger1")
+
      => #<Example::Animal:0x2be37d8>
+
      
+
      irb(main):003:0> 
+
+zoo = Example::Zoo.new()
+
      => #<Example::Zoo:0x2be0a18>
+
      
+
      irb(main):004:0> 
+
+zoo.add_animal(tiger1)
+
      => nil
+
      
+
      irb(main):006:0> 
+
+tiger2 = zoo.remove_animal(0)
+
      => #<Example::Animal:0x2be37d8>
+
      
+
      irb(main):007:0> 
+
+tiger1.equal?(tiger2)
+
      => true
+
      
+
      irb(main):008:0> 
+
+tiger1 = nil
+
      => nil
+
      
+
      irb(main):009:0> 
+
+GC.start
+
      => nil
+
      
+
      irb(main):010:0> 
+
+tiger.get_name()
+
      => "tiger1"
+
      irb(main):011:0>
+
      
+
      +
      +

      For those who are interested, object tracking is implemented by + storing Ruby objects in a hash table and keying them on C++ pointers. + The underlying API is: +

      +
      +
      static void SWIG_RubyAddTracking(void* ptr, VALUE object);
+
      static VALUE SWIG_RubyInstanceFor(void* ptr) ;
+
      static void SWIG_RubyRemoveTracking(void* ptr);
+
      static void SWIG_RubyUnlinkObjects(void* ptr);
      +
      +

      When an object is created, SWIG will automatically call the +SWIG_RubyAddTracking method. Similarly, when an object is deleted, + SWIG will call the SWIG_RubyRemoveTracking. When an object is + returned to Ruby from C++, SWIG will use the SWIG_RubyInstanceFor + method to ensure a one-to-one mapping from Ruby to C++ objects. Last, + the RubyUnlinkObjects method unlinks a Ruby object from its + underlying C++ object.

      +

      In general, you will only need to use the SWIG_RubyInstanceFor +, which is required for implementing mark functions as shown below. + However, if you implement your own free functions (see below) you may + also have to call the SWIG_RubyRemoveTracking and +RubyUnlinkObjects methods.

      +

      32.10.4 Mark Functions

      +

      With a bit more testing, we see that our class library still has + problems. For example: +

      +
      +
      $ irb
+
      irb(main):001:0> 
+
+require 'example'
+
      => true
+
      
+
      irb(main):002:0> tiger1 = 
+
+Example::Animal.new("tiger1")
+
      => #<Example::Animal:0x2bea6a8>
+
      
+
      irb(main):003:0> zoo = 
+
+Example::Zoo.new()
+
      => #<Example::Zoo:0x2be7960>
+
      
+
      irb(main):004:0> 
+
+zoo.add_animal(tiger1)
+
      => nil
+
      
+
      irb(main):007:0> 
+
+tiger1 = nil
+
      => nil
+
      
+
      irb(main):007:0> 
+
+GC.start
+
      => nil
+
      
+
      irb(main):005:0> 
+
+tiger2 = zoo.get_animal(0)
+
      (irb):12: [BUG] Segmentation fault
      +
      +

      The problem is that Ruby does not know that the zoo object + contains a reference to a Ruby object. Thus, when Ruby garbage collects + + tiger1 it frees the underlying C++ object.

      +

      This can be fixed by implementing a mark function as + described above in the Mark and Sweep Garbage + Collector section. You can specify a mark function by using the +%markfunc directive. Since the %markfunc directive is + implemented using SWIG's' "features" mechanism it uses the same name + matching rules as other kinds of features (see the chapter on +"Customization Features" for more details).

      +

      A mark function takes a single argument, which is a pointer + to the C++ object being marked; it should, in turn, call +rb_gc_mark() for any instances that are reachable from the current + object. The mark function for our Zoo class should therefore + loop over all of the C++ animal objects in the zoo object, look up + their Ruby object equivalent, and then call rb_gc_mark(). One + possible implementation is:

      +
      +
      %module example
+
      
+
      %{
+
      #include "example.h"
+
      %}
+
      
+
      /* Keep track of mappings between C/C++ structs/classes
+
       and Ruby objects so we can implement a mark function. */
+
      
+
+%trackobjects;
+
      
+
      /* Specify the mark function */
+
      
+
+%markfunc Zoo "mark_Zoo";
+
      
+
      %include "example.h"
+
      
+
      %header %{
+
      
+
      static void mark_Zoo(void* ptr) {
+
       Zoo* zoo = (Zoo*) ptr;
+
      
+
       /* Loop over each object and tell the garbage collector
+
       that we are holding a reference to them. */
+
       int count = zoo->get_num_animals();
+
      
+
       for(int i = 0; i < count; ++i) {
+
       Animal* animal = zoo->get_animal(i);
+
       VALUE object = SWIG_RubyInstanceFor(animal);
+
      
+
       if (object != Qnil) {
+
       rb_gc_mark(object);
+
       }
+
       }
+
      }
+
      %}
+
      
+
      +
      +

      Note the mark function is dependent on the +SWIG_RUBY_InstanceFor method, and thus requires that +%trackobjects is enabled. For more information, please refer to the + track_object.i test case in the SWIG test suite.

      +

      When this code is compiled we now see:

      +
      +
      $ irb
+
      irb(main):002:0> 
+
+tiger1=Example::Animal.new("tiger1")
+
      => #<Example::Animal:0x2be3bf8>
+
      
+
      irb(main):003:0> 
+
+Example::Zoo.new()
+
      => #<Example::Zoo:0x2be1780>
+
      
+
      irb(main):004:0> 
+
+zoo = Example::Zoo.new()
+
      => #<Example::Zoo:0x2bde9c0>
+
      
+
      irb(main):005:0> 
+
+zoo.add_animal(tiger1)
+
      => nil
+
      
+
      irb(main):009:0> 
+
+tiger1 = nil
+
      => nil
+
      
+
      irb(main):010:0> 
+
+GC.start
+
      => nil
+
      irb(main):014:0> 
+
+tiger2 = zoo.get_animal(0)
+
      => #<Example::Animal:0x2be3bf8>
+
      
+
      irb(main):015:0> 
+
+tiger2.get_name()
+
      => "tiger1"
+
      irb(main):016:0>
+
      
+
      +
      +
      +

      This code can be seen in swig/examples/ruby/mark_function.

      +

      32.10.5 Free Functions

      +

      By default, SWIG creates a "free" function that is called when a Ruby + object is garbage collected. The free function simply calls the C++ + object's destructor.

      +

      However, sometimes an appropriate destructor does not exist or + special processing needs to be performed before the destructor is + called. Therefore, SWIG allows you to manually specify a "free" + function via the use of the %freefunc directive. The +%freefunc directive is implemented using SWIG's' "features" + mechanism and so the same name matching rules used for other kinds of + features apply (see the chapter on +"Customization Features") for more details).

      +

      IMPORTANT ! - If you define your own free function, then you must + ensure that you call the underlying C++ object's destructor. In + addition, if object tracking is activated for the object's class, you + must also call the SWIG_RubyRemoveTracking function (of course + call this before you destroy the C++ object). Note that it is harmless + to call this method if object tracking if off so it is advised to + always call it.

      +

      Note there is a subtle interaction between object ownership and free + functions. A custom defined free function will only be called if the + Ruby object owns the underlying C++ object. This also to Ruby objects + which are created, but then transfer ownership to C++ objects via the + use of the disown typemap described above.

      +

      To show how to use the %freefunc directive, let's slightly + change our example. Assume that the zoo object is responsible for + freeing animal that it contains. This means that the + + Zoo::add_animal function should be marked with a + + DISOWN typemap and the destructor should be updated as below::

      +
      +
      Zoo::~Zoo() {
+
       IterType iter = this->animals.begin();
+
       IterType end = this->animals.end();
+
      
+
       for(iter; iter != end; ++iter) {
+
       Animal* animal = *iter;
+
       delete animal;
+
       }
+
      }
      +
      +

      When we use these objects in IRB we see:

      +
      +
      +
+$irb
+
      irb(main):002:0> 
+
+require 'example'
+
      => true
+
      
+
      irb(main):003:0> 
+
+zoo = Example::Zoo.new()
+
      => #<Example::Zoo:0x2be0fe8>
+
      
+
      irb(main):005:0> 
+
+tiger1 = Example::Animal.new("tiger1")
+
      => #<Example::Animal:0x2bda760>
+
      
+
      irb(main):006:0> 
+
+zoo.add_animal(tiger1)
+
      => nil
+
      
+
      irb(main):007:0> 
+
+zoo = nil
+
      => nil
+
      
+
      irb(main):008:0> 
+
+GC.start
+
      => nil
+
      
+
      irb(main):009:0> 
+
+tiger1.get_name()
+
      (irb):12: [BUG] Segmentation fault
+
      
+
      +
      +

      The error happens because the C++ animal object is freed + when the zoo object is freed. Although this error is + unavoidable, we can at least prevent the segmentation fault. To do this + requires enabling object tracking and implementing a custom free + function that calls the SWIG_RubyUnlinkObjects function for + each animal object that is destroyed. The SWIG_RubyUnlinkObjects + function notifies SWIG that a Ruby object's underlying C++ object is no + longer valid. Once notified, SWIG will intercept any calls from the + existing Ruby object to the destroyed C++ object and raise an + exception. +

      +
      +
      %module example
+
      
+
      %{
+
      #include "example.h"
+
      %}
+
      
+
      /* Specify that ownership is transferred to the zoo
+
      	when calling add_animal */
+
      %apply SWIGTYPE *DISOWN { Animal* animal };
+
      
+
      /* Track objects */
+
      %trackobjects;
+
      
+
      /* Specify the mark function */
+
      %freefunc Zoo "free_Zoo";
+
      
+
      %include "example.h"
+
      
+
      %header %{
+
       static void free_Zoo(void* ptr) {
+
       Zoo* zoo = (Zoo*) ptr;
+
      
+
       /* Loop over each animal */
+
       int count = zoo->get_num_animals();
+
      
+
       for(int i = 0; i < count; ++i) {
+
       /* Get an animal */
+
       Animal* animal = zoo->get_animal(i);
+
      
+
       /* Unlink the Ruby object from the C++ object */
+
       SWIG_RubyUnlinkObjects(animal);
+
      
+
       /* Now remove the tracking for this animal */
+
       SWIG_RubyRemoveTracking(animal);
+
       }
+
      
+
       /* Now call SWIG_RubyRemoveTracking for the zoo */
+
       SWIG_RubyRemoveTracking(ptr);
+
       
+
       /* Now free the zoo which will free the animals it contains */
+
       delete zoo;
+
       }
+
      %}
      +
      +

      Now when we use these objects in IRB we see:

      +
      +
      +
+$irb
+
      irb(main):002:0> 
+
+require 'example'
+
      => true
+
      
+
      irb(main):003:0> 
+
+zoo = Example::Zoo.new()
+
      => #<Example::Zoo:0x2be0fe8>
+
      
+
      irb(main):005:0> 
+
+tiger1 = Example::Animal.new("tiger1")
+
      => #<Example::Animal:0x2bda760>
+
      
+
      irb(main):006:0> 
+
+zoo.add_animal(tiger1)
+
      => nil
+
      
+
      irb(main):007:0> 
+
+zoo = nil
+
      => nil
+
      
+
      irb(main):008:0> 
+
+GC.start
+
      => nil
+
      
+
      irb(main):009:0> 
+
+tiger1.get_name()
+
      RuntimeError: This Animal * already released
+
       from (irb):10:in `get_name'
+
       from (irb):10
+
      irb(main):011:0>
      +
      +

      Notice that SWIG can now detect the underlying C++ object has been + freed, and thus raises a runtime exception.

      +

      This code can be seen in swig/examples/ruby/free_function.

      +

      32.10.6 Embedded Ruby and the C++ Stack

      +

      As has been said, the Ruby GC runs and marks objects before its sweep + phase.  When the garbage collector is called, it will also try to mark + any Ruby objects (VALUE) it finds in the machine registers and in the + C++ stack.

      +

      The stack is basically the history of the functions that have been + called and also contains local variables, such as the ones you define + whenever you do inside a function:

      +
      VALUE obj;
      +

      For ruby to determine where its stack space begins, during + initialization a normal Ruby interpreter will call the ruby_init() + function which in turn will call a function called Init_stack or + similar.  This function will store a pointer to the location where the + stack points at at that point in time.

      +

      ruby_init() is presumed to always be called within the main() + function of your program and whenever the GC is called, ruby will + assume that the memory between the current location in memory and the + pointer that was stored previously represents the stack, which may + contain local (and temporary) VALUE ruby objects.   Ruby will then be + careful not to remove any of those objects in that location.

      +

      So far so good.  For a normal Ruby session, all the above is + completely transparent and magic to the extensions developer.   

      +

      However, with an embedded Ruby, it may not always be possible to + modify main() to make sure ruby_init() is called there.   As such, + ruby_init() will likely end up being called from within some other + function.  This can lead Ruby to measure incorrectly where the stack + begins and can result in Ruby incorrectly collecting those temporary + VALUE objects that are created once another function is called.  The + end result: random crashes and segmentation faults.

      +

      This problem will often be seen in director functions that are used + for callbacks, for example.  

      +

      To solve the problem, SWIG can now generate code with director + functions containing the optional macros SWIG_INIT_STACK and + SWIG_RELEASE_STACK.   These macros will try to force Ruby to + reinitiliaze the beginning of the stack the first time a director + function is called.  This will lead Ruby to measure and not collect any + VALUE objects defined from that point on.  

      +

      To mark functions to either reset the ruby stack or not, you can use:

      +
      %initstack   + Class::memberfunction;  // only re-init the stack in this director + method +
      %ignorestack Class::memberfunction;  // do not re-init the stack in + this director method +
      %initstack   Class;               // init the stack on all the + methods of this class +
      %initstack;   // all director functions will re-init the stack
      +
      +

      33 SWIG and Tcl

      + + +
      + +
      + +

      Caution: This chapter is under repair!

      +

      This chapter discusses SWIG's support of Tcl. SWIG currently + requires Tcl 8.0 or a later release. Earlier releases of SWIG supported + Tcl 7.x, but this is no longer supported.

      +

      33.1 Preliminaries

      +

      To build a Tcl module, run SWIG using the -tcl option :

      +
      +
      +$ swig -tcl example.i
+
      +
      +

      If building a C++ extension, add the -c++ option:

      +
      +
      +$ swig -c++ -tcl example.i
+
      +
      +

      This creates a file example_wrap.c or example_wrap.cxx + that contains all of the code needed to build a Tcl extension module. + To finish building the module, you need to compile this file and link + it with the rest of your program.

      +

      33.1.1 Getting the right header files

      +

      In order to compile the wrapper code, the compiler needs the +tcl.h header file. This file is usually contained in the directory

      +
      +
      +/usr/local/include
+
      +
      +

      Be aware that some Tcl versions install this header file with a + version number attached to it. If this is the case, you should probably + make a symbolic link so that tcl.h points to the correct + header file.

      +

      33.1.2 Compiling a dynamic module

      +

      The preferred approach to building an extension module is to compile + it into a shared object file or DLL. To do this, you will need to + compile your program using commands like this (shown for Linux):

      +
      +
      +$ swig -tcl example.i
+$ gcc -c example.c
+$ gcc -c example_wrap.c -I/usr/local/include
+$ gcc -shared example.o example_wrap.o -o example.so
+
      +
      +

      The exact commands for doing this vary from platform to platform. + SWIG tries to guess the right options when it is installed. Therefore, + you may want to start with one of the examples in the +SWIG/Examples/tcl directory. If that doesn't work, you will need to + read the man-pages for your compiler and linker to get the right set of + options. You might also check the +SWIG Wiki for additional information.

      +

      When linking the module, the name of the output file has to match + the name of the module. If the name of your SWIG module is "example +", the name of the corresponding object file should be "example.so +". The name of the module is specified using the %module + directive or the -module command line option.

      +

      33.1.3 Static linking

      +

      An alternative approach to dynamic linking is to rebuild the Tcl + interpreter with your extension module added to it. In the past, this + approach was sometimes necessary due to limitations in dynamic loading + support on certain machines. However, the situation has improved + greatly over the last few years and you should not consider this + approach unless there is really no other option.

      +

      The usual procedure for adding a new module to Tcl involves writing + a special function Tcl_AppInit() and using it to initialize + the interpreter and your module. With SWIG, the tclsh.i and +wish.i library files can be used to rebuild the tclsh and +wish interpreters respectively. For example:

      +
      +
      +%module example
+
+%inline %{
+extern int fact(int);
+extern int mod(int, int);
+extern double My_variable;
+%}
+
+%include "tclsh.i"       // Include code for rebuilding tclsh
+
+
      +
      +

      The tclsh.i library file includes supporting code that + contains everything needed to rebuild tclsh. To rebuild the + interpreter, you simply do something like this:

      +
      +
      +$ swig -tcl example.i
+$ gcc example.c example_wrap.c \
+        -Xlinker -export-dynamic \
+        -DHAVE_CONFIG_H -I/usr/local/include/ \
+	-L/usr/local/lib -ltcl -lm -ldl \
+	-o mytclsh
+
+
      +
      +

      You will need to supply the same libraries that were used to build + Tcl the first time. This may include system libraries such as +-lsocket, -lnsl, and -lpthread. If this actually + works, the new version of Tcl should be identical to the default + version except that your extension module will be a built-in part of + the interpreter.

      +

      Comment: In practice, you should probably try to avoid static + linking if possible. Some programmers may be inclined to use static + linking in the interest of getting better performance. However, the + performance gained by static linking tends to be rather minimal in most + situations (and quite frankly not worth the extra hassle in the opinion + of this author).

      +

      33.1.4 Using your module

      +

      To use your module, simply use the Tcl load command. If all + goes well, you will be able to this:

      +
      +
      +$ tclsh
+% load ./example.so
+% fact 4
+24
+%
+
      +
      +

      A common error received by first-time users is the following:

      +
      +
      +% load ./example.so
+couldn't find procedure Example_Init
+% 
+
      +
      +

      This error is almost always caused when the name of the shared + object file doesn't match the name of the module supplied using the + SWIG %module directive. Double-check the interface to make + sure the module name and the shared object file match. Another possible + cause of this error is forgetting to link the SWIG-generated wrapper + code with the rest of your application when creating the extension + module.

      +

      Another common error is something similar to the following:

      +
      +
      +% load ./example.so
+couldn't load file "./example.so": ./example.so: undefined symbol: fact
+% 
+
      +
      +

      This error usually indicates that you forgot to include some object + files or libraries in the linking of the shared library file. Make sure + you compile both the SWIG wrapper file and your original program into a + shared library file. Make sure you pass all of the required libraries + to the linker.

      +

      Sometimes unresolved symbols occur because a wrapper has been + created for a function that doesn't actually exist in a library. This + usually occurs when a header file includes a declaration for a function + that was never actually implemented or it was removed from a library + without updating the header file. To fix this, you can either edit the + SWIG input file to remove the offending declaration or you can use the +%ignore directive to ignore the declaration.

      +

      Finally, suppose that your extension module is linked with another + library like this:

      +
      +
      +$ gcc -shared example.o example_wrap.o -L/home/beazley/projects/lib -lfoo \
+      -o example.so
+
      +
      +

      If the foo library is compiled as a shared library, you + might get the following problem when you try to use your module:

      +
      +
      +% load ./example.so
+couldn't load file "./example.so": libfoo.so: cannot open shared object file:
+No such file or directory
+%        
+
      +
      +

      This error is generated because the dynamic linker can't locate the +libfoo.so library. When shared libraries are loaded, the system + normally only checks a few standard locations such as /usr/lib + and /usr/local/lib. To fix this problem, there are several + things you can do. First, you can recompile your extension module with + extra path information. For example, on Linux you can do this:

      +
      +
      +$ gcc -shared example.o example_wrap.o -L/home/beazley/projects/lib -lfoo \
+      -Xlinker -rpath /home/beazley/projects/lib \
+      -o example.so
+
      +
      +

      Alternatively, you can set the LD_LIBRARY_PATH environment + variable to include the directory with your shared libraries. If + setting LD_LIBRARY_PATH, be aware that setting this variable + can introduce a noticeable performance impact on all other applications + that you run. To set it only for Tcl, you might want to do this + instead:

      +
      +
      +$ env LD_LIBRARY_PATH=/home/beazley/projects/lib tclsh
+
      +
      +

      Finally, you can use a command such as ldconfig to add + additional search paths to the default system configuration (this + requires root access and you will need to read the man pages).

      +

      33.1.5 Compilation of C++ extensions

      +

      Compilation of C++ extensions has traditionally been a tricky + problem. Since the Tcl interpreter is written in C, you need to take + steps to make sure C++ is properly initialized and that modules are + compiled correctly.

      +

      On most machines, C++ extension modules should be linked using the + C++ compiler. For example:

      +
      +
      +% swig -c++ -tcl example.i
+% g++ -c example.cxx
+% g++ -c example_wrap.cxx -I/usr/local/include
+% g++ -shared example.o example_wrap.o -o example.so
+
      +
      +

      In addition to this, you may need to include additional library + files to make it work. For example, if you are using the Sun C++ + compiler on Solaris, you often need to add an extra library -lCrun + like this:

      +
      +
      +% swig -c++ -tcl example.i
+% CC -c example.cxx
+% CC -c example_wrap.cxx -I/usr/local/include
+% CC -G example.o example_wrap.o -L/opt/SUNWspro/lib -o example.so -lCrun
+
      +
      +

      Of course, the extra libraries to use are completely + non-portable---you will probably need to do some experimentation.

      +

      Sometimes people have suggested that it is necessary to relink the + Tcl interpreter using the C++ compiler to make C++ extension modules + work. In the experience of this author, this has never actually + appeared to be necessary. Relinking the interpreter with C++ really + only includes the special run-time libraries described above---as long + as you link your extension modules with these libraries, it should not + be necessary to rebuild Tcl.

      +

      If you aren't entirely sure about the linking of a C++ extension, + you might look at an existing C++ program. On many Unix machines, the +ldd command will list library dependencies. This should give you + some clues about what you might have to include when you link your + extension module. For example:

      +
      +
      +$ ldd swig
+        libstdc++-libc6.1-1.so.2 => /usr/lib/libstdc++-libc6.1-1.so.2 (0x40019000)
+        libm.so.6 => /lib/libm.so.6 (0x4005b000)
+        libc.so.6 => /lib/libc.so.6 (0x40077000)
+        /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
+$
+
      +
      +

      As a final complication, a major weakness of C++ is that it does not + define any sort of standard for binary linking of libraries. This means + that C++ code compiled by different compilers will not link together + properly as libraries nor is the memory layout of classes and data + structures implemented in any kind of portable manner. In a monolithic + C++ program, this problem may be unnoticed. However, in Tcl, it is + possible for different extension modules to be compiled with different + C++ compilers. As long as these modules are self-contained, this + probably won't matter. However, if these modules start sharing data, + you will need to take steps to avoid segmentation faults and other + erratic program behavior. If working with lots of software components, + you might want to investigate using a more formal standard such as COM.

      +

      33.1.6 Compiling for 64-bit platforms

      +

      On platforms that support 64-bit applications (Solaris, Irix, etc.), + special care is required when building extension modules. On these + machines, 64-bit applications are compiled and linked using a different + set of compiler/linker options. In addition, it is not generally + possible to mix 32-bit and 64-bit code together in the same + application.

      +

      To utilize 64-bits, the Tcl executable will need to be recompiled as + a 64-bit application. In addition, all libraries, wrapper code, and + every other part of your application will need to be compiled for + 64-bits. If you plan to use other third-party extension modules, they + will also have to be recompiled as 64-bit extensions.

      +

      If you are wrapping commercial software for which you have no source + code, you will be forced to use the same linking standard as used by + that software. This may prevent the use of 64-bit extensions. It may + also introduce problems on platforms that support more than one linking + standard (e.g., -o32 and -n32 on Irix).

      +

      33.1.7 Setting a package prefix

      +

      To avoid namespace problems, you can instruct SWIG to append a + package prefix to all of your functions and variables. This is done + using the -prefix option as follows :

      +
      +
      +swig -tcl -prefix Foo example.i
+
      +
      +

      If you have a function "bar" in the SWIG file, the prefix + option will append the prefix to the name when creating a command and + call it "Foo_bar".

      +

      33.1.8 Using namespaces

      +

      Alternatively, you can have SWIG install your module into a Tcl + namespace by specifying the -namespace option :

      +
      +
      +swig -tcl -namespace example.i
+
      +
      +

      By default, the name of the namespace will be the same as the module + name, but you can override it using the -prefix option.

      +

      When the -namespace option is used, objects in the module + are always accessed with the namespace name such as Foo::bar.

      +

      33.2 Building Tcl/Tk Extensions under Windows + 95/NT

      +

      Building a SWIG extension to Tcl/Tk under Windows 95/NT is roughly + similar to the process used with Unix. Normally, you will want to + produce a DLL that can be loaded into tclsh or wish. This section + covers the process of using SWIG with Microsoft Visual C++. although + the procedure may be similar with other compilers.

      +

      33.2.1 Running SWIG from Developer Studio

      +

      If you are developing your application within Microsoft developer + studio, SWIG can be invoked as a custom build option. The process + roughly follows these steps :

      +
        +
      • Open up a new workspace and use the AppWizard to select a DLL + project.
        • +
      • Add both the SWIG interface file (the .i file), any supporting C + files, and the name of the wrapper file that will be created by SWIG + (ie. example_wrap.c). Note : If using C++, choose a different + suffix for the wrapper file such as example_wrap.cxx. Don't + worry if the wrapper file doesn't exist yet--Developer studio will keep + a reference to it around.
        • +
      • Select the SWIG interface file and go to the settings menu. Under + settings, select the "Custom Build" option.
        • +
      • Enter "SWIG" in the description field.
        • +
      • Enter "swig -tcl -o $(ProjDir)\$(InputName)_wrap.c $(InputPath) +" in the "Build command(s) field"
        • +
      • Enter "$(ProjDir)\$(InputName)_wrap.c" in the "Output + files(s) field".
        • +
      • Next, select the settings for the entire project and go to + "C++:Preprocessor". Add the include directories for your Tcl + installation under "Additional include directories".
        • +
      • Finally, select the settings for the entire project and go to "Link + Options". Add the Tcl library file to your link libraries. For example + "tcl80.lib". Also, set the name of the output file to match + the name of your Tcl module (ie. example.dll).
        • +
      • Build your project.
        • +
      +

      Now, assuming all went well, SWIG will be automatically invoked when + you build your project. Any changes made to the interface file will + result in SWIG being automatically invoked to produce a new version of + the wrapper file. To run your new Tcl extension, simply run tclsh + or wish and use the load command. For example :

      +
      +
      +MSDOS > tclsh80
+% load example.dll
+% fact 4
+24
+%
+
      +
      +

      33.2.2 Using NMAKE

      +

      Alternatively, SWIG extensions can be built by writing a Makefile + for NMAKE. To do this, make sure the environment variables for MSVC++ + are available and the MSVC++ tools are in your path. Now, just write a + short Makefile like this :

      +
      +
      +# Makefile for building various SWIG generated extensions
+
+SRCS          = example.c
+IFILE         = example
+INTERFACE     = $(IFILE).i
+WRAPFILE      = $(IFILE)_wrap.c
+
+# Location of the Visual C++ tools (32 bit assumed)
+
+TOOLS         = c:\msdev
+TARGET        = example.dll
+CC            = $(TOOLS)\bin\cl.exe
+LINK          = $(TOOLS)\bin\link.exe
+INCLUDE32     = -I$(TOOLS)\include
+MACHINE       = IX86
+
+# C Library needed to build a DLL
+
+DLLIBC        = msvcrt.lib oldnames.lib  
+
+# Windows libraries that are apparently needed
+WINLIB        = kernel32.lib advapi32.lib user32.lib gdi32.lib comdlg32.lib 
+winspool.lib
+
+# Libraries common to all DLLs
+LIBS          = $(DLLIBC) $(WINLIB) 
+
+# Linker options
+LOPT      = -debug:full -debugtype:cv /NODEFAULTLIB /RELEASE /NOLOGO /
+MACHINE:$(MACHINE) -entry:_DllMainCRTStartup@12 -dll
+
+# C compiler flags
+
+CFLAGS    = /Z7 /Od /c /nologo
+TCL_INCLUDES  = -Id:\tcl8.0a2\generic -Id:\tcl8.0a2\win
+TCLLIB        = d:\tcl8.0a2\win\tcl80.lib
+
+tcl::
+	..\..\swig -tcl -o $(WRAPFILE) $(INTERFACE)
+	$(CC) $(CFLAGS) $(TCL_INCLUDES) $(SRCS) $(WRAPFILE)
+	set LIB=$(TOOLS)\lib
+	$(LINK) $(LOPT) -out:example.dll $(LIBS) $(TCLLIB) example.obj example_wrap.obj
+
+
      +
      +

      To build the extension, run NMAKE (you may need to run vcvars32 + first). This is a pretty minimal Makefile, but hopefully its enough to + get you started. With a little practice, you'll be making lots of Tcl + extensions.

      +

      33.3 A tour of basic C/C++ wrapping

      +

      By default, SWIG tries to build a very natural Tcl interface to your + C/C++ code. Functions are wrapped as functions, classes are wrapped in + an interface that mimics the style of Tk widgets and [incr Tcl] + classes. This section briefly covers the essential aspects of this + wrapping.

      +

      33.3.1 Modules

      +

      The SWIG %module directive specifies the name of the Tcl + module. If you specify `%module example', then everything is + compiled into an extension module example.so. When choosing a + module name, make sure you don't use the same name as a built-in Tcl + command.

      +

      One pitfall to watch out for is module names involving numbers. If + you specify a module name like %module md5, you'll find that + the load command no longer seems to work:

      +
      +
      +% load ./md5.so
+couldn't find procedure Md_Init
+
      +
      +

      To fix this, supply an extra argument to load like this:

      +
      +
      +% load ./md5.so md5
+
      +
      +

      33.3.2 Functions

      +

      Global functions are wrapped as new Tcl built-in commands. For + example,

      +
      +
      +%module example
+int fact(int n);
+
      +
      +

      creates a built-in function fact that works exactly like + you think it does:

      +
      +
      +% load ./example.so
+% fact 4
+24
+% set x [fact 6]
+%
+
      +
      +

      33.3.3 Global variables

      +

      C/C++ global variables are wrapped by Tcl global variables. For + example:

      +
      +
      +// SWIG interface file with global variables
+%module example
+...
+%inline %{
+extern double density;
+%}
+...
+
      +
      +

      Now look at the Tcl interface:

      +
      +
      +% puts $density          # Output value of C global variable
+1.0
+% set density 0.95       # Change value
+
      +
      +

      If you make an error in variable assignment, you will get an error + message. For example:

      +
      +
      +% set density "hello"
+can't set "density": Type error. expected a double.
+%
+
      +
      +

      If a variable is declared as const, it is wrapped as a + read-only variable. Attempts to modify its value will result in an + error.

      +

      To make ordinary variables read-only, you can use the %immutable + directive. For example:

      +
      +
      +%{
+extern char *path;
+%}
+%immutable;
+extern char *path;
+%mutable;
+
      +
      +

      The %immutable directive stays in effect until it is + explicitly disabled or cleared using %mutable. See the +Creating read-only variables section for further details.

      +

      If you just want to make a specific variable immutable, supply a + declaration name. For example:

      +
      +
      +%{
+extern char *path;
+%}
+%immutable path;
+...
+extern char *path;      // Read-only (due to %immutable)
+
      +
      +

      33.3.4 Constants and enums

      +

      C/C++ constants are installed as global Tcl variables containing the + appropriate value. To create a constant, use #define, enum +, or the %constant directive. For example:

      +
      +
      +#define PI 3.14159
+#define VERSION "1.0"
+
+enum Beverage { ALE, LAGER, STOUT, PILSNER };
+
+%constant int FOO = 42;
+%constant const char *path = "/usr/local";
+
      +
      +

      For enums, make sure that the definition of the enumeration actually + appears in a header file or in the wrapper file somehow---if you just + stick an enum in a SWIG interface without also telling the C compiler + about it, the wrapper code won't compile.

      +

      Note: declarations declared as const are wrapped as + read-only variables and will be accessed using the cvar object + described in the previous section. They are not wrapped as constants. + For further discussion about this, see the SWIG Basics + chapter.

      +

      Constants are not guaranteed to remain constant in Tcl---the value + of the constant could be accidentally reassigned.You will just have to + be careful.

      +

      A peculiarity of installing constants as variables is that it is + necessary to use the Tcl global statement to access constants + in procedure bodies. For example:

      +
      +
      +proc blah {} {
+   global FOO
+   bar $FOO
+}
+
      +
      +

      If a program relies on a lot of constants, this can be extremely + annoying. To fix the problem, consider using the following typemap + rule:

      +
      +
      +%apply int CONSTANT { int x };
+#define FOO 42
+...
+void bar(int x);
+
      +
      +

      When applied to an input argument, the CONSTANT rule allows + a constant to be passed to a function using its actual value or a + symbolic identifier name. For example:

      +
      +
      +proc blah {} {
+   bar FOO
+}
+
      +
      +

      When an identifier name is given, it is used to perform an implicit + hash-table lookup of the value during argument conversion. This allows + the global statement to be omitted.

      +

      33.3.5 Pointers

      +

      C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no + problem working with incomplete type information. Here is a rather + simple interface:

      +
      +
      +%module example
+
+FILE *fopen(const char *filename, const char *mode);
+int fputs(const char *, FILE *);
+int fclose(FILE *);
+
      +
      +

      When wrapped, you will be able to use the functions in a natural way + from Tcl. For example:

      +
      +
      +% load ./example.so
+% set f [fopen junk w]
+% fputs "Hello World\n" $f
+% fclose $f
+
      +
      +

      If this makes you uneasy, rest assured that there is no deep magic + involved. Underneath the covers, pointers to C/C++ objects are simply + represented as opaque values--normally an encoded character string like + this:

      +
      +
      +% puts $f
+_c0671108_p_FILE
+% 
+
      +
      +

      This pointer value can be freely passed around to different C + functions that expect to receive an object of type FILE *. The + only thing you can't do is dereference the pointer from Tcl.

      +

      The NULL pointer is represented by the string NULL.

      +

      As much as you might be inclined to modify a pointer value directly + from Tcl, don't. The hexadecimal encoding is not necessarily the same + as the logical memory address of the underlying object. Instead it is + the raw byte encoding of the pointer value. The encoding will vary + depending on the native byte-ordering of the platform (i.e., big-endian + vs. little-endian). Similarly, don't try to manually cast a pointer to + a new type by simply replacing the type-string. This may not work like + you expect and it is particularly dangerous when casting C++ objects. + If you need to cast a pointer or change its value, consider writing + some helper functions instead. For example:

      +
      +
      +%inline %{
+/* C-style cast */
+Bar *FooToBar(Foo *f) {
+   return (Bar *) f;
+}
+
+/* C++-style cast */
+Foo *BarToFoo(Bar *b) {
+   return dynamic_cast<Foo*>(b);
+}
+
+Foo *IncrFoo(Foo *f, int i) {
+    return f+i;
+}
+%}
+
      +
      +

      Also, if working with C++, you should always try to use the new C++ + style casts. For example, in the above code, the C-style cast may + return a bogus result whereas as the C++-style cast will return +None if the conversion can't be performed.

      +

      33.3.6 Structures

      +

      If you wrap a C structure, it is wrapped by a Tcl interface that + somewhat resembles a Tk widget. This provides a very natural interface. + For example,

      +
      +
      +struct Vector {
+	double x,y,z;
+};
+
+
      +
      +

      is used as follows:

      +
      +
      +% Vector v
+% v configure -x 3.5 -y 7.2
+% puts "[v cget -x] [v cget -y] [v cget -z]"
+3.5 7.2 0.0
+% 
+
      +
      +

      Similar access is provided for unions and the data members of C++ + classes.

      +

      In the above example, v is a name that's used for the + object. However, underneath the covers, there's a pointer to a raw C + structure. This can be obtained by looking at the -this + attribute. For example:

      +
      +
      +% puts [v cget -this]
+_88e31408_p_Vector
+
      +
      +

      Further details about the relationship between the Tcl and the + underlying C structure are covered a little later.

      +

      const members of a structure are read-only. Data members + can also be forced to be read-only using the %immutable + directive. For example:

      +
      +
      +struct Foo {
+   ...
+   %immutable;
+   int x;        /* Read-only members */
+   char *name;
+   %mutable;
+   ...
+};
+
      +
      +

      When char * members of a structure are wrapped, the + contents are assumed to be dynamically allocated using malloc + or new (depending on whether or not SWIG is run with the -c++ + option). When the structure member is set, the old contents will be + released and a new value created. If this is not the behavior you want, + you will have to use a typemap (described later).

      +

      If a structure contains arrays, access to those arrays is managed + through pointers. For example, consider this:

      +
      +
      +struct Bar {
+    int  x[16];
+};
+
      +
      +

      If accessed in Tcl, you will see behavior like this:

      +
      +
      +% Bar b
+% puts [b cget -x]
+_801861a4_p_int
+% 
+
      +
      +

      This pointer can be passed around to functions that expect to + receive an int * (just like C). You can also set the value of + an array member using another pointer. For example:

      +
      +
      +% Bar c
+% c configure -x [b cget -x]   # Copy contents of b.x to c.x
+
      +
      +

      For array assignment, SWIG copies the entire contents of the array + starting with the data pointed to by b.x. In this example, 16 + integers would be copied. Like C, SWIG makes no assumptions about + bounds checking---if you pass a bad pointer, you may get a segmentation + fault or access violation.

      +

      When a member of a structure is itself a structure, it is handled as + a pointer. For example, suppose you have two structures like this:

      +
      +
      +struct Foo {
+   int a;
+};
+
+struct Bar {
+   Foo f;
+};
+
      +
      +

      Now, suppose that you access the f attribute of Bar + like this:

      +
      +
      +% Bar b
+% set x [b cget -f]
+
      +
      +

      In this case, x is a pointer that points to the Foo + that is inside b. This is the same value as generated by this + C code:

      +
      +
      +Bar b;
+Foo *x = &b->f;       /* Points inside b */
+
      +
      +

      However, one peculiarity of accessing a substructure like this is + that the returned value does work quite like you might expect. For + example:

      +
      +
      +% Bar b
+% set x [b cget -f]
+% x cget -a
+invalid command name "x"
+
      +
      +

      This is because the returned value was not created in a normal way + from the interpreter (x is not a command object). To make it function + normally, just evaluate the variable like this:

      +
      +
      +% Bar b
+% set x [b cget -f]
+% $x cget -a
+0
+%
+
      +
      +

      In this example, x points inside the original structure. + This means that modifications work just like you would expect. For + example:

      +
      +
      +
+% Bar b
+% set x [b cget -f]
+% $x configure -a 3            # Modifies contents of f (inside b)
+% [b cget -f] -configure -a 3  # Same thing
+
      +
      +

      In many of these structure examples, a simple name like "v" or "b" + has been given to wrapped structures. If necessary, this name can be + passed to functions that expect to receive an object. For example, if + you have a function like this,

      +
      +
      +void blah(Foo *f);
+
      +
      +

      you can call the function in Tcl as follows:

      +
      +
      +% Foo x            # Create a Foo object 
+% blah x           # Pass the object to a function
+
      +
      +

      It is also possible to call the function using the raw pointer + value. For instance:

      +
      +
      +% blah [x cget -this]   # Pass object to a function
+
      +
      +

      It is also possible to create and use objects using variables. For + example:

      +
      +
      +% set b [Bar]            # Create a Bar
+% $b cget -f             # Member access
+% puts $b
+_108fea88_p_Bar
+%
+
      +
      +

      Finally, to destroy objects created from Tcl, you can either let the + object name go out of scope or you can explicitly delete the object. + For example:

      +
      +
      +% Foo f                 # Create object f
+% rename f ""
+
      +
      +

      or

      +
      +
      +% Foo f                 # Create object f
+% f -delete
+
      +
      +

      Note: Tcl only destroys the underlying object if it has ownership. + See the memory management section that appears shortly.

      +

      33.3.7 C++ classes

      +

      C++ classes are wrapped as an extension of structure wrapping. For + example, if you have this class,

      +
      +
      +class List {
+public:
+  List();
+  ~List();
+  int  search(char *item);
+  void insert(char *item);
+  void remove(char *item);
+  char *get(int n);
+  int  length;
+};
+
      +
      +

      you can use it in Tcl like this:

      +
      +
      +% List x
+% x insert Ale
+% x insert Stout
+% x insert Lager
+% x get 1
+Stout
+% puts [l cget -length]
+3
+%
+
      +
      +

      Class data members are accessed in the same manner as C structures.

      +

      Static class members are accessed as global functions or variables. + To illustrate, suppose you have a class like this:

      +
      +
      +class Spam {
+public:
+   static void foo();
+   static int bar;
+
+};
+
      +
      +

      In Tcl, the static member is accessed as follows:

      +
      +
      +% Spam_foo        # Spam::foo()
+% puts $Spam_bar  # Spam::bar
+
      +
      +

      33.3.8 C++ inheritance

      +

      SWIG is fully aware of issues related to C++ inheritance. Therefore, + if you have classes like this

      +
      +
      +class Foo {
+...
+};
+
+class Bar : public Foo {
+...
+};
+
      +
      +

      An object of type Bar can be used where a Foo is + expected. For example, if you have this function:

      +
      +
      +void spam(Foo *f);
+
      +
      +

      then the function spam() accepts a Foo * or a + pointer to any class derived from Foo. For instance:

      +
      +
      +% Foo f      # Create a Foo
+% Bar b      # Create a Bar
+% spam f     # OK
+% spam b     # OK
+
      +
      +

      It is safe to use multiple inheritance with SWIG.

      +

      33.3.9 Pointers, references, values, and + arrays

      +

      In C++, there are many different ways a function might receive and + manipulate objects. For example:

      +
      +
      +void spam1(Foo *x);      // Pass by pointer
+void spam2(Foo &x);      // Pass by reference
+void spam3(Foo x);       // Pass by value
+void spam4(Foo x[]);     // Array of objects
+
      +
      +

      In Tcl, there is no detailed distinction like this. Because of this, + SWIG unifies all of these types together in the wrapper code. For + instance, if you actually had the above functions, it is perfectly + legal to do this:

      +
      +
      +% Foo f             # Create a Foo
+% spam1 f           # Ok. Pointer
+% spam2 f           # Ok. Reference
+% spam3 f           # Ok. Value.
+% spam4 f           # Ok. Array (1 element)
+
      +
      +

      Similar behavior occurs for return values. For example, if you had + functions like this,

      +
      +
      +Foo *spam5();
+Foo &spam6();
+Foo  spam7();
+
      +
      +

      then all three functions will return a pointer to some Foo + object. Since the third function (spam7) returns a value, newly + allocated memory is used to hold the result and a pointer is returned + (Tcl will release this memory when the return value is garbage + collected).

      +

      33.3.10 C++ overloaded functions

      +

      C++ overloaded functions, methods, and constructors are mostly + supported by SWIG. For example, if you have two functions like this:

      +
      +
      +void foo(int);
+void foo(char *c);
+
      +
      +

      You can use them in Tcl in a straightforward manner:

      +
      +
      +% foo 3            # foo(int)
+% foo Hello        # foo(char *c)
+
      +
      +

      Similarly, if you have a class like this,

      +
      +
      +class Foo {
+public:
+    Foo();
+    Foo(const Foo &);
+    ...
+};
+
      +
      +

      you can write Tcl code like this:

      +
      +
      +% Foo f                # Create a Foo
+% Foo g f              # Copy f
+
      +
      +

      Overloading support is not quite as flexible as in C++. Sometimes + there are methods that SWIG can't disambiguate. For example:

      +
      +
      +void spam(int);
+void spam(short);
+
      +
      +

      or

      +
      +
      +void foo(Bar *b);
+void foo(Bar &b);
+
      +
      +

      If declarations such as these appear, you will get a warning message + like this:

      +
      +
      +example.i:12: Warning(509): Overloaded spam(short) is shadowed by spam(int)
+at example.i:11.
+
      +
      +

      To fix this, you either need to ignore or rename one of the methods. + For example:

      +
      +
      +%rename(spam_short) spam(short);
+...
+void spam(int);    
+void spam(short);   // Accessed as spam_short
+
      +
      +

      or

      +
      +
      +%ignore spam(short);
+...
+void spam(int);    
+void spam(short);   // Ignored
+
      +
      +

      SWIG resolves overloaded functions and methods using a + disambiguation scheme that ranks and sorts declarations according to a + set of type-precedence rules. The order in which declarations appear in + the input does not matter except in situations where ambiguity + arises--in this case, the first declaration takes precedence.

      +

      Please refer to the "SWIG and C++" chapter for more information + about overloading.

      +

      33.3.11 C++ operators

      +

      Certain C++ overloaded operators can be handled automatically by + SWIG. For example, consider a class like this:

      +
      +
      +class Complex {
+private:
+  double rpart, ipart;
+public:
+  Complex(double r = 0, double i = 0) : rpart(r), ipart(i) { }
+  Complex(const Complex &c) : rpart(c.rpart), ipart(c.ipart) { }
+  Complex &operator=(const Complex &c);
+  Complex operator+(const Complex &c) const;
+  Complex operator-(const Complex &c) const;
+  Complex operator*(const Complex &c) const;
+  Complex operator-() const;
+  
+  double re() const { return rpart; }
+  double im() const { return ipart; }
+};
+
      +
      +

      When wrapped, it works like this:

      +
      +
      +% Complex c 3 4
+% Complex d 7 8
+% set e [c + d]
+% $e re
+10.0
+% $e im
+12.0
+
      +
      +

      It should be stressed that operators in SWIG have no relationship to + operators in Tcl. In fact, the only thing that's happening here is that + an operator like operator + has been renamed to a method + +. Therefore, the statement [c + d] is really just invoking the ++ method on c. When more than operator is defined (with + different arguments), the standard method overloading facilities are + used. Here is a rather odd looking example:

      +
      +
      +% Complex c 3 4
+% Complex d 7 8
+% set e [c - d]       # operator-(const Complex &)
+% puts "[$e re] [$e im]"
+10.0 12.0
+% set f [c -]         # operator-()
+% puts "[$f re] [$f im]"
+-3.0 -4.0
+%
+
      +
      +

      One restriction with operator overloading support is that SWIG is + not able to fully handle operators that aren't defined as part of the + class. For example, if you had code like this

      +
      +
      +class Complex {
+...
+friend Complex operator+(double, const Complex &c);
+...
+};
+
      +
      +

      then SWIG doesn't know what to do with the friend function--in fact, + it simply ignores it and issues a warning. You can still wrap the + operator, but you may have to encapsulate it in a special function. For + example:

      +
      +
      +%rename(Complex_add_dc) operator+(double, const Complex &);
+...
+Complex operator+(double, const Complex &c);
+
      +
      +

      There are ways to make this operator appear as part of the class + using the %extend directive. Keep reading.

      +

      33.3.12 C++ namespaces

      +

      SWIG is aware of C++ namespaces, but namespace names do not appear + in the module nor do namespaces result in a module that is broken up + into submodules or packages. For example, if you have a file like this,

      +
      +
      +%module example
+
+namespace foo {
+   int fact(int n);
+   struct Vector {
+       double x,y,z;
+   };
+};
+
      +
      +

      it works in Tcl as follows:

      +
      +
      +% load ./example.so
+% fact 3
+6
+% Vector v
+% v configure -x 3.4
+
      +
      +

      If your program has more than one namespace, name conflicts (if any) + can be resolved using %rename For example:

      +
      +
      +%rename(Bar_spam) Bar::spam;
+
+namespace Foo {
+    int spam();
+}
+
+namespace Bar {
+    int spam();
+}
+
      +
      +

      If you have more than one namespace and your want to keep their + symbols separate, consider wrapping them as separate SWIG modules. For + example, make the module name the same as the namespace and create + extension modules for each namespace separately. If your program + utilizes thousands of small deeply nested namespaces each with + identical symbol names, well, then you get what you deserve.

      +

      33.3.13 C++ templates

      +

      C++ templates don't present a huge problem for SWIG. However, in + order to create wrappers, you have to tell SWIG to create wrappers for + a particular template instantiation. To do this, you use the +%template directive. For example:

      +
      +
      +%module example
+%{
+#include "pair.h"
+%}
+
+template<class T1, class T2>
+struct pair {
+   typedef T1 first_type;
+   typedef T2 second_type;
+   T1 first;
+   T2 second;
+   pair();
+   pair(const T1&, const T2&);
+  ~pair();
+};
+
+%template(pairii) pair<int,int>;
+
      +
      +

      In Tcl:

      +
      +
      +% pairii p 3 4
+% p cget -first
+3
+% p cget -second
+4
+
      +
      +

      Obviously, there is more to template wrapping than shown in this + example. More details can be found in the SWIG and + C++ chapter. Some more complicated examples will appear later.

      +

      33.3.14 C++ Smart Pointers

      +

      In certain C++ programs, it is common to use classes that have been + wrapped by so-called "smart pointers." Generally, this involves the use + of a template class that implements operator->() like this:

      +
      +
      +template<class T> class SmartPtr {
+   ...
+   T *operator->();
+   ...
+}
+
      +
      +

      Then, if you have a class like this,

      +
      +
      +class Foo {
+public:
+     int x;
+     int bar();
+};
+
      +
      +

      A smart pointer would be used in C++ as follows:

      +
      +
      +SmartPtr<Foo> p = CreateFoo();   // Created somehow (not shown)
+...
+p->x = 3;                        // Foo::x
+int y = p->bar();                // Foo::bar
+
      +
      +

      To wrap this in Tcl, simply tell SWIG about the SmartPtr + class and the low-level Foo object. Make sure you instantiate +SmartPtr using %template if necessary. For example:

      +
      +
      +%module example
+...
+%template(SmartPtrFoo) SmartPtr<Foo>;
+...
+
      +
      +

      Now, in Tcl, everything should just "work":

      +
      +
      +% set p [CreateFoo]                  # Create a smart-pointer somehow
+% $p configure -x 3                  # Foo::x
+% $p bar                             # Foo::bar
+
      +
      +

      If you ever need to access the underlying pointer returned by +operator->() itself, simply use the __deref__() method. + For example:

      +
      +
      +% set f [$p __deref__]    # Returns underlying Foo *
+
      +
      +

      33.4 Further details on the Tcl class + interface

      +

      In the previous section, a high-level view of Tcl wrapping was + presented. A key component of this wrapping is that structures and + classes are wrapped by Tcl class-like objects. This provides a very + natural Tcl interface and allows SWIG to support a number of advanced + features such as operator overloading. However, a number of low-level + details were omitted. This section provides a brief overview of how the + proxy classes work.

      +

      33.4.1 Proxy classes

      +

      In the "SWIG basics" and +"SWIG and C++" chapters, details of low-level structure and class + wrapping are described. To summarize those chapters, if you have a + class like this

      +
      +
      +class Foo {
+public:
+     int x;
+     int spam(int);
+     ...
+
      +
      +

      then SWIG transforms it into a set of low-level procedural wrappers. + For example:

      +
      +
      +Foo *new_Foo() {
+    return new Foo();
+}
+void delete_Foo(Foo *f) {
+    delete f;
+}
+int Foo_x_get(Foo *f) {
+    return f->x;
+}
+void Foo_x_set(Foo *f, int value) {
+    f->x = value;
+}
+int Foo_spam(Foo *f, int arg1) {
+    return f->spam(arg1);
+}
+
      +
      +

      These wrappers are actually found in the Tcl extension module. For + example, you can certainly do this:

      +
      +
      +% load ./example.so
+% set f [new_Foo]
+% Foo_x_get $f
+0
+% Foo_spam $f 3
+1
+%
+
      +
      +

      However, in addition to this, the classname Foo is used as + an object constructor function. This allows objects to be encapsulated + objects that look a lot like Tk widgets as shown in the last section.

      +

      33.4.2 Memory management

      +

      Associated with each wrapped object, is an ownership flag +thisown The value of this flag determines who is responsible for + deleting the underlying C++ object. If set to 1, the Tcl interpreter + destroys the C++ object when the proxy class is garbage collected. If + set to 0 (or if the attribute is missing), then the destruction of the + proxy class has no effect on the C++ object.

      +

      When an object is created by a constructor or returned by value, Tcl + automatically takes ownership of the result. For example:

      +
      +
      +class Foo {
+public:
+    Foo();
+    Foo bar();
+};
+
      +
      +

      In Tcl:

      +
      +
      +% Foo f
+% f cget -thisown
+1
+% set g [f bar]
+% $g cget -thisown
+1
+
      +
      +

      On the other hand, when pointers are returned to Tcl, there is often + no way to know where they came from. Therefore, the ownership is set to + zero. For example:

      +
      +
      +class Foo {
+public:
+    ...
+    Foo *spam();
+    ...
+};
+
      +
      +
      +
      +% Foo f
+% set s [f spam]
+% $s cget -thisown
+0
+% 
+
      +
      +

      This behavior is especially important for classes that act as + containers. For example, if a method returns a pointer to an object + that is contained inside another object, you definitely don't want Tcl + to assume ownership and destroy it!

      +

      Related to containers, ownership issues can arise whenever an object + is assigned to a member or global variable. For example, consider this + interface:

      +
      +
      +%module example
+
+struct Foo {
+    int  value;
+    Foo  *next;
+};
+
+Foo *head = 0;
+
      +
      +

      When wrapped in Tcl, careful observation will reveal that ownership + changes whenever an object is assigned to a global variable. For + example:

      +
      +
      +% Foo f
+% f cget -thisown
+1
+% set head f
+% f cget -thisown
+0
+
      +
      +

      In this case, C is now holding a reference to the object---you + probably don't want Tcl to destroy it. Similarly, this occurs for + members. For example:

      +
      +
      +% Foo f
+% Foo g
+% f cget -thisown
+1
+% g cget -thisown
+1
+% f configure -next g
+% g cget -thisown 
+0
+%
+
      +
      +

      For the most part, memory management issues remain hidden. However, + there are occasionally situations where you might have to manually + change the ownership of an object. For instance, consider code like + this:

      +
      +
      +class Node {
+   Object *value;
+public:
+   void set_value(Object *v) { value = v; }
+   ...
+};
+
      +
      +

      Now, consider the following Tcl code:

      +
      +
      +% Object v                 # Create an object
+% Node n                   # Create a node
+% n setvalue v             # Set value
+% v cget -thisown
+1
+% 
+
      +
      +

      In this case, the object n is holding a reference to v + internally. However, SWIG has no way to know that this has occurred. + Therefore, Tcl still thinks that it has ownership of the object. Should + the proxy object be destroyed, then the C++ destructor will be invoked + and n will be holding a stale-pointer. If you're lucky, you + will only get a segmentation fault.

      +

      To work around this, it is always possible to flip the ownership + flag. For example,

      +
      +
      +% v -disown              # Give ownership to C/C++
+% v -acquire             # Acquire ownership
+
      +
      +

      It is also possible to deal with situations like this using + typemaps--an advanced topic discussed later.

      +

      33.5 Input and output parameters

      +

      A common problem in some C programs is handling parameters passed as + simple pointers. For example:

      +
      +
      +void add(int x, int y, int *result) {
+   *result = x + y;
+}
+
      +
      +

      or perhaps

      +
      +
      +int sub(int *x, int *y) {
+   return *x+*y;
+}
+
      +
      +

      The easiest way to handle these situations is to use the +typemaps.i file. For example:

      +
      +
      +%module example
+%include "typemaps.i"
+
+void add(int, int, int *OUTPUT);
+int  sub(int *INPUT, int *INPUT);
+
      +
      +

      In Tcl, this allows you to pass simple values instead of pointer. + For example:

      +
      +
      +set a [add 3 4]
+puts $a
+7
+
      +
      +

      Notice how the INPUT parameters allow integer values to be + passed instead of pointers and how the OUTPUT parameter + creates a return result.

      +

      If you don't want to use the names INPUT or OUTPUT +, use the %apply directive. For example:

      +
      +
      +%module example
+%include "typemaps.i"
+
+%apply int *OUTPUT { int *result };
+%apply int *INPUT  { int *x, int *y};
+
+void add(int x, int y, int *result);
+int  sub(int *x, int *y);
+
      +
      +

      If a function mutates one of its parameters like this,

      +
      +
      +void negate(int *x) {
+   *x = -(*x);
+}
+
      +
      +

      you can use INOUT like this:

      +
      +
      +%include "typemaps.i"
+...
+void negate(int *INOUT);
+
      +
      +

      In Tcl, a mutated parameter shows up as a return value. For example:

      +
      +
      +set a [negate 3]
+puts $a
+-3
+
      +
      +

      The most common use of these special typemap rules is to handle + functions that return more than one value. For example, sometimes a + function returns a result as well as a special error code:

      +
      +
      +/* send message, return number of bytes sent, along with success code */
+int send_message(char *text, int len, int *success);
+
      +
      +

      To wrap such a function, simply use the OUTPUT rule above. + For example:

      +
      +
      +%module example
+%include "typemaps.i"
+%apply int *OUTPUT { int *success };
+...
+int send_message(char *text, int *success);
+
      +
      +

      When used in Tcl, the function will return multiple values as a + list.

      +
      +
      +set r [send_message "Hello World"]
+set bytes [lindex $r 0]
+set success [lindex $r 1]
+
      +
      +

      Another common use of multiple return values are in query functions. + For example:

      +
      +
      +void get_dimensions(Matrix *m, int *rows, int *columns);
+
      +
      +

      To wrap this, you might use the following:

      +
      +
      +%module example
+%include "typemaps.i"
+%apply int *OUTPUT { int *rows, int *columns };
+...
+void get_dimensions(Matrix *m, int *rows, *columns);
+
      +
      +

      Now, in Perl:

      +
      +
      +set dim [get_dimensions $m]
+set r  [lindex $dim 0]
+set c  [lindex $dim 1]
+
      +
      +

      33.6 Exception handling

      +

      The %exception directive can be used to create a + user-definable exception handler in charge of converting exceptions in + your C/C++ program into Tcl exceptions. The chapter on customization + features contains more details, but suppose you extended the array + example into a C++ class like the following :

      +
      +
      +class RangeError {};   // Used for an exception
+
+class DoubleArray {
+  private:
+    int n;
+    double *ptr;
+  public:
+    // Create a new array of fixed size
+    DoubleArray(int size) {
+      ptr = new double[size];
+      n = size;
+    }
+    // Destroy an array
+    ~DoubleArray() {
+       delete ptr;
+    }
+    // Return the length of the array
+    int   length() {
+      return n;
+    }
+
+    // Get an item from the array and perform bounds checking.
+    double getitem(int i) {
+      if ((i >= 0) && (i < n))
+        return ptr[i];
+      else
+        throw RangeError();
+    }
+
+    // Set an item in the array and perform bounds checking.
+    void setitem(int i, double val) {
+      if ((i >= 0) && (i < n))
+        ptr[i] = val;
+      else {
+        throw RangeError();
+      }
+    }
+  };
+
      +
      +

      The functions associated with this class can throw a C++ range + exception for an out-of-bounds array access. We can catch this in our + Tcl extension by specifying the following in an interface file :

      +
      +
      +%exception {
+  try {
+    $action                // Gets substituted by actual function call
+  }
+  catch (RangeError) {
+    Tcl_SetStringObj(tcl_result,"Array index out-of-bounds");
+    return TCL_ERROR;
+  }
+}
+
      +
      +

      As shown, the exception handling code will be added to every wrapper + function. Since this is somewhat inefficient. You might consider + refining the exception handler to only apply to specific methods like + this:

      +
      +
      +%exception getitem {
+  try {
+    $action
+  }
+  catch (RangeError) {
+    Tcl_SetStringObj(tcl_result,"Array index out-of-bounds");
+    return TCL_ERROR;
+  }
+}
+
+%exception setitem {
+  try {
+    $action
+  }
+  catch (RangeError) {
+    Tcl_SetStringObj(tcl_result,"Array index out-of-bounds");
+    return TCL_ERROR;
+  }
+}
+
      +
      +

      In this case, the exception handler is only attached to methods and + functions named getitem and setitem.

      +

      If you had a lot of different methods, you can avoid extra typing by + using a macro. For example:

      +
      +
      +%define RANGE_ERROR
+{
+  try {
+    $action
+  }
+  catch (RangeError) {
+    Tcl_SetStringObj(tcl_result,"Array index out-of-bounds");
+    return TCL_ERROR;
+  }
+}
+%enddef
+
+%exception getitem RANGE_ERROR;
+%exception setitem RANGE_ERROR;
+
      +
      +

      Since SWIG's exception handling is user-definable, you are not + limited to C++ exception handling. See the chapter on " +Customization Features" for more examples.

      +

      33.7 Typemaps

      +

      This section describes how you can modify SWIG's default wrapping + behavior for various C/C++ datatypes using the %typemap + directive. This is an advanced topic that assumes familiarity with the + Tcl C API as well as the material in the "Typemaps +" chapter.

      +

      Before proceeding, it should be stressed that typemaps are not a + required part of using SWIG---the default wrapping behavior is enough + in most cases. Typemaps are only used if you want to change some aspect + of the primitive C-Tcl interface.

      +

      33.7.1 What is a typemap?

      +

      A typemap is nothing more than a code generation rule that is + attached to a specific C datatype. For example, to convert integers + from Tcl to C, you might define a typemap like this:

      +
      +
      +%module example
+
+%typemap(in) int {
+        if (Tcl_GetIntFromObj(interp,$input,&$1) == TCL_ERROR) return TCL_ERROR;
+	printf("Received an integer : %d\n",$1);
+}
+%inline %{
+extern int fact(int n);
+%}
+
      +
      +

      Typemaps are always associated with some specific aspect of code + generation. In this case, the "in" method refers to the conversion of + input arguments to C/C++. The datatype int is the datatype to + which the typemap will be applied. The supplied C code is used to + convert values. In this code a number of special variable prefaced by a + $ are used. The $1 variable is placeholder for a + local variable of type int. The $input variable is + the input object of type Tcl_Obj *.

      +

      When this example is compiled into a Tcl module, it operates as + follows:

      +
      +
      +% load ./example.so
+% fact 6
+Received an integer : 6
+720
+
      +
      +

      In this example, the typemap is applied to all occurrences of the +int datatype. You can refine this by supplying an optional + parameter name. For example:

      +
      +
      +%module example
+
+%typemap(in) int n {
+        if (Tcl_GetIntFromObj(interp,$input,&$1) == TCL_ERROR) return TCL_ERROR;
+	printf("n = %d\n",$1);
+}
+%inline %{
+extern int fact(int n);
+%}
+
      +
      +

      In this case, the typemap code is only attached to arguments that + exactly match int n.

      +

      The application of a typemap to specific datatypes and argument + names involves more than simple text-matching--typemaps are fully + integrated into the SWIG type-system. When you define a typemap for +int, that typemap applies to int and qualified variations + such as const int. In addition, the typemap system follows +typedef declarations. For example:

      +
      +
      +%typemap(in) int n {
+        if (Tcl_GetIntFromObj(interp,$input,&$1) == TCL_ERROR) return TCL_ERROR;
+	printf("n = %d\n",$1);
+}
+%inline %{
+typedef int Integer;
+extern int fact(Integer n);    // Above typemap is applied
+%}
+
      +
      +

      However, the matching of typedef only occurs in one + direction. If you defined a typemap for Integer, it is not + applied to arguments of type int.

      +

      Typemaps can also be defined for groups of consecutive arguments. + For example:

      +
      +
      +%typemap(in) (char *str, int len) {
+    $1 = Tcl_GetStringFromObj($input,&$2);
+};
+
+int count(char c, char *str, int len);
+
      +
      +

      When a multi-argument typemap is defined, the arguments are always + handled as a single Tcl object. This allows the function to be used + like this (notice how the length parameter is omitted):

      +
      +
      +% count e "Hello World"
+1
+
      +
      +

      33.7.2 Tcl typemaps

      +

      The previous section illustrated an "in" typemap for converting Tcl + objects to C. A variety of different typemap methods are defined by the + Tcl module. For example, to convert a C integer back into a Tcl object, + you might define an "out" typemap like this:

      +
      +
      +%typemap(out) int {
+    Tcl_SetObjResult(interp,Tcl_NewIntObj($1));
+}
+
      +
      +

      The following list details all of the typemap methods that can be + used by the Tcl module:

      +

      %typemap(in)

      +
      Converts Tcl objects to input function arguments
      +

      %typemap(out)

      +
      Converts return value of a C function to a Tcl + object
      +

      %typemap(varin)

      +
      Assigns a C global variable from a Tcl object
      +

      %typemap(varout)

      +
      Returns a C global variable as a Tcl object
      +

      %typemap(freearg)

      +
      Cleans up a function argument (if necessary)
      +

      %typemap(argout)

      +
      Output argument processing
      +

      %typemap(ret)

      +
      Cleanup of function return values
      +

      %typemap(consttab)

      +
      Creation of Tcl constants (constant table)
      +

      %typemap(constcode)

      +
      Creation of Tcl constants (init function)
      +

      %typemap(memberin)

      +
      Setting of structure/class member data
      +

      %typemap(globalin)

      +
      Setting of C global variables
      +

      %typemap(check)

      +
      Checks function input values.
      +

      %typemap(default)

      +
      Set a default value for an argument (making it + optional).
      +

      %typemap(arginit)

      +
      Initialize an argument to a value before any + conversions occur.
      +

      Examples of these methods will appear shortly.

      +

      33.7.3 Typemap variables

      +

      Within typemap code, a number of special variables prefaced with a +$ may appear. A full list of variables can be found in the " +Typemaps" chapter. This is a list of the most common variables:

      +

      $1

      +
      A C local variable corresponding to the actual type + specified in the %typemap directive. For input values, this is + a C local variable that's supposed to hold an argument value. For + output values, this is the raw result that's supposed to be returned to + Tcl.
      +

      $input

      +
      A Tcl_Obj * holding a raw Tcl object with + an argument or variable value.
      +

      $result

      +
      A Tcl_Obj * that holds the result to be + returned to Tcl.
      +

      $1_name

      +
      The parameter name that was matched.
      +

      $1_type

      +
      The actual C datatype matched by the typemap.
      +

      $1_ltype

      +
      An assignable version of the datatype matched by + the typemap (a type that can appear on the left-hand-side of a C + assignment operation). This type is stripped of qualifiers and may be + an altered version of $1_type. All arguments and local + variables in wrapper functions are declared using this type so that + their values can be properly assigned.
      +

      $symname

      +
      The Tcl name of the wrapper function being created.
      +

      33.7.4 Converting a Tcl list to a char **

      +

      A common problem in many C programs is the processing of command + line arguments, which are usually passed in an array of NULL terminated + strings. The following SWIG interface file allows a Tcl list to be used + as a char ** object.

      +
      +
      +%module argv
+
+// This tells SWIG to treat char ** as a special case
+%typemap(in) char ** {
+     Tcl_Obj **listobjv;
+     int       nitems;
+     int       i;
+     if (Tcl_ListObjGetElements(interp, $input, &nitems, &listobjv) == TCL_ERROR) {
+        return TCL_ERROR;
+     }
+     $1 = (char **) malloc((nitems+1)*sizeof(char *));
+     for (i = 0; i < nitems; i++) {
+        $1[i] = Tcl_GetStringFromObj(listobjv[i],0);
+     }
+     $1[i] = 0;
+}
+
+// This gives SWIG some cleanup code that will get called after the function call
+%typemap(freearg) char ** {
+     if ($1) {
+        free($1);
+     }
+}
+
+// Now a test functions
+%inline %{
+int print_args(char **argv) {
+    int i = 0;
+    while (argv[i]) {
+         printf("argv[%d] = %s\n", i,argv[i]);
+         i++;
+    }
+    return i;
+}
+%}
+%include "tclsh.i"
+
+
      +
      +

      In Tcl:

      +
      +
      +% print_args {John Guido Larry}
+argv[0] = John
+argv[1] = Guido
+argv[2] = Larry
+3
+
      +
      +

      33.7.5 Returning values in arguments

      +

      The "argout" typemap can be used to return a value originating from + a function argument. For example :

      +
      +
      +// A typemap defining how to return an argument by appending it to the result
+%typemap(argout) double *outvalue {
+     Tcl_Obj *o = Tcl_NewDoubleObj($1);
+     Tcl_ListObjAppendElement(interp,$result,o);
+}
+
+// A typemap telling SWIG to ignore an argument for input
+// However, we still need to pass a pointer to the C function
+%typemap(in,numinputs=0) double *outvalue (double temp) {
+     $1 = &temp;
+}
+
+// Now a function returning two values
+int mypow(double a, double b, double *outvalue) {
+        if ((a < 0) || (b < 0)) return -1;
+        *outvalue = pow(a,b);
+        return 0;
+};
+
      +
      +

      When wrapped, SWIG matches the argout typemap to the " +double *outvalue" argument. The numinputs=0 specification tells + SWIG to simply ignore this argument when generating wrapper code. As a + result, a Tcl function using these typemaps will work like this :

      +
      +
      +% mypow 2 3     # Returns two values, a status value and the result
+0 8
+%
+
      +
      +

      33.7.6 Useful functions

      +

      The following tables provide some functions that may be useful in + writing Tcl typemaps.

      +

      Integers

      +
      +
      +Tcl_Obj   *Tcl_NewIntObj(int Value);
+void       Tcl_SetIntObj(Tcl_Obj *obj, int Value);
+int        Tcl_GetIntFromObj(Tcl_Interp *, Tcl_Obj *obj, int *ip);
+
      +
      +

      Floating Point

      +
      +
      +Tcl_Obj  *Tcl_NewDoubleObj(double Value);
+void      Tcl_SetDoubleObj(Tcl_Obj *obj, double value);
+int       Tcl_GetDoubleFromObj(Tcl_Interp *, Tcl_Obj *o, double *dp);
+
      +
      +

      Strings

      +
      +
      +Tcl_Obj  *Tcl_NewStringObj(char *str, int len);
+void      Tcl_SetStringObj(Tcl_Obj *obj, char *str, int len);
+char     *Tcl_GetStringFromObj(Tcl_Obj *obj, int *len);
+void      Tcl_AppendToObj(Tcl_Obj *obj, char *str, int len);
+
      +
      +

      Lists

      +
      +
      +Tcl_Obj  *Tcl_NewListObj(int objc, Tcl_Obj *objv);
+int       Tcl_ListObjAppendList(Tcl_Interp *, Tcl_Obj *listPtr, Tcl_Obj *elemListPtr);
+int       Tcl_ListObjAppendElement(Tcl_Interp *, Tcl_Obj *listPtr, Tcl_Obj *element);
+int       Tcl_ListObjGetElements(Tcl_Interp *, Tcl_Obj *listPtr, int *objcPtr,
+                                 Tcl_Obj ***objvPtr);
+int       Tcl_ListObjLength(Tcl_Interp *, Tcl_Obj *listPtr, int *intPtr);
+int       Tcl_ListObjIndex(Tcl_Interp *, Tcl_Obj *listPtr, int index,
+                           Tcl_Obj_Obj **objptr);
+int       Tcl_ListObjReplace(Tcl_Interp *, Tcl_Obj *listPtr, int first, int count,
+                             int objc, Tcl_Obj *objv);
+
      +
      +

      Objects

      +
      +
      +Tcl_Obj *Tcl_DuplicateObj(Tcl_Obj *obj);
+void     Tcl_IncrRefCount(Tcl_Obj *obj);
+void     Tcl_DecrRefCount(Tcl_Obj *obj);
+int      Tcl_IsShared(Tcl_Obj *obj);
+
      +
      +

      33.7.7 Standard typemaps

      +

      The following typemaps show how to convert a few common kinds of + objects between Tcl and C (and to give a better idea of how typemaps + work)

      +

      Integer conversion

      +
      +
      +%typemap(in) int, short, long {
+   int temp;
+   if (Tcl_GetIntFromObj(interp, $input, &temp) == TCL_ERROR)
+      return TCL_ERROR;
+   $1 = ($1_ltype) temp;
+}
+
      +
      +
      +
      +%typemap(out) int, short, long {
+   Tcl_SetIntObj($result,(int) $1);
+}
+
      +
      +

      Floating point conversion

      +
      +
      +%typemap(in) float, double {
+   double temp;
+   if (Tcl_GetDoubleFromObj(interp, $input, &temp) == TCL_ERROR)
+       return TCL_ERROR;
+   $1 = ($1_ltype) temp;
+}
+
      +
      +
      +
      +%typemap(out) float, double {
+   Tcl_SetDoubleObj($result, $1);
+}
+
      +
      +

      String Conversion

      +
      +
      +%typemap(in) char * {
+   int len;
+   $1 = Tcl_GetStringFromObj(interp, &len);
+   }
+}
+
      +
      +
      +
      +%typemap(out) char * {
+   Tcl_SetStringObj($result,$1);
+}
+
      +
      +

      33.7.8 Pointer handling

      +

      SWIG pointers are mapped into Tcl strings containing the hexadecimal + value and type. The following functions can be used to create and read + pointer values.

      +

      int SWIG_ConvertPtr(Tcl_Obj *obj, void **ptr, swig_type_info + *ty, int flags)

      +
      Converts a Tcl object obj to a C pointer. + The result of the conversion is placed into the pointer located at +ptr. ty is a SWIG type descriptor structure. flags + is used to handle error checking and other aspects of conversion. It is + currently reserved for future expansion. Returns 0 on success and -1 on + error.
      +

      Tcl_Obj *SWIG_NewPointerObj(void *ptr, swig_type_info *ty, int + flags)

      +
      Creates a new Tcl pointer object. ptr is + the pointer to convert, ty is the SWIG type descriptor + structure that describes the type, and own is a flag reserved + for future expansion.
      +

      Both of these functions require the use of a special SWIG + type-descriptor structure. This structure contains information about + the mangled name of the datatype, type-equivalence information, as well + as information about converting pointer values under C++ inheritance. + For a type of Foo *, the type descriptor structure is usually + accessed as follows:

      +
      +
      +Foo *f;
+if (SWIG_ConvertPtr($input, (void **) &f, SWIGTYPE_p_Foo, 0) == -1) return NULL;
+
+Tcl_Obj *;
+obj = SWIG_NewPointerObj(f, SWIGTYPE_p_Foo, 0);
+
      +
      +

      In a typemap, the type descriptor should always be accessed using + the special typemap variable $1_descriptor. For example:

      +
      +
      +%typemap(in) Foo * {
+   if ((SWIG_ConvertPtr($input,(void **) &$1, $1_descriptor,0)) == -1) return NULL;
+}
+
      +
      +

      If necessary, the descriptor for any type can be obtained using the +$descriptor() macro in a typemap. For example:

      +
      +
      +%typemap(in) Foo * {
+   if ((SWIG_ConvertPtr($input,(void **) &$1, $descriptor(Foo *), 0)) == -1) return NULL;
+}
+
      +
      +

      33.8 Turning a SWIG module into a Tcl + Package.

      +

      Tcl 7.4 introduced the idea of an extension package. By default, + SWIG generates all of the code necessary to create a package. To set + the package version, simply use the -pkgversion option. For + example:

      +
      +
      +% swig -tcl -pkgversion 2.3 example.i
+
      +
      +

      After building the SWIG generated module, you need to execute the " +pkg_mkIndex" command inside tclsh. For example :

      +
      +
      +unix > tclsh
+% pkg_mkIndex . example.so
+% exit
+
      +
      +

      This creates a file "pkgIndex.tcl" with information about + the package. To use your package, you now need to move it to its own + subdirectory which has the same name as the package. For example :

      +
      +
      +./example/
+	   pkgIndex.tcl           # The file created by pkg_mkIndex
+	   example.so             # The SWIG generated module
+
      +
      +

      Finally, assuming that you're not entirely confused at this point, + make sure that the example subdirectory is visible from the directories + contained in either the tcl_library or auto_path + variables. At this point you're ready to use the package as follows :

      +
      +
      +unix > tclsh
+% package require example
+% fact 4
+24
+%
+
      +
      +

      If you're working with an example in the current directory and this + doesn't work, do this instead :

      +
      +
      +unix > tclsh
+% lappend auto_path .
+% package require example
+% fact 4
+24
+
      +
      +

      As a final note, most SWIG examples do not yet use the package + commands. For simple extensions it may be easier just to use the +load command instead.

      +

      33.9 Building new kinds of Tcl interfaces (in + Tcl)

      +

      One of the most interesting aspects of Tcl and SWIG is that you can + create entirely new kinds of Tcl interfaces in Tcl using the low-level + SWIG accessor functions. For example, suppose you had a library of + helper functions to access arrays :

      +
      +
      +/* File : array.i */
+%module array
+
+%inline %{
+double *new_double(int size) {
+        return (double *) malloc(size*sizeof(double));
+}
+void delete_double(double *a) {
+        free(a);
+}
+double get_double(double *a, int index) {
+        return a[index];
+}
+void set_double(double *a, int index, double val) {
+        a[index] = val;
+}
+int *new_int(int size) {
+        return (int *) malloc(size*sizeof(int));
+}
+void delete_int(int *a) {
+        free(a);
+}
+int get_int(int *a, int index) {
+        return a[index];
+}
+int set_int(int *a, int index, int val) {
+        a[index] = val;
+}
+%}
+
+
      +
      +

      While these could be called directly, we could also write a Tcl + script like this :

      +
      +
      +proc Array {type size} {
+    set ptr [new_$type $size]
+    set code {
+        set method [lindex $args 0]
+        set parms [concat $ptr [lrange $args 1 end]]
+        switch $method {
+            get {return [eval "get_$type $parms"]}
+            set {return [eval "set_$type $parms"]}
+            delete {eval "delete_$type $ptr; rename $ptr {}"}
+        }
+    }
+    # Create a procedure
+    uplevel "proc $ptr args {set ptr $ptr; set type $type;$code}"
+    return $ptr
+}
+
      +
      +

      Our script allows easy array access as follows :

      +
      +
      +set a [Array double 100]                   ;# Create a double [100]
+for {set i 0} {$i < 100} {incr i 1} {      ;# Clear the array
+	$a set $i 0.0
+}
+$a set 3 3.1455                            ;# Set an individual element
+set b [$a get 10]                          ;# Retrieve an element
+
+set ia [Array int 50]                      ;# Create an int[50]
+for {set i 0} {$i < 50} {incr i 1} {       ;# Clear it
+	$ia set $i 0
+}
+$ia set 3 7                                ;# Set an individual element
+set ib [$ia get 10]                        ;# Get an individual element
+
+$a delete                                  ;# Destroy a
+$ia delete                                 ;# Destroy ia
+
      +
      +

      The cool thing about this approach is that it makes a common + interface for two different types of arrays. In fact, if we were to add + more C datatypes to our wrapper file, the Tcl code would work with + those as well--without modification. If an unsupported datatype was + requested, the Tcl code would simply return with an error so there is + very little danger of blowing something up (although it is easily + accomplished with an out of bounds array access).

      +

      33.9.1 Proxy classes

      +

      A similar approach can be applied to proxy classes (also known as + shadow classes). The following example is provided by Erik Bierwagen + and Paul Saxe. To use it, run SWIG with the -noobject option + (which disables the builtin object oriented interface). When running + Tcl, simply source this file. Now, objects can be used in a more or + less natural fashion.

      +
      +
      +# swig_c++.tcl
+# Provides a simple object oriented interface using
+# SWIG's low level interface.
+#
+
+proc new {objectType handle_r args} {
+    # Creates a new SWIG object of the given type,
+    # returning a handle in the variable "handle_r".
+    #
+    # Also creates a procedure for the object and a trace on
+    # the handle variable that deletes the object when the
+    # handle variable is overwritten or unset
+    upvar $handle_r handle
+    #
+    # Create the new object
+    #
+    eval set handle \[new_$objectType $args\]
+    #
+    # Set up the object procedure
+    #
+    proc $handle {cmd args} "eval ${objectType}_\$cmd $handle \$args"
+    #
+    # And the trace ...
+    #
+    uplevel trace variable $handle_r uw "{deleteObject $objectType $handle}"
+    #
+    # Return the handle so that 'new' can be used as an argument to a procedure
+    #
+    return $handle
+}
+
+proc deleteObject {objectType handle name element op} {
+    #
+    # Check that the object handle has a reasonable form
+    #
+    if {![regexp {_[0-9a-f]*_(.+)_p} $handle]} {
+        error "deleteObject: not a valid object handle: $handle"
+    }
+    #
+    # Remove the object procedure
+    #
+    catch {rename $handle {}}
+    #
+    # Delete the object
+    #
+    delete_$objectType $handle
+}
+
+proc delete {handle_r} {
+    #
+    # A synonym for unset that is more familiar to C++ programmers
+    #
+    uplevel unset $handle_r
+}
+
      +
      +

      To use this file, we simply source it and execute commands such as + "new" and "delete" to manipulate objects. For example :

      +
      +
      +// list.i
+%module List
+%{
+#include "list.h"
+%}
+
+// Very simple C++ example
+
+class List {
+public:
+  List();  // Create a new list
+  ~List(); // Destroy a list
+  int  search(char *value);
+  void insert(char *);  // Insert a new item into the list
+  void remove(char *);  // Remove item from list
+  char *get(int n);     // Get the nth item in the list
+  int  length;          // The current length of the list
+static void print(List *l);  // Print out the contents of the list
+};
+
      +
      +

      Now a Tcl script using the interface...

      +
      +
      +load ./list.so list       ; # Load the module
+source swig_c++.tcl       ; # Source the object file
+
+new List l
+$l insert Dave
+$l insert John
+$l insert Guido
+$l remove Dave
+puts $l length_get
+
+delete l
+
      +
      +

      The cool thing about this example is that it works with any C++ + object wrapped by SWIG and requires no special compilation. Proof that + a short, but clever Tcl script can be combined with SWIG to do many + interesting things.

      +

      33.10 Tcl/Tk Stubs

      +

      For background information about the Tcl Stubs feature, see +http://www.tcl.tk/doc/howto/stubs.html.

      +

      As of SWIG 1.3.10, the generated C/C++ wrapper will use the Tcl + Stubs feature if compiled with -DUSE_TCL_STUBS.

      +

      As of SWIG 1.3.40, the generated C/C++ wrapper will use the Tk Stubs + feature if compiled with -DUSE_TK_STUBS. Also, you can + override the minimum version to support which is passed to +Tcl_InitStubs() and Tk_InitStubs() with +-DSWIG_TCL_STUBS_VERSION="8.3" or the version being compiled with + using -DSWIG_TCL_STUBS_VERSION=TCL_VERSION.

      +
      +

      34 SWIG and R

      + + +
      + +
      + +

      R is a GPL'ed open source statistical and plotting environment. + Information about R can be found at +www.r-project.org. The R bindings are under active development. They + have been used to compile and run an R interface to QuantLib running on + Mandriva Linux with gcc. The R bindings also work on Microsoft Windows + using Visual C++.

      +

      34.1 Bugs

      +

      Currently the following features are not implemented or broken:

      +
        +
      • Garbage collection of created objects
        • +
      • C Array wrappings
        • +
      +

      34.2 Using R and SWIG

      +

      To use R and SWIG in C mode, execute the following commands where + example.c is the name of the file with the functions in them

      +
      +
      +swig -r example.i
+PKG_LIBS="example.c" R CMD SHLIB example_wrap.c
+
      +
      +

      The corresponding comments for C++ mode are

      +
      +
      +swig -c++ -r -o example_wrap.cpp example.i
+PKG_LIBS="example.cxx" R CMD SHLIB example_wrap.cpp
+
      +
      +

      Note that R is sensitive to the name of the file and to the file + extension in C and C++ mode. The name of the wrapper file must be the + name of the library. Also in C++ mode, the file extension must be .cpp + rather than .cxx for the R compile command to recognize it.

      +

      The commands produces two files. A dynamic shared object file called + example.so, or example.dll, and an R wrapper file called example.R. To + load these files, start up R and type in the following commands

      +
      +
      +dyn.load(paste("example", .Platform$dynlib.ext, sep=""))
+source("example.R")
+cacheMetaData(1)
+
      +
      The cacheMetaData(1) will cause R to refresh its object tables. + Without it, inheritance of wrapped objects may fail. +

      These two files can be loaded in any order

      +

      34.3 Precompiling large R files

      + In cases where the R file is large, one make save a lot of loading time + by precompiling the R wrapper. This can be done by creating the file + makeRData.R which contains the following +
      +source('BigFile.R')
+save(list=ls(all=TRUE),file="BigFile.RData", compress=TRUE)
+q(save="no")
+
      + This will generate a compiled R file called BigFile.RData that will + save a large amount of loading time. +

      34.4 General policy

      +

      The general policy of the module is to treat the C/C++ as a basic + wrapping over the underlying functions and rely on the R type system to + provide R syntax.

      +

      34.5 Language conventions

      +

      getitem and setitem use C++ conventions (i.e. zero based indices). [ + +

      +

      34.6 C++ classes

      +

      C++ objects are implemented as external pointer objects with the + class being the mangled name of the class. The C++ classes are + encapsulated as an SEXP with an external pointer type. The class is the + mangled name of the class. The nice thing about R is that is allows you + to keep track of the pointer object which removes the necessity for a + lot of the proxy class baggage you see in other languages.

      +

      34.7 Enumerations

      +

      enumerations are characters which are then converted back and forth + to ints before calling the C routines. All of the enumeration code is + done in R.

      +
      +

      35 Extending SWIG to support new languages

      + + +
      + +
      + +

      35.1 Introduction

      +

      This chapter describes SWIG's internal organization and the process + by which new target languages can be developed. First, a brief word of + warning---SWIG is continually evolving. The information in this chapter + is mostly up to date, but changes are ongoing. Expect a few + inconsistencies.

      +

      Also, this chapter is not meant to be a hand-holding tutorial. As a + starting point, you should probably look at one of SWIG's existing + modules.

      +

      35.2 Prerequisites

      +

      In order to extend SWIG, it is useful to have the following + background:

      +
        +
      • An understanding of the C API for the target language.
        • +
      • A good grasp of the C++ type system.
        • +
      • An understanding of typemaps and some of SWIG's advanced features.
        • +
      • Some familiarity with writing C++ (language modules are currently + written in C++).
        • +
      +

      Since SWIG is essentially a specialized C++ compiler, it may be + useful to have some prior experience with compiler design (perhaps even + a compilers course) to better understand certain parts of the system. A + number of books will also be useful. For example, "The C Programming + Language" by Kernighan and Ritchie (a.k.a, "K&R") and the C++ standard, + "ISO/IEC 14882 Programming Languages - C++" will be of great use.

      +

      Also, it is useful to keep in mind that SWIG primarily operates as + an extension of the C++ type system. At first glance, this + might not be obvious, but almost all SWIG directives as well as the + low-level generation of wrapper code are driven by C++ datatypes.

      +

      35.3 The Big Picture

      +

      SWIG is a special purpose compiler that parses C++ declarations to + generate wrapper code. To make this conversion possible, SWIG makes + three fundamental extensions to the C++ language:

      +
        +
      • Typemaps. Typemaps are used to define the + conversion/marshalling behavior of specific C++ datatypes. All type + conversion in SWIG is based on typemaps. Furthermore, the association + of typemaps to datatypes utilizes an advanced pattern matching + mechanism that is fully integrated with the C++ type system.
        • +
      • Declaration Annotation. To customize wrapper code generation, + most declarations can be annotated with special features. For example, + you can make a variable read-only, you can ignore a declaration, you + can rename a member function, you can add exception handling, and so + forth. Virtually all of these customizations are built on top of a + low-level declaration annotator that can attach arbitrary attributes to + any declaration. Code generation modules can look for these attributes + to guide the wrapping process.
        • +
      • Class extension. SWIG allows classes and structures to be + extended with new methods and attributes (the %extend + directive). This has the effect of altering the API in the target + language and can be used to generate OO interfaces to C libraries.
        • +
      +

      It is important to emphasize that virtually all SWIG features reduce + to one of these three fundamental concepts. The type system and pattern + matching rules also play a critical role in making the system work. For + example, both typemaps and declaration annotation are based on pattern + matching and interact heavily with the underlying type system.

      +

      35.4 Execution Model

      +

      When you run SWIG on an interface, processing is handled in stages + by a series of system components:

      +
        +
      • An integrated C preprocessor reads a collection of configuration + files and the specified interface file into memory. The preprocessor + performs the usual functions including macro expansion and file + inclusion. However, the preprocessor also performs some transformations + of the interface. For instance, #define statements are + sometimes transformed into %constant declarations. In + addition, information related to file/line number tracking is inserted.
        • +
      • A C/C++ parser reads the preprocessed input and generates a full + parse tree of all of the SWIG directives and C declarations found. The + parser is responsible for many aspects of the system including + renaming, declaration annotation, and template expansion. However, the + parser does not produce any output nor does it interact with the target + language module as it runs. SWIG is not a one-pass compiler.
        • +
      • A type-checking pass is made. This adjusts all of the C++ typenames + to properly handle namespaces, typedefs, nested classes, and other + issues related to type scoping.
        • +
      • A semantic pass is made on the parse tree to collect information + related to properties of the C++ interface. For example, this pass + would determine whether or not a class allows a default constructor.
        • +
      • A code generation pass is made using a specific target language + module. This phase is responsible for generating the actual wrapper + code. All of SWIG's user-defined modules are invoked during this latter + stage of compilation.
        • +
      +

      The next few sections briefly describe some of these stages.

      +

      35.4.1 Preprocessing

      +

      The preprocessor plays a critical role in the SWIG implementation. + This is because a lot of SWIG's processing and internal configuration + is managed not by code written in C, but by configuration files in the + SWIG library. In fact, when you run SWIG, parsing starts with a small + interface file like this (note: this explains the cryptic error + messages that new users sometimes get when SWIG is misconfigured or + installed incorrectly):

      +
      +
      +%include "swig.swg"             // Global SWIG configuration
+%include "langconfig.swg"       // Language specific configuration
+%include "yourinterface.i"      // Your interface file
+
      +
      +

      The swig.swg file contains global configuration + information. In addition, this file defines many of SWIG's standard + directives as macros. For instance, part of of swig.swg looks + like this:

      +
      +
      +...
+/* Code insertion directives such as %wrapper %{ ... %} */
+
+#define %begin       %insert("begin")
+#define %runtime     %insert("runtime")
+#define %header      %insert("header")
+#define %wrapper     %insert("wrapper")
+#define %init        %insert("init")
+
+/* Access control directives */
+
+#define %immutable   %feature("immutable","1")
+#define %mutable     %feature("immutable")
+
+/* Directives for callback functions */
+
+#define %callback(x) %feature("callback") `x`;
+#define %nocallback  %feature("callback");
+
+/* %ignore directive */
+
+#define %ignore         %rename($ignore)
+#define %ignorewarn(x)  %rename("$ignore:" x)
+...
+
      +
      +

      The fact that most of the standard SWIG directives are macros is + intended to simplify the implementation of the internals. For instance, + rather than having to support dozens of special directives, it is + easier to have a few basic primitives such as %feature or +%insert.

      +

      The langconfig.swg file is supplied by the target + language. This file contains language-specific configuration + information. More often than not, this file provides run-time wrapper + support code (e.g., the type-checker) as well as a collection of + typemaps that define the default wrapping behavior. Note: the name of + this file depends on the target language and is usually something like +python.swg or perl5.swg.

      +

      As a debugging aide, the text that SWIG feeds to its C++ parser can + be obtained by running swig -E interface.i. This output + probably isn't too useful in general, but it will show how macros have + been expanded as well as everything else that goes into the low-level + construction of the wrapper code.

      +

      35.4.2 Parsing

      +

      The current C++ parser handles a subset of C++. Most + incompatibilities with C are due to subtle aspects of how SWIG parses + declarations. Specifically, SWIG expects all C/C++ declarations to + follow this general form:

      +
      +
      +storage type declarator initializer;
+
      +
      +

      storage is a keyword such as extern, +static, typedef, or virtual. type + is a primitive datatype such as int or void. +type may be optionally qualified with a qualifier such as +const or volatile. declarator is a name + with additional type-construction modifiers attached to it (pointers, + arrays, references, functions, etc.). Examples of declarators include +*x, **x, x[20], and (*x)(int,double). + The initializer may be a value assigned using = + or body of code enclosed in braces { ... }.

      +

      This declaration format covers most common C++ declarations. + However, the C++ standard is somewhat more flexible in the placement of + the parts. For example, it is technically legal, although uncommon to + write something like int typedef const a in your program. SWIG + simply doesn't bother to deal with this case.

      +

      The other significant difference between C++ and SWIG is in the + treatment of typenames. In C++, if you have a declaration like this,

      +
      +
      +int blah(Foo *x, Bar *y);
+
      +
      +

      it won't parse correctly unless Foo and Bar have + been previously defined as types either using a class + definition or a typedef. The reasons for this are subtle, but + this treatment of typenames is normally integrated at the level of the + C tokenizer---when a typename appears, a different token is returned to + the parser instead of an identifier.

      +

      SWIG does not operate in this manner--any legal identifier can be + used as a type name. The reason for this is primarily motivated by the + use of SWIG with partially defined data. Specifically, SWIG is supposed + to be easy to use on interfaces with missing type information.

      +

      Because of the different treatment of typenames, the most serious + limitation of the SWIG parser is that it can't process type + declarations where an extra (and unnecessary) grouping operator is + used. For example:

      +
      +
      +int (x);         /* A variable x */
+int (y)(int);    /* A function y */
+
      +
      +

      The placing of extra parentheses in type declarations like this is + already recognized by the C++ community as a potential source of + strange programming errors. For example, Scott Meyers "Effective STL" + discusses this problem in a section on avoiding C++'s "most vexing + parse."

      +

      The parser is also unable to handle declarations with no return type + or bare argument names. For example, in an old C program, you might see + things like this:

      +
      +
      +foo(a,b) {
+...
+}
+
      +
      +

      In this case, the return type as well as the types of the arguments + are taken by the C compiler to be an int. However, SWIG + interprets the above code as an abstract declarator for a function + returning a foo and taking types a and b as + arguments).

      +

      35.4.3 Parse Trees

      +

      The SWIG parser produces a complete parse tree of the input file + before any wrapper code is actually generated. Each item in the tree is + known as a "Node". Each node is identified by a symbolic tag. + Furthermore, a node may have an arbitrary number of children. The parse + tree structure and tag names of an interface can be displayed using +swig -debug-tags. For example:

      +
      +
      +$ swig -c++ -python -debug-tags example.i
+ . top (example.i:1)
+ . top . include (example.i:1)
+ . top . include . typemap (/r0/beazley/Projects/lib/swig1.3/swig.swg:71)
+ . top . include . typemap . typemapitem (/r0/beazley/Projects/lib/swig1.3/swig.swg:71)
+ . top . include . typemap (/r0/beazley/Projects/lib/swig1.3/swig.swg:83)
+ . top . include . typemap . typemapitem (/r0/beazley/Projects/lib/swig1.3/swig.swg:83)
+ . top . include (example.i:4)
+ . top . include . insert (/r0/beazley/Projects/lib/swig1.3/python/python.swg:7)
+ . top . include . insert (/r0/beazley/Projects/lib/swig1.3/python/python.swg:8)
+ . top . include . typemap (/r0/beazley/Projects/lib/swig1.3/python/python.swg:19)
+...
+ . top . include (example.i:6)
+ . top . include . module (example.i:2)
+ . top . include . insert (example.i:6)
+ . top . include . include (example.i:9)
+ . top . include . include . class (example.h:3)
+ . top . include . include . class . access (example.h:4)
+ . top . include . include . class . constructor (example.h:7)
+ . top . include . include . class . destructor (example.h:10)
+ . top . include . include . class . cdecl (example.h:11)
+ . top . include . include . class . cdecl (example.h:11)
+ . top . include . include . class . cdecl (example.h:12)
+ . top . include . include . class . cdecl (example.h:13)
+ . top . include . include . class . cdecl (example.h:14)
+ . top . include . include . class . cdecl (example.h:15)
+ . top . include . include . class (example.h:18)
+ . top . include . include . class . access (example.h:19)
+ . top . include . include . class . cdecl (example.h:20)
+ . top . include . include . class . access (example.h:21)
+ . top . include . include . class . constructor (example.h:22)
+ . top . include . include . class . cdecl (example.h:23)
+ . top . include . include . class . cdecl (example.h:24)
+ . top . include . include . class (example.h:27)
+ . top . include . include . class . access (example.h:28)
+ . top . include . include . class . cdecl (example.h:29)
+ . top . include . include . class . access (example.h:30)
+ . top . include . include . class . constructor (example.h:31)
+ . top . include . include . class . cdecl (example.h:32)
+ . top . include . include . class . cdecl (example.h:33)
+
      +
      +

      Even for the most simple interface, the parse tree structure is + larger than you might expect. For example, in the above output, a + substantial number of nodes are actually generated by the +python.swg configuration file which defines typemaps and other + directives. The contents of the user-supplied input file don't appear + until the end of the output.

      +

      The contents of each parse tree node consist of a collection of + attribute/value pairs. Internally, the nodes are simply represented by + hash tables. A display of the entire parse-tree structure can be + obtained using swig -debug-top <n>, where n is the + stage being processed. There are a number of other parse tree display + options, for example, swig -debug-module <n> will avoid + displaying system parse information and only display the parse tree + pertaining to the user's module at stage n of processing.

      +
      +
      +$ swig -c++ -python -debug-module 4 example.i
+      +++ include ----------------------------------------
+      | name         - "example.i"
+
+            +++ module ----------------------------------------
+            | name         - "example"
+            |
+            +++ insert ----------------------------------------
+            | code         - "\n#include \"example.h\"\n"
+            |
+            +++ include ----------------------------------------
+            | name         - "example.h"
+
+                  +++ class ----------------------------------------
+                  | abstract     - "1"
+                  | sym:name     - "Shape"
+                  | name         - "Shape"
+                  | kind         - "class"
+                  | symtab       - 0x40194140
+                  | sym:symtab   - 0x40191078
+
+                        +++ access ----------------------------------------
+                        | kind         - "public"
+                        |
+                        +++ constructor ----------------------------------------
+                        | sym:name     - "Shape"
+                        | name         - "Shape"
+                        | decl         - "f()."
+                        | code         - "{\n    nshapes++;\n  }"
+                        | sym:symtab   - 0x40194140
+                        |
+                        +++ destructor ----------------------------------------
+                        | sym:name     - "~Shape"
+                        | name         - "~Shape"
+                        | storage      - "virtual"
+                        | code         - "{\n    nshapes--;\n  }"
+                        | sym:symtab   - 0x40194140
+                        |
+                        +++ cdecl ----------------------------------------
+                        | sym:name     - "x"
+                        | name         - "x"
+                        | decl         - ""
+                        | type         - "double"
+                        | sym:symtab   - 0x40194140
+                        |
+                        +++ cdecl ----------------------------------------
+                        | sym:name     - "y"
+                        | name         - "y"
+                        | decl         - ""
+                        | type         - "double"
+                        | sym:symtab   - 0x40194140
+                        |
+                        +++ cdecl ----------------------------------------
+                        | sym:name     - "move"
+                        | name         - "move"
+                        | decl         - "f(double,double)."
+                        | parms        - double ,double
+                        | type         - "void"
+                        | sym:symtab   - 0x40194140
+                        |
+                        +++ cdecl ----------------------------------------
+                        | sym:name     - "area"
+                        | name         - "area"
+                        | decl         - "f(void)."
+                        | parms        - void
+                        | storage      - "virtual"
+                        | value        - "0"
+                        | type         - "double"
+                        | sym:symtab   - 0x40194140
+                        |
+                        +++ cdecl ----------------------------------------
+                        | sym:name     - "perimeter"
+                        | name         - "perimeter"
+                        | decl         - "f(void)."
+                        | parms        - void
+                        | storage      - "virtual"
+                        | value        - "0"
+                        | type         - "double"
+                        | sym:symtab   - 0x40194140
+                        |
+                        +++ cdecl ----------------------------------------
+                        | sym:name     - "nshapes"
+                        | name         - "nshapes"
+                        | decl         - ""
+                        | storage      - "static"
+                        | type         - "int"
+                        | sym:symtab   - 0x40194140
+                        |
+                  +++ class ----------------------------------------
+                  | sym:name     - "Circle"
+                  | name         - "Circle"
+                  | kind         - "class"
+                  | bases        - 0x40194510
+                  | symtab       - 0x40194538
+                  | sym:symtab   - 0x40191078
+
+                        +++ access ----------------------------------------
+                        | kind         - "private"
+                        |
+                        +++ cdecl ----------------------------------------
+                        | name         - "radius"
+                        | decl         - ""
+                        | type         - "double"
+                        |
+                        +++ access ----------------------------------------
+                        | kind         - "public"
+                        |
+                        +++ constructor ----------------------------------------
+                        | sym:name     - "Circle"
+                        | name         - "Circle"
+                        | parms        - double
+                        | decl         - "f(double)."
+                        | code         - "{ }"
+                        | sym:symtab   - 0x40194538
+                        |
+                        +++ cdecl ----------------------------------------
+                        | sym:name     - "area"
+                        | name         - "area"
+                        | decl         - "f(void)."
+                        | parms        - void
+                        | storage      - "virtual"
+                        | type         - "double"
+                        | sym:symtab   - 0x40194538
+                        |
+                        +++ cdecl ----------------------------------------
+                        | sym:name     - "perimeter"
+                        | name         - "perimeter"
+                        | decl         - "f(void)."
+                        | parms        - void
+                        | storage      - "virtual"
+                        | type         - "double"
+                        | sym:symtab   - 0x40194538
+                        |
+                  +++ class ----------------------------------------
+                  | sym:name     - "Square"
+                  | name         - "Square"
+                  | kind         - "class"
+                  | bases        - 0x40194760
+                  | symtab       - 0x40194788
+                  | sym:symtab   - 0x40191078
+
+                        +++ access ----------------------------------------
+                        | kind         - "private"
+                        |
+                        +++ cdecl ----------------------------------------
+                        | name         - "width"
+                        | decl         - ""
+                        | type         - "double"
+                        |
+                        +++ access ----------------------------------------
+                        | kind         - "public"
+                        |
+                        +++ constructor ----------------------------------------
+                        | sym:name     - "Square"
+                        | name         - "Square"
+                        | parms        - double
+                        | decl         - "f(double)."
+                        | code         - "{ }"
+                        | sym:symtab   - 0x40194788
+                        |
+                        +++ cdecl ----------------------------------------
+                        | sym:name     - "area"
+                        | name         - "area"
+                        | decl         - "f(void)."
+                        | parms        - void
+                        | storage      - "virtual"
+                        | type         - "double"
+                        | sym:symtab   - 0x40194788
+                        |
+                        +++ cdecl ----------------------------------------
+                        | sym:name     - "perimeter"
+                        | name         - "perimeter"
+                        | decl         - "f(void)."
+                        | parms        - void
+                        | storage      - "virtual"
+                        | type         - "double"
+                        | sym:symtab   - 0x40194788
+
      +
      +

      35.4.4 Attribute namespaces

      +

      Attributes of parse tree nodes are often prepended with a namespace + qualifier. For example, the attributes sym:name and +sym:symtab are attributes related to symbol table management and + are prefixed with sym:. As a general rule, only those + attributes which are directly related to the raw declaration appear + without a prefix (type, name, declarator, etc.).

      +

      Target language modules may add additional attributes to nodes to + assist the generation of wrapper code. The convention for doing this is + to place these attributes in a namespace that matches the name of the + target language. For example, python:foo or perl:foo.

      +

      35.4.5 Symbol Tables

      +

      During parsing, all symbols are managed in the space of the target + language. The sym:name attribute of each node contains the + symbol name selected by the parser. Normally, sym:name and +name are the same. However, the %rename directive can be + used to change the value of sym:name. You can see the effect + of %rename by trying it on a simple interface and dumping the + parse tree. For example:

      +
      +
      +%rename(foo_i) foo(int);
+%rename(foo_d) foo(double);
+
+void foo(int);
+void foo(double);
+void foo(Bar *b);
+
      +
      +

      There are various debug- options that can be useful for + debugging and analysing the parse tree. For example, the debug-top + <n> or debug-module <n> options will dump the entire/top + of the parse tree or the module subtree at one of the four n + stages of processing. The parse tree can be viewed after the final + stage of processing by running SWIG:

      +
      +
      +$ swig -debug-top 4 example.i
+...
+            +++ cdecl ----------------------------------------
+            | sym:name     - "foo_i"
+            | name         - "foo"
+            | decl         - "f(int)."
+            | parms        - int
+            | type         - "void"
+            | sym:symtab   - 0x40165078
+            |
+            +++ cdecl ----------------------------------------
+            | sym:name     - "foo_d"
+            | name         - "foo"
+            | decl         - "f(double)."
+            | parms        - double
+            | type         - "void"
+            | sym:symtab   - 0x40165078
+            |
+            +++ cdecl ----------------------------------------
+            | sym:name     - "foo"
+            | name         - "foo"
+            | decl         - "f(p.Bar)."
+            | parms        - Bar *
+            | type         - "void"
+            | sym:symtab   - 0x40165078
+
      +
      +

      All symbol-related conflicts and complaints about overloading are + based on sym:name values. For instance, the following example + uses %rename in reverse to generate a name clash.

      +
      +
      +%rename(foo) foo_i(int);
+%rename(foo) foo_d(double;
+
+void foo_i(int);
+void foo_d(double);
+void foo(Bar *b);
+
      +
      +

      When you run SWIG on this you now get:

      +
      +
      +$ ./swig example.i
+example.i:6. Overloaded declaration ignored.  foo_d(double )
+example.i:5. Previous declaration is foo_i(int )
+example.i:7. Overloaded declaration ignored.  foo(Bar *)
+example.i:5. Previous declaration is foo_i(int )
+
      +
      +

      35.4.6 The %feature directive

      +

      A number of SWIG directives such as %exception are + implemented using the low-level %feature directive. For + example:

      +
      +
      +%feature("except") getitem(int) {
+  try {
+     $action
+  } catch (badindex) {
+     ...
+  }
+}
+
+...
+class Foo {
+public:
+    Object *getitem(int index) throws(badindex);
+    ...
+};
+
      +
      +

      The behavior of %feature is very easy to describe--it + simply attaches a new attribute to any parse tree node that matches the + given prototype. When a feature is added, it shows up as an attribute + in the feature: namespace. You can see this when running with + the -debug-top 4 option. For example:

      +
      +
      + +++ cdecl ----------------------------------------
+ | sym:name     - "getitem"
+ | name         - "getitem"
+ | decl         - "f(int).p."
+ | parms        - int
+ | type         - "Object"
+ | feature:except - "{\n    try {\n       $action\n    } catc..."
+ | sym:symtab   - 0x40168ac8
+ |
+
      +
      +

      Feature names are completely arbitrary and a target language module + can be programmed to respond to any feature name that it wants to + recognize. The data stored in a feature attribute is usually just a raw + unparsed string. For example, the exception code above is simply stored + without any modifications.

      +

      35.4.7 Code Generation

      +

      Language modules work by defining handler functions that know how to + respond to different types of parse-tree nodes. These handlers simply + look at the attributes of each node in order to produce low-level code.

      +

      In reality, the generation of code is somewhat more subtle than + simply invoking handler functions. This is because parse-tree nodes + might be transformed. For example, suppose you are wrapping a class + like this:

      +
      +
      +class Foo {
+public:
+    virtual int *bar(int x);
+};
+
      +
      +

      When the parser constructs a node for the member bar, it + creates a raw "cdecl" node with the following attributes:

      +
      +
      +nodeType    : cdecl
+name        : bar
+type        : int
+decl        : f(int).p
+parms       : int x
+storage     : virtual
+sym:name    : bar
+
      +
      +

      To produce wrapper code, this "cdecl" node undergoes a number of + transformations. First, the node is recognized as a function + declaration. This adjusts some of the type information--specifically, + the declarator is joined with the base datatype to produce this:

      +
      +
      +nodeType    : cdecl
+name        : bar
+type        : p.int        <-- Notice change in return type
+decl        : f(int).p
+parms       : int x
+storage     : virtual
+sym:name    : bar
+
      +
      +

      Next, the context of the node indicates that the node is really a + member function. This produces a transformation to a low-level accessor + function like this:

      +
      +
      +nodeType    : cdecl
+name        : bar
+type        : int.p
+decl        : f(int).p
+parms       : Foo *self, int x            <-- Added parameter
+storage     : virtual
+wrap:action : result = (arg1)->bar(arg2)  <-- Action code added
+sym:name    : Foo_bar                     <-- Symbol name changed
+
      +
      +

      In this transformation, notice how an additional parameter was added + to the parameter list and how the symbol name of the node has suddenly + changed into an accessor using the naming scheme described in the "SWIG + Basics" chapter. A small fragment of "action" code has also been + generated--notice how the wrap:action attribute defines the + access to the underlying method. The data in this transformed node is + then used to generate a wrapper.

      +

      Language modules work by registering handler functions for dealing + with various types of nodes at different stages of transformation. This + is done by inheriting from a special Language class and + defining a collection of virtual methods. For example, the Python + module defines a class as follows:

      +
      +
      +class PYTHON : public Language {
+protected:
+public :
+  virtual void main(int, char *argv[]);
+  virtual int  top(Node *);
+  virtual int  functionWrapper(Node *);
+  virtual int  constantWrapper(Node *);
+  virtual int  variableWrapper(Node *);
+  virtual int  nativeWrapper(Node *);
+  virtual int  membervariableHandler(Node *);
+  virtual int  memberconstantHandler(Node *);
+  virtual int  memberfunctionHandler(Node *);
+  virtual int  constructorHandler(Node *);
+  virtual int  destructorHandler(Node *);
+  virtual int  classHandler(Node *);
+  virtual int  classforwardDeclaration(Node *);
+  virtual int  insertDirective(Node *);
+  virtual int  importDirective(Node *);
+};
+
      +
      +

      The role of these functions is described shortly.

      +

      35.4.8 SWIG and XML

      +

      Much of SWIG's current parser design was originally motivated by + interest in using XML to represent SWIG parse trees. Although XML is + not currently used in any direct manner, the parse tree structure, use + of node tags, attributes, and attribute namespaces are all influenced + by aspects of XML parsing. Therefore, in trying to understand SWIG's + internal data structures, it may be useful to keep XML in the back of + your mind as a model.

      +

      35.5 Primitive Data Structures

      +

      Most of SWIG is constructed using three basic data structures: + strings, hashes, and lists. These data structures are dynamic in same + way as similar structures found in many scripting languages. For + instance, you can have containers (lists and hash tables) of mixed + types and certain operations are polymorphic.

      +

      This section briefly describes the basic structures so that later + sections of this chapter make more sense.

      +

      When describing the low-level API, the following type name + conventions are used:

      +
        +
      • String. A string object.
        • +
      • Hash. A hash object.
        • +
      • List. A list object.
        • +
      • String_or_char. A string object or a char *.
        • +
      • Object_or_char. An object or a char *.
        • +
      • Object. Any object (string, hash, list, etc.)
        • +
      +

      In most cases, other typenames in the source are aliases for one of + these primitive types. Specifically:

      +
      +
      +typedef String SwigType;
+typedef Hash   Parm;
+typedef Hash   ParmList;
+typedef Hash   Node;
+typedef Hash   Symtab;
+typedef Hash   Typetab;
+
      +
      +

      35.5.1 Strings

      +

      String *NewString(const String_or_char *val)

      +
      Creates a new string with initial value val +. val may be a char * or another String + object. If you want to create an empty string, use "" for val.
      +

      String *NewStringf(const char *fmt, ...)

      +
      Creates a new string whose initial value is set + according to a C printf style format string in fmt. + Additional arguments follow depending on fmt.
      +

      String *Copy(String *s)

      +
      Make a copy of the string s.
      +

      void Delete(String *s)

      +
      Deletes s.
      +

      int Len(const String_or_char *s)

      +
      Returns the length of the string.
      +

      char *Char(const String_or_char *s)

      +
      Returns a pointer to the first character in a + string.
      +

      void Append(String *s, const String_or_char *t)

      +
      Appends t to the end of string s.
      +

      void Insert(String *s, int pos, const String_or_char *t) +

      +
      Inserts t into s at position +pos. The contents of s are shifted accordingly. The + special value DOH_END can be used for pos to indicate + insertion at the end of the string (appending).
      +

      int Strcmp(const String_or_char *s, const String_or_char *t) +

      +
      Compare strings s and t. Same as + the C strcmp() function.
      +

      int Strncmp(const String_or_char *s, const String_or_char *t, + int len)

      +
      Compare the first len characters of + strings s and t. Same as the C strncmp() + function.
      +

      char *Strstr(const String_or_char *s, const String_or_char + *pat)

      +
      Returns a pointer to the first occurrence of +pat in s. Same as the C strstr() function.
      +

      char *Strchr(const String_or_char *s, char ch)

      +
      Returns a pointer to the first occurrence of + character ch in s. Same as the C strchr() + function.
      +

      void Chop(String *s)

      +
      Chops trailing whitespace off the end of s +.
      +

      int Replace(String *s, const String_or_char *pat, const + String_or_char *rep, int flags)

      +
      +

      Replaces the pattern pat with rep in string s +. flags is a combination of the following flags:

      +
      +
      +DOH_REPLACE_ANY       - Replace all occurrences
+DOH_REPLACE_ID        - Valid C identifiers only
+DOH_REPLACE_NOQUOTE   - Don't replace in quoted strings
+DOH_REPLACE_FIRST     - Replace first occurrence only.
+
      +
      +

      Returns the number of replacements made (if any).

      +
      +

      35.5.2 Hashes

      +

      Hash *NewHash()

      +
      Creates a new empty hash table.
      +

      Hash *Copy(Hash *h)

      +
      Make a shallow copy of the hash h.
      +

      void Delete(Hash *h)

      +
      Deletes h.
      +

      int Len(Hash *h)

      +
      Returns the number of items in h.
      +

      Object *Getattr(Hash *h, const String_or_char *key)

      +
      Gets an object from h. key may be + a string or a simple char * string. Returns NULL if not found.
      +

      int Setattr(Hash *h, const String_or_char *key, const + Object_or_char *val)

      +
      Stores val in h. key may + be a string or a simple char *. If val is not a + standard object (String, Hash, or List) it is assumed to be a char + * in which case it is used to construct a String that is + stored in the hash. If val is NULL, the object is deleted. + Increases the reference count of val. Returns 1 if this + operation replaced an existing hash entry, 0 otherwise.
      +

      int Delattr(Hash *h, const String_or_char *key)

      +
      Deletes the hash item referenced by key. + Decreases the reference count on the corresponding object (if any). + Returns 1 if an object was removed, 0 otherwise.
      +

      List *Keys(Hash *h)

      +
      Returns the list of hash table keys.
      +

      35.5.3 Lists

      +

      List *NewList()

      +
      Creates a new empty list.
      +

      List *Copy(List *x)

      +
      Make a shallow copy of the List x.
      +

      void Delete(List *x)

      +
      Deletes x.
      +

      int Len(List *x)

      +
      Returns the number of items in x.
      +

      Object *Getitem(List *x, int n)

      +
      Returns an object from x with index n +. If n is beyond the end of the list, the last item is + returned. If n is negative, the first item is returned.
      +

      int *Setitem(List *x, int n, const Object_or_char *val) +

      +
      Stores val in x. If val + is not a standard object (String, Hash, or List) it is assumed to be a +char * in which case it is used to construct a String that + is stored in the list. n must be in range. Otherwise, an + assertion will be raised.
      +

      int *Delitem(List *x, int n)

      +
      Deletes item n from the list, shifting + items down if necessary. To delete the last item in the list, use the + special value DOH_END for n.
      +

      void Append(List *x, const Object_or_char *t)

      +
      Appends t to the end of x. If +t is not a standard object, it is assumed to be a char * + and is used to create a String object.
      +

      void Insert(String *s, int pos, const Object_or_char *t) +

      +
      Inserts t into s at position +pos. The contents of s are shifted accordingly. The + special value DOH_END can be used for pos to indicate + insertion at the end of the list (appending). If t is not a + standard object, it is assumed to be a char * and is used to + create a String object.
      +

      35.5.4 Common operations

      + The following operations are applicable to all datatypes. +

      Object *Copy(Object *x)

      +
      Make a copy of the object x.
      +

      void Delete(Object *x)

      +
      Deletes x.
      +

      void Setfile(Object *x, String_or_char *f)

      +
      Sets the filename associated with x. Used + to track objects and report errors.
      +

      String *Getfile(Object *x)

      +
      Gets the filename associated with x.
      +

      void Setline(Object *x, int n)

      +
      Sets the line number associated with x. + Used to track objects and report errors.
      +

      int Getline(Object *x)

      +
      Gets the line number associated with x.
      +

      35.5.5 Iterating over Lists and Hashes

      + To iterate over the elements of a list or a hash table, the following + functions are used: +

      Iterator First(Object *x)

      +
      Returns an iterator object that points to the first + item in a list or hash table. The item attribute of the + Iterator object is a pointer to the item. For hash tables, the key + attribute of the Iterator object additionally points to the + corresponding Hash table key. The item and key + attributes are NULL if the object contains no items or if there are no + more items.
      +

      Iterator Next(Iterator i)

      +
      +

      Returns an iterator that points to the next item in a list or hash + table. Here are two examples of iteration:

      +
      +
      +List *l = (some list);
+Iterator i;
+
+for (i = First(l); i.item; i = Next(i)) {
+    Printf(stdout,"%s\n", i.item);
+}
+
+Hash *h = (some hash);
+Iterator j;
+
+for (j = First(j); j.item; j= Next(j)) {
+    Printf(stdout,"%s : %s\n", j.key, j.item);
+}
+
      +
      +

      35.5.6 I/O

      + Special I/O functions are used for all internal I/O. These operations + work on C FILE * objects, String objects, and special File + objects (which are merely a wrapper around FILE *). +

      int Printf(String_or_FILE *f, const char *fmt, ...)

      +
      Formatted I/O. Same as the C fprintf() + function except that output can also be directed to a string object. + Note: the %s format specifier works with both strings and +char *. All other format operators have the same meaning.
      +

      int Printv(String_or_FILE *f, String_or_char *arg1,..., NULL) +

      +
      Prints a variable number of strings arguments to + the output. The last argument to this function must be NULL. The other + arguments can either be char * or string objects.
      +

      int Putc(int ch, String_or_FILE *f)

      +
      Same as the C fputc() function.
      +

      int Write(String_or_FILE *f, void *buf, int len)

      +
      Same as the C write() function.
      +

      int Read(String_or_FILE *f, void *buf, int maxlen)

      +
      Same as the C read() function.
      +

      int Getc(String_or_FILE *f)

      +
      Same as the C fgetc() function.
      +

      int Ungetc(int ch, String_or_FILE *f)

      +
      Same as the C ungetc() function.
      +

      int Seek(String_or_FILE *f, int offset, int whence)

      +
      Same as the C seek() function. offset + is the number of bytes. whence is one of SEEK_SET, +SEEK_CUR, or SEEK_END..
      +

      long Tell(String_or_FILE *f)

      +
      Same as the C tell() function.
      +

      File *NewFile(const char *filename, const char *mode, List + *newfiles)

      +
      Create a File object using the fopen() + library call. This file differs from FILE * in that it can be + placed in the standard SWIG containers (lists, hashes, etc.). The +filename is added to the newfiles list if newfiles + is non-zero and the file was created successfully.
      +

      File *NewFileFromFile(FILE *f)

      +
      Create a File object wrapper around an existing +FILE * object.
      +

      int Close(String_or_FILE *f)

      +
      +

      Closes a file. Has no effect on strings.

      +

      The use of the above I/O functions and strings play a critical role + in SWIG. It is common to see small code fragments of code generated + using code like this:

      +
      +
      +/* Print into a string */
+String *s = NewString("");
+Printf(s,"Hello\n");
+for (i = 0; i < 10; i++) {
+    Printf(s,"%d\n", i);
+}
+...
+/* Print string into a file */
+Printf(f, "%s\n", s);
+
      +
      +

      Similarly, the preprocessor and parser all operate on string-files.

      +
      +

      35.6 Navigating and manipulating parse + trees

      + Parse trees are built as collections of hash tables. Each node is a + hash table in which arbitrary attributes can be stored. Certain + attributes in the hash table provide links to other parse tree nodes. + The following macros can be used to move around the parse tree. +

      String *nodeType(Node *n)

      +
      Returns the node type tag as a string. The returned + string indicates the type of parse tree node.
      +

      Node *nextSibling(Node *n)

      +
      Returns the next node in the parse tree. For + example, the next C declaration.
      +

      Node *previousSibling(Node *n)

      +
      Returns the previous node in the parse tree. For + example, the previous C declaration.
      +

      Node *firstChild(Node *n)

      +
      Returns the first child node. For example, if n + was a C++ class node, this would return the node for the first class + member.
      +

      Node *lastChild(Node *n)

      +
      Returns the last child node. You might use this if + you wanted to append a new node to the of a class.
      +

      Node *parentNode(Node *n)

      +
      Returns the parent of node n. Use this to + move up the pass tree.
      +

      The following macros can be used to change all of the above + attributes. Normally, these functions are only used by the parser. + Changing them without knowing what you are doing is likely to be + dangerous.

      +

      void set_nodeType(Node *n, const String_or_char)

      +
      Change the node type. tree node.
      +

      void set_nextSibling(Node *n, Node *s)

      +
      Set the next sibling.
      +

      void set_previousSibling(Node *n, Node *s)

      +
      Set the previous sibling.
      +

      void set_firstChild(Node *n, Node *c)

      +
      Set the first child node.
      +

      void set_lastChild(Node *n, Node *c)

      +
      Set the last child node.
      +

      void set_parentNode(Node *n, Node *p)

      +
      Set the parent node.
      +

      The following utility functions are used to alter the parse tree (at + your own risk)

      +

      void appendChild(Node *parent, Node *child)

      +
      Append a child to parent. The appended + node becomes the last child.
      +

      void deleteNode(Node *node)

      +
      Deletes a node from the parse tree. Deletion + reconnects siblings and properly updates the parent so that sibling + nodes are unaffected.
      +

      35.7 Working with attributes

      +

      Since parse tree nodes are just hash tables, attributes are accessed + using the Getattr(), Setattr(), and Delattr() + operations. For example:

      +
      +
      +int functionHandler(Node *n) {
+    String *name    = Getattr(n,"name");
+    String *symname = Getattr(n,"sym:name");
+    SwigType *type  = Getattr(n,"type");
+    ...
+}
+
      +
      +

      New attributes can be freely attached to a node as needed. However, + when new attributes are attached during code generation, they should be + prepended with a namespace prefix. For example:

      +
      +
      +...
+Setattr(n,"python:docstring", doc);     /* Store docstring */
+...
+
      +
      +

      A quick way to check the value of an attribute is to use the +checkAttribute() function like this:

      +
      +
      +if (checkAttribute(n,"storage","virtual")) {
+   /* n is virtual */
+   ...
+}
+
      +
      +

      Changing the values of existing attributes is allowed and is + sometimes done to implement node transformations. However, if a + function/method modifies a node, it is required to restore modified + attributes to their original values. To simplify the task of + saving/restoring attributes, the following functions are used:

      +

      int Swig_save(const char *ns, Node *n, const char *name1, + const char *name2, ..., NIL)

      +
      Saves a copy of attributes name1, +name2, etc. from node n. Copies of the attributes are + actually resaved in the node in a different namespace which is set by + the ns argument. For example, if you call +Swig_save("foo",n,"type",NIL), then the "type" attribute will be + copied and saved as "foo:type". The namespace name itself is stored in + the "view" attribute of the node. If necessary, this can be examined to + find out where previous values of attributes might have been saved.
      +

      int Swig_restore(Node *n)

      +
      +

      Restores the attributes saved by the previous call to +Swig_save(). Those attributes that were supplied to Swig_save() + will be restored to their original values.

      +

      The Swig_save() and Swig_restore() functions must + always be used as a pair. That is, every call to Swig_save() + must have a matching call to Swig_restore(). Calls can be + nested if necessary. Here is an example that shows how the functions + might be used:

      +
      +
      +int variableHandler(Node *n) {
+    Swig_save("variableHandler",n,"type","sym:name",NIL);
+    String *symname = Getattr(n,"sym:name");
+    SwigType *type  = Getattr(n,"type");
+    ...
+    Append(symname,"_global");         // Change symbol name
+    SwigType_add_pointer(type);        // Add pointer
+    ...
+    generate wrappers
+    ...
+    Swig_restore(n);                  // Restore original values
+    return SWIG_OK;
+}
+
      +
      +

      int Swig_require(const char *ns, Node *n, const char *name1, + const char *name2, ..., NIL)

      +
      This is an enhanced version of Swig_save() + that adds error checking. If an attribute name is not present in n +, a failed assertion results and SWIG terminates with a fatal error. + Optionally, if an attribute name is specified as "*name", a + copy of the attribute is saved as with Swig_save(). If an + attribute is specified as "?name", the attribute is optional. +Swig_restore() must always be called after using this function.
      +

      35.8 Type system

      +

      SWIG implements the complete C++ type system including typedef, + inheritance, pointers, references, and pointers to members. A detailed + discussion of type theory is impossible here. However, let's cover the + highlights.

      +

      35.8.1 String encoding of types

      +

      All types in SWIG consist of a base datatype and a collection of + type operators that are applied to the base. A base datatype is almost + always some kind of primitive type such as int or double +. The operators consist of things like pointers, references, arrays, and + so forth. Internally, types are represented as strings that are + constructed in a very precise manner. Here are some examples:

      +
      +
      +C datatype                     SWIG encoding (strings)
+-----------------------------  --------------------------
+int                            "int"
+int *                          "p.int"
+const int *                    "p.q(const).int"
+int (*x)(int,double)           "p.f(int,double).int"
+int [20][30]                   "a(20).a(30).int"
+int (F::*)(int)                "m(F).f(int).int"
+vector<int> *                  "p.vector<(int)>"
+
      +
      +

      Reading the SWIG encoding is often easier than figuring out the C + code---just read it from left to right. For a type of + "p.f(int,double).int" is a "pointer to a function(int,double) that + returns int".

      +

      The following operator encodings are used in type strings:

      +
      +
      +Operator              Meaning
+-------------------   -------------------------------
+p.                    Pointer to
+a(n).                 Array of dimension n
+r.                    C++ reference
+m(class).             Member pointer to class
+f(args).              Function.
+q(qlist).             Qualifiers
+
      +
      +

      In addition, type names may be parameterized by templates. This is + represented by enclosing the template parameters in <( ... )>. + Variable length arguments are represented by the special base type of +v(...).

      +

      If you want to experiment with type encodings, the raw type strings + can be inserted into an interface file using backticks `` wherever a + type is expected. For instance, here is an extremely perverted example:

      +
      +
      +`p.a(10).p.f(int,p.f(int).int)` foo(int, int (*x)(int));
+
      +
      +

      This corresponds to the immediately obvious C declaration:

      +
      +
      +(*(*foo(int,int (*)(int)))[10])(int,int (*)(int));
+
      +
      +

      Aside from the potential use of this declaration on a C programming + quiz, it motivates the use of the special SWIG encoding of types. The + SWIG encoding is much easier to work with because types can be easily + examined, modified, and constructed using simple string operations + (comparison, substrings, concatenation, etc.). For example, in the + parser, a declaration like this

      +
      +
      +int *a[30];
+
      +
      +

      is processed in a few pieces. In this case, you have the base type " +int" and the declarator of type "a(30).p.". To make the + final type, the two parts are just joined together using string + concatenation.

      +

      35.8.2 Type construction

      +

      The following functions are used to construct types. You should use + these functions instead of trying to build the type strings yourself.

      +

      void SwigType_add_pointer(SwigType *ty)

      +
      Adds a pointer to ty.
      +

      void SwigType_del_pointer(SwigType *ty)

      +
      Removes a single pointer from ty.
      +

      void SwigType_add_reference(SwigType *ty)

      +
      Adds a reference to ty.
      +

      void SwigType_add_array(SwigType *ty, const String_or_char + *size)

      +
      Adds an array with dimension dim to ty +.
      +

      void SwigType_del_array(SwigType *ty)

      +
      Removes a single array dimension from ty.
      +

      int SwigType_array_ndim(SwigType *ty)

      +
      Returns number of array dimensions of ty.
      +

      String* SwigType_array_getdim(SwigType *ty,int n)

      +
      Returns nth array dimension of ty +.
      +

      void SwigType_array_setdim(SwigType *ty, int n, const + String_or_char *rep)

      +
      Sets nth array dimensions of ty + to rep.
      +

      void SwigType_add_qualifier(SwigType *ty, const + String_or_char *q)

      +
      Adds a type qualifier q to ty. +q is typically "const" or "volatile".
      +

      void SwigType_add_memberpointer(SwigType *ty, const + String_or_char *cls)

      +
      Adds a pointer to a member of class cls to + ty.
      +

      void SwigType_add_function(SwigType *ty, ParmList *p) +

      +
      Adds a function to ty. p is a + linked-list of parameter nodes as generated by the parser. See the + section on parameter lists for details about the representation.
      +

      void SwigType_add_template(SwigType *ty, ParmList *p) +

      +
      Adds a template to ty. p is a + linked-list of parameter nodes as generated by the parser. See the + section on parameter lists for details about the representation.
      +

      SwigType *SwigType_pop(SwigType *ty)

      +
      Removes the last type constructor from ty + and returns it. ty is modified.
      +

      void SwigType_push(SwigType *ty, SwigType *op)

      +
      Pushes the type operators in op onto type +ty. The opposite of SwigType_pop().
      +

      SwigType *SwigType_pop_arrays(SwigType *ty)

      +
      Removes all leading array operators from ty + and returns them. ty is modified. For example, if ty + is "a(20).a(10).p.int", then this function would return +"a(20).a(10)." and modify ty so that it has the value +"p.int".
      +

      SwigType *SwigType_pop_function(SwigType *ty)

      +
      Removes a function operator from ty + including any qualification. ty is modified. For example, if +ty is "f(int).int", then this function would return +"f(int)." and modify ty so that it has the value "int" +.
      +

      SwigType *SwigType_base(SwigType *ty)

      +
      Returns the base type of a type. For example, if +ty is "p.a(20).int", this function would return "int" +. ty is unmodified.
      +

      SwigType *SwigType_prefix(SwigType *ty)

      +
      Returns the prefix of a type. For example, if +ty is "p.a(20).int", this function would return +"p.a(20).". ty is unmodified.
      +

      35.8.3 Type tests

      +

      The following functions can be used to test properties of a + datatype.

      +

      int SwigType_ispointer(SwigType *ty)

      +
      Checks if ty is a standard pointer.
      +

      int SwigType_ismemberpointer(SwigType *ty)

      +
      Checks if ty is a member pointer.
      +

      int SwigType_isreference(SwigType *ty)

      +
      Checks if ty is a C++ reference.
      +

      int SwigType_isarray(SwigType *ty)

      +
      Checks if ty is an array.
      +

      int SwigType_isfunction(SwigType *ty)

      +
      Checks if ty is a function.
      +

      int SwigType_isqualifier(SwigType *ty)

      +
      Checks if ty is a qualifier.
      +

      int SwigType_issimple(SwigType *ty)

      +
      Checks if ty is a simple type. No + operators applied.
      +

      int SwigType_isconst(SwigType *ty)

      +
      Checks if ty is a const type.
      +

      int SwigType_isvarargs(SwigType *ty)

      +
      Checks if ty is a varargs type.
      +

      int SwigType_istemplate(SwigType *ty)

      +
      Checks if ty is a templatized type.
      +

      35.8.4 Typedef and inheritance

      +

      The behavior of typedef declaration is to introduce a type + alias. For instance, typedef int Integer makes the identifier +Integer an alias for int. The treatment of typedef in SWIG + is somewhat complicated due to the pattern matching rules that get + applied in typemaps and the fact that SWIG prefers to generate wrapper + code that closely matches the input to simplify debugging (a user will + see the typedef names used in their program instead of the low-level + primitive C datatypes).

      +

      To handle typedef, SWIG builds a collection of trees + containing typedef relations. For example,

      +
      +
      +typedef int Integer;
+typedef Integer *IntegerPtr;
+typedef int Number;
+typedef int Size;
+
      +
      +

      produces two trees like this:

      +
      +
      +                 int               p.Integer
+               ^  ^  ^                 ^
+              /   |   \                |
+             /    |    \               |
+        Integer  Size   Number    IntegerPtr
+
      +
      +

      To resolve a single typedef relationship, the following function is + used:

      +

      SwigType *SwigType_typedef_resolve(SwigType *ty)

      +
      Checks if ty can be reduced to a new type + via typedef. If so, returns the new type. If not, returns NULL.
      +

      Typedefs are only resolved in simple typenames that appear in a + type. For example, the type base name and in function parameters. When + resolving types, the process starts in the leaf nodes and moves up the + tree towards the root. Here are a few examples that show how it works:

      +
      +
      +Original type            After typedef_resolve()
+------------------------ -----------------------
+Integer                  int
+a(30).Integer            int
+p.IntegerPtr             p.p.Integer
+p.p.Integer              p.p.int
+
      +
      +

      For complicated types, the process can be quite involved. Here is + the reduction of a function pointer:

      +
      +
      +p.f(Integer, p.IntegerPtr, Size).Integer          : Start
+p.f(Integer, p.IntegerPtr, Size).int
+p.f(int, p.IntegerPtr, Size).int
+p.f(int, p.p.Integer, Size).int
+p.f(int, p.p.int, Size).int
+p.f(int, p.p.int, int).int                        : End
+
      +
      +

      Two types are equivalent if their full type reductions are the same. + The following function will fully reduce a datatype:

      +

      SwigType *SwigType_typedef_resolve_all(SwigType *ty)

      +
      Fully reduces ty according to typedef + rules. Resulting datatype will consist only of primitive typenames.
      +

      35.8.5 Lvalues

      +

      When generating wrapper code, it is necessary to emit datatypes that + can be used on the left-hand side of an assignment operator (an + lvalue). However, not all C datatypes can be used in this + way---especially arrays and const-qualified types. To generate a type + that can be used as an lvalue, use the following function:

      +

      SwigType *SwigType_ltype(SwigType *ty)

      +
      Converts type ty to a type that can be + used as an lvalue in assignment. The resulting type is stripped of + qualifiers and arrays are converted to a pointers.
      +

      The creation of lvalues is fully aware of typedef and other aspects + of the type system. Therefore, the creation of an lvalue may result in + unexpected results. Here are a few examples:

      +
      +
      +typedef double Matrix4[4][4];
+Matrix4 x;    // type = 'Matrix4', ltype='p.a(4).double'
+
+typedef const char * Literal;
+Literal y;    // type = 'Literal', ltype='p.char'
+
      +
      +

      35.8.6 Output functions

      +

      The following functions produce strings that are suitable for + output.

      +

      String *SwigType_str(SwigType *ty, const String_or_char *id = + 0)

      +
      Generates a C string for a datatype. id is + an optional declarator. For example, if ty is "p.f(int).int" + and id is "foo", then this function produces "int + (*foo)(int)". This function is used to convert string-encoded + types back into a form that is valid C syntax.
      +

      String *SwigType_lstr(SwigType *ty, const String_or_char *id + = 0)

      +
      This is the same as SwigType_str() except + that the result is generated from the type's lvalue (as generated from + SwigType_ltype).
      +

      String *SwigType_lcaststr(SwigType *ty, const String_or_char + *id = 0)

      +
      Generates a casting operation that converts from + type ty to its lvalue. id is an optional name to + include in the cast. For example, if ty is " +q(const).p.char" and id is "foo", this function + produces the string "(char *) foo".
      +

      String *SwigType_rcaststr(SwigType *ty, const String_or_char + *id = 0)

      +
      Generates a casting operation that converts from a + type's lvalue to a type equivalent to ty. id is an + optional name to include in the cast. For example, if ty is " +q(const).p.char" and id is "foo", this function + produces the string "(const char *) foo".
      +

      String *SwigType_manglestr(SwigType *ty)

      +
      Generates a mangled string encoding of type ty +. The mangled string only contains characters that are part of a valid C + identifier. The resulting string is used in various parts of SWIG, but + is most commonly associated with type-descriptor objects that appear in + wrappers (e.g., SWIGTYPE_p_double).
      +

      35.9 Parameters

      +

      Several type-related functions involve parameter lists. These + include functions and templates. Parameter list are represented as a + list of nodes with the following attributes:

      +
      +
      +"type"        -  Parameter type  (required)
+"name"        -  Parameter name  (optional)
+"value"       -  Initializer     (optional)
+
      +
      +

      Typically parameters are denoted in the source by using a typename + of Parm * or ParmList *. To walk a parameter list, + simply use code like this:

      +
      +
      +Parm *parms;
+Parm *p;
+for (p = parms; p; p = nextSibling(p)) {
+    SwigType *type  = Getattr(p,"type");
+    String   *name  = Getattr(p,"name");
+    String   *value = Getattr(p,"value");
+    ...
+}
+
      +
      +

      Note: this code is exactly the same as what you would use to walk + parse tree nodes.

      +

      An empty list of parameters is denoted by a NULL pointer.

      +

      Since parameter lists are fairly common, the following utility + functions are provided to manipulate them:

      +

      Parm *CopyParm(Parm *p);

      +
      Copies a single parameter.
      +

      ParmList *CopyParmList(ParmList *p);

      +
      Copies an entire list of parameters.
      +

      int ParmList_len(ParmList *p);

      +
      Returns the number of parameters in a parameter + list.
      +

      String *ParmList_str(ParmList *p);

      +
      Converts a parameter list into a C string. For + example, produces a string like "(int *p, int n, double x);".
      +

      String *ParmList_protostr(ParmList *p);

      +
      The same as ParmList_str() except that + parameter names are not included. Used to emit prototypes.
      +

      int ParmList_numrequired(ParmList *p);

      +
      Returns the number of required (non-optional) + arguments in p.
      +

      35.10 Writing a Language Module

      +

      One of the easiest routes to supporting a new language module is to + copy an already supported language module implementation and modify it. + Be sure to choose a language that is similar in nature to the new + language. All language modules follow a similar structure and this + section briefly outlines the steps needed to create a bare-bones + language module from scratch. Since the code is relatively easy to + read, this section describes the creation of a minimal Python module. + You should be able to extrapolate this to other languages.

      +

      35.10.1 Execution model

      +

      Code generation modules are defined by inheriting from the +Language class, currently defined in the Source/Modules + directory of SWIG. Starting from the parsing of command line options, + all aspects of code generation are controlled by different methods of + the Language that must be defined by your module.

      +

      35.10.2 Starting out

      +

      To define a new language module, first create a minimal + implementation using this example as a guide:

      +
      +
      +#include "swigmod.h"
+
+class PYTHON : public Language {
+public:
+
+  virtual void main(int argc, char *argv[]) {
+    printf("I'm the Python module.\n");
+  }
+
+  virtual int top(Node *n) {
+    printf("Generating code.\n");
+    return SWIG_OK;
+  }
+
+};
+
+extern "C" Language *
+swig_python(void) {
+  return new PYTHON();
+}
+
      +
      +

      The "swigmod.h" header file contains, among other things, the + declaration of the Language base class and so you should + include it at the top of your language module's source file. Similarly, + the "swigconfig.h" header file contains some other useful definitions + that you may need. Note that you should not include any header + files that are installed with the target language. That is to say, the + implementation of the SWIG Python module shouldn't have any + dependencies on the Python header files. The wrapper code generated by + SWIG will almost always depend on some language-specific C/C++ header + files, but SWIG itself does not.

      +

      Give your language class a reasonable name, usually the same as the + target language. By convention, these class names are all uppercase + (e.g. "PYTHON" for the Python language module) but this is not a + requirement. This class will ultimately consist of a number of + overrides of the virtual functions declared in the Language + base class, in addition to any language-specific member functions and + data you need. For now, just use the dummy implementations shown above.

      +

      The language module ends with a factory function, swig_python() +, that simply returns a new instance of the language class. As shown, it + should be declared with the extern "C" storage qualifier so + that it can be called from C code. It should also return a pointer to + the base class (Language) so that only the interface (and not + the implementation) of your language module is exposed to the rest of + SWIG.

      +

      Save the code for your language module in a file named " +python.cxx" and. place this file in the Source/Modules + directory of the SWIG distribution. To ensure that your module is + compiled into SWIG along with the other language modules, modify the + file Source/Modules/Makefile.am to include the additional + source files. In addition, modify the file +Source/Modules/swigmain.cxx with an additional command line option + that activates the module. Read the source---it's straightforward.

      +

      Next, at the top level of the SWIG distribution, re-run the +autogen.sh script to regenerate the various build files:

      +
      +
      +$ ./autogen.sh
+
      +
      +

      Next re-run configure to regenerate all of the Makefiles:

      +
      +
      +$ ./configure
+
      +
      +

      Finally, rebuild SWIG with your module added:

      +
      +
      +$ make
+
      +
      +

      Once it finishes compiling, try running SWIG with the command-line + option that activates your module. For example, swig -python foo.i +. The messages from your new module should appear.

      +

      35.10.3 Command line options

      +

      When SWIG starts, the command line options are passed to your + language module. This occurs before any other processing occurs + (preprocessing, parsing, etc.). To capture the command line options, + simply use code similar to this:

      +
      +
      +void Language::main(int argc, char *argv[]) {
+  for (int i = 1; i < argc; i++) {
+      if (argv[i]) {
+          if(strcmp(argv[i],"-interface") == 0) {
+            if (argv[i+1]) {
+              interface = NewString(argv[i+1]);
+              Swig_mark_arg(i);
+              Swig_mark_arg(i+1);
+              i++;
+            } else {
+              Swig_arg_error();
+            }
+	  } else if (strcmp(argv[i],"-globals") == 0) {
+	    if (argv[i+1]) {
+	      global_name = NewString(argv[i+1]);
+	      Swig_mark_arg(i);
+	      Swig_mark_arg(i+1);
+	      i++;
+	    } else {
+	      Swig_arg_error();
+	    }
+	  } else if ( (strcmp(argv[i],"-proxy") == 0)) {
+	    proxy_flag = 1;
+	    Swig_mark_arg(i);
+	  } else if (strcmp(argv[i],"-keyword") == 0) {
+	    use_kw = 1;
+	    Swig_mark_arg(i);
+	  } else if (strcmp(argv[i],"-help") == 0) {
+	    fputs(usage,stderr);
+	  }
+          ...
+      }
+  }
+}
+
      +
      +

      The exact set of options depends on what you want to do in your + module. Generally, you would use the options to change code generation + modes or to print diagnostic information.

      +

      If a module recognizes an option, it should always call +Swig_mark_arg() to mark the option as valid. If you forget to do + this, SWIG will terminate with an unrecognized command line option + error.

      +

      35.10.4 Configuration and preprocessing

      +

      In addition to looking at command line options, the main() + method is responsible for some initial configuration of the SWIG + library and preprocessor. To do this, insert some code like this:

      +
      +
      +void main(int argc, char *argv[]) {
+   ... command line options ...
+
+   /* Set language-specific subdirectory in SWIG library */
+   SWIG_library_directory("python");
+
+   /* Set language-specific preprocessing symbol */
+   Preprocessor_define("SWIGPYTHON 1", 0);
+
+   /* Set language-specific configuration file */
+   SWIG_config_file("python.swg");
+
+   /* Set typemap language (historical) */
+   SWIG_typemap_lang("python");
+}
+
      +
      +

      The above code does several things--it registers the name of the + language module with the core, it supplies some preprocessor macro + definitions for use in input files (so that they can determine the + target language), and it registers a start-up file. In this case, the + file python.swg will be parsed before any part of the + user-supplied input file.

      +

      Before proceeding any further, create a directory for your module in + the SWIG library (The Lib directory). Now, create a + configuration file in the directory. For example, python.swg.

      +

      Just to review, your language module should now consist of two + files-- an implementation file python.cxx and a configuration + file python.swg.

      +

      35.10.5 Entry point to code generation

      +

      SWIG is a multi-pass compiler. Once the main() method has + been invoked, the language module does not execute again until + preprocessing, parsing, and a variety of semantic analysis passes have + been performed. When the core is ready to start generating wrappers, it + invokes the top() method of your language class. The argument + to top is a single parse tree node that corresponds to the top + of the entire parse tree.

      +

      To get the code generation process started, the top() + procedure needs to do several things:

      +
        +
      • Initialize the wrapper code output.
        • +
      • Set the module name.
        • +
      • Emit common initialization code.
        • +
      • Emit code for all of the child nodes.
        • +
      • Finalize the wrapper module and cleanup.
        • +
      +

      An outline of top() might be as follows:

      +
      +
      +int Python::top(Node *n) {
+
+   /* Get the module name */
+   String *module = Getattr(n,"name");
+
+   /* Get the output file name */
+   String *outfile = Getattr(n,"outfile");
+
+   /* Initialize I/O (see next section) */
+   ...
+
+   /* Output module initialization code */
+   ...
+
+   /* Emit code for children */
+   Language::top(n);
+
+   ...
+   /* Cleanup files */
+   ...
+
+   return SWIG_OK;
+}
+
      +
      +

      35.10.6 Module I/O and wrapper skeleton

      + + +

      Within SWIG wrappers, there are four main sections. These are (in + order)

      +
        +
      • runtime: This section has most of the common SWIG runtime code
        • +
      • header: This section holds declarations and inclusions from the .i + file
        • +
      • wrapper: This section holds all the wrappering code
        • +
      • init: This section holds the module initalisation function (the + entry point for the interpreter)
        • +
      +

      Different parts of the SWIG code will fill different sections, then + upon completion of the wrappering all the sections will be saved to the + wrapper file.

      +

      To perform this will require several additions to the code in + various places, such as:

      +
      +
      +class PYTHON : public Language {
+protected:
+   /* General DOH objects used for holding the strings */
+   File *f_begin;
+   File *f_runtime;
+   File *f_header;
+   File *f_wrappers;
+   File *f_init;
+
+public:
+   ...
+
+};
+
+int Python::top(Node *n) {
+
+   ...
+
+   /* Initialize I/O */
+   f_begin = NewFile(outfile, "w", SWIG_output_files());
+   if (!f_begin) {
+      FileErrorDisplay(outfile);
+      SWIG_exit(EXIT_FAILURE);
+   }
+   f_runtime = NewString("");
+   f_init = NewString("");
+   f_header = NewString("");
+   f_wrappers = NewString("");
+
+   /* Register file targets with the SWIG file handler */
+   Swig_register_filebyname("begin", f_begin);
+   Swig_register_filebyname("header", f_header);
+   Swig_register_filebyname("wrapper", f_wrappers);
+   Swig_register_filebyname("runtime", f_runtime);
+   Swig_register_filebyname("init", f_init);
+
+   /* Output module initialization code */
+   Swig_banner(f_begin);
+   ...
+
+   /* Emit code for children */
+   Language::top(n);
+
+   ...
+   /* Write all to the file */
+   Dump(f_runtime, f_begin);
+   Dump(f_header, f_begin);
+   Dump(f_wrappers, f_begin);
+   Wrapper_pretty_print(f_init, f_begin);
+
+   /* Cleanup files */
+   Delete(f_runtime);
+   Delete(f_header);
+   Delete(f_wrappers);
+   Delete(f_init);
+   Close(f_begin);
+   Delete(f_begin);
+
+   return SWIG_OK;
+}
+
      +
      +

      Using this to process a file will generate a wrapper file, however + the wrapper will only consist of the common SWIG code as well as any + inline code which was written in the .i file. It does not contain any + wrappers for any of the functions or classes.

      +

      The code to generate the wrappers are the various member functions, + which currently have not been touched. We will look at +functionWrapper() as this is the most commonly used function. In + fact many of the other wrapper routines will call this to do their + work.

      +

      A simple modification to write some basic details to the wrapper + looks like this:

      +
      +
      +int Python::functionWrapper(Node *n) {
+  /* Get some useful attributes of this function */
+  String   *name   = Getattr(n,"sym:name");
+  SwigType *type   = Getattr(n,"type");
+  ParmList *parms  = Getattr(n,"parms");
+  String   *parmstr= ParmList_str_defaultargs(parms); // to string
+  String   *func   = SwigType_str(type, NewStringf("%s(%s)", name, parmstr));
+  String   *action = Getattr(n,"wrap:action");
+
+  Printf(f_wrappers,"functionWrapper   : %s\n", func);
+  Printf(f_wrappers,"           action : %s\n", action);
+  return SWIG_OK;
+}
+
      +
      +

      This will now produce some useful information within your wrapper + file.

      +
      +
      +functionWrapper   : void delete_Shape(Shape *self)
+           action : delete arg1;
+
+functionWrapper   : void Shape_x_set(Shape *self,double x)
+           action : if (arg1) (arg1)->x = arg2;
+
+functionWrapper   : double Shape_x_get(Shape *self)
+           action : result = (double) ((arg1)->x);
+
+functionWrapper   : void Shape_y_set(Shape *self,double y)
+           action : if (arg1) (arg1)->y = arg2;
+...
+
      +
      +

      35.10.7 Low-level code generators

      + + +

      As ingenious as SWIG is, and despite all its capabilities and the + power of its parser, the Low-level code generation takes a lot of work + to write properly. Mainly because every language insists on its own + manner of interfacing to C/C++. To write the code generators you will + need a good understanding of how to manually write an interface to your + chosen language, so make sure you have your documentation handy.

      +

      At this point it is also probably a good idea to take a very simple + file (just one function), and try letting SWIG generate wrappers for + many different languages. Take a look at all of the wrappers generated, + and decide which one looks closest to the language you are trying to + wrap. This may help you to decide which code to look at.

      +

      In general most language wrappers look a little like this:

      +
      +
      +/* wrapper for TYPE3 some_function(TYPE1,TYPE2); */
+RETURN_TYPE _wrap_some_function(ARGS){
+  TYPE1 arg1;
+  TYPE2 arg2;
+  TYPE3 result;
+
+  if(ARG1 is not of TYPE1) goto fail;
+  arg1=(convert ARG1);
+  if(ARG2 is not of TYPE2) goto fail;
+  arg2=(convert ARG2);
+
+  result=some_function(arg1,arg2);
+
+  convert 'result' to whatever the language wants;
+
+  do any tidy up;
+
+  return ALL_OK;
+
+  fail:
+  do any tidy up;
+  return ERROR;
+}
+
      +
      +

      Yes, it is rather vague and not very clear. But each language works + differently so this will have to do for now.

      +

      Tackling this problem will be done in two stages:

      +
        +
      • The skeleton: the function wrapper, and call, but without the + conversion
        • +
      • The conversion: converting the arguments to-from what the language + wants
        • +
      +

      The first step will be done in the code, the second will be done in + typemaps.

      +

      Our first step will be to write the code for functionWrapper() +. What is shown below is NOT the solution, merely a step in the + right direction. There are a lot of issues to address.

      +
        +
      • Variable length and default parameters
        • +
      • Typechecking and number of argument checks
        • +
      • Overloaded functions
        • +
      • Inout and Output only arguments
        • +
      +
      +
      +virtual int functionWrapper(Node *n) {
+  /* get useful atributes */
+  String   *name   = Getattr(n,"sym:name");
+  SwigType *type   = Getattr(n,"type");
+  ParmList *parms  = Getattr(n,"parms");
+  ...
+
+  /* create the wrapper object */
+  Wrapper *wrapper = NewWrapper();
+
+  /* create the functions wrappered name */
+  String *wname = Swig_name_wrapper(iname);
+
+  /* deal with overloading */
+  ....
+
+  /* write the wrapper function definition */
+  Printv(wrapper->def,"RETURN_TYPE ", wname, "(ARGS) {",NIL);
+
+  /* if any additional local variable needed, add them now */
+  ...
+
+  /* write the list of locals/arguments required */
+  emit_args(type, parms, wrapper);
+
+  /* check arguments */
+  ...
+
+  /* write typemaps(in) */
+  ....
+
+  /* write constriants */
+  ....
+
+  /* Emit the function call */
+  emit_action(n,wrapper);
+
+  /* return value if necessary  */
+  ....
+
+  /* write typemaps(out) */
+  ....
+
+  /* add cleanup code */
+  ....
+
+  /* Close the function(ok) */
+  Printv(wrapper->code, "return ALL_OK;\n", NIL);
+
+  /* add the failure cleanup code */
+  ...
+
+  /* Close the function(error) */
+  Printv(wrapper->code, "return ERROR;\n", "}\n", NIL);
+
+  /* final substititions if applicable */
+  ...
+
+  /* Dump the function out */
+  Wrapper_print(wrapper,f_wrappers);
+
+  /* tidy up */
+  Delete(wname);
+  DelWrapper(wrapper);
+
+  return SWIG_OK;
+}
+
      +
      +

      Executing this code will produce wrappers which have our basic + skeleton but without the typemaps, there is still work to do.

      +

      35.10.8 Configuration files

      + + +

      At the time of this writing, SWIG supports nearly a dozen languages, + which means that for continued sanity in maintaining the configuration + files, the language modules need to follow some conventions. These are + outlined here along with the admission that, yes it is ok to violate + these conventions in minor ways, as long as you know where to apply the + proper kludge to keep the overall system regular and running. + Engineering is the art of compromise, see...

      +

      Much of the maintenance regularity depends on choosing a suitable + nickname for your language module (and then using it in a controlled + way). Nicknames should be all lower case letters with an optional + numeric suffix (no underscores, no dashes, no spaces). Some examples + are: foo, bar, qux99.

      +

      The numeric suffix variant, as in the last example, is somewhat + tricky to work with because sometimes people expect to refer to the + language without this number but sometimes that number is extremely + relevant (especially when it corresponds to language implementation + versions with incompatible interfaces). New language modules that + unavoidably require a numeric suffix in their nickname should include + that number in all uses, or be prepared to kludge.

      +

      The nickname is used in four places:

      + + + + + + + + +
      usagetransform
      "skip" tag(none)
      Examples/ subdir name(none)
      Examples/GIFPlot/ subdir namecapitalize (upcase first + letter)
      Examples/test-suite/ subdir name(none)
      +

      As you can see, most usages are direct.

      +
      +
      configure.in
      +
      This file is processed by +

      autoconf to + generate the configure script. This is where you need to add + shell script fragments and autoconf macros to detect the presence of + whatever development support your language module requires, typically + directories where headers and libraries can be found, and/or utility + programs useful for integrating the generated wrapper code.

      +

      Use the AC_ARG_WITH, AC_MSG_CHECKING, AC_SUBST + macros and so forth (see other languages for examples). Avoid using the + [ and ] character in shell script fragments. The + variable names passed to AC_SUBST should begin with the + nickname, entirely upcased.

      +

      At the end of the new section is the place to put the aforementioned + nickname kludges (should they be needed). See Perl5 for examples of + what to do. [If this is still unclear after you've read the code, ping + me and I'll expand on this further. --ttn]

      +
      +
      Makefile.in
      +
      +

      Some of the variables AC_SUBSTituted are essential to the support of + your language module. Fashion these into a shell script "test" clause + and assign that to a skip tag using "-z" and "-o":

      +
      skip-qux99 = [ -z "@QUX99INCLUDE@" -o -z + "@QUX99LIBS" ]
      +

      This means if those vars should ever be empty, qux99 support should + be considered absent and so it would be a good idea to skip actions + that might rely on it.

      +

      Here is where you may also define an alias (but then you'll need to + kludge --- don't do this):

      +
      skip-qux = $(skip-qux99)
      +

      Lastly, you need to modify each of check-aliveness, +check-examples, check-test-suite, check-gifplot + (all targets) and lib-languages (var). Use the nickname for + these, not the alias. Note that you can do this even before you have + any tests or examples set up; the Makefile rules do some sanity + checking and skip around these kinds of problems.

      +
      +
      Examples/Makefile.in
      +
      Nothing special here; see comments at top the of this file and look + to the existing languages for examples.
      +
      Examples/qux99/check.list
      +
      Do cp ../python/check.list . and modify to taste. One + subdir per line.
      +
      Examples/GIFPlot/Qux99/check.list
      +
      Do cp ../Python/check.list . and modify to taste. One + subdir per line.
      +
      Lib/qux99/extra-install.list
      +
      If you add your language to the top-level Makefile.in var +lib-languages, then make install will install all *.i + and *.swg files from the language-specific subdirectory of +Lib. Use (optional) file extra-install.list in that + directory to name additional files to install (see ruby for example).
      +
      Source/Modules/Makefile.am
      +
      Add appropriate files to this Automake file. That's it! +

      When you have modified these files, please make sure that the new + language module is completely ignored if it is not installed and + detected on a box, that is, make check-examples and make + check-test-suite politely displays the ignoring language message.

      +
      +
      +

      35.10.9 Runtime support

      +

      Discuss the kinds of functions typically needed for SWIG runtime + support (e.g. SWIG_ConvertPtr() and SWIG_NewPointerObj() +) and the names of the SWIG files that implement those functions.

      +

      35.10.10 Standard library files

      +

      The standard library files that most languages supply keeps growing + as SWIG matures. The following are the minimum that are usually + supported:

      +
        +
      • typemaps.i
        • +
      • std_string.i
        • +
      • std_vector.i
        • +
      • stl.i
        • +
      +

      Please copy these and modify for any new language.

      +

      35.10.11 Examples and test cases

      +

      Each of the language modules provides one or more examples. These + examples are used to demonstrate different features of the language + module to SWIG end-users, but you'll find that they're useful during + development and testing of your language module as well. You can use + examples from the existing SWIG language modules for inspiration.

      +

      Each example is self-contained and consists of (at least) a +Makefile, a SWIG interface file for the example module, and a + 'runme' script that demonstrates the functionality for that module. All + of these files are stored in the same subdirectory under the +Examples/[lang] directory. There are two classic examples which + should be the first to convert to a new language module. These are the + "simple" C example and the "class" C++ example. These can be found, for + example for Python, in Examples/python/simple and +Examples/python/class.

      +

      By default, all of the examples are built and run when the user + types make check. To ensure that your examples are + automatically run during this process, see the section on +configuration files.

      +

      35.10.12 Documentation

      +

      Don't forget to write end-user documentation for your language + module. Currently, each language module has a dedicated chapter You + shouldn't rehash things that are already covered in sufficient detail + in the SWIG Basics and SWIG and + C++ chapters. There is no fixed format for what, exactly, + you should document about your language module, but you'll obviously + want to cover issues that are unique to your language.

      +

      Some topics that you'll want to be sure to address include:

      +
        +
      • Command line options unique to your language module.
        • +
      • Non-obvious mappings between C/C++ and target language concepts. + For example, if your target language provides a single floating point + type, it should be no big surprise to find that C/C++ float + and double types are mapped to it. On the other hand, if your + target language doesn't provide support for "classes" or something + similar, you'd want to discuss how C++ classes are handled.
        • +
      • How to compile the SWIG-generated wrapper code into shared + libraries that can actually be used. For some languages, there are + well-defined procedures for doing this, but for others it's an ad hoc + process. Provide as much detail as appropriate, and links to other + resources if available.
        • +
      +

      35.10.13 Prerequisites for + adding a new language module to the SWIG distribution

      +

      If you wish for a new language module to be distributed with SWIG, + which we encourage for all popular languages, there are a few + requirements. While we appreciate that getting all aspects of a new + language working won't happen at the outset, there are a set of minimum + requirements before a module can be committed into the SVN repository + for distribution with future versions of SWIG. The following are really + a summary of this whole section with details being outlined earlier on.

      +
        +
      1. Demonstrate basic C code working by porting the "simple" example + including a runtime test, see for example Examples/python/simple +.
        2. +
      2. Demonstrate basic C++ code working by porting the "class" example + including a runtime test, see for example Examples/python/class +.
        3. +
      3. Modify configure.in, Makefile.in and +Examples/Makefile.in to run these examples. Please make sure that + if the new language is not installed properly on a box, make -k + check should still work by skipping the tests and examples for the + new language module.
        4. +
      4. Get the test-suite running for the new language (make + check-[lang]-test-suite). While the test-suite tests many corner + cases, we'd expect the majority of it to work by compiling the + generated code correctly as most of the corner cases are covered in the + SWIG core. Get at least one C and one C++ runtime test running in the + test-suite.
        5. +
      5. Provide a chapter in the html documentation on the basics of using + the language module.
        6. +
      6. Ensure your source code is formatted according to the +coding style guidelines.
        7. +
      7. Finally, email the SWIG developers with a patch and a demonstration + of commitment to maintaining the language module, certainly in the + short term and ideally long term.
        8. +
      +

      Once accepted into SVN, development efforts should concentrate on + getting the entire test-suite to work with plenty of runtime tests. + Runtime tests should be for existing testcases and new test cases + should be added should there be an area not already covered by the + existing tests.

      +

      35.10.14 Coding + style guidelines

      +

      The coding guidelines for the C/C++ source code are pretty much K&R + C style. The style can be inferred from the existing code base and is + largely dictated by the indent code beautifier tool set to K&R + style. The code can formatted using the make targets in the Source + directory. Below is an example of how to format the emit.cxx file:

      +
      +
      +$ cd Source
+$ make beautify-file INDENTFILE=Modules/emit.cxx
+
      +
      +

      Of particular note is indentation is set to 2 spaces and a tab is + used instead of 8 spaces. The generated C/C++ code should also follow + this style as close as possible. However, tabs should be avoided as + unlike the SWIG developers, users will never have consistent tab + settings.

      +

      35.11 Typemaps

      +

      35.11.1 Proxy classes

      +

      35.12 Guide to parse tree nodes

      +

      This section describes the different parse tree nodes and their + attributes.

      +

      cdecl

      +

      Describes general C declarations including variables, functions, and + typedefs. A declaration is parsed as "storage T D" where storage is a + storage class, T is a base type, and D is a declarator.

      +
      +
      +"name"          - Declarator name
+"type"          - Base type T
+"decl"          - Declarator type (abstract)
+"storage"       - Storage class (static, extern, typedef, etc.)
+"parms"         - Function parameters (if a function)
+"code"          - Function body code (if supplied)
+"value"         - Default value (if supplied)
+
      +
      +

      constructor

      +

      C++ constructor declaration.

      +
      +
      +"name"          - Name of constructor
+"parms"         - Parameters
+"decl"          - Declarator (function with parameters)
+"code"          - Function body code (if any)
+"feature:new"   - Set to indicate return of new object.
+
      +
      +

      destructor

      +

      C++ destructor declaration.

      +
      +
      +"name"          - Name of destructor
+"code"          - Function body code (if any)
+"storage"       - Storage class (set if virtual)
+"value"         - Default value (set if pure virtual).
+
      +
      +

      access

      +

      C++ access change.

      +
      +
      +"kind"          - public, protected, private
+
      +
      +

      constant

      +

      Constant created by %constant or #define.

      +
      +
      +"name"          - Name of constant.
+"type"          - Base type.
+"value"         - Value.
+"storage"       - Set to %constant
+"feature:immutable" - Set to indicate read-only
+
      +
      +

      class

      +

      C++ class definition or C structure definition.

      +
      +
      +"name"          - Name of the class.
+"kind"          - Class kind ("struct", "union", "class")
+"symtab"        - Enclosing symbol table.
+"tdname"        - Typedef name. Use for typedef struct { ... } A.
+"abstract"      - Set if class has pure virtual methods.
+"baselist"      - List of base class names.
+"storage"       - Storage class (if any)
+"unnamed"       - Set if class is unnamed.
+
      +
      +

      enum

      +

      Enumeration.

      +
      +
      +"name"          - Name of the enum (if supplied).
+"storage"       - Storage class (if any)
+"tdname"        - Typedef name (typedef enum { ... } name).
+"unnamed"       - Set if enum is unnamed.
+
      +
      +

      enumitem

      +

      Enumeration value.

      +
      +
      +"name"          - Name of the enum value.
+"type"          - Type (integer or char)
+"value"         - Enum value (if given)
+"feature:immutable" - Set to indicate read-only
+
      +
      +

      namespace

      +

      C++ namespace.

      +
      +
      +"name"          - Name of the namespace.
+"symtab"        - Symbol table for enclosed scope.
+"unnamed"       - Set if unnamed namespace
+"alias"         - Alias name. Set for namespace A = B;
+
      +
      +

      using

      +

      C++ using directive.

      +
      +
      +"name"          - Name of the object being referred to.
+"uname"         - Qualified name actually given to using.
+"node"          - Node being referenced.
+"namespace"     - Namespace name being reference (using namespace name)
+
      +
      +

      classforward

      +

      A forward C++ class declaration.

      +
      +
      +"name"          - Name of the class.
+"kind"          - Class kind ("union", "struct", "class")
+
      +
      +

      insert

      +

      Code insertion directive. For example, %{ ... %} or + %insert(section).

      +
      +
      +"code"          - Inserted code
+"section"       - Section name ("header", "wrapper", etc.)
+
      +
      +

      top

      +

      Top of the parse tree.

      +
      +
      +"module"        - Module name
+
      +
      +

      extend

      +

      %extend directive.

      +
      +
      +"name"          - Module name
+"symtab"        - Symbol table of enclosed scope.
+
      +
      +

      apply

      +

      %apply pattern { patternlist }.

      +
      +
      +"pattern"       - Source pattern.
+"symtab"        - Symbol table of enclosed scope.
+
      +
      +

      clear

      +

      %clear patternlist;

      +
      +
      +"firstChild"    - Patterns to clear
+
      +
      +

      include

      +

      %include directive.

      +
      +
      +"name"         - Filename
+"firstChild"   - Children
+
      +
      +

      import

      +

      %import directive.

      +
      +
      +"name"         - Filename
+"firstChild"   - Children
+
      +
      +

      module

      +

      %module directive.

      +
      +
      +"name"         - Name of the module
+
      +
      +

      typemap

      +

      %typemap directive.

      +
      +
      +"method"       - Typemap method name.
+"code"         - Typemap code.
+"kwargs"       - Keyword arguments (if any)
+"firstChild"   - Typemap patterns
+
      +
      +

      typemapcopy

      +

      %typemap directive with copy.

      +
      +
      +"method"       - Typemap method name.
+"pattern"      - Typemap source pattern.
+"firstChild"   - Typemap patterns
+
      +
      +

      typemapitem

      +

      %typemap pattern. Used with %apply, %clear, %typemap.

      +
      +
      +"pattern"      - Typemap pattern (a parameter list)
+"parms"        - Typemap parameters.
+
      +
      +

      types

      +

      %types directive.

      +
      +
      +"parms"        - List of parameter types.
+"convcode"     - Code which replaces the default casting / conversion code
+
      +
      +

      extern

      +

      extern "X" { ... } declaration.

      +
      +
      +"name"       - Name "C", "Fortran", etc.
+
      +
      + \ No newline at end of file diff --git a/Doc/Manual/SWIGDocumentation.pdf b/Doc/Manual/SWIGDocumentation.pdf new file mode 100644 index 0000000..37c65d8 Binary files /dev/null and b/Doc/Manual/SWIGDocumentation.pdf differ diff --git a/Doc/Manual/SWIGPlus.html b/Doc/Manual/SWIGPlus.html new file mode 100644 index 0000000..ef7487f --- /dev/null +++ b/Doc/Manual/SWIGPlus.html @@ -0,0 +1,4843 @@ + + + +SWIG and C++ + + + + +

      6 SWIG and C++

      + +
      + +
      + + + + +

      +This chapter describes SWIG's support for wrapping C++. As a prerequisite, +you should first read the chapter SWIG Basics to see +how SWIG wraps ANSI C. Support for C++ builds upon ANSI C +wrapping and that material will be useful in understanding this chapter. +

      + +

      6.1 Comments on C++ Wrapping

      + + +

      +Because of its complexity and the fact that C++ can be +difficult to integrate with itself let alone other languages, SWIG +only provides support for a subset of C++ features. Fortunately, +this is now a rather large subset. +

      + +

      +In part, the problem with C++ wrapping is that there is no +semantically obvious (or automatic ) way to map many of its advanced +features into other languages. As a simple example, consider the +problem of wrapping C++ multiple inheritance to a target language with +no such support. Similarly, the use of overloaded operators and +overloaded functions can be problematic when no such capability exists +in a target language. +

      + +

      +A more subtle issue with C++ has to do with the way that some C++ +programmers think about programming libraries. In the world of SWIG, +you are really trying to create binary-level software components for +use in other languages. In order for this to work, a "component" has +to contain real executable instructions and there has to be some kind +of binary linking mechanism for accessing its functionality. In +contrast, C++ has increasingly relied upon generic programming and +templates for much of its functionality. +Although templates are a powerful feature, they are largely orthogonal +to the whole notion of binary components and libraries. For example, +an STL vector does not define any kind of binary object for +which SWIG can just create a wrapper. To further complicate matters, +these libraries often utilize a lot of behind the scenes magic in +which the semantics of seemingly basic operations (e.g., pointer +dereferencing, procedure call, etc.) can be changed in dramatic and +sometimes non-obvious ways. Although this "magic" may present few +problems in a C++-only universe, it greatly complicates the problem of +crossing language boundaries and provides many opportunities to shoot +yourself in the foot. You will just have to be careful. +

      + +

      6.2 Approach

      + + +

      +To wrap C++, SWIG uses a layered approach to code generation. +At the lowest level, SWIG generates a collection of procedural ANSI-C style +wrappers. These wrappers take care of basic type conversion, +type checking, error handling, and other low-level details of the C++ binding. +These wrappers are also sufficient to bind C++ into any target language +that supports built-in procedures. In some sense, you might view this +layer of wrapping as providing a C library interface to C++. +On top of the low-level procedural (flattened) interface, SWIG generates proxy classes +that provide a natural object-oriented (OO) interface to the underlying code. The proxy classes are typically +written in the target language itself. For instance, in Python, a real +Python class is used to provide a wrapper around the underlying C++ object. +

      + +

      +It is important to emphasize that SWIG takes a deliberately +conservative and non-intrusive approach to C++ wrapping. SWIG does not +encapsulate C++ classes inside a special C++ adaptor, it does not rely +upon templates, nor does it add in additional C++ inheritance when +generating wrappers. The last thing that most C++ programs need is +even more compiler magic. Therefore, SWIG tries to maintain a very +strict and clean separation between the implementation of your C++ +application and the resulting wrapper code. You might say that SWIG +has been written to follow the principle of least surprise--it does +not play sneaky tricks with the C++ type system, it doesn't mess with +your class hierarchies, and it doesn't introduce new semantics. +Although this approach might not provide the most seamless integration +with C++, it is safe, simple, portable, and debuggable. +

      + +

      +Some of this chapter focuses on the low-level procedural interface to +C++ that is used as the foundation for all language modules. Keep in +mind that the target languages also provide the high-level OO interface via +proxy classes. More detailed coverage can be found in the documentation +for each target language. +

      + +

      6.3 Supported C++ features

      + + +

      +SWIG currently supports most C++ features including the following:

      + +
        +
      • Classes +
      • Constructors and destructors +
      • Virtual functions +
      • Public inheritance (including multiple inheritance) +
      • Static functions +
      • Function and method overloading +
      • Operator overloading for many standard operators +
      • References +
      • Templates (including specialization and member templates) +
      • Pointers to members +
      • Namespaces +
      • Default parameters +
      • Smart pointers +
      + +

      +The following C++ features are not currently supported:

      + +
        +
      • Overloaded versions of certain operators (new, delete, etc.) +
      • Nested classes, see Nested classes for workarounds. +
      + +

      +As a rule of thumb, SWIG should not be used on raw C++ source files, use header files only. +

      + +

      +SWIG's C++ support is an ongoing project so some of these limitations may be lifted +in future releases. However, we make no promises. Also, submitting a bug report is a very +good way to get problems fixed (wink). +

      + +

      6.4 Command line options and compilation

      + + +

      +When wrapping C++ code, it is critical that SWIG be called with the +`-c++' option. This changes the way a number of critical +features such as memory management are handled. It +also enables the recognition of C++ keywords. Without the -c++ +flag, SWIG will either issue a warning or a large number of syntax +errors if it encounters C++ code in an interface file.

      + +

      +When compiling and linking the resulting wrapper file, it is normal +to use the C++ compiler. For example: +

      + +
      +
      +$ swig -c++ -tcl example.i
+$ c++ -c example_wrap.cxx 
+$ c++ example_wrap.o $(OBJS) -o example.so
+
      +
      + +

      +Unfortunately, the process varies slightly on each platform. Make sure +you refer to the documentation on each target language for further +details. The SWIG Wiki also has further details. +

      + +Compatibility Note: Early versions of SWIG generated just a flattened low-level C style API to C++ classes by default. +The -noproxy commandline option is recognised by many target languages and will generate just this +interface as in earlier versions. + +

      6.5 Proxy classes

      + + +

      +In order to provide a natural mapping from C++ classes to the target language classes, SWIG's target +languages mostly wrap C++ classes with special proxy classes. These +proxy classes are typically implemented in the target language itself. +For example, if you're building a Python module, each C++ class is +wrapped by a Python proxy class. Or if you're building a Java module, each +C++ class is wrapped by a Java proxy class. +

      + +

      6.5.1 Construction of proxy classes

      + + +

      +Proxy classes are always constructed as an extra layer of wrapping that uses low-level +accessor functions. To illustrate, suppose you had a +C++ class like this: +

      + +
      +
      +class Foo {
+public:
+      Foo();
+     ~Foo();
+      int  bar(int x);
+      int  x;
+};
+
      +
      + +

      +Using C++ as pseudocode, a proxy class looks something like this: +

      + +
      +
      +class FooProxy {
+private:
+      Foo    *self;
+public:
+      FooProxy() {
+            self = new_Foo();
+      }
+     ~FooProxy() {
+            delete_Foo(self);
+      }
+      int bar(int x) {
+            return Foo_bar(self,x);
+      }
+      int x_get() {
+            return Foo_x_get(self);
+      }
+      void x_set(int x) {
+            Foo_x_set(self,x);
+      }
+};
+
      +
      + +

      +Of course, always keep in mind that the real proxy class is written in the target language. +For example, in Python, the proxy might look roughly like this: +

      + +
      +
      +class Foo:
+    def __init__(self):
+         self.this = new_Foo()
+    def __del__(self):
+         delete_Foo(self.this)
+    def bar(self,x):
+         return Foo_bar(self.this,x)
+    def __getattr__(self,name):
+         if name == 'x':
+              return Foo_x_get(self.this)
+         ...
+    def __setattr__(self,name,value):
+         if name == 'x':
+              Foo_x_set(self.this,value)
+         ...
+
      +
      + +

      +Again, it's important to emphasize that the low-level accessor functions are always used by the +proxy classes. +Whenever possible, proxies try to take advantage of language features that are similar to C++. This +might include operator overloading, exception handling, and other features. +

      + +

      6.5.2 Resource management in proxies

      + + +

      +A major issue with proxies concerns the memory management of wrapped objects. Consider the following +C++ code: +

      + +
      +
      +class Foo {
+public:
+      Foo();
+     ~Foo();
+      int bar(int x);
+      int x;
+};
+
+class Spam {
+public:
+      Foo *value;
+      ...
+};
+
      +
      + +

      +Consider some script code that uses these classes: +

      + +
      +
      +f = Foo()               # Creates a new Foo
+s = Spam()              # Creates a new Spam
+s.value = f             # Stores a reference to f inside s
+g = s.value             # Returns stored reference
+g = 4                   # Reassign g to some other value
+del f                   # Destroy f 
+
      +
      + +

      +Now, ponder the resulting memory management issues. When objects are +created in the script, the objects are wrapped by newly created proxy +classes. That is, there is both a new proxy class instance and a new +instance of the underlying C++ class. In this example, both +f and s are created in this way. However, the +statement s.value is rather curious---when executed, a +pointer to f is stored inside another object. This means +that the scripting proxy class AND another C++ class share a +reference to the same object. To make matters even more interesting, +consider the statement g = s.value. When executed, this +creates a new proxy class g that provides a wrapper around the +C++ object stored in s.value. In general, there is no way to +know where this object came from---it could have been created by the +script, but it could also have been generated internally. In this +particular example, the assignment of g results in a second +proxy class for f. In other words, a reference to f +is now shared by two proxy classes and a C++ class. +

      + +

      +Finally, consider what happens when objects are destroyed. In the +statement, g=4, the variable g is reassigned. In +many languages, this makes the old value of g available for +garbage collection. Therefore, this causes one of the proxy classes +to be destroyed. Later on, the statement del f destroys the +other proxy class. Of course, there is still a reference to the +original object stored inside another C++ object. What happens to it? +Is the object still valid? +

      + +

      +To deal with memory management problems, proxy classes provide an API +for controlling ownership. In C++ pseudocode, ownership control might look +roughly like this: +

      + +
      +
      +class FooProxy {
+public:
+      Foo    *self;
+      int     thisown;
+
+      FooProxy() {
+            self = new_Foo();
+            thisown = 1;       // Newly created object
+      }
+     ~FooProxy() {
+            if (thisown) delete_Foo(self);
+      }
+      ...
+      // Ownership control API
+      void disown() {
+           thisown = 0;
+      }
+      void acquire() {
+           thisown = 1;
+      }
+};
+
+class FooPtrProxy: public FooProxy {
+public:
+      FooPtrProxy(Foo *s) {
+          self = s;
+          thisown = 0;
+      }
+};
+
+class SpamProxy {
+     ...
+     FooProxy *value_get() {
+          return FooPtrProxy(Spam_value_get(self));
+     }
+     void value_set(FooProxy *v) {
+          Spam_value_set(self,v->self);
+          v->disown();
+     }
+     ...
+};
+
      +
      + +

      +Looking at this code, there are a few central features: +

      + +
        +
      • Each proxy class keeps an extra flag to indicate ownership. C++ objects are only destroyed +if the ownership flag is set. +
        • + +
      • When new objects are created in the target language, the ownership flag is set. +
        • + +
      • When a reference to an internal C++ object is returned, it is wrapped by a proxy +class, but the proxy class does not have ownership. +
        • + +
      • In certain cases, ownership is adjusted. For instance, when a value is assigned to the member of +a class, ownership is lost. +
        • + +
      • Manual ownership control is provided by special disown() and acquire() methods. +
        • +
      + +

      +Given the tricky nature of C++ memory management, it is impossible for proxy classes to automatically handle +every possible memory management problem. However, proxies do provide a mechanism for manual control that +can be used (if necessary) to address some of the more tricky memory management problems. +

      + +

      6.5.3 Language specific details

      + + +

      +Language specific details on proxy classes are contained in the chapters describing each target language. This +chapter has merely introduced the topic in a very general way. +

      + +

      6.6 Simple C++ wrapping

      + + +

      +The following code shows a SWIG interface file for a simple C++ +class.

      + +
      +%module list
+%{
+#include "list.h"
+%}
+
+// Very simple C++ example for linked list
+
+class List {
+public:
+  List();
+  ~List();
+  int  search(char *value);
+  void insert(char *);
+  void remove(char *);
+  char *get(int n);
+  int  length;
+static void print(List *l);
+};
+
      + +

      +To generate wrappers for this class, SWIG first reduces the class to a collection of low-level C-style +accessor functions which are then used by the proxy classes. +

      + +

      6.6.1 Constructors and destructors

      + + +

      +C++ constructors and destructors are translated into accessor +functions such as the following :

      + +
      +List * new_List(void) {
+	return new List;
+}
+void delete_List(List *l) {
+	delete l;
+}
+
+
      + +

      6.6.2 Default constructors, copy constructors and implicit destructors

      + + +

      +Following the C++ rules for implicit constructor and destructors, SWIG +will automatically assume there is one even when they are not +explicitly declared in the class interface. +

      + +

      +In general then: +

      + +
        +
      • +If a C++ class does not declare any explicit constructor, SWIG will +automatically generate a wrapper for one. +
        • + +
      • +If a C++ class does not declare an explicit copy constructor, SWIG will +automatically generate a wrapper for one if the %copyctor is used. +
        • + +
      • +If a C++ class does not declare an explicit destructor, SWIG will +automatically generate a wrapper for one. +
        • +
      + +

      + And as in C++, a few rules that alters the previous behavior: +

      + +
        +
      • A default constructor is not created if a class already defines a constructor with arguments. +
        • + +
      • Default constructors are not generated for classes with pure virtual methods or for classes that +inherit from an abstract class, but don't provide definitions for all of the pure methods. +
        • + +
      • A default constructor is not created unless all base classes support a +default constructor. +
        • + +
      • Default constructors and implicit destructors are not created if a class +defines them in a private or protected section. +
        • + +
      • Default constructors and implicit destructors are not created if any base +class defines a non-public default constructor or destructor. +
        • +
      + +

      +SWIG should never generate a default constructor, copy constructor or +default destructor wrapper for a class in which it is illegal to do so. In +some cases, however, it could be necessary (if the complete class +declaration is not visible from SWIG, and one of the above rules is +violated) or desired (to reduce the size of the final interface) by +manually disabling the implicit constructor/destructor generation. +

      + +

      +To manually disable these, the %nodefaultctor and %nodefaultdtor +feature flag directives +can be used. Note that these directives only affects the +implicit generation, and they have no effect if the default/copy +constructors or destructor are explicitly declared in the class +interface. +

      + +

      +For example: +

      + +
      +
      +%nodefaultctor Foo;  // Disable the default constructor for class Foo.
+class Foo {          // No default constructor is generated, unless one is declared
+...
+};
+class Bar {          // A default constructor is generated, if possible
+...
+};
+
      +
      + +

      +The directive %nodefaultctor can also be applied "globally", as in: +

      + +
      +
      +%nodefaultctor; // Disable creation of default constructors
+class Foo {     // No default constructor is generated, unless one is declared
+...
+};
+class Bar {   
+public:
+  Bar();        // The default constructor is generated, since one is declared
+};
+%clearnodefaultctor; // Enable the creation of default constructors again
+
      +
      + +

      +The corresponding %nodefaultdtor directive can be used +to disable the generation of the default or implicit destructor, if +needed. Be aware, however, that this could lead to memory leaks in the +target language. Hence, it is recommended to use this directive only +in well known cases. For example: +

      + +
      +
      +%nodefaultdtor Foo;   // Disable the implicit/default destructor for class Foo.
+class Foo {           // No destructor is generated, unless one is declared
+...
+};
+
      +
      + +

      +Compatibility Note: The generation of default +constructors/implicit destructors was made the default behavior in SWIG +1.3.7. This may break certain older modules, but the old behavior can +be easily restored using %nodefault or the +-nodefault command line option. Furthermore, in order for +SWIG to properly generate (or not generate) default constructors, it +must be able to gather information from both the private and +protected sections (specifically, it needs to know if a private or +protected constructor/destructor is defined). In older versions of +SWIG, it was fairly common to simply remove or comment out +the private and protected sections of a class due to parser limitations. +However, this removal may now cause SWIG to erroneously generate constructors +for classes that define a constructor in those sections. Consider restoring +those sections in the interface or using %nodefault to fix the problem. +

      + +

      +Note: The %nodefault +directive/-nodefault options described above, which disable both the default +constructor and the implicit destructors, could lead to memory +leaks, and so it is strongly recommended to not use them. +

      + + +

      6.6.3 When constructor wrappers aren't created

      + + +

      +If a class defines a constructor, SWIG normally tries to generate a wrapper for it. However, SWIG will +not generate a constructor wrapper if it thinks that it will result in illegal wrapper code. There are really +two cases where this might show up. +

      + +

      +First, SWIG won't generate wrappers for protected or private constructors. For example: +

      + +
      +
      +class Foo {
+protected:
+     Foo();         // Not wrapped.
+public:
+      ...
+};
+
      +
      + +

      +Next, SWIG won't generate wrappers for a class if it appears to be abstract--that is, it has undefined +pure virtual methods. Here are some examples: +

      + +
      +
      +class Bar {
+public:
+     Bar();               // Not wrapped.  Bar is abstract.
+     virtual void spam(void) = 0; 
+};
+
+class Grok : public Bar {
+public:
+      Grok();            // Not wrapped. No implementation of abstract spam().
+};
+
      +
      + +

      +Some users are surprised (or confused) to find missing constructor wrappers in their interfaces. In almost +all cases, this is caused when classes are determined to be abstract. To see if this is the case, run SWIG with +all of its warnings turned on: +

      + +
      +
      +% swig -Wall -python module.i
+
      +
      + +

      +In this mode, SWIG will issue a warning for all abstract classes. It is possible to force a class to be +non-abstract using this: +

      + +
      +
      +%feature("notabstract") Foo;
+
+class Foo : public Bar {
+public:
+     Foo();    // Generated no matter what---not abstract. 
+     ...
+};
+
      +
      + +

      +More information about %feature can be found in the Customization features chapter. +

      + +

      6.6.4 Copy constructors

      + + +

      +If a class defines more than one constructor, its behavior depends on the capabilities of the +target language. If overloading is supported, the copy constructor is accessible using +the normal constructor function. For example, if you have this: +

      + +
      +
      +class List {
+public:
+    List();    
+    List(const List &);      // Copy constructor
+    ...
+};
+
      +
      + +

      +then the copy constructor can be used as follows: +

      + +
      +
      +x = List()               # Create a list
+y = List(x)              # Copy list x
+
      +
      + +

      +If the target language does not support overloading, then the copy constructor is available +through a special function like this: +

      + +
      +
      +List *copy_List(List *f) {
+    return new List(*f);
+}
+
      +
      + +

      +Note: For a class X, SWIG only treats a constructor as +a copy constructor if it can be applied to an object of type +X or X *. If more than one copy constructor is +defined, only the first definition that appears is used as the copy +constructor--other definitions will result in a name-clash. +Constructors such as X(const X &), X(X &), and +X(X *) are handled as copy constructors in SWIG. +

      + +

      +Note: SWIG does not generate a copy constructor +wrapper unless one is explicitly declared in the class. This differs +from the treatment of default constructors and destructors. +However, copy constructor wrappers can be generated if using the copyctor +feature flag. For example: +

      + +
      +
      +%copyctor List;
+
+class List {
+public:
+    List();    
+};
+
      +
      + +

      +Will generate a copy constructor wrapper for List. +

      + +

      +Compatibility note: Special support for copy constructors was +not added until SWIG-1.3.12. In previous versions, copy constructors +could be wrapped, but they had to be renamed. For example: +

      + +
      +
      +class Foo {
+public:
+    Foo();
+  %name(CopyFoo) Foo(const Foo &);
+    ...
+};
+
      +
      + +

      +For backwards compatibility, SWIG does not perform any special +copy-constructor handling if the constructor has been manually +renamed. For instance, in the above example, the name of the +constructor is set to new_CopyFoo(). This is the same as in +older versions. +

      + +

      6.6.5 Member functions

      + + +

      +All member functions are roughly translated into accessor functions like this :

      + +
      +int List_search(List *obj, char *value) {
+	return obj->search(value);
+}
+
+
      + +

      +This translation is the same even if the member function has been +declared as virtual. +

      + +

      +It should be noted that SWIG does not actually create a C accessor +function in the code it generates. Instead, member access such as +obj->search(value) is directly inlined into the generated +wrapper functions. However, the name and calling convention of the +low-level procedural wrappers match the accessor function prototype described above. +

      + +

      6.6.6 Static members

      + + +

      +Static member functions are called directly without making any special +transformations. For example, the static member function +print(List *l) directly invokes List::print(List *l) +in the generated wrapper code. +

      + +

      6.6.7 Member data

      + + +

      +Member data is handled in exactly the same manner as for C +structures. A pair of accessor functions are effectively created. For example +:

      + +
      +int List_length_get(List *obj) {
+	return obj->length;
+}
+int List_length_set(List *obj, int value) {
+	obj->length = value;
+	return value;
+}
+
+
      + +

      +A read-only member can be created using the %immutable and %mutable +feature flag directive. +For example, we probably wouldn't want +the user to change the length of a list so we could do the following +to make the value available, but read-only.

      + +
      +class List {
+public:
+...
+%immutable;
+	int length;
+%mutable;
+...
+};
+
      + +

      +Alternatively, you can specify an immutable member in advance like this: +

      + +
      +
      +%immutable List::length;
+...
+class List {
+   ...
+   int length;         // Immutable by above directive
+   ...
+};
+
      +
      + +

      +Similarly, all data attributes declared as const are wrapped as read-only members. +

      + +

      +There are some subtle issues when wrapping data members that are +themselves classes. For instance, if you had another class like this, +

      + +
      +
      +class Foo {
+public:
+    List items;
+    ...
+
      +
      + +

      +then the low-level accessor to the items member actually uses pointers. For example: +

      + +
      +
      +List *Foo_items_get(Foo *self) {
+    return &self->items;
+}
+void Foo_items_set(Foo *self, List *value) {
+    self->items = *value;
+}
+
      +
      + +

      +More information about this can be found in the SWIG Basics chapter, +Structure data members section. +

      + +

      +The wrapper code to generate the accessors for classes comes from the pointer typemaps. +This can be somewhat unnatural for some types. +For example, a user would expect the STL std::string class member variables to be wrapped as a string in the target language, +rather than a pointer to this class. +The const reference typemaps offer this type of marshalling, so there is a feature to tell SWIG to use the const reference typemaps rather than the pointer typemaps. +It is the %naturalvar directive and is used as follows: +

      + +
      +
      +// All List variables will use const List& typemaps
+%naturalvar List;
+
+// Only Foo::myList will use const List& typemaps
+%naturalvar Foo::myList;
+struct Foo {
+  List myList;
+};
+
+// All variables will use const reference typemaps
+%naturalvar;
+
      +
      + +

      +The observant reader will notice that %naturalvar works like any other +feature flag directive, +except it can also be attached to class types. +The first of the example usages above show %naturalvar attaching to the List class. +Effectively this feature changes the way accessors are generated to the following: +

      + +
      +
      +const List &Foo_items_get(Foo *self) {
+    return self->items;
+}
+void Foo_items_set(Foo *self, const List &value) {
+    self->items = value;
+}
+
      +
      + +

      +In fact it is generally a good idea to use this feature globally as the reference typemaps have extra NULL checking compared to the pointer typemaps. +A pointer can be NULL, whereas a reference cannot, so the extra checking ensures that the target language user does not pass in a value that translates +to a NULL pointer and thereby preventing any potential NULL pointer dereferences. +The %naturalvar feature will apply to global variables in addition to member variables in some language modules, eg C# and Java. +

      + +

      +Other alternatives for turning this feature on globally are to use the swig -naturalvar commandline option +or the module mode option, %module(naturalvar=1) +

      + +

      +Compatibility note: The %naturalvar feature was introduced in SWIG-1.3.28, prior to which it was necessary to manually apply the const reference +typemaps, eg %apply const std::string & { std::string * }, but this example would also apply the typemaps to methods taking a std::string pointer. +

      + +

      +Compatibility note: Read-only access used to be controlled by a pair of directives +%readonly and %readwrite. Although these directives still work, they +generate a warning message. Simply change the directives to %immutable; and +%mutable; to silence the warning. Don't forget the extra semicolon! +

      + +

      +Compatibility note: Prior to SWIG-1.3.12, all members of unknown type were +wrapped into accessor functions using pointers. For example, if you had a structure +like this +

      + +
      +
      +struct Foo {
+   size_t  len;
+};
+
      +
      + +

      +and nothing was known about size_t, then accessors would be +written to work with size_t *. Starting in SWIG-1.3.12, this +behavior has been modified. Specifically, pointers will only +be used if SWIG knows that a datatype corresponds to a structure or +class. Therefore, the above code would be wrapped into accessors +involving size_t. This change is subtle, but it smooths over +a few problems related to structure wrapping and some of SWIG's +customization features. +

      + +

      6.7 Default arguments

      + + +

      +SWIG will wrap all types of functions that have default arguments. For example member functions: +

      + +
      +
      +class Foo {
+public:
+    void bar(int x, int y = 3, int z = 4);
+};
+
      +
      + +

      +SWIG handles default arguments by generating an extra overloaded method for each defaulted argument. +SWIG is effectively handling methods with default arguments as if it was wrapping the equivalent overloaded methods. +Thus for the example above, it is as if we had instead given the following to SWIG: +

      + +
      +
      +class Foo {
+public:
+    void bar(int x, int y, int z);
+    void bar(int x, int y);
+    void bar(int x);
+};
+
      +
      + +

      +The wrappers produced are exactly the same as if the above code was instead fed into SWIG. +Details of this are covered later in the Wrapping Overloaded Functions and Methods section. +This approach allows SWIG to wrap all possible default arguments, but can be verbose. +For example if a method has ten default arguments, then eleven wrapper methods are generated. +

      + +

      +Please see the Features and default arguments +section for more information on using %feature with functions with default arguments. +The Ambiguity resolution and renaming section +also deals with using %rename and %ignore on methods with default arguments. +If you are writing your own typemaps for types used in methods with default arguments, you may also need to write a typecheck typemap. +See the Typemaps and overloading section for details or otherwise +use the compactdefaultargs feature flag as mentioned below. +

      + +

      +Compatibility note: Versions of SWIG prior to SWIG-1.3.23 wrapped default arguments slightly differently. +Instead a single wrapper method was generated and the default values were copied into the C++ wrappers +so that the method being wrapped was then called with all the arguments specified. +If the size of the wrappers are a concern then this approach to wrapping methods with default arguments +can be re-activated by using the compactdefaultargs +feature flag. +

      + +
      +
      +%feature("compactdefaultargs") Foo::bar;
+class Foo {
+public:
+    void bar(int x, int y = 3, int z = 4);
+};
+
      +
      + + +

      +This is great for reducing the size of the wrappers, but the caveat is it does not work for the statically typed languages, +such as C# and Java, +which don't have optional arguments in the language, +Another restriction of this feature is that it cannot handle default arguments that are not public. +The following example illustrates this: +

      + +
      +
      +class Foo {
+private:
+   static const int spam;
+public:
+   void bar(int x, int y = spam);   // Won't work with %feature("compactdefaultargs") -
+                                    // private default value
+};
+
      +
      + +

      +This produces uncompileable wrapper code because default values in C++ are +evaluated in the same scope as the member function whereas SWIG +evaluates them in the scope of a wrapper function (meaning that the +values have to be public). +

      + +

      +This feature is automatically turned on when wrapping C code with default arguments +and whenever keyword arguments (kwargs) are specified for either C or C++ code. +Keyword arguments are a language feature of some scripting languages, for example Ruby and Python. +SWIG is unable to support kwargs when wrapping overloaded methods, so the default approach cannot be used. +

      + +

      6.8 Protection

      + + +

      + SWIG wraps class members that are public following the C++ + conventions, i.e., by explicit public declaration or by the use of + the using directive. In general, anything specified in a + private or protected section will be ignored, although the internal + code generator sometimes looks at the contents of the private and + protected sections so that it can properly generate code for default + constructors and destructors. Directors could also modify the way + non-public virtual protected members are treated. +

      + +

      +By default, members of a class definition are assumed to be private +until you explicitly give a `public:' declaration (This is +the same convention used by C++). +

      + +

      6.9 Enums and constants

      + + +

      +Enumerations and constants are handled differently by the different language modules and are described in detail in the appropriate language chapter. +However, many languages map enums and constants in a class definition +into constants with the classname as a prefix. For example :

      + +
      +class Swig {
+public:
+	enum {ALE, LAGER, PORTER, STOUT};
+};
+
+
      +

      +Generates the following set of constants in the target scripting language :

      + +
      +Swig_ALE = Swig::ALE
+Swig_LAGER = Swig::LAGER
+Swig_PORTER = Swig::PORTER
+Swig_STOUT = Swig::STOUT
+
+
      + +

      +Members declared as const are wrapped as read-only members and do not create constants. +

      + +

      6.10 Friends

      + + +

      +Friend declarations are recognised by SWIG. For example, if +you have this code: +

      + +
      +
      +class Foo {
+public:
+     ...
+     friend void blah(Foo *f);
+     ...
+};
+
      +
      + +

      +then the friend declaration does result in a wrapper code +equivalent to one generated for the following declaration +

      + +
      +
      +class Foo {
+public:
+    ...
+};
+
+void blah(Foo *f);    
+
      +
      + +

      +A friend declaration, as in C++, is understood to be in the same scope +where the class is declared, hence, you can have +

      + +
      +
      +
+%ignore bar::blah(Foo *f);
+
+namespace bar {
+
+  class Foo {
+  public:
+     ...
+     friend void blah(Foo *f);
+     ...
+  };
+}
+
      +
      + +

      +and a wrapper for the method 'blah' will not be generated. +

      + +

      6.11 References and pointers

      + + +

      +C++ references are supported, but SWIG transforms them back into pointers. For example, +a declaration like this :

      + +
      +class Foo {
+public:
+	double bar(double &a);
+}
+
      + +

      +has a low-level accessor +

      + +
      +double Foo_bar(Foo *obj, double *a) {
+	obj->bar(*a);
+}
+
      + +

      +As a special case, most language modules pass const references to primitive datatypes (int, short, +float, etc.) by value instead of pointers. For example, if you have a function like this, +

      + +
      +
      +void foo(const int &x);
+
      +
      + +

      +it is called from a script as follows: +

      + +
      +
      +foo(3)              # Notice pass by value
+
      +
      + +

      +Functions that return a reference are remapped to return a pointer instead. +For example: +

      + +
      +class Bar {
+public:
+     Foo &spam();
+};
+
      +
      + +

      +Generates an accessor like this: +

      + +
      +
      +Foo *Bar_spam(Bar *obj) {
+   Foo &result = obj->spam();
+   return &result;
+}
+
      +
      + +

      +However, functions that return const references to primitive datatypes (int, short, etc.) normally +return the result as a value rather than a pointer. For example, a function like this, +

      + +
      +
      +const int &bar();
+
      +
      + +

      +will return integers such as 37 or 42 in the target scripting language rather than a pointer to an integer. +

      + +

      +Don't return references to objects allocated as local variables on the +stack. SWIG doesn't make a copy of the objects so this will probably +cause your program to crash. + + + +

      +Note: The special treatment for references to primitive datatypes is necessary to provide +more seamless integration with more advanced C++ wrapping applications---especially related to +templates and the STL. This was first added in SWIG-1.3.12. +

      + + +

      6.12 Pass and return by value

      + + +

      +Occasionally, a C++ program will pass and return class objects by value. For example, a function +like this might appear: +

      + +
      +
      +Vector cross_product(Vector a, Vector b);
+
      +
      + +

      +If no information is supplied about Vector, SWIG creates a wrapper function similar to the +following: +

      + +
      +
      +Vector *wrap_cross_product(Vector *a, Vector *b) {
+   Vector x = *a;
+   Vector y = *b;
+   Vector r = cross_product(x,y);
+   return new Vector(r);
+}
      +
      + +

      +In order for the wrapper code to compile, Vector must define a copy constructor and a +default constructor. +

      + +

      +If Vector is defined as a class in the interface, but it does not +support a default constructor, SWIG changes the wrapper code by encapsulating +the arguments inside a special C++ template wrapper class, through a process +called the "Fulton Transform". This produces a wrapper that looks like this: +

      + +
      +
      +Vector cross_product(Vector *a, Vector *b) {
+   SwigValueWrapper<Vector> x = *a;
+   SwigValueWrapper<Vector> y = *b;
+   SwigValueWrapper<Vector> r = cross_product(x,y);
+   return new Vector(r);
+}
+
      +
      + +

      +This transformation is a little sneaky, but it provides support for +pass-by-value even when a class does not provide a default constructor +and it makes it possible to properly support a number of SWIG's +customization options. The definition of SwigValueWrapper +can be found by reading the SWIG wrapper code. This class is really nothing more than a thin +wrapper around a pointer. +

      + +

      +Although SWIG usually detects the classes to which the Fulton Transform should +be applied, in some situations it's necessary to override it. That's done with +%feature("valuewrapper") to ensure it is used and %feature("novaluewrapper") +to ensure it is not used: +

      + +
      +%feature("novaluewrapper") A;    
+class A;
+
+%feature("valuewrapper") B;
+struct B { 
+    B();
+    // ....
+};   
+
      + +

      +It is well worth considering turning this feature on for classes that do have a default constructor. +It will remove a redundant constructor call at the point of the variable declaration in the wrapper, +so will generate notably better performance for large objects or for classes with expensive construction. +Alternatively consider returning a reference or a pointer. +

      + +

      +Note: this transformation has no effect on typemaps +or any other part of SWIG---it should be transparent except that you +may see this code when reading the SWIG output file. +

      + +

      + +Note: This template transformation is new in SWIG-1.3.11 and may be refined in +future SWIG releases. In practice, it is only absolutely necessary to do this for +classes that don't define a default constructor. +

      + +

      +Note: The use of this template only occurs when objects are passed or returned by value. +It is not used for C++ pointers or references. +

      + +

      6.13 Inheritance

      + + +

      +SWIG supports C++ inheritance of classes and allows both single and +multiple inheritance, as limited or allowed by the target +language. The SWIG type-checker knows about the relationship between +base and derived classes and allows pointers to any object of a +derived class to be used in functions of a base class. The +type-checker properly casts pointer values and is safe to use with +multiple inheritance. +

      + +

      SWIG treats private or protected inheritance as close to the C++ +spirit, and target language capabilities, as possible. In most +cases, this means that SWIG will parse the non-public inheritance +declarations, but that will have no effect in the generated code, +besides the implicit policies derived for constructor and +destructors. +

      + + +

      +The following example shows how SWIG handles inheritance. For clarity, +the full C++ code has been omitted.

      + +
      +// shapes.i
+%module shapes
+%{
+#include "shapes.h"
+%}
+
+class Shape {
+public:
+        double x,y;
+	virtual double area() = 0;
+	virtual double perimeter() = 0;
+	void    set_location(double x, double y);
+};
+class Circle : public Shape {
+public:
+	Circle(double radius);
+	~Circle();
+	double area();
+	double perimeter();
+};
+class Square : public Shape {
+public:
+	Square(double size);
+	~Square();
+	double area();
+	double perimeter();
+}
+
      + +

      +When wrapped into Python, we can perform the following operations (shown using the low level Python accessors): +

      + +
      +$ python
+>>> import shapes
+>>> circle = shapes.new_Circle(7)
+>>> square = shapes.new_Square(10)
+>>> print shapes.Circle_area(circle)
+153.93804004599999757
+>>> print shapes.Shape_area(circle)
+153.93804004599999757
+>>> print shapes.Shape_area(square)
+100.00000000000000000
+>>> shapes.Shape_set_location(square,2,-3)
+>>> print shapes.Shape_perimeter(square)
+40.00000000000000000
+>>>
+
      + +

      +In this example, Circle and Square objects have been created. Member +functions can be invoked on each object by making calls to +Circle_area, Square_area, and so on. However, the same +results can be accomplished by simply using the Shape_area +function on either object. +

      + +

      +One important point concerning inheritance is that the low-level +accessor functions are only generated for classes in which they are +actually declared. For instance, in the above example, the method +set_location() is only accessible as +Shape_set_location() and not as +Circle_set_location() or Square_set_location(). Of +course, the Shape_set_location() function will accept any +kind of object derived from Shape. Similarly, accessor functions for +the attributes x and y are generated as +Shape_x_get(), Shape_x_set(), +Shape_y_get(), and Shape_y_set(). Functions such as +Circle_x_get() are not available--instead you should use +Shape_x_get(). +

      + +

      +Note that there is a one to one correlation between the low-level accessor functions and +the proxy methods and therefore there is also a one to one correlation between +the C++ class methods and the generated proxy class methods. +

      + +

      +Note: For the best results, SWIG requires all +base classes to be defined in an interface. Otherwise, you may get a +warning message like this: +

      + +
      +
      +example.i:18: Warning(401): Nothing known about base class 'Foo'. Ignored.
+
      +
      + +

      +If any base class is undefined, SWIG still generates correct type +relationships. For instance, a function accepting a Foo * +will accept any object derived from Foo regardless of whether +or not SWIG actually wrapped the Foo class. If you really +don't want to generate wrappers for the base class, but you want to +silence the warning, you might consider using the %import +directive to include the file that defines Foo. +%import simply gathers type information, but doesn't generate +wrappers. Alternatively, you could just define Foo as an empty class +in the SWIG interface or use +warning suppression. +

      + +

      +Note: typedef-names can be used as base classes. For example: +

      + +
      +
      +class Foo {
+...
+};
+
+typedef Foo FooObj;
+class Bar : public FooObj {     // Ok.  Base class is Foo
+...
+};
+
      +
      + +

      +Similarly, typedef allows unnamed structures to be used as base classes. For example: +

      + +
      +
      +typedef struct {
+   ...
+} Foo;
+
+class Bar : public Foo {    // Ok. 
+...
+};
+
      +
      + +

      +Compatibility Note: Starting in version 1.3.7, SWIG only +generates low-level accessor wrappers for the declarations that are +actually defined in each class. This differs from SWIG1.1 which used +to inherit all of the declarations defined in base classes and +regenerate specialized accessor functions such as +Circle_x_get(), Square_x_get(), +Circle_set_location(), and Square_set_location(). +This behavior resulted in huge amounts of replicated code for large +class hierarchies and made it awkward to build applications spread +across multiple modules (since accessor functions are duplicated in +every single module). It is also unnecessary to have such wrappers +when advanced features like proxy classes are used. + +Note: Further optimizations are enabled when using the +-fvirtual option, which avoids the regenerating of wrapper +functions for virtual members that are already defined in a base +class. +

      + +

      6.14 A brief discussion of multiple inheritance, pointers, and type checking

      + + +

      +When a target scripting language refers to a C++ object, it normally +uses a tagged pointer object that contains both the value of the +pointer and a type string. For example, in Tcl, a C++ pointer might +be encoded as a string like this: +

      + +
      +
      +_808fea88_p_Circle
+
      +
      + +

      +A somewhat common question is whether or not the type-tag could be safely +removed from the pointer. For instance, to get better performance, could you +strip all type tags and just use simple integers instead? +

      + +

      +In general, the answer to this question is no. In the wrappers, all +pointers are converted into a common data representation in the target +language. Typically this is the equivalent of casting a pointer to void *. +This means that any C++ type information associated with the pointer is +lost in the conversion. +

      + +

      +The problem with losing type information is that it is needed to +properly support many advanced C++ features--especially multiple +inheritance. For example, suppose you had code like this: +

      + +
      +
      +class A {
+public:
+   int x;
+};
+
+class B {
+public:
+   int y;
+};
+
+class C : public A, public B {
+};
+
+int A_function(A *a) {
+   return a->x;
+}
+
+int B_function(B *b) {
+   return b->y;
+}
+
      +
      + +

      +Now, consider the following code that uses void *. +

      + +
      +
      +C *c = new C();
+void *p = (void *) c;
+...
+int x = A_function((A *) p);
+int y = B_function((B *) p);
+
      +
      + +

      +In this code, both A_function() and B_function() may +legally accept an object of type C * (via inheritance). +However, one of the functions will always return the wrong result when +used as shown. The reason for this is that even though p +points to an object of type C, the casting operation doesn't +work like you would expect. Internally, this has to do with the data +representation of C. With multiple inheritance, the data from +each base class is stacked together. For example: +

      + +
      +
      +             ------------    <--- (C *),  (A *)
+            |     A      |
+            |------------|   <--- (B *)
+            |     B      |
+             ------------   
+
      +
      + +

      +Because of this stacking, a pointer of type C * may change +value when it is converted to a A * or B *. +However, this adjustment does not occur if you are converting from a +void *. +

      + +

      +The use of type tags marks all pointers with the real type of the +underlying object. This extra information is then used by SWIG +generated wrappers to correctly cast pointer values under inheritance +(avoiding the above problem). +

      + +

      +Some of the language modules are able to solve the problem by storing multiple instances of the pointer, for example, A *, +in the A proxy class as well as C * in the C proxy class. The correct cast can then be made by choosing the correct void * +pointer to use and is guaranteed to work as the cast to a void pointer and back to the same type does not lose any type information: +

      + +
      +
      +C *c = new C();
+void *p = (void *) c;
+void *pA = (void *) c;
+void *pB = (void *) c;
+...
+int x = A_function((A *) pA);
+int y = B_function((B *) pB);
+
      +
      + +

      +In practice, the pointer is held as an integral number in the target language proxy class. +

      + +

      6.15 Wrapping Overloaded Functions and Methods

      + + +

      +In many language modules, SWIG provides partial support for overloaded functions, methods, and +constructors. For example, if you supply SWIG with overloaded functions like this: +

      + +
      +
      +void foo(int x) {
+   printf("x is %d\n", x);
+}
+void foo(char *x) {
+   printf("x is '%s'\n", x);
+}
+
      +
      + +

      +The function is used in a completely natural way. For example: +

      + +
      +
      +>>> foo(3)
+x is 3
+>>> foo("hello")
+x is 'hello'
+>>>
+
      +
      + +

      +Overloading works in a similar manner for methods and constructors. For example if you have +this code, +

      + +
      +
      +class Foo {
+public:
+     Foo();
+     Foo(const Foo &);   // Copy constructor
+     void bar(int x);
+     void bar(char *s, int y);
+};
+
      +
      + +

      +it might be used like this +

      + +
      +
      +>>> f = Foo()          # Create a Foo
+>>> f.bar(3)
+>>> g = Foo(f)         # Copy Foo
+>>> f.bar("hello",2)
+
      +
      + +

      6.15.1 Dispatch function generation

      + + +

      +The implementation of overloaded functions and methods is somewhat +complicated due to the dynamic nature of scripting languages. Unlike +C++, which binds overloaded methods at compile time, SWIG must +determine the proper function as a runtime check for scripting language targets. This check is +further complicated by the typeless nature of certain scripting languages. For instance, +in Tcl, all types are simply strings. Therefore, if you have two overloaded functions +like this, +

      + +
      +
      +void foo(char *x);
+void foo(int x);
+
      +
      + +

      +the order in which the arguments are checked plays a rather critical role. +

      + +

      +For statically typed languages, SWIG uses the language's method overloading mechanism. +To implement overloading for the scripting languages, SWIG generates a dispatch function that checks the +number of passed arguments and their types. To create this function, SWIG +first examines all of the overloaded methods and ranks them according +to the following rules: +

      + +
        +
      1. Number of required arguments. Methods are sorted by increasing number of +required arguments. +
        2. +

      2. Argument type precedence. All C++ datatypes are assigned a numeric type precedence value +(which is determined by the language module).

        + +
        +
        +Type              Precedence
+----------------  ----------
+TYPE *            0     (High)
+void *            20
+Integers          40
+Floating point    60
+char              80
+Strings           100   (Low)
+
        +
        + +

        +Using these precedence values, overloaded methods with the same number of required arguments are sorted in increased +order of precedence values. +

        +
        3. +
      + +

      +This may sound very confusing, but an example will help. Consider the following collection of +overloaded methods: +

      + +
      +
      +void foo(double);
+void foo(int);
+void foo(Bar *);
+void foo();
+void foo(int x, int y, int z, int w);
+void foo(int x, int y, int z = 3);
+void foo(double x, double y);
+void foo(double x, Bar *z);
+
      +
      + +

      +The first rule simply ranks the functions by required argument count. +This would produce the following list: +

      + +
      +
      +rank
+-----
+[0]   foo()
+[1]   foo(double);
+[2]   foo(int);
+[3]   foo(Bar *);
+[4]   foo(int x, int y, int z = 3);
+[5]   foo(double x, double y)
+[6]   foo(double x, Bar *z)
+[7]   foo(int x, int y, int z, int w);
+
      +
      + +

      +The second rule, simply refines the ranking by looking at argument type precedence values. +

      + +
      +
      +rank
+-----
+[0]   foo()
+[1]   foo(Bar *);
+[2]   foo(int);
+[3]   foo(double);
+[4]   foo(int x, int y, int z = 3);
+[5]   foo(double x, Bar *z)
+[6]   foo(double x, double y)
+[7]   foo(int x, int y, int z, int w);
+
      +
      + +

      +Finally, to generate the dispatch function, the arguments passed to an overloaded method are simply +checked in the same order as they appear in this ranking. +

      + +

      +If you're still confused, don't worry about it---SWIG is probably doing the right thing. +

      + +

      6.15.2 Ambiguity in Overloading

      + + +

      +Regrettably, SWIG is not able to support every possible use of valid C++ overloading. Consider +the following example: +

      + +
      +
      +void foo(int x);
+void foo(long x);
+
      +
      + +

      +In C++, this is perfectly legal. However, in a scripting language, there is generally only one kind of integer +object. Therefore, which one of these functions do you pick? Clearly, there is no way to truly make a distinction +just by looking at the value of the integer itself (int and long may even be the same precision). +Therefore, when SWIG encounters this situation, it may generate a warning message like this for scripting languages: +

      + +
      +
      +example.i:4: Warning(509): Overloaded foo(long) is shadowed by foo(int) at example.i:3.
+
      +
      + +

      +or for statically typed languages like Java: +

      + +
      +
      +example.i:4: Warning(516): Overloaded method foo(long) ignored. Method foo(int)
+at example.i:3 used.
+
      +
      + +

      +This means that the second overloaded function will be inaccessible +from a scripting interface or the method won't be wrapped at all. +This is done as SWIG does not know how to disambiguate it from an earlier method. +

      + +

      +Ambiguity problems are known to arise in the following situations: +

      + +
        +
      • Integer conversions. Datatypes such as int, long, and short cannot be disambiguated in some languages. Shown above. +
        • + +
      • Floating point conversion. float and double can not be disambiguated in some languages. +
        • + +
      • Pointers and references. For example, Foo * and Foo &. +
        • + +
      • Pointers and arrays. For example, Foo * and Foo [4]. +
        • + +
      • Pointers and instances. For example, Foo and Foo *. Note: SWIG converts all +instances to pointers. +
        • + +
      • Qualifiers. For example, const Foo * and Foo *. +
        • + +
      • Default vs. non default arguments. For example, foo(int a, int b) and foo(int a, int b = 3). +
        • +
      + +

      +When an ambiguity arises, methods are checked in the same order as they appear in the interface file. +Therefore, earlier methods will shadow methods that appear later. +

      + +

      +When wrapping an overloaded function, there is a chance that you will get an error message like this: +

      + +
      +
      +example.i:3: Warning(467): Overloaded foo(int) not supported (no type checking
+rule for 'int').
+
      +
      + +

      +This error means that the target language module supports overloading, +but for some reason there is no type-checking rule that can be used to +generate a working dispatch function. The resulting behavior is then +undefined. You should report this as a bug to the +SWIG bug tracking database. +

      + +

      +If you get an error message such as the following, +

      + +
      +
      +foo.i:6. Overloaded declaration ignored.  Spam::foo(double )
+foo.i:5. Previous declaration is Spam::foo(int )
+foo.i:7. Overloaded declaration ignored.  Spam::foo(Bar *,Spam *,int )
+foo.i:5. Previous declaration is Spam::foo(int )
+
      +
      + +

      +it means that the target language module has not yet implemented support for overloaded +functions and methods. The only way to fix the problem is to read the next section. +

      + +

      6.15.3 Ambiguity resolution and renaming

      + + +

      +If an ambiguity in overload resolution occurs or if a module doesn't +allow overloading, there are a few strategies for dealing with the +problem. First, you can tell SWIG to ignore one of the methods. This +is easy---simply use the %ignore directive. For example: +

      + +
      +
      +%ignore foo(long);
+
+void foo(int);
+void foo(long);       // Ignored.  Oh well.
+
      +
      + +

      +The other alternative is to rename one of the methods. This can be +done using %rename. For example: +

      + +
      +
      +%rename("foo_short") foo(short);
+%rename(foo_long) foo(long);
+
+void foo(int);
+void foo(short);      // Accessed as foo_short()
+void foo(long);       // Accessed as foo_long()
+
      +
      + +

      +Note that the quotes around the new name are optional, however, +should the new name be a C/C++ keyword they would be essential in order to avoid a parsing error. +The %ignore and %rename directives are both rather powerful +in their ability to match declarations. When used in their simple form, they apply to +both global functions and methods. For example: +

      + +
      +
      +/* Forward renaming declarations */
+%rename(foo_i) foo(int); 
+%rename(foo_d) foo(double);
+...
+void foo(int);           // Becomes 'foo_i'
+void foo(char *c);       // Stays 'foo' (not renamed)
+
+class Spam {
+public:
+   void foo(int);      // Becomes 'foo_i'
+   void foo(double);   // Becomes 'foo_d'
+   ...
+};
+
      +
      + +

      +If you only want the renaming to apply to a certain scope, the C++ scope resolution operator (::) can be used. +For example: +

      + +
      +
      +%rename(foo_i) ::foo(int);      // Only rename foo(int) in the global scope.
+                                // (will not rename class members)
+
+%rename(foo_i) Spam::foo(int);  // Only rename foo(int) in class Spam
+
      +
      + +

      +When a renaming operator is applied to a class as in Spam::foo(int), it is applied to +that class and all derived classes. This can be used to apply a consistent renaming across +an entire class hierarchy with only a few declarations. For example: +

      + +
      +
      +%rename(foo_i) Spam::foo(int);
+%rename(foo_d) Spam::foo(double);
+
+class Spam {
+public:
+   virtual void foo(int);      // Renamed to foo_i
+   virtual void foo(double);   // Renamed to foo_d
+   ...
+};
+
+class Bar : public Spam {
+public:
+   virtual void foo(int);      // Renamed to foo_i
+   virtual void foo(double);   // Renamed to foo_d
+...
+};
+
+class Grok : public Bar {
+public:
+   virtual void foo(int);      // Renamed to foo_i
+   virtual void foo(double);   // Renamed to foo_d
+...
+};
+
      +
      + +

      +It is also possible to include %rename specifications in the +class definition itself. For example: +

      + +
      +
      +class Spam {
+   %rename(foo_i) foo(int);
+   %rename(foo_d) foo(double);
+public:
+   virtual void foo(int);      // Renamed to foo_i
+   virtual void foo(double);   // Renamed to foo_d
+   ...
+};
+
+class Bar : public Spam {
+public:
+   virtual void foo(int);      // Renamed to foo_i
+   virtual void foo(double);   // Renamed to foo_d
+...
+};
+
      +
      + +

      +In this case, the %rename directives still get applied across the entire +inheritance hierarchy, but it's no longer necessary to explicitly specify the +class prefix Spam::. +

      + +

      +A special form of %rename can be used to apply a renaming just to class +members (of all classes): +

      + +
      +
      +%rename(foo_i) *::foo(int);   // Only rename foo(int) if it appears in a class.
+
      +
      + +

      +Note: the *:: syntax is non-standard C++, but the '*' is meant to be a +wildcard that matches any class name (we couldn't think of a better +alternative so if you have a better idea, send email to +the swig-devel mailing list. +

      + +

      +Although this discussion has primarily focused on %rename all of the same rules +also apply to %ignore. For example: +

      + +
      +
      +%ignore foo(double);          // Ignore all foo(double)
+%ignore Spam::foo;            // Ignore foo in class Spam
+%ignore Spam::foo(double);    // Ignore foo(double) in class Spam
+%ignore *::foo(double);       // Ignore foo(double) in all classes
+
      +
      + +

      +When applied to a base class, %ignore forces all definitions in derived classes +to disappear. For example, %ignore Spam::foo(double) will eliminate foo(double) in +Spam and all classes derived from Spam. +

      + +

      +Notes on %rename and %ignore: +

      + +
        +

      • Since, the %rename declaration is used to declare a renaming in advance, it can be +placed at the start of an interface file. This makes it possible to apply a consistent name +resolution without having to modify header files. For example:

        + +
        +
        +%module foo
+
+/* Rename these overloaded functions */
+%rename(foo_i) foo(int); 
+%rename(foo_d) foo(double);
+
+%include "header.h"
+
        +
        +
        • + +

      • The scope qualifier (::) can also be used on simple names. For example:

        +
        +
        +%rename(bar) ::foo;       // Rename foo to bar in global scope only
+%rename(bar) Spam::foo;   // Rename foo to bar in class Spam only
+%rename(bar) *::foo;      // Rename foo in classes only
+
        +
        +
        • + +

      • Name matching tries to find the most specific match that is +defined. A qualified name such as Spam::foo always has +higher precedence than an unqualified name foo. +Spam::foo has higher precedence than *::foo and +*::foo has higher precedence than foo. A +parameterized name has higher precedence than an unparameterized name +within the same scope level. However, an unparameterized name with a +scope qualifier has higher precedence than a parameterized name in +global scope (e.g., a renaming of Spam::foo takes precedence +over a renaming of foo(int)).

        +
        • + +

      • +The order in which %rename directives are defined does not matter +as long as they appear before the declarations to be renamed. Thus, there is no difference +between saying:

        + +
        +
        +%rename(bar) foo;
+%rename(foo_i) Spam::foo(int);
+%rename(Foo) Spam::foo;
+
        +
        + +

        +and this +

        + +
        +
        +%rename(Foo) Spam::foo;
+%rename(bar) foo;
+%rename(foo_i) Spam::foo(int);
+
        +
        + +

        +(the declarations are not stored in a linked list and order has no +importance). Of course, a repeated %rename directive will +change the setting for a previous %rename directive if exactly the +same name, scope, and parameters are supplied. +

        +
        • + +
      • For multiple inheritance where renaming rules are defined for multiple base classes, +the first renaming rule found on a depth-first traversal of the class hierarchy +is used. +
        • + +

      • The name matching rules strictly follow member qualification rules. +For example, if you have a class like this:

        + +
        +
        +class Spam {
+public:
+   ...
+   void bar() const;
+   ...
+};
+
        +
        + +

        +the declaration +

        + +
        +
        +%rename(name) Spam::bar();
+
        +
        + +

        +will not apply as there is no unqualified member bar(). The following will apply as +the qualifier matches correctly: +

        + +
        +
        +%rename(name) Spam::bar() const;
+
        +
        + +

        +An often overlooked C++ feature is that classes can define two different overloaded members +that differ only in their qualifiers, like this: +

        + +
        +
        +class Spam {
+public:
+   ...
+   void bar();         // Unqualified member
+   void bar() const;   // Qualified member
+   ...
+};
+
        +
        + +

        +%rename can then be used to target each of the overloaded methods individually. +For example we can give them separate names in the target language: +

        + +
        +
        +%rename(name1) Spam::bar();
+%rename(name2) Spam::bar() const;
+
        +
        + +

        +Similarly, if you +merely wanted to ignore one of the declarations, use %ignore +with the full qualification. For example, the following directive +would tell SWIG to ignore the const version of bar() +above: +

        + +
        +
        +%ignore Spam::bar() const;   // Ignore bar() const, but leave other bar() alone
+
        +
        + +
        • + +

      • +Currently no resolution is performed in order to match function parameters. This means function parameter types must match exactly. +For example, namespace qualifiers and typedefs will not work. The following usage of typedefs demonstrates this: + +

        +
        +typedef int Integer;
+
+%rename(foo_i) foo(int);
+
+class Spam {
+public:
+   void foo(Integer);  // Stays 'foo' (not renamed)
+};
+class Ham {
+public:
+   void foo(int);      // Renamed to foo_i
+};
+
        +
        + +

      • +The name matching rules also use default arguments for finer control when wrapping methods that have default arguments. +Recall that methods with default arguments are wrapped as if the equivalent overloaded methods had been parsed +(Default arguments section). +Let's consider the following example class:

        + +
        +
        +class Spam {
+public:
+   ...
+   void bar(int i=-1, double d=0.0);
+   ...
+};
+
        +
        + +

        +The following %rename will match exactly and apply to all the target language overloaded methods because the declaration with the default arguments +exactly matches the wrapped method: +

        + +
        +
        +%rename(newbar) Spam::bar(int i=-1, double d=0.0);
+
        +
        + +

        +The C++ method can then be called from the target language with the new name no matter how many arguments are specified, for example: +newbar(2, 2.0), newbar(2) or newbar(). +However, if the %rename does not contain the default arguments, it will only apply to the single equivalent target language overloaded method. +So if instead we have: +

        + +
        +
        +%rename(newbar) Spam::bar(int i, double d);
+
        +
        + +

        +The C++ method must then be called from the target language with the new name newbar(2, 2.0) when both arguments are supplied +or with the original name as bar(2) (one argument) or bar() (no arguments). +In fact it is possible to use %rename on the equivalent overloaded methods, to rename all the equivalent overloaded methods: +

        + +
        +
        +%rename(bar_2args)   Spam::bar(int i, double d);
+%rename(bar_1arg)    Spam::bar(int i);
+%rename(bar_default) Spam::bar();
+
        +
        + +

        +Similarly, the extra overloaded methods can be selectively ignored using %ignore. +

        + +

        +Compatibility note: The %rename directive introduced the default argument matching rules in SWIG-1.3.23 at the same time as the changes +to wrapping methods with default arguments was introduced. +

        + +
        • + +
      + +

      6.15.4 Comments on overloading

      + + +

      +Support for overloaded methods was first added in SWIG-1.3.14. The implementation +is somewhat unusual when compared to similar tools. For instance, the order in which +declarations appear is largely irrelevant in SWIG. Furthermore, SWIG does not rely +upon trial execution or exception handling to figure out which method to invoke. +

      + +

      +Internally, the overloading mechanism is completely configurable by the target language +module. Therefore, the degree of overloading support may vary from language to language. +As a general rule, statically typed languages like Java are able to provide more support +than dynamically typed languages like Perl, Python, Ruby, and Tcl. +

      + +

      6.16 Wrapping overloaded operators

      + + +

      +C++ overloaded operator declarations can be wrapped. +For example, consider a class like this: +

      + +
      +
      +class Complex {
+private:
+  double rpart, ipart;
+public:
+  Complex(double r = 0, double i = 0) : rpart(r), ipart(i) { }
+  Complex(const Complex &c) : rpart(c.rpart), ipart(c.ipart) { }
+  Complex &operator=(const Complex &c) {
+    rpart = c.rpart;
+    ipart = c.ipart;
+    return *this;
+  }
+  Complex operator+(const Complex &c) const {
+    return Complex(rpart+c.rpart, ipart+c.ipart);
+  }
+  Complex operator-(const Complex &c) const {
+    return Complex(rpart-c.rpart, ipart-c.ipart);
+  }
+  Complex operator*(const Complex &c) const {
+    return Complex(rpart*c.rpart - ipart*c.ipart,
+		   rpart*c.ipart + c.rpart*ipart);
+  }
+  Complex operator-() const {
+    return Complex(-rpart, -ipart);
+  }
+  double re() const { return rpart; }
+  double im() const { return ipart; }
+};
+
      +
      + +

      +When operator declarations appear, they are handled in +exactly the same manner as regular methods. However, the +names of these methods are set to strings like "operator +" +or "operator -". The problem with these names is that they +are illegal identifiers in most scripting languages. For instance, +you can't just create a method called "operator +" in +Python--there won't be any way to call it. +

      + +

      +Some language modules already know how to automatically handle certain +operators (mapping them into operators in the target language). +However, the underlying implementation of this is really managed in a +very general way using the %rename directive. For example, +in Python a declaration similar to this is used: +

      + +
      +
      +%rename(__add__) Complex::operator+;
+
      +
      + +

      +This binds the + operator to a method called __add__ (which +is conveniently the same name used to implement the Python + operator). +Internally, the generated wrapper code for a wrapped operator will look +something like this pseudocode: +

      + +
      +
      +_wrap_Complex___add__(args) {
+   ... get args ...
+   obj->operator+(args);
+   ...
+}
+
      +
      + +

      +When used in the target language, it may now be possible to use the overloaded +operator normally. For example: +

      + +
      +
      +>>> a = Complex(3,4)
+>>> b = Complex(5,2)
+>>> c = a + b           # Invokes __add__ method
+
      +
      + +

      +It is important to realize that there is nothing magical happening +here. The %rename directive really only picks a valid method +name. If you wrote this: +

      + +
      +
      +%rename(add) operator+;
+
      +
      + +

      +The resulting scripting interface might work like this: +

      + +
      +
      +a = Complex(3,4)
+b = Complex(5,2)
+c = a.add(b)      # Call a.operator+(b)
+
      +
      + +

      +All of the techniques described to deal with overloaded functions also +apply to operators. For example: +

      + +
      +
      +%ignore Complex::operator=;             // Ignore = in class Complex
+%ignore *::operator=;                   // Ignore = in all classes
+%ignore operator=;                      // Ignore = everywhere.
+
+%rename(__sub__) Complex::operator-; 
+%rename(__neg__) Complex::operator-();  // Unary - 
+
      +
      + +

      +The last part of this example illustrates how multiple definitions of +the operator- method might be handled. +

      + +

      +Handling operators in this manner is mostly straightforward. However, there are a few subtle +issues to keep in mind: +

      + +
        +

      • In C++, it is fairly common to define different versions of the operators to account for +different types. For example, a class might also include a friend function like this:

        + +
        +
        +class Complex {
+public:
+  friend Complex operator+(Complex &, double);
+};
+Complex operator+(Complex &, double);
+
        +
        + +

        +SWIG simply ignores all friend declarations. Furthermore, it +doesn't know how to associate the associated operator+ with +the class (because it's not a member of the class). +

        + +

        +It's still possible to make a wrapper for this operator, but you'll +have to handle it like a normal function. For example: +

        + +
        +
        +%rename(add_complex_double) operator+(Complex &, double);
+
        +
        +
        • + +

      • Certain operators are ignored by default. For instance, new and delete operators +are ignored as well as conversion operators. +

        • + +
      • The semantics of certain C++ operators may not match those in the target language. +
        • +
      + +

      6.17 Class extension

      + + +

      +New methods can be added to a class using the %extend +directive. This directive is primarily used in conjunction with proxy +classes to add additional functionality to an existing class. For +example : +

      + +
      +%module vector
+%{
+#include "vector.h"
+%}
+
+class Vector {
+public:
+	double x,y,z;
+	Vector();
+	~Vector();
+	... bunch of C++ methods ...
+	%extend {
+		char *__str__() {
+			static char temp[256];
+			sprintf(temp,"[ %g, %g, %g ]", $self->x,$self->y,$self->z);
+			return &temp[0];
+		}
+	}
+};
+
      + +

      +This code adds a __str__ method to our class for producing a +string representation of the object. In Python, such a method would +allow us to print the value of an object using the print +command. +

      + +
      +>>>
+>>> v = Vector();
+>>> v.x = 3
+>>> v.y = 4
+>>> v.z = 0
+>>> print(v)
+[ 3.0, 4.0, 0.0 ]
+>>>
+
+
      + +

      +The C++ 'this' pointer is often needed to access member variables, methods etc. +The $self special variable should be used wherever you could use 'this'. +The example above demonstrates this for accessing member variables. +Note that the members dereferenced by $self must be public members as the code is ultimately generated +into a global function and so will not have any access to non-public members. +The implicit 'this' pointer that is present in C++ methods is not present in %extend methods. +In order to access anything in the extended class or its base class, an explicit 'this' is required. +The following example shows how one could access base class members: +

      + +
      +struct Base {
+  virtual void method(int v) {
+    ...
+  }
+  int value;
+};
+struct Derived : Base {
+};
+%extend Derived {
+  virtual void method(int v) {
+    $self->Base::method(v); // akin to this->Base::method(v);
+    $self->value = v;       // akin to this->value = v;
+    ...
+  }
+}
+
      + +

      +The %extend directive follows all of the same conventions +as its use with C structures. Please refer to the Adding member functions to C structures +section for further details. +

      + +

      +Compatibility note: The %extend directive is a new +name for the %addmethods directive in SWIG1.1. Since %addmethods could +be used to extend a structure with more than just methods, a more suitable +directive name has been chosen. +

      + +

      6.18 Templates

      + + +

      +Template type names may appear anywhere a type +is expected in an interface file. For example: +

      + +
      +
      +void foo(vector<int> *a, int n);
+void bar(list<int,100> *x);
+
      +
      + +

      +There are some restrictions on the use of non-type arguments. Simple literals +are supported, and so are some constant expressions. However, use of '<' +and '>' within a constant expressions currently is not supported by SWIG +('<=' and '>=' are though). For example: +

      + +
      +
      +void bar(list<int,100> *x);                // OK
+void bar(list<int,2*50> *x);               // OK
+void bar(list<int,(2>1 ? 100 : 50)> *x)    // Not supported
+
      +
      + +

      +The type system is smart enough to figure out clever games +you might try to play with typedef. For instance, consider this code: +

      + +
      +
      +typedef int Integer;
+void foo(vector<int> *x, vector<Integer> *y);
+
      +
      + +

      +In this case, vector<Integer> is exactly the same type +as vector<int>. The wrapper for foo() will +accept either variant. +

      + +

      +Starting with SWIG-1.3.7, simple C++ template declarations can also be +wrapped. SWIG-1.3.12 greatly expands upon the earlier implementation. Before discussing this any further, there are a few things +you need to know about template wrapping. First, a bare C++ template +does not define any sort of runnable object-code for which SWIG can +normally create a wrapper. Therefore, in order to wrap a template, +you need to give SWIG information about a particular template +instantiation (e.g., vector<int>, +array<double>, etc.). Second, an instantiation name +such as vector<int> is generally not a valid identifier +name in most target languages. Thus, you will need to give the +template instantiation a more suitable name such as intvector +when creating a wrapper. +

      + +

      +To illustrate, consider the following template definition: +

      + +
      +template<class T> class List {
+private:
+    T *data;
+    int nitems;
+    int maxitems;
+public:
+    List(int max) {
+      data = new T [max];
+      nitems = 0;
+      maxitems = max;
+    }
+    ~List() {
+      delete [] data;
+    };
+    void append(T obj) {
+      if (nitems < maxitems) {
+        data[nitems++] = obj;
+      }
+    }
+    int length() {
+      return nitems;
+    }
+    T get(int n) {
+      return data[n];
+    }
+};
+
      + +

      +By itself, this template declaration is useless--SWIG simply ignores it +because it doesn't know how to generate any code until unless a definition of +T is provided. +

      + +

      +One way to create wrappers for a specific template instantiation is to simply +provide an expanded version of the class directly like this: +

      + +
      +
      +%rename(intList) List<int>;       // Rename to a suitable identifier
+class List<int> {
+private:
+    int *data;
+    int nitems;
+    int maxitems;
+public:
+    List(int max);
+    ~List();
+    void append(int obj);
+    int length();
+    int get(int n);
+};
+
      +
      + + +

      +The %rename directive is needed to give the template class an appropriate identifier +name in the target language (most languages would not recognize C++ template syntax as a valid +class name). The rest of the code is the same as what would appear in a normal +class definition. +

      + +

      +Since manual expansion of templates gets old in a hurry, the %template directive can +be used to create instantiations of a template class. Semantically, %template is +simply a shortcut---it expands template code in exactly the same way as shown above. Here +are some examples: +

      + +
      +
      +/* Instantiate a few different versions of the template */
+%template(intList) List<int>;
+%template(doubleList) List<double>;
+
      +
      + +

      +The argument to %template() is the name of the instantiation +in the target language. The name you choose should not conflict with +any other declarations in the interface file with one exception---it +is okay for the template name to match that of a typedef declaration. +For example: +

      + +
      +
      +%template(intList) List<int>;
+...
+typedef List<int> intList;    // OK
+
      +
      + +

      +SWIG can also generate wrappers for function templates using a similar technique. +For example: +

      + +
      +
      +// Function template
+template<class T> T max(T a, T b) { return a > b ? a : b; }
+
+// Make some different versions of this function
+%template(maxint) max<int>;
+%template(maxdouble) max<double>;
+
      +
      + +

      +In this case, maxint and maxdouble become unique names for specific +instantiations of the function. +

      + +

      +The number of arguments supplied to %template should match that in the +original template definition. Template default arguments are supported. For example: +

      + +
      +
      +template vector<typename T, int max=100> class vector {
+...
+};
+
+%template(intvec) vector<int>;           // OK
+%template(vec1000) vector<int,1000>;     // OK
+
      +
      + +

      +The %template directive should not be used to wrap the same +template instantiation more than once in the same scope. This will +generate an error. For example: +

      + +
      +
      +%template(intList) List<int>;
+%template(Listint) List<int>;    // Error.   Template already wrapped.
+
      +
      + +

      +This error is caused because the template expansion results in two +identical classes with the same name. This generates a symbol table +conflict. Besides, it probably more efficient to only wrap a specific +instantiation only once in order to reduce the potential for code +bloat. +

      + +

      +Since the type system knows how to handle typedef, it is +generally not necessary to instantiate different versions of a template +for typenames that are equivalent. For instance, consider this code: +

      + +
      +
      +%template(intList) vector<int>;
+typedef int Integer;
+...
+void foo(vector<Integer> *x);
+
      +
      + +

      +In this case, vector<Integer> is exactly the same type as +vector<int>. Any use of Vector<Integer> is mapped back to the +instantiation of vector<int> created earlier. Therefore, it is +not necessary to instantiate a new class for the type Integer (doing so is +redundant and will simply result in code bloat). +

      + +

      +When a template is instantiated using %template, information +about that class is saved by SWIG and used elsewhere in the program. +For example, if you wrote code like this, +

      + +
      +
      +...
+%template(intList) List<int>;
+...
+class UltraList : public List<int> {
+   ...
+};
+
      +
      + +

      +then SWIG knows that List<int> was already wrapped as a class called +intList and arranges to handle the inheritance correctly. If, on the other hand, +nothing is known about List<int>, you will get a warning message similar to this: +

      + +
      +
      +example.h:42. Nothing known about class 'List<int >' (ignored). 
+example.h:42. Maybe you forgot to instantiate 'List<int >' using %template. 
+
      +
      + +

      +If a template class inherits from another template class, you need to +make sure that base classes are instantiated before derived classes. +For example: +

      + +
      +
      +template<class T> class Foo {
+...
+};
+
+template<class T> class Bar : public Foo<T> {
+...
+};
+
+// Instantiate base classes first 
+%template(intFoo) Foo<int>;
+%template(doubleFoo) Foo<double>;
+
+// Now instantiate derived classes
+%template(intBar) Bar<int>;
+%template(doubleBar) Bar<double>;
+
      +
      + +

      +The order is important since SWIG uses the instantiation names to +properly set up the inheritance hierarchy in the resulting wrapper +code (and base classes need to be wrapped before derived classes). +Don't worry--if you get the order wrong, SWIG should generate a warning message. +

      + +

      +Occasionally, you may need to tell SWIG about base classes that are defined by templates, +but which aren't supposed to be wrapped. Since SWIG is not able to automatically +instantiate templates for this purpose, you must do it manually. To do this, simply +use %template with no name. For example: +

      + +
      +
      +// Instantiate traits<double,double>, but don't wrap it.
+%template() traits<double,double>;
+
      +
      + +

      +If you have to instantiate a lot of different classes for many different types, +you might consider writing a SWIG macro. For example: +

      + +
      +
      +%define TEMPLATE_WRAP(prefix, T...) 
+%template(prefix ## Foo) Foo<T >;
+%template(prefix ## Bar) Bar<T >;
+...
+%enddef
+
+TEMPLATE_WRAP(int, int)
+TEMPLATE_WRAP(double, double)
+TEMPLATE_WRAP(String, char *)
+TEMPLATE_WRAP(PairStringInt, std::pair<string, int>)
+...
+
      +
      + +

      +Note the use of a vararg macro for the type T. If this wasn't used, the comma in the templated type in the last example would not be possible. +

      + +

      +The SWIG template mechanism does support specialization. For instance, if you define +a class like this, +

      + +
      +
      +template<> class List<int> {
+private:
+    int *data;
+    int nitems;
+    int maxitems;
+public:
+    List(int max);
+    ~List();
+    void append(int obj);
+    int length();
+    int get(int n);
+};
+
      +
      + +

      +then SWIG will use this code whenever the user expands List<int>. In practice, +this may have very little effect on the underlying wrapper code since +specialization is often used to provide slightly modified method bodies (which +are ignored by SWIG). However, special SWIG +directives such as %typemap, %extend, and so forth can be attached +to a specialization to provide customization for specific types. +

      + +

      +Partial template specialization is partially supported by SWIG. For example, this +code defines a template that is applied when the template argument is a pointer. +

      + +
      +
      +template<class T> class List<T*> {
+private:
+    T *data;
+    int nitems;
+    int maxitems;
+public:
+    List(int max);
+    ~List();
+    void append(int obj);
+    int length();
+    T get(int n);
+};
+
      +
      + +

      +SWIG should be able to handle most simple uses of partial specialization. However, it may fail +to match templates properly in more complicated cases. For example, if you have this code, +

      + +
      +
      +template<class T1, class T2> class Foo<T1, T2 *> { };
+
      +
      + +

      +SWIG isn't able to match it properly for instantiations like Foo<int *, int *>. +This problem is not due to parsing, but due to the fact that SWIG does not currently implement all +of the C++ argument deduction rules. +

      + +

      +Member function templates are supported. The underlying principle is the same +as for normal templates--SWIG can't create a wrapper unless you provide +more information about types. For example, a class with a member template might +look like this: +

      + +
      +
      +class Foo {
+public:
+     template<class T> void bar(T x, T y) { ... };
+     ...
+};
+
      +
      + +

      +To expand the template, simply use %template inside the class. +

      + +
      +
      +class Foo {
+public:
+     template<class T> void bar(T x, T y) { ... };
+     ...
+     %template(barint)    bar<int>;
+     %template(bardouble) bar<double>;
+};
+
      +
      + +

      +Or, if you want to leave the original class definition alone, just do this: +

      + +
      +
      +class Foo {
+public:
+     template<class T> void bar(T x, T y) { ... };
+     ...
+};
+...
+%extend Foo {
+     %template(barint)    bar<int>;
+     %template(bardouble) bar<double>;
+};
+
      +
      + +

      +or simply +

      + +
      +
      +class Foo {
+public:
+     template<class T> void bar(T x, T y) { ... };
+     ...
+};
+...
+
+%template(bari) Foo::bar<int>;
+%template(bard) Foo::bar<double>;
+
      +
      + +

      +In this case, the %extend directive is not needed, and +%template does the exactly same job, i.e., it adds two new +methods to the Foo class. +

      + + +

      +Note: because of the way that templates are handled, the %template directive +must always appear after the definition of the template to be expanded. +

      + +

      +Now, if your target language supports overloading, you can even try +

      + +
      +
      +%template(bar) Foo::bar<int>;
+%template(bar) Foo::bar<double>;
+
      +
      + +

      +and since the two new wrapped methods have the same name 'bar', they will be +overloaded, and when called, the correct method will be dispatched +depending on the argument type. +

      + + +

      +When used with members, the %template directive may be placed in another +template class. Here is a slightly perverse example: +

      + +
      +
      +// A template
+template<class T> class Foo {
+public:
+     // A member template
+     template<class S> T bar(S x, S y) { ... };
+     ...
+};
+
+// Expand a few member templates
+%extend Foo {
+  %template(bari) bar<int>;
+  %template(bard) bar<double>;
+}
+
+// Create some wrappers for the template
+%template(Fooi) Foo<int>;
+%template(Food) Foo<double>;
+
      +
      + +

      +Miraculously, you will find that each expansion of Foo has member +functions bari() and bard() added. +

      + +

      +A common use of member templates is to define constructors for copies +and conversions. For example: +

      + +
      +
      +template<class T1, class T2> struct pair {
+   T1 first;
+   T2 second;
+   pair() : first(T1()), second(T2()) { }
+   pair(const T1 &x, const T2 &y) : first(x), second(y) { }
+   template<class U1, class U2> pair(const pair<U1,U2> &x) 
+                                        : first(x.first),second(x.second) { }
+};
+
      +
      + +

      +This declaration is perfectly acceptable to SWIG, but the constructor template will be ignored +unless you explicitly expand it. To do that, you could expand a few versions of the constructor +in the template class itself. For example: +

      + +
      +
      +%extend pair {
+   %template(pair) pair<T1,T2>;        // Generate default copy constructor
+};
+
      +
      + +

      +When using %extend in this manner, notice how you can still use the template parameters in +the original template definition. +

      + +

      +Alternatively, you could expand the constructor template in selected instantiations. For example: +

      + +
      +
      +// Instantiate a few versions
+%template(pairii) pair<int,int>;
+%template(pairdd) pair<double,double>;
+
+// Create a default constructor only 
+%extend pair<int,int> {
+   %template(paird) pair<int,int>;         // Default constructor
+};
+
+// Create default and conversion constructors 
+%extend pair<double,double> {
+   %template(paird) pair<double,dobule>;   // Default constructor
+   %template(pairc) pair<int,int>;         // Conversion constructor
+};
+
      +
      + + +

      And if your target language supports overloading, then you can try +instead: +

      + +
      +
      +// Create default and conversion constructors 
+%extend pair<double,double> {
+   %template(pair) pair<double,dobule>;   // Default constructor
+   %template(pair) pair<int,int>;         // Conversion constructor
+};
+
      +
      + +

      +In this case, the default and conversion constructors have the same +name. Hence, Swig will overload them and define an unique visible +constructor, that will dispatch the proper call depending on the argument +type. +

      + +

      +If all of this isn't quite enough and you really want to make +someone's head explode, SWIG directives such as +%rename, %extend, and %typemap can be +included directly in template definitions. For example: +

      + +
      +// File : list.h
+template<class T> class List {
+   ...
+public:
+    %rename(__getitem__) get(int);
+    List(int max);
+    ~List();
+    ...
+    T get(int index);
+    %extend {
+        char *__str__() {
+            /* Make a string representation */
+            ...
+        }
+    }
+};
+
      + +

      +In this example, the extra SWIG directives are propagated to every template +instantiation. +

      + +

      +It is also possible to separate these declarations from the template class. For example: +

      + +
      +
      +%rename(__getitem__) List::get;
+%extend List {
+    char *__str__() {
+        /* Make a string representation */
+        ...
+    }
+    /* Make a copy */
+    T *__copy__() {
+       return new List<T>(*$self);
+    }
+};
+
+...
+template<class T> class List {
+    ...
+    public:
+    List() { };
+    T get(int index);
+    ...
+};
+
      +
      + +

      +When %extend is decoupled from the class definition, it is +legal to use the same template parameters as provided in the class definition. +These are replaced when the template is expanded. +In addition, the %extend directive can be used to add +additional methods to a specific instantiation. For example: +

      + +
      +
      +%template(intList) List<int>;
+
+%extend List<int> {
+    void blah() {
+          printf("Hey, I'm an List<int>!\n");
+    }
+};
+
      +
      + +

      +SWIG even supports overloaded templated functions. As usual the %template directive +is used to wrap templated functions. For example: +

      + +
      +
      +template<class T> void foo(T x) { };
+template<class T> void foo(T x, T y) { };
+
+%template(foo) foo<int>;
+
      +
      + +

      +This will generate two overloaded wrapper methods, the first will take a single integer as an argument +and the second will take two integer arguments. +

      + +

      +Needless to say, SWIG's template support provides plenty of +opportunities to break the universe. That said, an important final +point is that SWIG does not perform extensive error checking of +templates! Specifically, SWIG does not perform type checking nor +does it check to see if the actual contents of the template +declaration make any sense. Since the C++ compiler will hopefully +check this when it compiles the resulting wrapper file, there is no +practical reason for SWIG to duplicate this functionality (besides, +none of the SWIG developers are masochistic enough to want to +implement this right now). +

      + +

      +Compatibility Note: The first implementation of template support relied heavily on +macro expansion in the preprocessor. Templates have been more tightly integrated into +the parser and type system in SWIG-1.3.12 and the preprocessor is no longer used. Code +that relied on preprocessing features in template expansion will no longer work. However, +SWIG still allows the # operator to be used to generate a string from a template argument. +

      + +

      +Compatibility Note: In earlier versions of SWIG, the %template directive +introduced a new class name. This name could then be used with other directives. For example: +

      + +
      +
      +%template(vectori) vector<int>;
+%extend vectori {
+    void somemethod() { }
+};
+
      +
      + +

      +This behavior is no longer supported. Instead, you should use the original template name +as the class name. For example: +

      + +
      +
      +%template(vectori) vector<int>;
+%extend vector<int> {
+    void somemethod() { }
+};
+
      +
      + +

      +Similar changes apply to typemaps and other customization features. +

      + +

      6.19 Namespaces

      + + +

      +Support for C++ namespaces is a relatively late addition to SWIG, +first appearing in SWIG-1.3.12. Before describing the implementation, +it is worth noting that the semantics of C++ namespaces is extremely +non-trivial--especially with regard to the C++ type system and class +machinery. At a most basic level, namespaces are sometimes used to +encapsulate common functionality. For example: +

      + +
      +
      +namespace math {
+   double sin(double);
+   double cos(double);
+
+   class Complex {
+      double im,re;
+   public:
+      ...
+   };
+   ...
+};
+
      +
      + +

      +Members of the namespace are accessed in C++ by prepending the namespace prefix +to names. For example: +

      + +
      +
      +double x = math::sin(1.0);
+double magnitude(math::Complex *c);
+math::Complex c;
+...
+
      +
      + +

      +At this level, namespaces are relatively easy to manage. However, things start to get +very ugly when you throw in the other ways a namespace can be used. For example, +selective symbols can be exported from a namespace with using. +

      + +
      +
      +using math::Complex;
+double magnitude(Complex *c);       // Namespace prefix stripped
+
      +
      + +

      +Similarly, the contents of an entire namespace can be made available like this: +

      + +
      +
      +using namespace math;
+double x = sin(1.0);
+double magnitude(Complex *c);
+
      +
      + +

      +Alternatively, a namespace can be aliased: +

      + +
      +
      +namespace M = math;
+double x = M::sin(1.0);
+double magnitude(M::Complex *c);
+
      +
      + +

      +Using combinations of these features, it is possible to write head-exploding code like this: +

      + +
      +
      +namespace A {
+  class Foo {
+  };
+}
+
+namespace B {
+   namespace C {
+      using namespace A;
+   }
+   typedef C::Foo FooClass;
+}
+
+namespace BIGB = B;
+
+namespace D {
+   using BIGB::FooClass;
+   class Bar : public FooClass {
+   }
+};
+
+class Spam : public D::Bar {
+};
+
+void evil(A::Foo *a, B::FooClass *b, B::C::Foo *c, BIGB::FooClass *d,
+          BIGB::C::Foo *e, D::FooClass *f);
+
+
      +
      + +

      +Given the possibility for such perversion, it's hard to imagine how +every C++ programmer might want such code wrapped into the target +language. Clearly this code defines three different classes. However, one +of those classes is accessible under at least six different names! +

      + +

      +SWIG fully supports C++ namespaces in its internal type system and +class handling code. If you feed SWIG the above code, it will be +parsed correctly, it will generate compilable wrapper code, and it +will produce a working scripting language module. However, the +default wrapping behavior is to flatten namespaces in the target +language. This means that the contents of all namespaces are merged +together in the resulting scripting language module. For example, if +you have code like this, +

      + +
      +
      +%module foo
+namespace foo {
+   void bar(int);
+   void spam();
+}
+
+namespace bar {
+   void blah();
+}
+
+
      +
      + +

      +then SWIG simply creates three wrapper functions bar(), +spam(), and blah() in the target language. SWIG +does not prepend the names with a namespace prefix nor are the +functions packaged in any kind of nested scope. +

      + +

      +There is some rationale for taking this approach. Since C++ +namespaces are often used to define modules in C++, there is a natural +correlation between the likely contents of a SWIG module and the contents of +a namespace. For instance, it would not be unreasonable to assume +that a programmer might make a separate extension module for each C++ +namespace. In this case, it would be redundant to prepend everything +with an additional namespace prefix when the module itself already +serves as a namespace in the target language. Or put another way, if +you want SWIG to keep namespaces separate, simply wrap each namespace with its +own SWIG interface. +

      + +

      +Because namespaces are flattened, it is possible for symbols defined in different +namespaces to generate a name conflict in the target language. For example: +

      + +
      +
      +namespace A {
+   void foo(int);
+}
+namespace B {
+   void foo(double);
+}
+
      +
      + +

      +When this conflict occurs, you will get an error message that resembles this: +

      + +
      +
      +example.i:26. Error. 'foo' is multiply defined in the generated module.
+example.i:23. Previous declaration of 'foo'
+
      +
      + +

      +To resolve this error, simply use %rename to disambiguate the declarations. For example: +

      + +
      +
      +%rename(B_foo) B::foo;
+...
+namespace A {
+   void foo(int);
+}
+namespace B {
+   void foo(double);     // Gets renamed to B_foo
+}
+
      +
      + +

      +Similarly, %ignore can be used to ignore declarations. +

      + +

      +using declarations do not have any effect on the generated wrapper +code. They are ignored by SWIG language modules and they do not result in any +code. However, these declarations are used by the internal type +system to track type-names. Therefore, if you have code like this: +

      + +
      +
      +namespace A {
+   typedef int Integer;
+}
+using namespace A;
+void foo(Integer x);
+
      +
      + +

      +SWIG knows that Integer is the same as A::Integer which +is the same as int. +

      + +

      +Namespaces may be combined with templates. If necessary, the +%template directive can be used to expand a template defined +in a different namespace. For example: +

      + +
      +
      +namespace foo {
+    template<typename T> T max(T a, T b) { return a > b ? a : b; }
+}
+
+using foo::max;
+
+%template(maxint)   max<int>;           // Okay.
+%template(maxfloat) foo::max<float>;    // Okay (qualified name).
+
+namespace bar {
+    using namespace foo;
+    %template(maxdouble)  max<double>;    // Okay.
+}
+
      +
      + +

      +The combination of namespaces and other SWIG directives may introduce subtle scope-related problems. +The key thing to keep in mind is that all SWIG generated wrappers are produced +in the global namespace. Symbols from other namespaces are always accessed using fully +qualified names---names are never imported into the global space unless the interface happens to +do so with a using declaration. In almost all cases, SWIG adjusts typenames and symbols +to be fully qualified. However, this is not done in code fragments such as function bodies, +typemaps, exception handlers, and so forth. For example, consider the following: +

      + +
      +
      +namespace foo {
+    typedef int Integer;
+    class bar {
+    public:
+       ...
+    };
+}
+
+%extend foo::bar {
+   Integer add(Integer x, Integer y) {
+       Integer r = x + y;        // Error. Integer not defined in this scope
+       return r;
+   }
+};
+
      +
      + +

      +In this case, SWIG correctly resolves the added method parameters and return type to +foo::Integer. However, since function bodies aren't parsed and such code is +emitted in the global namespace, this code produces a compiler error about Integer. +To fix the problem, make sure you use fully qualified names. For example: +

      + +
      +
      +%extend foo::bar {
+   Integer add(Integer x, Integer y) {
+       foo::Integer r = x + y;        // Ok.
+       return r;
+   }
+};
+
      +
      + +

      +Note: SWIG does not propagate using declarations to +the resulting wrapper code. If these declarations appear in an interface, +they should also appear in any header files that might have been +included in a %{ ... %} section. In other words, don't insert extra +using declarations into a SWIG interface unless they also appear +in the underlying C++ code. +

      + +

      +Note: Code inclusion directives such as %{ ... %} or +%inline %{ ... %} should not be placed inside a namespace declaration. +The code emitted by these directives will not be enclosed in a namespace and +you may get very strange results. If you need to use namespaces with +these directives, consider the following: +

      + +
      +
      +// Good version
+%inline %{
+namespace foo {
+     void bar(int) { ... }
+     ...
+}
+%}
+
+// Bad version.  Emitted code not placed in namespace.
+namespace foo {
+%inline %{
+     void bar(int) { ... }   /* I'm bad */
+     ...
+%}
+}
+
      +
      + +

      +Note: When the %extend directive is used inside a namespace, the namespace name is +included in the generated functions. For example, if you have code like this, +

      + +
      +
      +namespace foo {
+   class bar {
+   public:
+        %extend {
+           int blah(int x);
+        };
+   };
+}
+
      +
      + +

      +the added method blah() is mapped to a function int foo_bar_blah(foo::bar *self, int x). +This function resides in the global namespace. +

      + +

      +Note: Although namespaces are flattened in the target language, the SWIG generated wrapper +code observes the same namespace conventions as used in the input file. Thus, if there are no symbol +conflicts in the input, there will be no conflicts in the generated code. +

      + +

      +Note: In the same way that no resolution is performed on parameters, a conversion operator name must match exactly to how it is defined. Do not change the qualification of the operator. For example, suppose you had an interface like this: +

      + +
      +
      +namespace foo {
+   class bar;
+   class spam {
+   public:
+        ...
+        operator bar();      // Conversion of spam -> bar
+        ...
+   };
+}
+
      +
      + +

      +The following is how the feature is expected to be written for a successful match: +

      + +
      +
      +%rename(tofoo) foo::spam::operator bar();
+
      +
      + +

      +The following does not work as no namespace resolution is performed in the matching of conversion operator names: +

      + +
      +
      +%rename(tofoo) foo::spam::operator foo::bar();
+
      +
      + +

      +Note, however, that if the operator is defined using a qualifier in its name, then the feature must use it too... +

      + +
      +
      +%rename(tofoo) foo::spam::operator bar();      // will not match
+%rename(tofoo) foo::spam::operator foo::bar(); // will match
+namespace foo {
+   class bar;
+   class spam {
+   public:
+        ...
+        operator foo::bar();
+        ...
+   };
+}
+
      +
      + +

      +Compatibility Note: Versions of SWIG prior to 1.3.32 were inconsistent in this approach. A fully qualified name was usually required, but would not work in some situations. +

      + + +

      +Note: The flattening of namespaces is only intended to serve as +a basic namespace implementation. +None of the target language modules are currently programmed +with any namespace awareness. In the future, language modules may or may not provide +more advanced namespace support. +

      + +

      6.20 Renaming templated types in namespaces

      + + +

      +As has been mentioned, when %rename includes parameters, the parameter types must match exactly (no typedef or namespace resolution is performed). +SWIG treats templated types slightly differently and has an additional matching rule so unlike non-templated types, an exact match is not always required. +If the fully qualified templated type is specified, it will have a higher precedence over the generic template type. +In the example below, the generic template type is used to rename to bbb and the fully qualified type is used to rename to ccc. +

      + +
      +
      +%rename(bbb) Space::ABC::aaa(T t);                       // will match but with lower precedence than ccc
+%rename(ccc) Space::ABC<Space::XYZ>::aaa(Space::XYZ t);  // will match but with higher precedence than bbb
+
+namespace Space {
+  class XYZ {};
+  template<typename T> struct ABC {
+    void aaa(T t) {}
+  };
+}
+%template(ABCXYZ) Space::ABC<Space::XYZ>;
+
      +
      + +

      +It should now be apparent that there are many ways to achieve a renaming with %rename. This is demonstrated +by the following two examples, which are effectively the same as the above example. +Below shows how %rename can be placed inside a namespace. +

      + +
      +
      +namespace Space {
+  %rename(bbb) ABC::aaa(T t);                       // will match but with lower precedence than ccc
+  %rename(ccc) ABC<Space::XYZ>::aaa(Space::XYZ t);  // will match but with higher precedence than bbb
+  %rename(ddd) ABC<Space::XYZ>::aaa(XYZ t);         // will not match
+}
+
+namespace Space {
+  class XYZ {};
+  template<typename T> struct ABC {
+    void aaa(T t) {}
+  };
+}
+%template(ABCXYZ) Space::ABC<Space::XYZ>;
+
      +
      + +

      +Note that ddd does not match as there is no namespace resolution for parameter types and the fully qualified type must be specified for template type expansion. +The following example shows how %rename can be placed within %extend. +

      + +
      +
      +namespace Space {
+  %extend ABC {
+    %rename(bbb) aaa(T t);           // will match but with lower precedence than ccc
+  }
+  %extend ABC<Space::XYZ> {
+    %rename(ccc) aaa(Space::XYZ t);  // will match but with higher precedence than bbb
+    %rename(ddd) aaa(XYZ t);         // will not match
+  }
+}
+
+namespace Space {
+  class XYZ {};
+  template<typename T> struct ABC {
+    void aaa(T t) {}
+  };
+}
+%template(ABCXYZ) Space::ABC<Space::XYZ>;
+
      +
      + + +

      6.21 Exception specifications

      + + +

      +When C++ programs utilize exceptions, exceptional behavior is sometimes specified as +part of a function or method declaration. For example: +

      + +
      +
      +class Error { };
+
+class Foo {
+public:
+    ...
+    void blah() throw(Error);
+    ...
+};
+
      +
      + +

      +If an exception specification is used, SWIG automatically generates +wrapper code for catching the indicated exception and, when possible, +rethrowing it into the target language, or converting it into an error +in the target language otherwise. For example, in Python, you can +write code like this: +

      + +
      +
      +f = Foo()
+try:
+    f.blah()
+except Error,e:
+     # e is a wrapped instance of "Error"
+
      +
      + +

      +Details of how to tailor code for handling the caught C++ exception and converting it into the target language's exception/error handling mechanism +is outlined in the "throws" typemap section. +

      + +

      +Since exception specifications are sometimes only used sparingly, this alone may not be enough to +properly handle C++ exceptions. To do that, a different set of special SWIG directives are used. +Consult the "Exception handling with %exception" section for details. +The next section details a way of simulating an exception specification or replacing an existing one. +

      + +

      6.22 Exception handling with %catches

      + + +

      +Exceptions are automatically handled for methods with an exception specification. +Similar handling can be achieved for methods without exception specifications through the %catches feature. +It is also possible to replace any declared exception specification using the %catches feature. +In fact, %catches uses the same "throws" typemaps that SWIG uses for exception specifications in handling exceptions. +The %catches feature must contain a list of possible types that can be thrown. +For each type that is in the list, SWIG will generate a catch handler, in the same way that it would for types declared in the exception specification. +Note that the list can also include the catch all specification "...". +For example, +

      + +
      +
      +struct EBase { virtual ~EBase(); };
+struct Error1 : EBase { };
+struct Error2 : EBase { };
+struct Error3 : EBase { };
+struct Error4 : EBase { };
+
+%catches(Error1,Error2,...) Foo::bar();
+%catches(EBase) Foo::blah();
+
+class Foo {
+public:
+    ...
+    void bar();
+    void blah() throw(Error1,Error2,Error3,Error4);
+    ...
+};
+
      +
      + +

      +For the Foo::bar() method, which can throw anything, +SWIG will generate catch handlers for Error1, Error2 as well as a catch all handler (...). +Each catch handler will convert the caught exception and convert it into a target language error/exception. +The catch all handler will convert the caught exception into an unknown error/exception. +

      + +

      +Without the %catches feature being attached to Foo::blah(), +SWIG will generate catch handlers for all of the types in the exception specification, that is, Error1, Error2, Error3, Error4. +However, with the %catches feature above, +just a single catch handler for the base class, EBase will be generated to convert the C++ exception into a target language error/exception. +

      + + +

      6.23 Pointers to Members

      + + +

      +Starting with SWIG-1.3.7, there is limited parsing support for pointers to C++ class members. +For example: +

      + +
      +
      +double do_op(Object *o, double (Object::*callback)(double,double));
+extern double (Object::*fooptr)(double,double);
+%constant double (Object::*FOO)(double,double) = &Object::foo;
+
      +
      + +

      +Although these kinds of pointers can be parsed and represented by the +SWIG type system, few language modules know how to handle them due to +implementation differences from standard C pointers. Readers are +strongly advised to consult an advanced text such as the "The +Annotated C++ Manual" for specific details. +

      + +

      +When pointers to members are supported, the pointer value might appear as a special +string like this: +

      + +
      +
      +>>> print example.FOO
+_ff0d54a800000000_m_Object__f_double_double__double
+>>>
+
      +
      + +

      +In this case, the hexadecimal digits represent the entire value of the +pointer which is usually the contents of a small C++ structure on most +machines. +

      + +

      +SWIG's type-checking mechanism is also more limited when working with +member pointers. Normally SWIG tries to keep track of inheritance +when checking types. However, no such support is currently provided +for member pointers. +

      + +

      6.24 Smart pointers and operator->()

      + + +

      +In some C++ programs, objects are often encapsulated by smart-pointers +or proxy classes. This is sometimes done to implement automatic memory management (reference counting) or +persistence. Typically a smart-pointer is defined by a template class where +the -> operator has been overloaded. This class is then wrapped +around some other class. For example: +

      + +
      +
      +// Smart-pointer class
+template<class T> class SmartPtr {
+    T *pointee;
+public:
+    ...
+    T *operator->() {
+        return pointee;
+    }
+    ...
+};
+
+// Ordinary class
+class Foo_Impl {
+public:
+    int x;
+    virtual void bar();
+    ...
+};
+
+// Smart-pointer wrapper
+typedef SmartPtr<Foo_Impl> Foo;
+
+// Create smart pointer Foo
+Foo make_Foo() {
+    return SmartPtr(new Foo_Impl());
+}
+
+// Do something with smart pointer Foo
+void do_something(Foo f) {
+    printf("x = %d\n", f->x);
+    f->bar();
+}
+
      +
      + +

      +A key feature of this approach is that by defining +operator-> the methods and attributes of the object +wrapped by a smart pointer are transparently accessible. For example, +expressions such as these (from the previous example), +

      + +
      +
      +f->x
+f->bar()
+
      +
      + +

      +are transparently mapped to the following +

      + +
      +
      +(f.operator->())->x;
+(f.operator->())->bar();
+
      +
      + +

      +When generating wrappers, SWIG tries to emulate this functionality to +the extent that it is possible. To do this, whenever +operator->() is encountered in a class, SWIG looks at its +returned type and uses it to generate wrappers for accessing +attributes of the underlying object. For example, wrapping the above +code produces wrappers like this: +

      + +
      +
      +int Foo_x_get(Foo *f) {
+   return (*f)->x;
+}
+void Foo_x_set(Foo *f, int value) {
+   (*f)->x = value;
+}
+void Foo_bar(Foo *f) {
+   (*f)->bar();
+}
+
      +
      + +

      +These wrappers take a smart-pointer instance as an argument, but +dereference it in a way to gain access to the object returned by +operator->(). You should carefully compare these wrappers +to those in the first part of this chapter (they are slightly +different). +

      + +

      +The end result is that access looks very similar to C++. For +example, you could do this in Python: +

      + +
      +
      +>>> f = make_Foo()
+>>> print f.x
+0
+>>> f.bar()
+>>>
+
      +
      + +

      +When generating wrappers through a smart-pointer, SWIG tries to +generate wrappers for all methods and attributes that might be +accessible through operator->(). This includes any methods +that might be accessible through inheritance. However, there are a number of restrictions: +

      + +
        +
      • Member variables and methods are wrapped through a smart +pointer. Enumerations, constructors, and destructors are not wrapped. +
        • + +

      • If the smart-pointer class and the underlying object both define a method or +variable of the same name, then the smart-pointer version has precedence. For +example, if you have this code

        + +
        +
        +class Foo {
+public:
+    int x;
+};
+
+class Bar {
+public:
+    int x;       
+    Foo *operator->();
+};
+
        +
        + +

        +then the wrapper for Bar::x accesses the x defined in Bar, and +not the x defined in Foo.

        +
        • +
      + +

      +If your intent is to only expose the smart-pointer class in the interface, it is not necessary to wrap both +the smart-pointer class and the class for the underlying object. However, you must still tell SWIG about both +classes if you want the technique described in this section to work. To only generate wrappers for the +smart-pointer class, you can use the %ignore directive. For example: +

      + +
      +
      +%ignore Foo;
+class Foo {       // Ignored
+};
+
+class Bar {
+public:
+   Foo *operator->();
+   ...
+};
+
      +
      + +

      +Alternatively, you can import the definition of Foo from a separate file using +%import. +

      + +

      +Note: When a class defines operator->(), the operator itself is wrapped +as a method __deref__(). For example: +

      + +
      +
      +f = Foo()               # Smart-pointer
+p = f.__deref__()       # Raw pointer from operator->
+
      +
      + +

      +Note: To disable the smart-pointer behavior, use %ignore to ignore +operator->(). For example: +

      + +
      +
      +%ignore Bar::operator->;
+
      +
      + +

      +Note: Smart pointer support was first added in SWIG-1.3.14. +

      + + +

      6.25 Using declarations and inheritance

      + + +

      +using declarations are sometimes used to adjust access to members of +base classes. For example: +

      + +
      +
      +class Foo {
+public:
+      int  blah(int x);
+};
+
+class Bar {
+public:
+      double blah(double x);
+};
+
+class FooBar : public Foo, public Bar {
+public:
+      using Foo::blah;  
+      using Bar::blah;
+      char *blah(const char *x);
+};
+
      +
      + +

      +In this example, the using declarations make different +versions of the overloaded blah() method accessible from the +derived class. For example: +

      + +
      +
      +FooBar *f;
+f->blah(3);         // Ok. Invokes Foo::blah(int)
+f->blah(3.5);       // Ok. Invokes Bar::blah(double)
+f->blah("hello");   // Ok. Invokes FooBar::blah(const char *);
+
      +
      + +

      +SWIG emulates the same functionality when creating wrappers. For example, if +you wrap this code in Python, the module works just like you would expect: +

      + +
      +
      +>>> import example
+>>> f = example.FooBar()
+>>> f.blah(3)
+>>> f.blah(3.5)
+>>> f.blah("hello")
+
      +
      + +

      +using declarations can also be used to change access when applicable. For example: +

      + +
      +
      +class Foo {
+protected:
+    int x;
+    int blah(int x);
+};
+
+class Bar : public Foo {
+public:
+    using Foo::x;       // Make x public
+    using Foo::blah;    // Make blah public
+};
+
      +
      + +

      +This also works in SWIG---the exposed declarations will be wrapped normally. +

      + +

      +When using declarations are used as shown in these examples, declarations +from the base classes are copied into the derived class and wrapped normally. When +copied, the declarations retain any properties that might have been attached using +%rename, %ignore, or %feature. Thus, if a method is +ignored in a base class, it will also be ignored by a using declaration. +

      + +

      +Because a using declaration does not provide fine-grained +control over the declarations that get imported, it may be difficult +to manage such declarations in applications that make heavy use of +SWIG customization features. If you can't get using to work +correctly, you can always change the interface to the following: +

      + +
      +
      +
+class FooBar : public Foo, public Bar {
+public:
+#ifndef SWIG
+      using Foo::blah;  
+      using Bar::blah;
+#else
+      int blah(int x);         // explicitly tell SWIG about other declarations
+      double blah(double x);
+#endif
+
+      char *blah(const char *x);
+};
+
      +
      + +

      +Notes: +

      + +
        +

      • If a derived class redefines a method defined in a base class, then a using declaration +won't cause a conflict. For example:

        + +
        +
        +class Foo {
+public:
+       int blah(int );
+       double blah(double);
+};
+
+class Bar : public Foo {
+public:
+       using Foo::blah;    // Only imports blah(double);
+       int blah(int);
+};
+
        +
        + +

      • Resolving ambiguity in overloading may prevent declarations from being +imported by using. For example: +

        + +
        +
        +%rename(blah_long) Foo::blah(long);
+class Foo {
+public:
+     int blah(int);
+     long blah(long);  // Renamed to blah_long
+};
+
+class Bar : public Foo {
+public:
+     using Foo::blah;     // Only imports blah(int)
+     double blah(double x);
+};
+
        +
        +
      + +

      6.26 Nested classes

      + + +

      +There is limited support for nested structs and unions when wrapping C code, see Nested structures for further details. +However, there is no nested class/struct/union support when wrapping C++ code (using the -c++ commandline option). +This may be added at a future date, however, until then some of the following workarounds can be applied. +

      + +

      +It might be possible to use partial class information. Since +SWIG does not need the entire class specification to work, conditional +compilation can be used to comment out the problematic nested class definition, you might do this: +

      + +
      +
      +class Foo {
+public:
+#ifndef SWIG
+   class Bar {
+   public:
+     ...
+   };
+#endif
+   Foo();
+  ~Foo();
+   ...
+};
+
      +
      + +

      +The next workaround assumes you cannot modify the source code as was done above and it provides a solution for methods that use nested class types. +Imagine we are wrapping the Outer class which contains a nested class Inner: +

      + +
      +
      +// File outer.h
+class Outer {
+public:
+  class Inner {
+    public:
+      int var;
+      Inner(int v = 0) : var(v) {}
+  };
+  void method(Inner inner);
+};
+
      +
      + +

      +The following interface file works around SWIG nested class limitations by redefining the nested class as a global class. +A typedef for the compiler is also required in order for the generated wrappers to compile. +

      + +
      +
      +// File : example.i
+%module example
+
+// Suppress SWIG warning
+#pragma SWIG nowarn=SWIGWARN_PARSE_NESTED_CLASS
+
+// Redefine nested class in global scope in order for SWIG to generate
+// a proxy class. Only SWIG parses this definition.
+class Inner {
+  public:
+    int var;
+    Inner(int v = 0) : var(v) {}
+};
+
+%{
+#include "outer.h"
+%}
+%include "outer.h"
+
+%{
+// SWIG thinks that Inner is a global class, so we need to trick the C++
+// compiler into understanding this so called global type.
+typedef Outer::Inner Inner;
+%}
+
+
      +
      + +

      +The downside to this approach is having to maintain two definitions of Inner, the real one and the one in the interface file that SWIG parses. +

      + +

      6.27 A brief rant about const-correctness

      + + +

      +A common issue when working with C++ programs is dealing with all +possible ways in which the const qualifier (or lack thereof) +will break your program, all programs linked against your program, and +all programs linked against those programs. +

      + +

      +Although SWIG knows how to correctly deal with const in its +internal type system and it knows how to generate wrappers that are +free of const-related warnings, SWIG does not make any attempt to preserve +const-correctness in the target language. Thus, it is possible to +pass const qualified objects to non-const methods and functions. +For example, consider the following code in C++: +

      + +
      +
      +const Object * foo();
+void bar(Object *);
+
+...
+// C++ code
+void blah() {
+   bar(foo());         // Error: bar discards const
+};
+
      +
      + +

      +Now, consider the behavior when wrapped into a Python module: +

      + +
      +
      +>>> bar(foo())         # Okay
+>>> 
+
      +
      + +

      +Although this is clearly a violation of the C++ type-system, fixing +the problem doesn't seem to be worth the added implementation +complexity that would be required to support it in the SWIG run-time type +system. There are no plans to change this in future releases +(although we'll never rule anything out entirely). +

      + +

      +The bottom line is that this particular issue does not appear to be a problem +for most SWIG projects. Of course, you might want to consider +using another tool if maintaining constness is the most important part +of your project. +

      + +

      6.28 Where to go for more information

      + + +

      +If you're wrapping serious C++ code, you might want to pick up a copy +of "The Annotated C++ Reference Manual" by Ellis and Stroustrup. This +is the reference document we use to guide a lot of SWIG's C++ support. +

      + + + + + + + diff --git a/Doc/Manual/Scripting.html b/Doc/Manual/Scripting.html new file mode 100644 index 0000000..e6a2eee --- /dev/null +++ b/Doc/Manual/Scripting.html @@ -0,0 +1,474 @@ + + + +Scripting Languages + + + + +

      4 Scripting Languages

      + +
      + +
      + + + + +

      +This chapter provides a brief overview of scripting language extension +programming and the mechanisms by which scripting language interpreters +access C and C++ code. +

      + +

      4.1 The two language view of the world

      + + +

      +When a scripting language is used to control a C program, the +resulting system tends to look as follows: +

      + +
      Scripting language input - C/C++ functions output
      + +

      +In this programming model, the scripting language interpreter is used +for high level control whereas the underlying functionality of the +C/C++ program is accessed through special scripting language +"commands." If you have ever tried to write your own simple command +interpreter, you might view the scripting language approach +to be a highly advanced implementation of that. Likewise, +If you have ever used a package such as MATLAB or IDL, it is a +very similar model--the interpreter executes user commands and +scripts. However, most of the underlying functionality is written in +a low-level language like C or Fortran. +

      + +

      +The two-language model of computing is extremely powerful because it +exploits the strengths of each language. C/C++ can be used for maximal +performance and complicated systems programming tasks. Scripting +languages can be used for rapid prototyping, interactive debugging, +scripting, and access to high-level data structures such associative +arrays.

      + +

      4.2 How does a scripting language talk to C?

      + + +

      +Scripting languages are built around a parser that knows how +to execute commands and scripts. Within this parser, there is a +mechanism for executing commands and accessing variables. +Normally, this is used to implement the builtin features +of the language. However, by extending the interpreter, it is usually +possible to add new commands and variables. To do this, +most languages define a special API for adding new commands. +Furthermore, a special foreign function interface defines how these +new commands are supposed to hook into the interpreter. +

      + +

      +Typically, when you add a new command to a scripting interpreter +you need to do two things; first you need to write a special +"wrapper" function that serves as the glue between the interpreter +and the underlying C function. Then you need to give the interpreter +information about the wrapper by providing details about the name of the +function, arguments, and so forth. The next few sections illustrate +the process. +

      + +

      4.2.1 Wrapper functions

      + + +

      +Suppose you have an ordinary C function like this :

      + +
      +int fact(int n) {
+	if (n <= 1) return 1;
+	else return n*fact(n-1);
+}
+
      + +

      +In order to access this function from a scripting language, it is +necessary to write a special "wrapper" function that serves as the +glue between the scripting language and the underlying C function. A +wrapper function must do three things :

      + +
        +
      • Gather function arguments and make sure they are valid. +
      • Call the C function. +
      • Convert the return value into a form recognized by the scripting language. +
      + +

      +As an example, the Tcl wrapper function for the fact() +function above example might look like the following :

      + +
      +int wrap_fact(ClientData clientData, Tcl_Interp *interp,
+		int argc, char *argv[]) {
+	int result;
+	int arg0;
+	if (argc != 2) {
+		interp->result = "wrong # args";
+		return TCL_ERROR;
+	}
+	arg0 = atoi(argv[1]);
+	result = fact(arg0);
+	sprintf(interp->result,"%d", result);
+	return TCL_OK;
+}
+
+
      + +

      +Once you have created a wrapper function, the final step is to tell the +scripting language about the new function. This is usually done in an +initialization function called by the language when the module is +loaded. For example, adding the above function to the Tcl interpreter +requires code like the following :

      + +
      +int Wrap_Init(Tcl_Interp *interp) {
+	Tcl_CreateCommand(interp, "fact", wrap_fact, (ClientData) NULL,
+				(Tcl_CmdDeleteProc *) NULL);
+	return TCL_OK;
+}
+
      + +

      +When executed, Tcl will now have a new command called "fact" +that you can use like any other Tcl command.

      + +

      +Although the process of adding a new function to Tcl has been +illustrated, the procedure is almost identical for Perl and +Python. Both require special wrappers to be written and both need +additional initialization code. Only the specific details are +different.

      + +

      4.2.2 Variable linking

      + + +

      +Variable linking refers to the problem of mapping a +C/C++ global variable to a variable in the scripting +language interpreter. For example, suppose you had the following +variable:

      + +
      +double Foo = 3.5;
+
      + +

      +It might be nice to access it from a script as follows (shown for Perl):

      + +
      +$a = $Foo * 2.3;   # Evaluation
+$Foo = $a + 2.0;   # Assignment
+
      + +

      +To provide such access, variables are commonly manipulated using a +pair of get/set functions. For example, whenever the value of a +variable is read, a "get" function is invoked. Similarly, whenever +the value of a variable is changed, a "set" function is called. +

      + +

      +In many languages, calls to the get/set functions can be attached to +evaluation and assignment operators. Therefore, evaluating a variable +such as $Foo might implicitly call the get function. Similarly, +typing $Foo = 4 would call the underlying set function to change +the value. +

      + +

      4.2.3 Constants

      + + +

      +In many cases, a C program or library may define a large collection of +constants. For example: +

      + +
      +#define RED   0xff0000
+#define BLUE  0x0000ff
+#define GREEN 0x00ff00
+
      +

      +To make constants available, their values can be stored in scripting +language variables such as $RED, $BLUE, and +$GREEN. Virtually all scripting languages provide C +functions for creating variables so installing constants is usually +a trivial exercise. +

      + +

      4.2.4 Structures and classes

      + + +

      +Although scripting languages have no trouble accessing simple +functions and variables, accessing C/C++ structures and classes +present a different problem. This is because the implementation +of structures is largely related to the problem of +data representation and layout. Furthermore, certain language features +are difficult to map to an interpreter. For instance, what +does C++ inheritance mean in a Perl interface? +

      + +

      +The most straightforward technique for handling structures is to +implement a collection of accessor functions that hide the underlying +representation of a structure. For example, +

      + +
      +struct Vector {
+	Vector();
+	~Vector();
+	double x,y,z;
+};
+
+
      + +

      +can be transformed into the following set of functions : +

      + +
      +Vector *new_Vector();
+void delete_Vector(Vector *v);
+double Vector_x_get(Vector *v);
+double Vector_y_get(Vector *v);
+double Vector_z_get(Vector *v);
+void Vector_x_set(Vector *v, double x);
+void Vector_y_set(Vector *v, double y);
+void Vector_z_set(Vector *v, double z);
+
+
      +

      +Now, from an interpreter these function might be used as follows: +

      + +
      +% set v [new_Vector]
+% Vector_x_set $v 3.5
+% Vector_y_get $v
+% delete_Vector $v
+% ...
+
      + +

      +Since accessor functions provide a mechanism for accessing the +internals of an object, the interpreter does not need to know anything +about the actual representation of a Vector. +

      + +

      4.2.5 Proxy classes

      + + +

      +In certain cases, it is possible to use the low-level accessor functions +to create a proxy class, also known as a shadow class. +A proxy class is a special kind of object that gets created +in a scripting language to access a C/C++ class (or struct) in a way +that looks like the original structure (that is, it proxies the real +C++ class). For example, if you +have the following C definition :

      + +
      +class Vector {
+public:
+	Vector();
+	~Vector();
+	double x,y,z;
+};
+
      + +

      +A proxy classing mechanism would allow you to access the structure in +a more natural manner from the interpreter. For example, in Python, you might want to do this: +

      + +
      +>>> v = Vector()
+>>> v.x = 3
+>>> v.y = 4
+>>> v.z = -13
+>>> ...
+>>> del v
+
      + +

      +Similarly, in Perl5 you may want the interface to work like this:

      + +
      +$v = new Vector;
+$v->{x} = 3;
+$v->{y} = 4;
+$v->{z} = -13;
+
+
      +

      +Finally, in Tcl : +

      + +
      +Vector v
+v configure -x 3 -y 4 -z 13
+
+
      + +

      +When proxy classes are used, two objects are at really work--one in +the scripting language, and an underlying C/C++ object. Operations +affect both objects equally and for all practical purposes, it appears +as if you are simply manipulating a C/C++ object. +

      + +

      4.3 Building scripting language extensions

      + + +

      +The final step in using a scripting language with your C/C++ +application is adding your extensions to the scripting language +itself. There are two primary approaches for doing +this. The preferred technique is to build a dynamically loadable +extension in the form a shared library. Alternatively, you can +recompile the scripting language interpreter with your extensions +added to it. +

      + +

      4.3.1 Shared libraries and dynamic loading

      + + +

      +To create a shared library or DLL, you often need to look at the +manual pages for your compiler and linker. However, the procedure +for a few common machines is shown below:

      + +
      +# Build a shared library for Solaris
+gcc -c example.c example_wrap.c -I/usr/local/include
+ld -G example.o example_wrap.o -o example.so
+
+# Build a shared library for Linux
+gcc -fpic -c example.c example_wrap.c -I/usr/local/include
+gcc -shared example.o example_wrap.o -o example.so
+
+# Build a shared library for Irix
+gcc -c example.c example_wrap.c -I/usr/local/include
+ld -shared example.o example_wrap.o -o example.so
+
+
      + +

      +To use your shared library, you simply use the corresponding command +in the scripting language (load, import, use, etc...). This will +import your module and allow you to start using it. For example: +

      + +
      +% load ./example.so
+% fact 4
+24
+%
+
      + +

      +When working with C++ codes, the process of building shared libraries +may be more complicated--primarily due to the fact that C++ modules may need +additional code in order to operate correctly. On many machines, you +can build a shared C++ module by following the above procedures, but +changing the link line to the following :

      + +
      +c++ -shared example.o example_wrap.o -o example.so
+
      + +

      4.3.2 Linking with shared libraries

      + + +

      +When building extensions as shared libraries, it is not uncommon for +your extension to rely upon other shared libraries on your machine. In +order for the extension to work, it needs to be able to find all of +these libraries at run-time. Otherwise, you may get an error such as +the following :

      + +
      +>>> import graph
+Traceback (innermost last):
+  File "<stdin>", line 1, in ?
+  File "/home/sci/data1/beazley/graph/graph.py", line 2, in ?
+    import graphc
+ImportError:  1101:/home/sci/data1/beazley/bin/python: rld: Fatal Error: cannot 
+successfully map soname 'libgraph.so' under any of the filenames /usr/lib/libgraph.so:/
+lib/libgraph.so:/lib/cmplrs/cc/libgraph.so:/usr/lib/cmplrs/cc/libgraph.so:
+>>>
+
      +

      + +What this error means is that the extension module created by SWIG +depends upon a shared library called "libgraph.so" that the +system was unable to locate. To fix this problem, there are a few +approaches you can take.

      + +
        +
      • Link your extension and explicitly tell the linker where the +required libraries are located. Often times, this can be done with a +special linker flag such as -R, -rpath, etc. This +is not implemented in a standard manner so read the man pages for your +linker to find out more about how to set the search path for shared +libraries. + +
      • Put shared libraries in the same directory as the executable. This +technique is sometimes required for correct operation on non-Unix +platforms. + +
      • Set the UNIX environment variable LD_LIBRARY_PATH to the +directory where shared libraries are located before running Python. +Although this is an easy solution, it is not recommended. Consider setting +the path using linker options instead. + +
      + +

      4.3.3 Static linking

      + + +

      +With static linking, you rebuild the scripting language interpreter +with extensions. The process usually involves compiling a short main +program that adds your customized commands to the language and starts +the interpreter. You then link your program with a library to produce +a new scripting language executable. +

      + +

      +Although static linking is supported on all platforms, this is not +the preferred technique for building scripting language +extensions. In fact, there are very few practical reasons for doing this--consider +using shared libraries instead. +

      + + + diff --git a/Doc/Manual/Sections.html b/Doc/Manual/Sections.html new file mode 100644 index 0000000..e39633e --- /dev/null +++ b/Doc/Manual/Sections.html @@ -0,0 +1,86 @@ + + + +SWIG-1.3 Documentation + + +

      SWIG-1.3 Development Documentation

      + +Last update : SWIG-1.3.40 (18 August 2009) + +

      Sections

      + +

      +The SWIG documentation is being updated to reflect new SWIG +features and enhancements. However, this update process is not quite +finished--there is a lot of old SWIG-1.1 documentation and it is taking +some time to update all of it. Please pardon our dust (or volunteer +to help!). +

      + +

      SWIG Core Documentation

      + + +

      Language Module Documentation

      + + + +

      Developer Documentation

      + + + +

      Documentation that has not yet been updated

      + +

      +This documentation has not been completely updated from SWIG-1.1, but most of the topics +still apply to the current release. Make sure you read the +SWIG Basics chapter before reading +any of these chapters. Also, SWIG-1.3.10 features extensive changes to the +implementation of typemaps. Make sure you read the Typemaps +chapter above if you are using this feature. +

      + + + + + diff --git a/Doc/Manual/Tcl.html b/Doc/Manual/Tcl.html new file mode 100644 index 0000000..8b8c74d --- /dev/null +++ b/Doc/Manual/Tcl.html @@ -0,0 +1,3436 @@ + + + +SWIG and Tcl + + + + +

      33 SWIG and Tcl

      + +
      + +
      + + + + +

      +Caution: This chapter is under repair! +

      + +

      +This chapter discusses SWIG's support of Tcl. SWIG currently requires +Tcl 8.0 or a later release. Earlier releases of SWIG supported Tcl 7.x, but +this is no longer supported. +

      + +

      33.1 Preliminaries

      + + +

      +To build a Tcl module, run SWIG using the -tcl option : +

      + +
      +$ swig -tcl example.i
+
      + +

      +If building a C++ extension, add the -c++ option: +

      + +
      +$ swig -c++ -tcl example.i
+
      + +

      +This creates a file example_wrap.c or +example_wrap.cxx that contains all of the code needed to +build a Tcl extension module. To finish building the module, you +need to compile this file and link it with the rest of your program. +

      + +

      33.1.1 Getting the right header files

      + + +

      +In order to compile the wrapper code, the compiler needs the tcl.h header file. +This file is usually contained in the directory +

      + +
      +/usr/local/include
+
      + +

      +Be aware that some Tcl versions install this header file with a version number attached to it. If +this is the case, you should probably make a symbolic link so that tcl.h points to the correct +header file. +

      + +

      33.1.2 Compiling a dynamic module

      + + +

      +The preferred approach to building an extension module is to compile it into +a shared object file or DLL. To do this, you will need to compile your program +using commands like this (shown for Linux): +

      + +
      +$ swig -tcl example.i
+$ gcc -c example.c
+$ gcc -c example_wrap.c -I/usr/local/include
+$ gcc -shared example.o example_wrap.o -o example.so
+
      + +

      +The exact commands for doing this vary from platform to platform. +SWIG tries to guess the right options when it is installed. Therefore, +you may want to start with one of the examples in the SWIG/Examples/tcl +directory. If that doesn't work, you will need to read the man-pages for +your compiler and linker to get the right set of options. You might also +check the SWIG Wiki for +additional information. +

      + +

      +When linking the module, the name of the output file has to match the name +of the module. If the name of your SWIG module is "example", the +name of the corresponding object file should be +"example.so". +The name of the module is specified using the %module directive or the + -module command line option. +

      + +

      33.1.3 Static linking

      + + +

      +An alternative approach to dynamic linking is to rebuild the Tcl +interpreter with your extension module added to it. In the past, +this approach was sometimes necessary due to limitations in dynamic loading +support on certain machines. However, the situation has improved greatly +over the last few years and you should not consider this approach +unless there is really no other option. +

      + +

      +The usual procedure for adding a new module to Tcl involves writing a +special function Tcl_AppInit() and using it to initialize the interpreter and +your module. With SWIG, the tclsh.i and wish.i library files +can be used to rebuild the tclsh and wish interpreters respectively. +For example: +

      + +
      +%module example
+
+%inline %{
+extern int fact(int);
+extern int mod(int, int);
+extern double My_variable;
+%}
+
+%include "tclsh.i"       // Include code for rebuilding tclsh
+
+
      + +

      +The tclsh.i library file includes supporting code that +contains everything needed to rebuild tclsh. To rebuild the interpreter, +you simply do something like this: +

      + +
      +$ swig -tcl example.i
+$ gcc example.c example_wrap.c \
+        -Xlinker -export-dynamic \
+        -DHAVE_CONFIG_H -I/usr/local/include/ \
+	-L/usr/local/lib -ltcl -lm -ldl \
+	-o mytclsh
+
+
      + +

      +You will need to supply the same libraries that were used to build Tcl the first +time. This may include system libraries such as -lsocket, -lnsl, +and -lpthread. If this actually works, the new version of Tcl +should be identical to the default version except that your extension module will be +a built-in part of the interpreter. +

      + +

      +Comment: In practice, you should probably try to avoid static +linking if possible. Some programmers may be inclined +to use static linking in the interest of getting better performance. +However, the performance gained by static linking tends to be rather +minimal in most situations (and quite frankly not worth the extra +hassle in the opinion of this author). +

      + +

      33.1.4 Using your module

      + + +

      +To use your module, simply use the Tcl load command. If +all goes well, you will be able to this: +

      + +
      +$ tclsh
+% load ./example.so
+% fact 4
+24
+%
+
      + +

      +A common error received by first-time users is the following: +

      + +
      +
      +% load ./example.so
+couldn't find procedure Example_Init
+% 
+
      +
      + +

      +This error is almost always caused when the name of the shared object file doesn't +match the name of the module supplied using the SWIG %module directive. +Double-check the interface to make sure the module name and the shared object +file match. Another possible cause of this error is forgetting to link the SWIG-generated +wrapper code with the rest of your application when creating the extension module. +

      + +

      +Another common error is something similar to the following: +

      + +
      +
      +% load ./example.so
+couldn't load file "./example.so": ./example.so: undefined symbol: fact
+% 
+
      +
      + +

      +This error usually indicates that you forgot to include some object +files or libraries in the linking of the shared library file. Make +sure you compile both the SWIG wrapper file and your original program +into a shared library file. Make sure you pass all of the required libraries +to the linker. +

      + +

      +Sometimes unresolved symbols occur because a wrapper has been created +for a function that doesn't actually exist in a library. This usually +occurs when a header file includes a declaration for a function that +was never actually implemented or it was removed from a library +without updating the header file. To fix this, you can either edit +the SWIG input file to remove the offending declaration or you can use +the %ignore directive to ignore the declaration. +

      + +

      +Finally, suppose that your extension module is linked with another library like this: +

      + +
      +
      +$ gcc -shared example.o example_wrap.o -L/home/beazley/projects/lib -lfoo \
+      -o example.so
+
      +
      + +

      +If the foo library is compiled as a shared library, you might get the following +problem when you try to use your module: +

      + +
      +
      +% load ./example.so
+couldn't load file "./example.so": libfoo.so: cannot open shared object file:
+No such file or directory
+%        
+
      +
      + +

      +This error is generated because the dynamic linker can't locate the +libfoo.so library. When shared libraries are loaded, the +system normally only checks a few standard locations such as +/usr/lib and /usr/local/lib. To fix this problem, +there are several things you can do. First, you can recompile your extension +module with extra path information. For example, on Linux you can do this: +

      + +
      +
      +$ gcc -shared example.o example_wrap.o -L/home/beazley/projects/lib -lfoo \
+      -Xlinker -rpath /home/beazley/projects/lib \
+      -o example.so
+
      +
      + +

      +Alternatively, you can set the LD_LIBRARY_PATH environment variable to +include the directory with your shared libraries. +If setting LD_LIBRARY_PATH, be aware that setting this variable can introduce +a noticeable performance impact on all other applications that you run. +To set it only for Tcl, you might want to do this instead: +

      + +
      +
      +$ env LD_LIBRARY_PATH=/home/beazley/projects/lib tclsh
+
      +
      + +

      +Finally, you can use a command such as ldconfig to add additional search paths +to the default system configuration (this requires root access and you will need to read +the man pages). +

      + +

      33.1.5 Compilation of C++ extensions

      + + +

      +Compilation of C++ extensions has traditionally been a tricky problem. +Since the Tcl interpreter is written in C, you need to take steps to +make sure C++ is properly initialized and that modules are compiled +correctly. +

      + +

      +On most machines, C++ extension modules should be linked using the C++ +compiler. For example: +

      + +
      +% swig -c++ -tcl example.i
+% g++ -c example.cxx
+% g++ -c example_wrap.cxx -I/usr/local/include
+% g++ -shared example.o example_wrap.o -o example.so
+
      + +

      +In addition to this, you may need to include additional library +files to make it work. For example, if you are using the Sun C++ compiler on +Solaris, you often need to add an extra library -lCrun like this: +

      + +
      +% swig -c++ -tcl example.i
+% CC -c example.cxx
+% CC -c example_wrap.cxx -I/usr/local/include
+% CC -G example.o example_wrap.o -L/opt/SUNWspro/lib -o example.so -lCrun
+
      + +

      +Of course, the extra libraries to use are completely non-portable---you will +probably need to do some experimentation. +

      + +

      +Sometimes people have suggested that it is necessary to relink the +Tcl interpreter using the C++ compiler to make C++ extension modules work. +In the experience of this author, this has never actually appeared to be +necessary. Relinking the interpreter with C++ really only includes the +special run-time libraries described above---as long as you link your extension +modules with these libraries, it should not be necessary to rebuild Tcl. +

      + +

      +If you aren't entirely sure about the linking of a C++ extension, you +might look at an existing C++ program. On many Unix machines, the +ldd command will list library dependencies. This should give +you some clues about what you might have to include when you link your +extension module. For example: +

      + +
      +
      +$ ldd swig
+        libstdc++-libc6.1-1.so.2 => /usr/lib/libstdc++-libc6.1-1.so.2 (0x40019000)
+        libm.so.6 => /lib/libm.so.6 (0x4005b000)
+        libc.so.6 => /lib/libc.so.6 (0x40077000)
+        /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
+$
+
      +
      + +

      +As a final complication, a major weakness of C++ is that it does not +define any sort of standard for binary linking of libraries. This +means that C++ code compiled by different compilers will not link +together properly as libraries nor is the memory layout of classes and +data structures implemented in any kind of portable manner. In a +monolithic C++ program, this problem may be unnoticed. However, in Tcl, it +is possible for different extension modules to be compiled with +different C++ compilers. As long as these modules are self-contained, +this probably won't matter. However, if these modules start sharing data, +you will need to take steps to avoid segmentation faults and other +erratic program behavior. If working with lots of software components, you +might want to investigate using a more formal standard such as COM. +

      + +

      33.1.6 Compiling for 64-bit platforms

      + + +

      +On platforms that support 64-bit applications (Solaris, Irix, etc.), +special care is required when building extension modules. On these +machines, 64-bit applications are compiled and linked using a different +set of compiler/linker options. In addition, it is not generally possible to mix +32-bit and 64-bit code together in the same application. +

      + +

      +To utilize 64-bits, the Tcl executable will need to be recompiled +as a 64-bit application. In addition, all libraries, wrapper code, +and every other part of your application will need to be compiled for +64-bits. If you plan to use other third-party extension modules, they +will also have to be recompiled as 64-bit extensions. +

      + +

      +If you are wrapping commercial software for which you have no source +code, you will be forced to use the same linking standard as used by +that software. This may prevent the use of 64-bit extensions. It may +also introduce problems on platforms that support more than one +linking standard (e.g., -o32 and -n32 on Irix). +

      + +

      33.1.7 Setting a package prefix

      + + +

      +To avoid namespace problems, you can instruct SWIG to append a package +prefix to all of your functions and variables. This is done using the +-prefix option as follows : +

      + +
      +swig -tcl -prefix Foo example.i
+
      + +

      +If you have a function "bar" in the SWIG file, the prefix +option will append the prefix to the name when creating a command and +call it "Foo_bar". +

      + +

      33.1.8 Using namespaces

      + + +

      +Alternatively, you can have SWIG install your module into a Tcl +namespace by specifying the -namespace option : +

      + +
      +swig -tcl -namespace example.i
+
      + +

      +By default, the name of the namespace will be the same as the module +name, but you can override it using the -prefix option. +

      + +

      +When the -namespace option is used, objects in the module +are always accessed with the namespace name such as Foo::bar. +

      + +

      33.2 Building Tcl/Tk Extensions under Windows 95/NT

      + + +

      +Building a SWIG extension to Tcl/Tk under Windows 95/NT is roughly +similar to the process used with Unix. Normally, you will want to +produce a DLL that can be loaded into tclsh or wish. This section +covers the process of using SWIG with Microsoft Visual C++. +although the procedure may be similar with other compilers. +

      + +

      33.2.1 Running SWIG from Developer Studio

      + + +

      +If you are developing your application within Microsoft developer +studio, SWIG can be invoked as a custom build option. The process +roughly follows these steps : +

      + +
        +
      • Open up a new workspace and use the AppWizard to select a DLL project. + +
      • Add both the SWIG interface file (the .i file), any supporting C +files, and the name of the wrapper file that will be created by SWIG +(ie. example_wrap.c). Note : If using C++, choose a +different suffix for the wrapper file such as +example_wrap.cxx. Don't worry if the wrapper file doesn't +exist yet--Developer studio will keep a reference to it around. + +
      • Select the SWIG interface file and go to the settings menu. Under +settings, select the "Custom Build" option. + +
      • Enter "SWIG" in the description field. + +
      • Enter "swig -tcl -o $(ProjDir)\$(InputName)_wrap.c +$(InputPath)" in the "Build command(s) field" + +
      • Enter "$(ProjDir)\$(InputName)_wrap.c" in the "Output files(s) field". + +
      • Next, select the settings for the entire project and go to +"C++:Preprocessor". Add the include directories for your Tcl +installation under "Additional include directories". + +
      • Finally, select the settings for the entire project and go to +"Link Options". Add the Tcl library file to your link libraries. For +example "tcl80.lib". Also, set the name of the output file +to match the name of your Tcl module (ie. example.dll). + +
      • Build your project. +
      + +

      +Now, assuming all went well, SWIG will be automatically invoked when +you build your project. Any changes made to the interface file will +result in SWIG being automatically invoked to produce a new version of +the wrapper file. To run your new Tcl extension, simply run +tclsh or wish and use the load command. +For example : +

      + +
      +MSDOS > tclsh80
+% load example.dll
+% fact 4
+24
+%
+
      + +

      33.2.2 Using NMAKE

      + + +

      +Alternatively, SWIG extensions can be built by writing a Makefile for +NMAKE. To do this, make sure the environment variables for MSVC++ are +available and the MSVC++ tools are in your path. Now, just write a +short Makefile like this : +

      + +
      +# Makefile for building various SWIG generated extensions
+
+SRCS          = example.c
+IFILE         = example
+INTERFACE     = $(IFILE).i
+WRAPFILE      = $(IFILE)_wrap.c
+
+# Location of the Visual C++ tools (32 bit assumed)
+
+TOOLS         = c:\msdev
+TARGET        = example.dll
+CC            = $(TOOLS)\bin\cl.exe
+LINK          = $(TOOLS)\bin\link.exe
+INCLUDE32     = -I$(TOOLS)\include
+MACHINE       = IX86
+
+# C Library needed to build a DLL
+
+DLLIBC        = msvcrt.lib oldnames.lib  
+
+# Windows libraries that are apparently needed
+WINLIB        = kernel32.lib advapi32.lib user32.lib gdi32.lib comdlg32.lib 
+winspool.lib
+
+# Libraries common to all DLLs
+LIBS          = $(DLLIBC) $(WINLIB) 
+
+# Linker options
+LOPT      = -debug:full -debugtype:cv /NODEFAULTLIB /RELEASE /NOLOGO /
+MACHINE:$(MACHINE) -entry:_DllMainCRTStartup@12 -dll
+
+# C compiler flags
+
+CFLAGS    = /Z7 /Od /c /nologo
+TCL_INCLUDES  = -Id:\tcl8.0a2\generic -Id:\tcl8.0a2\win
+TCLLIB        = d:\tcl8.0a2\win\tcl80.lib
+
+tcl::
+	..\..\swig -tcl -o $(WRAPFILE) $(INTERFACE)
+	$(CC) $(CFLAGS) $(TCL_INCLUDES) $(SRCS) $(WRAPFILE)
+	set LIB=$(TOOLS)\lib
+	$(LINK) $(LOPT) -out:example.dll $(LIBS) $(TCLLIB) example.obj example_wrap.obj
+
+
      + +

      +To build the extension, run NMAKE (you may need to run vcvars32 +first). This is a pretty minimal Makefile, but hopefully its enough +to get you started. With a little practice, you'll be making lots of +Tcl extensions. +

      + +

      33.3 A tour of basic C/C++ wrapping

      + + +

      +By default, SWIG tries to build a very natural Tcl interface to your +C/C++ code. Functions are wrapped as functions, classes are wrapped +in an interface that mimics the style of Tk widgets and [incr Tcl] +classes. This section briefly covers the essential aspects of this +wrapping. +

      + +

      33.3.1 Modules

      + + +

      +The SWIG %module directive specifies the name of the Tcl +module. If you specify `%module example', then everything is +compiled into an extension module example.so. When choosing a +module name, make sure you don't use the same name as a built-in +Tcl command. +

      + +

      +One pitfall to watch out for is module names involving numbers. If +you specify a module name like %module md5, you'll find that the +load command no longer seems to work: +

      + +
      +
      +% load ./md5.so
+couldn't find procedure Md_Init
+
      +
      + +

      +To fix this, supply an extra argument to load like this: +

      + +
      +
      +% load ./md5.so md5
+
      +
      + +

      33.3.2 Functions

      + + +

      +Global functions are wrapped as new Tcl built-in commands. For example, +

      + +
      +%module example
+int fact(int n);
+
      + +

      +creates a built-in function fact that works exactly +like you think it does: +

      + +
      +% load ./example.so
+% fact 4
+24
+% set x [fact 6]
+%
+
      + +

      33.3.3 Global variables

      + + +

      +C/C++ global variables are wrapped by Tcl global variables. For example: +

      + +
      +// SWIG interface file with global variables
+%module example
+...
+%inline %{
+extern double density;
+%}
+...
+
      + +

      +Now look at the Tcl interface: +

      + +
      +% puts $density          # Output value of C global variable
+1.0
+% set density 0.95       # Change value
+
      + +

      +If you make an error in variable assignment, you will get an +error message. For example: +

      + +
      +% set density "hello"
+can't set "density": Type error. expected a double.
+%
+
      + +

      +If a variable is declared as const, it is wrapped as a +read-only variable. Attempts to modify its value will result in an +error. +

      + +

      +To make ordinary variables read-only, you can use the %immutable directive. For example: +

      + +
      +
      +%{
+extern char *path;
+%}
+%immutable;
+extern char *path;
+%mutable;
+
      +
      + +

      +The %immutable directive stays in effect until it is explicitly disabled or cleared using +%mutable. +See the Creating read-only variables section for further details. +

      + +

      +If you just want to make a specific variable immutable, supply a declaration name. For example: +

      + +
      +
      +%{
+extern char *path;
+%}
+%immutable path;
+...
+extern char *path;      // Read-only (due to %immutable)
+
      +
      + +

      33.3.4 Constants and enums

      + + +

      +C/C++ constants are installed as global Tcl variables containing the +appropriate value. To create a constant, use #define, enum, or the +%constant directive. For example: +

      + +
      +
      +#define PI 3.14159
+#define VERSION "1.0"
+
+enum Beverage { ALE, LAGER, STOUT, PILSNER };
+
+%constant int FOO = 42;
+%constant const char *path = "/usr/local";
+
      +
      + +

      +For enums, make sure that the definition of the enumeration actually appears in a header +file or in the wrapper file somehow---if you just stick an enum in a SWIG interface without +also telling the C compiler about it, the wrapper code won't compile. +

      + +

      +Note: declarations declared as const are wrapped as read-only variables and +will be accessed using the cvar object described in the previous section. They +are not wrapped as constants. For further discussion about this, see the SWIG Basics chapter. +

      + +

      +Constants are not guaranteed to remain constant in Tcl---the value +of the constant could be accidentally reassigned.You will just have to be careful. +

      + +

      +A peculiarity of installing constants as variables is that it is necessary to use the Tcl global statement to +access constants in procedure bodies. For example: +

      + +
      +
      +proc blah {} {
+   global FOO
+   bar $FOO
+}
+
      +
      + +

      +If a program relies on a lot of constants, this can be extremely annoying. To fix the problem, consider using the +following typemap rule: +

      + +
      +
      +%apply int CONSTANT { int x };
+#define FOO 42
+...
+void bar(int x);
+
      +
      + +

      +When applied to an input argument, the CONSTANT rule allows a constant to be passed to a function using +its actual value or a symbolic identifier name. For example: +

      + +
      +
      +proc blah {} {
+   bar FOO
+}
+
      +
      + +

      +When an identifier name is given, it is used to perform an implicit hash-table lookup of the value during argument +conversion. This allows the global statement to be omitted. +

      + +

      33.3.5 Pointers

      + + +

      +C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no problem working with +incomplete type information. Here is a rather simple interface: +

      + +
      +
      +%module example
+
+FILE *fopen(const char *filename, const char *mode);
+int fputs(const char *, FILE *);
+int fclose(FILE *);
+
      +
      + +

      +When wrapped, you will be able to use the functions in a natural way from Tcl. +For example: +

      + +
      +
      +% load ./example.so
+% set f [fopen junk w]
+% fputs "Hello World\n" $f
+% fclose $f
+
      +
      + +

      +If this makes you uneasy, rest assured that there is no +deep magic involved. Underneath the covers, pointers to C/C++ objects are +simply represented as opaque values--normally an encoded character +string like this: +

      + +
      +% puts $f
+_c0671108_p_FILE
+% 
+
      + +

      +This pointer value can be freely passed around to different C functions that +expect to receive an object of type FILE *. The only thing you can't do is +dereference the pointer from Tcl. +

      + +

      +The NULL pointer is represented by the string NULL. +

      + +

      +As much as you might be inclined to modify a pointer value directly +from Tcl, don't. The hexadecimal encoding is not necessarily the +same as the logical memory address of the underlying object. Instead +it is the raw byte encoding of the pointer value. The encoding will +vary depending on the native byte-ordering of the platform (i.e., +big-endian vs. little-endian). Similarly, don't try to manually cast +a pointer to a new type by simply replacing the type-string. This +may not work like you expect and it is particularly dangerous when +casting C++ objects. If you need to cast a pointer or +change its value, consider writing some helper functions instead. For +example: +

      + +
      +
      +%inline %{
+/* C-style cast */
+Bar *FooToBar(Foo *f) {
+   return (Bar *) f;
+}
+
+/* C++-style cast */
+Foo *BarToFoo(Bar *b) {
+   return dynamic_cast<Foo*>(b);
+}
+
+Foo *IncrFoo(Foo *f, int i) {
+    return f+i;
+}
+%}
+
      +
      + +

      +Also, if working with C++, you should always try +to use the new C++ style casts. For example, in the above code, the +C-style cast may return a bogus result whereas as the C++-style cast will return +None if the conversion can't be performed. +

      + +

      33.3.6 Structures

      + + +

      +If you wrap a C structure, it is wrapped by a Tcl interface that somewhat resembles a Tk widget. +This provides a very natural interface. For example, +

      + +
      +struct Vector {
+	double x,y,z;
+};
+
+
      + +

      +is used as follows: +

      + +
      +% Vector v
+% v configure -x 3.5 -y 7.2
+% puts "[v cget -x] [v cget -y] [v cget -z]"
+3.5 7.2 0.0
+% 
+
      + +

      +Similar access is provided for unions and the data members of C++ classes. +

      + +

      +In the above example, v is a name that's used for the object. However, +underneath the covers, there's a pointer to a raw C structure. This can be obtained +by looking at the -this attribute. For example: +

      + +
      +
      +% puts [v cget -this]
+_88e31408_p_Vector
+
      +
      + +

      +Further details about the relationship between the Tcl and the underlying C structure +are covered a little later. +

      + +

      +const members of a structure are read-only. Data members +can also be forced to be read-only using the %immutable directive. For example: +

      + +
      +
      +struct Foo {
+   ...
+   %immutable;
+   int x;        /* Read-only members */
+   char *name;
+   %mutable;
+   ...
+};
+
      +
      + +

      +When char * members of a structure are wrapped, the contents are assumed to be +dynamically allocated using malloc or new (depending on whether or not +SWIG is run with the -c++ option). When the structure member is set, the old contents will be +released and a new value created. If this is not the behavior you want, you will have to use +a typemap (described later). +

      + +

      +If a structure contains arrays, access to those arrays is managed through pointers. For +example, consider this: +

      + +
      +
      +struct Bar {
+    int  x[16];
+};
+
      +
      + +

      +If accessed in Tcl, you will see behavior like this: +

      + +
      +
      +% Bar b
+% puts [b cget -x]
+_801861a4_p_int
+% 
+
      +
      + +

      +This pointer can be passed around to functions that expect to receive +an int * (just like C). You can also set the value of an array member using +another pointer. For example: +

      + +
      +
      +% Bar c
+% c configure -x [b cget -x]   # Copy contents of b.x to c.x
+
      +
      + +

      +For array assignment, SWIG copies the entire contents of the array starting with the data pointed +to by b.x. In this example, 16 integers would be copied. Like C, SWIG makes +no assumptions about bounds checking---if you pass a bad pointer, you may get a segmentation +fault or access violation. +

      + +

      +When a member of a structure is itself a structure, it is handled as a +pointer. For example, suppose you have two structures like this: +

      + +
      +
      +struct Foo {
+   int a;
+};
+
+struct Bar {
+   Foo f;
+};
+
      +
      + +

      +Now, suppose that you access the f attribute of Bar like this: +

      + +
      +
      +% Bar b
+% set x [b cget -f]
+
      +
      + +

      +In this case, x is a pointer that points to the Foo that is inside b. +This is the same value as generated by this C code: +

      + +
      +
      +Bar b;
+Foo *x = &b->f;       /* Points inside b */
+
      +
      + +

      +However, one peculiarity of accessing a substructure like this is that the returned +value does work quite like you might expect. For example: +

      + +
      +
      +% Bar b
+% set x [b cget -f]
+% x cget -a
+invalid command name "x"
+
      +
      + +

      +This is because the returned value was not created in a normal way from the interpreter (x is +not a command object). To make it function normally, just +evaluate the variable like this: +

      + +
      +
      +% Bar b
+% set x [b cget -f]
+% $x cget -a
+0
+%
+
      +
      + +

      +In this example, x points inside the original structure. This means that modifications +work just like you would expect. For example: +

      + +
      +
      +
+% Bar b
+% set x [b cget -f]
+% $x configure -a 3            # Modifies contents of f (inside b)
+% [b cget -f] -configure -a 3  # Same thing
+
      +
      + +

      +In many of these structure examples, a simple name like "v" or "b" has been given +to wrapped structures. If necessary, this name can be passed to functions +that expect to receive an object. For example, if you have a function like this, +

      + +
      +
      +void blah(Foo *f);
+
      +
      + +

      +you can call the function in Tcl as follows: +

      + +
      +
      +% Foo x            # Create a Foo object 
+% blah x           # Pass the object to a function
+
      +
      + +

      +It is also possible to call the function using the raw pointer value. For +instance: +

      + +
      +
      +% blah [x cget -this]   # Pass object to a function
+
      +
      + +

      +It is also possible to create and use objects using variables. For example: +

      + +
      +
      +% set b [Bar]            # Create a Bar
+% $b cget -f             # Member access
+% puts $b
+_108fea88_p_Bar
+%
+
      +
      + +

      +Finally, to destroy objects created from Tcl, you can either let the object +name go out of scope or you can explicitly delete the object. For example: +

      + +
      +
      +% Foo f                 # Create object f
+% rename f ""
+
      +
      + +

      +or +

      + +
      +
      +% Foo f                 # Create object f
+% f -delete
+
      +
      + +

      +Note: Tcl only destroys the underlying object if it has ownership. See the +memory management section that appears shortly. +

      + +

      33.3.7 C++ classes

      + + +

      +C++ classes are wrapped as an extension of structure wrapping. For example, if you have this class, +

      + +
      +class List {
+public:
+  List();
+  ~List();
+  int  search(char *item);
+  void insert(char *item);
+  void remove(char *item);
+  char *get(int n);
+  int  length;
+};
+
      + +

      +you can use it in Tcl like this: +

      + +
      +% List x
+% x insert Ale
+% x insert Stout
+% x insert Lager
+% x get 1
+Stout
+% puts [l cget -length]
+3
+%
+
      + +

      +Class data members are accessed in the same manner as C structures. +

      + +

      +Static class members are accessed as global functions or variables. +To illustrate, suppose you have a class like this: +

      + +
      +
      +class Spam {
+public:
+   static void foo();
+   static int bar;
+
+};
+
      +
      + +

      +In Tcl, the static member is accessed as follows: +

      + +
      +
      +% Spam_foo        # Spam::foo()
+% puts $Spam_bar  # Spam::bar
+
      +
      + +

      33.3.8 C++ inheritance

      + + +

      +SWIG is fully aware of issues related to C++ inheritance. Therefore, if you have +classes like this +

      + +
      +
      +class Foo {
+...
+};
+
+class Bar : public Foo {
+...
+};
+
      +
      + +

      +An object of type Bar can be used where a Foo is expected. For +example, if you have this function: +

      + +
      +
      +void spam(Foo *f);
+
      +
      + +

      +then the function spam() accepts a Foo * or a pointer to any class derived from Foo. +For instance: +

      + +
      +
      +% Foo f      # Create a Foo
+% Bar b      # Create a Bar
+% spam f     # OK
+% spam b     # OK
+
      +
      + +

      +It is safe to use multiple inheritance with SWIG. +

      + +

      33.3.9 Pointers, references, values, and arrays

      + + +

      +In C++, there are many different ways a function might receive +and manipulate objects. For example: +

      + +
      +
      +void spam1(Foo *x);      // Pass by pointer
+void spam2(Foo &x);      // Pass by reference
+void spam3(Foo x);       // Pass by value
+void spam4(Foo x[]);     // Array of objects
+
      +
      + +

      +In Tcl, there is no detailed distinction like this. +Because of this, SWIG unifies all of these types +together in the wrapper code. For instance, if you actually had the +above functions, it is perfectly legal to do this: +

      + +
      +
      +% Foo f             # Create a Foo
+% spam1 f           # Ok. Pointer
+% spam2 f           # Ok. Reference
+% spam3 f           # Ok. Value.
+% spam4 f           # Ok. Array (1 element)
+
      +
      + +

      +Similar behavior occurs for return values. For example, if you had +functions like this, +

      + +
      +
      +Foo *spam5();
+Foo &spam6();
+Foo  spam7();
+
      +
      + +

      +then all three functions will return a pointer to some Foo object. +Since the third function (spam7) returns a value, newly allocated memory is used +to hold the result and a pointer is returned (Tcl will release this memory +when the return value is garbage collected). +

      + +

      33.3.10 C++ overloaded functions

      + + +

      +C++ overloaded functions, methods, and constructors are mostly supported by SWIG. For example, +if you have two functions like this: +

      + +
      +
      +void foo(int);
+void foo(char *c);
+
      +
      + +

      +You can use them in Tcl in a straightforward manner: +

      + +
      +
      +% foo 3            # foo(int)
+% foo Hello        # foo(char *c)
+
      +
      + +

      +Similarly, if you have a class like this, +

      + +
      +
      +class Foo {
+public:
+    Foo();
+    Foo(const Foo &);
+    ...
+};
+
      +
      + +

      +you can write Tcl code like this: +

      + +
      +
      +% Foo f                # Create a Foo
+% Foo g f              # Copy f
+
      +
      + +

      +Overloading support is not quite as flexible as in C++. Sometimes there are methods that SWIG +can't disambiguate. For example: +

      + +
      +
      +void spam(int);
+void spam(short);
+
      +
      + +

      +or +

      + +
      +
      +void foo(Bar *b);
+void foo(Bar &b);
+
      +
      + +

      +If declarations such as these appear, you will get a warning message like this: +

      + +
      +
      +example.i:12: Warning(509): Overloaded spam(short) is shadowed by spam(int)
+at example.i:11.
+
      +
      + +

      +To fix this, you either need to ignore or rename one of the methods. For example: +

      + +
      +
      +%rename(spam_short) spam(short);
+...
+void spam(int);    
+void spam(short);   // Accessed as spam_short
+
      +
      + +

      +or +

      + +
      +
      +%ignore spam(short);
+...
+void spam(int);    
+void spam(short);   // Ignored
+
      +
      + +

      +SWIG resolves overloaded functions and methods using a disambiguation scheme that ranks and sorts +declarations according to a set of type-precedence rules. The order in which declarations appear +in the input does not matter except in situations where ambiguity arises--in this case, the +first declaration takes precedence. +

      + +

      +Please refer to the "SWIG and C++" chapter for more information about overloading. +

      + +

      33.3.11 C++ operators

      + + +

      +Certain C++ overloaded operators can be handled automatically by SWIG. For example, +consider a class like this: +

      + +
      +
      +class Complex {
+private:
+  double rpart, ipart;
+public:
+  Complex(double r = 0, double i = 0) : rpart(r), ipart(i) { }
+  Complex(const Complex &c) : rpart(c.rpart), ipart(c.ipart) { }
+  Complex &operator=(const Complex &c);
+  Complex operator+(const Complex &c) const;
+  Complex operator-(const Complex &c) const;
+  Complex operator*(const Complex &c) const;
+  Complex operator-() const;
+  
+  double re() const { return rpart; }
+  double im() const { return ipart; }
+};
+
      +
      + +

      +When wrapped, it works like this: +

      + +
      +
      +% Complex c 3 4
+% Complex d 7 8
+% set e [c + d]
+% $e re
+10.0
+% $e im
+12.0
+
      +
      + +

      +It should be stressed that operators in SWIG have no relationship to operators +in Tcl. In fact, the only thing that's happening here is that an operator like +operator + has been renamed to a method +. Therefore, the +statement [c + d] is really just invoking the + method on c. +When more than operator is defined (with different arguments), the standard +method overloading facilities are used. Here is a rather odd looking example: +

      + +
      +
      +% Complex c 3 4
+% Complex d 7 8
+% set e [c - d]       # operator-(const Complex &)
+% puts "[$e re] [$e im]"
+10.0 12.0
+% set f [c -]         # operator-()
+% puts "[$f re] [$f im]"
+-3.0 -4.0
+%
+
      +
      + +

      +One restriction with operator overloading support is that SWIG is not +able to fully handle operators that aren't defined as part of the class. +For example, if you had code like this +

      + +
      +
      +class Complex {
+...
+friend Complex operator+(double, const Complex &c);
+...
+};
+
      +
      + +

      +then SWIG doesn't know what to do with the friend function--in fact, +it simply ignores it and issues a warning. You can still wrap the operator, +but you may have to encapsulate it in a special function. For example: +

      + +
      +
      +%rename(Complex_add_dc) operator+(double, const Complex &);
+...
+Complex operator+(double, const Complex &c);
+
      +
      + +

      +There are ways to make this operator appear as part of the class using the %extend directive. +Keep reading. +

      + +

      33.3.12 C++ namespaces

      + + +

      +SWIG is aware of C++ namespaces, but namespace names do not appear in +the module nor do namespaces result in a module that is broken up into +submodules or packages. For example, if you have a file like this, +

      + +
      +
      +%module example
+
+namespace foo {
+   int fact(int n);
+   struct Vector {
+       double x,y,z;
+   };
+};
+
      +
      + +

      +it works in Tcl as follows: +

      + +
      +
      +% load ./example.so
+% fact 3
+6
+% Vector v
+% v configure -x 3.4
+
      +
      + +

      +If your program has more than one namespace, name conflicts (if any) can be resolved using %rename +For example: +

      + +
      +
      +%rename(Bar_spam) Bar::spam;
+
+namespace Foo {
+    int spam();
+}
+
+namespace Bar {
+    int spam();
+}
+
      +
      + +

      +If you have more than one namespace and your want to keep their +symbols separate, consider wrapping them as separate SWIG modules. +For example, make the module name the same as the namespace and create +extension modules for each namespace separately. If your program +utilizes thousands of small deeply nested namespaces each with +identical symbol names, well, then you get what you deserve. +

      + +

      33.3.13 C++ templates

      + + +

      +C++ templates don't present a huge problem for SWIG. However, in order +to create wrappers, you have to tell SWIG to create wrappers for a particular +template instantiation. To do this, you use the %template directive. +For example: +

      + +
      +
      +%module example
+%{
+#include "pair.h"
+%}
+
+template<class T1, class T2>
+struct pair {
+   typedef T1 first_type;
+   typedef T2 second_type;
+   T1 first;
+   T2 second;
+   pair();
+   pair(const T1&, const T2&);
+  ~pair();
+};
+
+%template(pairii) pair<int,int>;
+
      +
      + +

      +In Tcl: +

      + +
      +
      +% pairii p 3 4
+% p cget -first
+3
+% p cget -second
+4
+
      +
      + +

      +Obviously, there is more to template wrapping than shown in this example. +More details can be found in the SWIG and C++ chapter. Some more complicated +examples will appear later. +

      + +

      33.3.14 C++ Smart Pointers

      + + +

      +In certain C++ programs, it is common to use classes that have been wrapped by +so-called "smart pointers." Generally, this involves the use of a template class +that implements operator->() like this: +

      + +
      +
      +template<class T> class SmartPtr {
+   ...
+   T *operator->();
+   ...
+}
+
      +
      + +

      +Then, if you have a class like this, +

      + +
      +
      +class Foo {
+public:
+     int x;
+     int bar();
+};
+
      +
      + +

      +A smart pointer would be used in C++ as follows: +

      + +
      +
      +SmartPtr<Foo> p = CreateFoo();   // Created somehow (not shown)
+...
+p->x = 3;                        // Foo::x
+int y = p->bar();                // Foo::bar
+
      +
      + +

      +To wrap this in Tcl, simply tell SWIG about the SmartPtr class and the low-level +Foo object. Make sure you instantiate SmartPtr using %template if necessary. +For example: +

      + +
      +
      +%module example
+...
+%template(SmartPtrFoo) SmartPtr<Foo>;
+...
+
      +
      + +

      +Now, in Tcl, everything should just "work": +

      + +
      +
      +% set p [CreateFoo]                  # Create a smart-pointer somehow
+% $p configure -x 3                  # Foo::x
+% $p bar                             # Foo::bar
+
      +
      + +

      +If you ever need to access the underlying pointer returned by operator->() itself, +simply use the __deref__() method. For example: +

      + +
      +
      +% set f [$p __deref__]    # Returns underlying Foo *
+
      +
      + +

      33.4 Further details on the Tcl class interface

      + + +

      +In the previous section, a high-level view of Tcl wrapping was +presented. A key component of this wrapping is that structures and +classes are wrapped by Tcl class-like objects. This provides a very +natural Tcl interface and allows SWIG to support a number of +advanced features such as operator overloading. However, a number +of low-level details were omitted. This section provides a brief overview +of how the proxy classes work. +

      + +

      33.4.1 Proxy classes

      + + +

      +In the "SWIG basics" and "SWIG and C++" chapters, +details of low-level structure and class wrapping are described. To summarize those chapters, if you +have a class like this +

      + +
      +
      +class Foo {
+public:
+     int x;
+     int spam(int);
+     ...
+
      +
      + +

      +then SWIG transforms it into a set of low-level procedural wrappers. For example: +

      + +
      +
      +Foo *new_Foo() {
+    return new Foo();
+}
+void delete_Foo(Foo *f) {
+    delete f;
+}
+int Foo_x_get(Foo *f) {
+    return f->x;
+}
+void Foo_x_set(Foo *f, int value) {
+    f->x = value;
+}
+int Foo_spam(Foo *f, int arg1) {
+    return f->spam(arg1);
+}
+
      +
      + +

      +These wrappers are actually found in the Tcl extension module. For example, you can certainly do this: +

      + +
      +
      +% load ./example.so
+% set f [new_Foo]
+% Foo_x_get $f
+0
+% Foo_spam $f 3
+1
+%
+
      +
      + +

      +However, in addition to this, the classname Foo is used as an object constructor +function. This allows objects to be encapsulated objects that look a lot like Tk widgets +as shown in the last section. +

      + +

      33.4.2 Memory management

      + + +

      +Associated with each wrapped object, is an ownership flag thisown The value of this +flag determines who is responsible for deleting the underlying C++ object. If set to 1, +the Tcl interpreter destroys the C++ object when the proxy class is +garbage collected. If set to 0 (or if the attribute is missing), then the destruction +of the proxy class has no effect on the C++ object. +

      + +

      +When an object is created by a constructor or returned by value, Tcl automatically takes +ownership of the result. For example: +

      + +
      +
      +class Foo {
+public:
+    Foo();
+    Foo bar();
+};
+
      +
      + +

      +In Tcl: +

      + +
      +
      +% Foo f
+% f cget -thisown
+1
+% set g [f bar]
+% $g cget -thisown
+1
+
      +
      + +

      +On the other hand, when pointers are returned to Tcl, there is often no way to know where +they came from. Therefore, the ownership is set to zero. For example: +

      + +
      +
      +class Foo {
+public:
+    ...
+    Foo *spam();
+    ...
+};
+
      +
      + +
      + +
      +
      +% Foo f
+% set s [f spam]
+% $s cget -thisown
+0
+% 
+
      +
      + +

      +This behavior is especially important for classes that act as +containers. For example, if a method returns a pointer to an object +that is contained inside another object, you definitely don't want +Tcl to assume ownership and destroy it! +

      + +

      +Related to containers, ownership issues can arise whenever an object is assigned to a member +or global variable. For example, consider this interface: +

      + +
      +
      +%module example
+
+struct Foo {
+    int  value;
+    Foo  *next;
+};
+
+Foo *head = 0;
+
      +
      + +

      +When wrapped in Tcl, careful observation will reveal that ownership changes whenever an object +is assigned to a global variable. For example: +

      + +
      +
      +% Foo f
+% f cget -thisown
+1
+% set head f
+% f cget -thisown
+0
+
      +
      + +

      +In this case, C is now holding a reference to the object---you probably don't want Tcl to destroy it. +Similarly, this occurs for members. For example: +

      + +
      +
      +% Foo f
+% Foo g
+% f cget -thisown
+1
+% g cget -thisown
+1
+% f configure -next g
+% g cget -thisown 
+0
+%
+
      +
      + +

      +For the most part, memory management issues remain hidden. However, +there are occasionally situations where you might have to manually +change the ownership of an object. For instance, consider code like this: +

      + +
      +
      +class Node {
+   Object *value;
+public:
+   void set_value(Object *v) { value = v; }
+   ...
+};
+
      +
      + +

      +Now, consider the following Tcl code: +

      + +
      +
      +% Object v                 # Create an object
+% Node n                   # Create a node
+% n setvalue v             # Set value
+% v cget -thisown
+1
+% 
+
      +
      + +

      +In this case, the object n is holding a reference to +v internally. However, SWIG has no way to know that this +has occurred. Therefore, Tcl still thinks that it has ownership of the +object. Should the proxy object be destroyed, then the C++ destructor +will be invoked and n will be holding a stale-pointer. If +you're lucky, you will only get a segmentation fault. +

      + +

      +To work around this, it is always possible to flip the ownership flag. For example, +

      + +
      +
      +% v -disown              # Give ownership to C/C++
+% v -acquire             # Acquire ownership
+
      +
      + +

      +It is also possible to deal with situations like this using +typemaps--an advanced topic discussed later. +

      + + +

      33.5 Input and output parameters

      + + +

      +A common problem in some C programs is handling parameters passed as simple pointers. For +example: +

      + +
      +
      +void add(int x, int y, int *result) {
+   *result = x + y;
+}
+
      +
      + +

      +or perhaps +

      + +
      +
      +int sub(int *x, int *y) {
+   return *x+*y;
+}
+
      +
      + +

      +The easiest way to handle these situations is to use the typemaps.i file. For example: +

      + +
      +
      +%module example
+%include "typemaps.i"
+
+void add(int, int, int *OUTPUT);
+int  sub(int *INPUT, int *INPUT);
+
      +
      + +

      +In Tcl, this allows you to pass simple values instead of pointer. For example: +

      + +
      +
      +set a [add 3 4]
+puts $a
+7
+
      +
      + +

      +Notice how the INPUT parameters allow integer values to be passed instead of pointers +and how the OUTPUT parameter creates a return result. +

      + +

      +If you don't want to use the names INPUT or OUTPUT, use the %apply +directive. For example: +

      + +
      +
      +%module example
+%include "typemaps.i"
+
+%apply int *OUTPUT { int *result };
+%apply int *INPUT  { int *x, int *y};
+
+void add(int x, int y, int *result);
+int  sub(int *x, int *y);
+
      +
      + +

      +If a function mutates one of its parameters like this, +

      + +
      +
      +void negate(int *x) {
+   *x = -(*x);
+}
+
      +
      + +

      +you can use INOUT like this: +

      + +
      +
      +%include "typemaps.i"
+...
+void negate(int *INOUT);
+
      +
      + +

      +In Tcl, a mutated parameter shows up as a return value. For example: +

      + +
      +
      +set a [negate 3]
+puts $a
+-3
+
      +
      + +

      +The most common use of these special typemap rules is to handle functions that +return more than one value. For example, sometimes a function returns a result +as well as a special error code: +

      + +
      +
      +/* send message, return number of bytes sent, along with success code */
+int send_message(char *text, int len, int *success);
+
      +
      + +

      +To wrap such a function, simply use the OUTPUT rule above. For example: +

      + +
      +
      +%module example
+%include "typemaps.i"
+%apply int *OUTPUT { int *success };
+...
+int send_message(char *text, int *success);
+
      +
      + +

      +When used in Tcl, the function will return multiple values as a list. +

      + +
      +
      +set r [send_message "Hello World"]
+set bytes [lindex $r 0]
+set success [lindex $r 1]
+
      +
      + +

      +Another common use of multiple return values are in query functions. For example: +

      + +
      +
      +void get_dimensions(Matrix *m, int *rows, int *columns);
+
      +
      + +

      +To wrap this, you might use the following: +

      + +
      +
      +%module example
+%include "typemaps.i"
+%apply int *OUTPUT { int *rows, int *columns };
+...
+void get_dimensions(Matrix *m, int *rows, *columns);
+
      +
      + +

      +Now, in Perl: +

      + +
      +
      +set dim [get_dimensions $m]
+set r  [lindex $dim 0]
+set c  [lindex $dim 1]
+
      +
      + +

      33.6 Exception handling

      + + +

      +The %exception directive can be used to create a user-definable +exception handler in charge of converting exceptions in your C/C++ +program into Tcl exceptions. The chapter on customization features +contains more details, but suppose you extended the array example into +a C++ class like the following : +

      + +
      +class RangeError {};   // Used for an exception
+
+class DoubleArray {
+  private:
+    int n;
+    double *ptr;
+  public:
+    // Create a new array of fixed size
+    DoubleArray(int size) {
+      ptr = new double[size];
+      n = size;
+    }
+    // Destroy an array
+    ~DoubleArray() {
+       delete ptr;
+    }
+    // Return the length of the array
+    int   length() {
+      return n;
+    }
+
+    // Get an item from the array and perform bounds checking.
+    double getitem(int i) {
+      if ((i >= 0) && (i < n))
+        return ptr[i];
+      else
+        throw RangeError();
+    }
+
+    // Set an item in the array and perform bounds checking.
+    void setitem(int i, double val) {
+      if ((i >= 0) && (i < n))
+        ptr[i] = val;
+      else {
+        throw RangeError();
+      }
+    }
+  };
+
      + +

      +The functions associated with this class can throw a C++ range +exception for an out-of-bounds array access. We can catch this in our +Tcl extension by specifying the following in an interface file : +

      + +
      +%exception {
+  try {
+    $action                // Gets substituted by actual function call
+  }
+  catch (RangeError) {
+    Tcl_SetStringObj(tcl_result,"Array index out-of-bounds");
+    return TCL_ERROR;
+  }
+}
+
      + +

      +As shown, the exception handling code will be added to every wrapper function. +Since this is somewhat inefficient. You might consider refining the +exception handler to only apply to specific methods like this: +

      + +
      +
      +%exception getitem {
+  try {
+    $action
+  }
+  catch (RangeError) {
+    Tcl_SetStringObj(tcl_result,"Array index out-of-bounds");
+    return TCL_ERROR;
+  }
+}
+
+%exception setitem {
+  try {
+    $action
+  }
+  catch (RangeError) {
+    Tcl_SetStringObj(tcl_result,"Array index out-of-bounds");
+    return TCL_ERROR;
+  }
+}
+
      +
      + +

      +In this case, the exception handler is only attached to methods and functions +named getitem and setitem. +

      + +

      +If you had a lot of different methods, you can avoid extra typing by using a macro. +For example: +

      + +
      +
      +%define RANGE_ERROR
+{
+  try {
+    $action
+  }
+  catch (RangeError) {
+    Tcl_SetStringObj(tcl_result,"Array index out-of-bounds");
+    return TCL_ERROR;
+  }
+}
+%enddef
+
+%exception getitem RANGE_ERROR;
+%exception setitem RANGE_ERROR;
+
      +
      + +

      +Since SWIG's exception handling is user-definable, you are not limited to C++ exception handling. +See the chapter on "Customization Features" for more examples. +

      + +

      33.7 Typemaps

      + + +

      +This section describes how you can modify SWIG's default wrapping behavior +for various C/C++ datatypes using the %typemap directive. This +is an advanced topic that assumes familiarity with the Tcl C API as well +as the material in the "Typemaps" chapter. +

      + +

      +Before proceeding, it should be stressed that typemaps are not a required +part of using SWIG---the default wrapping behavior is enough in most cases. +Typemaps are only used if you want to change some aspect of the primitive +C-Tcl interface. +

      + +

      33.7.1 What is a typemap?

      + + +

      +A typemap is nothing more than a code generation rule that is attached to +a specific C datatype. For example, to convert integers from Tcl to C, +you might define a typemap like this: +

      + +
      +%module example
+
+%typemap(in) int {
+        if (Tcl_GetIntFromObj(interp,$input,&$1) == TCL_ERROR) return TCL_ERROR;
+	printf("Received an integer : %d\n",$1);
+}
+%inline %{
+extern int fact(int n);
+%}
+
      + +

      +Typemaps are always associated with some specific aspect of code generation. +In this case, the "in" method refers to the conversion of input arguments +to C/C++. The datatype int is the datatype to which the typemap +will be applied. The supplied C code is used to convert values. In this +code a number of special variable prefaced by a $ are used. The +$1 variable is placeholder for a local variable of type int. +The $input variable is the input object of type Tcl_Obj *. +

      + +

      +When this example is compiled into a Tcl module, it operates as follows: +

      + +
      +% load ./example.so
+% fact 6
+Received an integer : 6
+720
+
      + +

      +In this example, the typemap is applied to all occurrences of the int datatype. +You can refine this by supplying an optional parameter name. For example: +

      + +
      +%module example
+
+%typemap(in) int n {
+        if (Tcl_GetIntFromObj(interp,$input,&$1) == TCL_ERROR) return TCL_ERROR;
+	printf("n = %d\n",$1);
+}
+%inline %{
+extern int fact(int n);
+%}
+
      + +

      +In this case, the typemap code is only attached to arguments that exactly match int n. +

      + +

      +The application of a typemap to specific datatypes and argument names involves +more than simple text-matching--typemaps are fully integrated into the +SWIG type-system. When you define a typemap for int, that typemap +applies to int and qualified variations such as const int. In addition, +the typemap system follows typedef declarations. For example: +

      + +
      +
      +%typemap(in) int n {
+        if (Tcl_GetIntFromObj(interp,$input,&$1) == TCL_ERROR) return TCL_ERROR;
+	printf("n = %d\n",$1);
+}
+%inline %{
+typedef int Integer;
+extern int fact(Integer n);    // Above typemap is applied
+%}
+
      +
      + +

      +However, the matching of typedef only occurs in one direction. If you +defined a typemap for Integer, it is not applied to arguments of +type int. +

      + +

      +Typemaps can also be defined for groups of consecutive arguments. For example: +

      + +
      +
      +%typemap(in) (char *str, int len) {
+    $1 = Tcl_GetStringFromObj($input,&$2);
+};
+
+int count(char c, char *str, int len);
+
      +
      + +

      +When a multi-argument typemap is defined, the arguments are always handled as a single +Tcl object. This allows the function to be used like this (notice how the length +parameter is omitted): +

      + +
      +
      +% count e "Hello World"
+1
+
      +
      + +

      33.7.2 Tcl typemaps

      + + +

      +The previous section illustrated an "in" typemap for converting Tcl objects to C. +A variety of different typemap methods are defined by the Tcl module. For example, +to convert a C integer back into a Tcl object, you might define an "out" typemap +like this: +

      + +
      +
      +%typemap(out) int {
+    Tcl_SetObjResult(interp,Tcl_NewIntObj($1));
+}
+
      +
      + +

      +The following list details all of the typemap methods that can be used by the Tcl module: +

      + +

      +%typemap(in) +

      + +
      +Converts Tcl objects to input function arguments +
      + +

      +%typemap(out) +

      + +
      +Converts return value of a C function to a Tcl object +
      + +

      +%typemap(varin) +

      + +
      +Assigns a C global variable from a Tcl object +
      + +

      +%typemap(varout) +

      + +
      +Returns a C global variable as a Tcl object +
      + +

      +%typemap(freearg) +

      + +
      +Cleans up a function argument (if necessary) +
      + +

      +%typemap(argout) +

      + +
      +Output argument processing +
      + +

      +%typemap(ret) +

      + +
      +Cleanup of function return values +
      + +

      +%typemap(consttab) +

      + +
      +Creation of Tcl constants (constant table) +
      + +

      +%typemap(constcode) +

      + +
      +Creation of Tcl constants (init function) +
      + +

      +%typemap(memberin) +

      + +
      +Setting of structure/class member data +
      + +

      +%typemap(globalin) +

      + +
      +Setting of C global variables +
      + +

      +%typemap(check) +

      + +
      +Checks function input values. +
      + +

      +%typemap(default) +

      + +
      +Set a default value for an argument (making it optional). +
      + +

      +%typemap(arginit) +

      + +
      +Initialize an argument to a value before any conversions occur. +
      + +

      +Examples of these methods will appear shortly. +

      + +

      33.7.3 Typemap variables

      + + +

      +Within typemap code, a number of special variables prefaced with a $ may appear. +A full list of variables can be found in the "Typemaps" chapter. +This is a list of the most common variables: +

      + +

      +$1 +

      + +
      +A C local variable corresponding to the actual type specified in the +%typemap directive. For input values, this is a C local variable +that's supposed to hold an argument value. For output values, this is +the raw result that's supposed to be returned to Tcl. +
      + +

      +$input +

      + +
      + A Tcl_Obj * holding a raw Tcl object with an argument or variable value. +
      + +

      +$result +

      + +
      +A Tcl_Obj * that holds the result to be returned to Tcl. +
      + +

      +$1_name +

      + +
      +The parameter name that was matched. +
      + +

      +$1_type +

      + +
      +The actual C datatype matched by the typemap. +
      + +

      +$1_ltype +

      + +
      +An assignable version of the datatype matched by the typemap (a type that can appear on the left-hand-side of +a C assignment operation). This type is stripped of qualifiers and may be an altered version of $1_type. +All arguments and local variables in wrapper functions are declared using this type so that their values can be +properly assigned. +
      + +

      +$symname +

      + +
      +The Tcl name of the wrapper function being created. +
      + +

      33.7.4 Converting a Tcl list to a char **

      + + +

      +A common problem in many C programs is the processing of command line +arguments, which are usually passed in an array of NULL terminated +strings. The following SWIG interface file allows a Tcl list to be +used as a char ** object. +

      + +
      +%module argv
+
+// This tells SWIG to treat char ** as a special case
+%typemap(in) char ** {
+     Tcl_Obj **listobjv;
+     int       nitems;
+     int       i;
+     if (Tcl_ListObjGetElements(interp, $input, &nitems, &listobjv) == TCL_ERROR) {
+        return TCL_ERROR;
+     }
+     $1 = (char **) malloc((nitems+1)*sizeof(char *));
+     for (i = 0; i < nitems; i++) {
+        $1[i] = Tcl_GetStringFromObj(listobjv[i],0);
+     }
+     $1[i] = 0;
+}
+
+// This gives SWIG some cleanup code that will get called after the function call
+%typemap(freearg) char ** {
+     if ($1) {
+        free($1);
+     }
+}
+
+// Now a test functions
+%inline %{
+int print_args(char **argv) {
+    int i = 0;
+    while (argv[i]) {
+         printf("argv[%d] = %s\n", i,argv[i]);
+         i++;
+    }
+    return i;
+}
+%}
+%include "tclsh.i"
+
+
      + +

      +In Tcl: +

      + +
      +% print_args {John Guido Larry}
+argv[0] = John
+argv[1] = Guido
+argv[2] = Larry
+3
+
      + +

      33.7.5 Returning values in arguments

      + + +

      +The "argout" typemap can be used to return a value originating from a +function argument. For example : +

      + +
      +// A typemap defining how to return an argument by appending it to the result
+%typemap(argout) double *outvalue {
+     Tcl_Obj *o = Tcl_NewDoubleObj($1);
+     Tcl_ListObjAppendElement(interp,$result,o);
+}
+
+// A typemap telling SWIG to ignore an argument for input
+// However, we still need to pass a pointer to the C function
+%typemap(in,numinputs=0) double *outvalue (double temp) {
+     $1 = &temp;
+}
+
+// Now a function returning two values
+int mypow(double a, double b, double *outvalue) {
+        if ((a < 0) || (b < 0)) return -1;
+        *outvalue = pow(a,b);
+        return 0;
+};
+
      + +

      +When wrapped, SWIG matches the argout typemap to the +"double *outvalue" argument. The numinputs=0 specification tells SWIG +to simply ignore this argument when generating wrapper code. As a +result, a Tcl function using these typemaps will work like this : +

      + +
      +% mypow 2 3     # Returns two values, a status value and the result
+0 8
+%
+
      + +

      33.7.6 Useful functions

      + + +

      +The following tables provide some functions that may be useful in +writing Tcl typemaps. +

      + +

      +Integers +

      + +
      +
      +Tcl_Obj   *Tcl_NewIntObj(int Value);
+void       Tcl_SetIntObj(Tcl_Obj *obj, int Value);
+int        Tcl_GetIntFromObj(Tcl_Interp *, Tcl_Obj *obj, int *ip);
+
      +
      + +

      +Floating Point +

      + +
      +
      +Tcl_Obj  *Tcl_NewDoubleObj(double Value);
+void      Tcl_SetDoubleObj(Tcl_Obj *obj, double value);
+int       Tcl_GetDoubleFromObj(Tcl_Interp *, Tcl_Obj *o, double *dp);
+
      +
      + +

      +Strings +

      + +
      +
      +Tcl_Obj  *Tcl_NewStringObj(char *str, int len);
+void      Tcl_SetStringObj(Tcl_Obj *obj, char *str, int len);
+char     *Tcl_GetStringFromObj(Tcl_Obj *obj, int *len);
+void      Tcl_AppendToObj(Tcl_Obj *obj, char *str, int len);
+
      +
      + +

      +Lists +

      + +
      +
      +Tcl_Obj  *Tcl_NewListObj(int objc, Tcl_Obj *objv);
+int       Tcl_ListObjAppendList(Tcl_Interp *, Tcl_Obj *listPtr, Tcl_Obj *elemListPtr);
+int       Tcl_ListObjAppendElement(Tcl_Interp *, Tcl_Obj *listPtr, Tcl_Obj *element);
+int       Tcl_ListObjGetElements(Tcl_Interp *, Tcl_Obj *listPtr, int *objcPtr,
+                                 Tcl_Obj ***objvPtr);
+int       Tcl_ListObjLength(Tcl_Interp *, Tcl_Obj *listPtr, int *intPtr);
+int       Tcl_ListObjIndex(Tcl_Interp *, Tcl_Obj *listPtr, int index,
+                           Tcl_Obj_Obj **objptr);
+int       Tcl_ListObjReplace(Tcl_Interp *, Tcl_Obj *listPtr, int first, int count,
+                             int objc, Tcl_Obj *objv);
+
      +
      + +

      +Objects +

      + +
      +
      +Tcl_Obj *Tcl_DuplicateObj(Tcl_Obj *obj);
+void     Tcl_IncrRefCount(Tcl_Obj *obj);
+void     Tcl_DecrRefCount(Tcl_Obj *obj);
+int      Tcl_IsShared(Tcl_Obj *obj);
+
      +
      + +

      33.7.7 Standard typemaps

      + + +

      +The following typemaps show how to convert a few common kinds of +objects between Tcl and C (and to give a better idea of how typemaps +work) +

      + + +

      +Integer conversion +

      + +
      +
      +%typemap(in) int, short, long {
+   int temp;
+   if (Tcl_GetIntFromObj(interp, $input, &temp) == TCL_ERROR)
+      return TCL_ERROR;
+   $1 = ($1_ltype) temp;
+}
+
      +
      + +
      + +
      +
      +%typemap(out) int, short, long {
+   Tcl_SetIntObj($result,(int) $1);
+}
+
      +
      + +

      +Floating point conversion +

      + +
      +
      +%typemap(in) float, double {
+   double temp;
+   if (Tcl_GetDoubleFromObj(interp, $input, &temp) == TCL_ERROR)
+       return TCL_ERROR;
+   $1 = ($1_ltype) temp;
+}
+
      +
      + +
      + +
      +
      +%typemap(out) float, double {
+   Tcl_SetDoubleObj($result, $1);
+}
+
      +
      + +

      +String Conversion +

      + +
      +
      +%typemap(in) char * {
+   int len;
+   $1 = Tcl_GetStringFromObj(interp, &len);
+   }
+}
+
      +
      + +
      + +
      +
      +%typemap(out) char * {
+   Tcl_SetStringObj($result,$1);
+}
+
      +
      + +

      33.7.8 Pointer handling

      + + +

      +SWIG pointers are mapped into Tcl strings containing the +hexadecimal value and type. The following functions can be used to +create and read pointer values. +

      + +

      + +int SWIG_ConvertPtr(Tcl_Obj *obj, void **ptr, swig_type_info *ty, int flags) +

      + +
      +Converts a Tcl object obj to a C pointer. The result of the conversion is placed +into the pointer located at ptr. ty is a SWIG type descriptor structure. +flags is used to handle error checking and other aspects of conversion. It is currently +reserved for future expansion. Returns 0 on success and -1 on error. +
      + +

      + +Tcl_Obj *SWIG_NewPointerObj(void *ptr, swig_type_info *ty, int flags) +

      + +
      +Creates a new Tcl pointer object. ptr is the pointer to convert, ty is the SWIG type descriptor structure that +describes the type, and own is a flag reserved for future expansion. +
      + +

      +Both of these functions require the use of a special SWIG +type-descriptor structure. This structure contains information about +the mangled name of the datatype, type-equivalence information, as +well as information about converting pointer values under C++ +inheritance. For a type of Foo *, the type descriptor structure +is usually accessed as follows: +

      + +
      +
      +Foo *f;
+if (SWIG_ConvertPtr($input, (void **) &f, SWIGTYPE_p_Foo, 0) == -1) return NULL;
+
+Tcl_Obj *;
+obj = SWIG_NewPointerObj(f, SWIGTYPE_p_Foo, 0);
+
      +
      + +

      +In a typemap, the type descriptor should always be accessed using the special typemap +variable $1_descriptor. For example: +

      + +
      +
      +%typemap(in) Foo * {
+   if ((SWIG_ConvertPtr($input,(void **) &$1, $1_descriptor,0)) == -1) return NULL;
+}
+
      +
      + +

      +If necessary, the descriptor for any type can be obtained using the $descriptor() macro in a typemap. +For example: +

      + +
      +
      +%typemap(in) Foo * {
+   if ((SWIG_ConvertPtr($input,(void **) &$1, $descriptor(Foo *), 0)) == -1) return NULL;
+}
+
      +
      + +

      33.8 Turning a SWIG module into a Tcl Package.

      + + +

      +Tcl 7.4 introduced the idea of an extension package. By default, SWIG +generates all of the code necessary to create a package. To set the package version, +simply use the -pkgversion option. For example: +

      + +
      +
      +% swig -tcl -pkgversion 2.3 example.i
+
      +
      + +

      +After building the SWIG generated module, you need to execute +the "pkg_mkIndex" command inside tclsh. For example : +

      + +
      +unix > tclsh
+% pkg_mkIndex . example.so
+% exit
+
      + +

      +This creates a file "pkgIndex.tcl" with information about the +package. To use your package, you now need to move it to its own +subdirectory which has the same name as the package. For example : +

      + +
      +./example/
+	   pkgIndex.tcl           # The file created by pkg_mkIndex
+	   example.so             # The SWIG generated module
+
      + +

      +Finally, assuming that you're not entirely confused at this point, +make sure that the example subdirectory is visible from the +directories contained in either the tcl_library or +auto_path variables. At this point you're ready to use the +package as follows : +

      + +
      +unix > tclsh
+% package require example
+% fact 4
+24
+%
+
      + +

      +If you're working with an example in the current directory and this doesn't work, do this instead : +

      + +
      +unix > tclsh
+% lappend auto_path .
+% package require example
+% fact 4
+24
+
      + +

      +As a final note, most SWIG examples do not yet use the +package commands. For simple extensions it may be easier just +to use the load command instead. +

      + +

      33.9 Building new kinds of Tcl interfaces (in Tcl)

      + + +

      +One of the most interesting aspects of Tcl and SWIG is that you can +create entirely new kinds of Tcl interfaces in Tcl using the low-level +SWIG accessor functions. For example, suppose you had a library of +helper functions to access arrays : +

      + +
      +/* File : array.i */
+%module array
+
+%inline %{
+double *new_double(int size) {
+        return (double *) malloc(size*sizeof(double));
+}
+void delete_double(double *a) {
+        free(a);
+}
+double get_double(double *a, int index) {
+        return a[index];
+}
+void set_double(double *a, int index, double val) {
+        a[index] = val;
+}
+int *new_int(int size) {
+        return (int *) malloc(size*sizeof(int));
+}
+void delete_int(int *a) {
+        free(a);
+}
+int get_int(int *a, int index) {
+        return a[index];
+}
+int set_int(int *a, int index, int val) {
+        a[index] = val;
+}
+%}
+
+
      + +

      +While these could be called directly, we could also write a Tcl script +like this : +

      + +
      +proc Array {type size} {
+    set ptr [new_$type $size]
+    set code {
+        set method [lindex $args 0]
+        set parms [concat $ptr [lrange $args 1 end]]
+        switch $method {
+            get {return [eval "get_$type $parms"]}
+            set {return [eval "set_$type $parms"]}
+            delete {eval "delete_$type $ptr; rename $ptr {}"}
+        }
+    }
+    # Create a procedure
+    uplevel "proc $ptr args {set ptr $ptr; set type $type;$code}"
+    return $ptr
+}
+
      + +

      +Our script allows easy array access as follows : +

      + +
      +set a [Array double 100]                   ;# Create a double [100]
+for {set i 0} {$i < 100} {incr i 1} {      ;# Clear the array
+	$a set $i 0.0
+}
+$a set 3 3.1455                            ;# Set an individual element
+set b [$a get 10]                          ;# Retrieve an element
+
+set ia [Array int 50]                      ;# Create an int[50]
+for {set i 0} {$i < 50} {incr i 1} {       ;# Clear it
+	$ia set $i 0
+}
+$ia set 3 7                                ;# Set an individual element
+set ib [$ia get 10]                        ;# Get an individual element
+
+$a delete                                  ;# Destroy a
+$ia delete                                 ;# Destroy ia
+
      + +

      +The cool thing about this approach is that it makes a common interface +for two different types of arrays. In fact, if we were to add more C +datatypes to our wrapper file, the Tcl code would work with those as +well--without modification. If an unsupported datatype was requested, +the Tcl code would simply return with an error so there is very little +danger of blowing something up (although it is easily accomplished +with an out of bounds array access). +

      + +

      33.9.1 Proxy classes

      + + +

      +A similar approach can be applied to proxy classes (also known as +shadow classes). The following +example is provided by Erik Bierwagen and Paul Saxe. To use it, run +SWIG with the -noobject option (which disables the builtin +object oriented interface). When running Tcl, simply source this +file. Now, objects can be used in a more or less natural fashion. +

      + +
      +# swig_c++.tcl
+# Provides a simple object oriented interface using
+# SWIG's low level interface.
+#
+
+proc new {objectType handle_r args} {
+    # Creates a new SWIG object of the given type,
+    # returning a handle in the variable "handle_r".
+    #
+    # Also creates a procedure for the object and a trace on
+    # the handle variable that deletes the object when the
+    # handle variable is overwritten or unset
+    upvar $handle_r handle
+    #
+    # Create the new object
+    #
+    eval set handle \[new_$objectType $args\]
+    #
+    # Set up the object procedure
+    #
+    proc $handle {cmd args} "eval ${objectType}_\$cmd $handle \$args"
+    #
+    # And the trace ...
+    #
+    uplevel trace variable $handle_r uw "{deleteObject $objectType $handle}"
+    #
+    # Return the handle so that 'new' can be used as an argument to a procedure
+    #
+    return $handle
+}
+
+proc deleteObject {objectType handle name element op} {
+    #
+    # Check that the object handle has a reasonable form
+    #
+    if {![regexp {_[0-9a-f]*_(.+)_p} $handle]} {
+        error "deleteObject: not a valid object handle: $handle"
+    }
+    #
+    # Remove the object procedure
+    #
+    catch {rename $handle {}}
+    #
+    # Delete the object
+    #
+    delete_$objectType $handle
+}
+
+proc delete {handle_r} {
+    #
+    # A synonym for unset that is more familiar to C++ programmers
+    #
+    uplevel unset $handle_r
+}
+
      + +

      +To use this file, we simply source it and execute commands such as +"new" and "delete" to manipulate objects. For example : +

      + +
      +// list.i
+%module List
+%{
+#include "list.h"
+%}
+
+// Very simple C++ example
+
+class List {
+public:
+  List();  // Create a new list
+  ~List(); // Destroy a list
+  int  search(char *value);
+  void insert(char *);  // Insert a new item into the list
+  void remove(char *);  // Remove item from list
+  char *get(int n);     // Get the nth item in the list
+  int  length;          // The current length of the list
+static void print(List *l);  // Print out the contents of the list
+};
+
      + +

      +Now a Tcl script using the interface... +

      + +
      +load ./list.so list       ; # Load the module
+source swig_c++.tcl       ; # Source the object file
+
+new List l
+$l insert Dave
+$l insert John
+$l insert Guido
+$l remove Dave
+puts $l length_get
+
+delete l
+
      + +

      +The cool thing about this example is that it works with any C++ object +wrapped by SWIG and requires no special compilation. Proof that a +short, but clever Tcl script can be combined with SWIG to do many +interesting things. +

      + +

      33.10 Tcl/Tk Stubs

      + + +

      +For background information about the Tcl Stubs feature, see +http://www.tcl.tk/doc/howto/stubs.html. +

      + +

      +As of SWIG 1.3.10, the generated C/C++ wrapper will use the Tcl Stubs +feature if compiled with -DUSE_TCL_STUBS. +

      + +

      +As of SWIG 1.3.40, the generated C/C++ wrapper will use the Tk Stubs +feature if compiled with -DUSE_TK_STUBS. Also, you can override +the minimum version to support which is passed to Tcl_InitStubs() +and Tk_InitStubs() with -DSWIG_TCL_STUBS_VERSION="8.3" +or the version being compiled with using +-DSWIG_TCL_STUBS_VERSION=TCL_VERSION. +

      + + + diff --git a/Doc/Manual/Typemaps.html b/Doc/Manual/Typemaps.html new file mode 100644 index 0000000..da4fdad --- /dev/null +++ b/Doc/Manual/Typemaps.html @@ -0,0 +1,4066 @@ + + + +Typemaps + + + + +

      10 Typemaps

      + +
      + +
      + + + + +

      10.1 Introduction

      + + +

      +Chances are, you are reading this chapter for one of two reasons; you +either want to customize SWIG's behavior or you overheard someone +mumbling some incomprehensible drivel about "typemaps" and you asked +yourself "typemaps, what are those?" That said, let's start with a +short disclaimer that "typemaps" are an advanced customization feature +that provide direct access to SWIG's low-level code generator. Not +only that, they are an integral part of the SWIG C++ type system (a +non-trivial topic of its own). Typemaps are generally +not a required part of using SWIG. Therefore, you might want +to re-read the earlier chapters if you have found your way to this +chapter with only a vague idea of what SWIG already does by default. +

      + +

      10.1.1 Type conversion

      + + +

      +One of the most important problems in wrapper code generation is the +conversion of datatypes between programming languages. Specifically, +for every C/C++ declaration, SWIG must somehow generate wrapper code +that allows values to be passed back and forth between languages. +Since every programming language represents data differently, this is +not a simple of matter of simply linking code together with the +C linker. Instead, SWIG has to know something about how data is +represented in each language and how it can be manipulated. +

      + +

      +To illustrate, suppose you had a simple C function like this: +

      + +
      +
      +int factorial(int n);
+
      +
      + +

      +To access this function from Python, a pair of Python API functions +are used to convert integer values. For example: +

      + +
      +
      +long PyInt_AsLong(PyObject *obj);      /* Python --> C */
+PyObject *PyInt_FromLong(long x);      /* C --> Python */
+
      +
      + +

      +The first function is used to convert the input argument from a Python integer object +to C long. The second function is used to convert a value from C back into a Python integer object. +

      + +

      +Inside the wrapper function, you might see these functions used like this: +

      + +
      +
      +PyObject *wrap_factorial(PyObject *self, PyObject *args) {
+    int       arg1;
+    int       result;
+    PyObject *obj1;
+    PyObject *resultobj;
+
+    if (!PyArg_ParseTuple("O:factorial", &obj1)) return NULL;
+    arg1 = PyInt_AsLong(obj1);
+    result = factorial(arg1);
+    resultobj = PyInt_FromLong(result);
+    return resultobj;
+}
+
      +
      + +

      +Every target language supported by SWIG has functions that work in a similar manner. For example, in +Perl, the following functions are used: +

      + +
      +
      +IV SvIV(SV *sv);                     /* Perl --> C */
+void sv_setiv(SV *sv, IV val);       /* C --> Perl */
+
      +
      + +

      +In Tcl: +

      + +
      +
      +int Tcl_GetLongFromObj(Tcl_Interp *interp, Tcl_Obj *obj, long *value);
+Tcl_Obj *Tcl_NewIntObj(long value);
+
      +
      + +

      +The precise details are not so important. What is important is that +all of the underlying type conversion is handled by collections of +utility functions and short bits of C code like this---you simply have +to read the extension documentation for your favorite language to know +how it works (an exercise left to the reader). +

      + +

      10.1.2 Typemaps

      + + +

      +Since type handling is so central to wrapper code generation, SWIG +allows it to be completely defined (or redefined) by the user. To do this, +a special %typemap directive is used. For example: +

      + +
      +
      +/* Convert from Python --> C */
+%typemap(in) int {
+    $1 = PyInt_AsLong($input);
+}
+
+/* Convert from C --> Python */
+%typemap(out) int {
+    $result = PyInt_FromLong($1);
+}
+
      +
      + +

      +At first glance, this code will look a little confusing. +However, there is really not much to it. The first typemap (the "in" +typemap) is used to convert a value from the target language to C. The second +typemap (the "out" typemap) is used to convert in the other +direction. The content of each typemap is a small fragment of code +that is inserted directly into the SWIG generated wrapper functions. +The code is usually C or C++ code which will be generated into the C/C++ wrapper functions. +Note that this isn't always the case as some target language modules allow target language +code within the typemaps which gets generated into target language specific files. +Within this code, a number of special variables prefixed with a $ are expanded. These are +really just placeholders for C/C++ variables that are generated in the course +of creating the wrapper function. In this case, $input refers to an +input object that needs to be converted to C/C++ and $result +refers to an object that is going to be returned by a wrapper +function. $1 refers to a C/C++ variable that has the same type as +specified in the typemap declaration (an int in this +example). +

      + +

      +A short example might make this a little more clear. If you were wrapping a +function like this: +

      + +
      +
      +int gcd(int x, int y);
+
      +
      + +

      +A wrapper function would look approximately like this: +

      + +
      +
      +PyObject *wrap_gcd(PyObject *self, PyObject *args) {
+   int arg1;
+   int arg2;
+   int result;
+   PyObject *obj1;
+   PyObject *obj2;
+   PyObject *resultobj;
+
+   if (!PyArg_ParseTuple("OO:gcd", &obj1, &obj2)) return NULL;
+
+   /* "in" typemap, argument 1 */   
+   {
+      arg1 = PyInt_AsLong(obj1);
+   }
+
+   /* "in" typemap, argument 2 */
+   {
+      arg2 = PyInt_AsLong(obj2);
+   }
+
+   result = gcd(arg1,arg2);
+
+   /* "out" typemap, return value */
+   {
+      resultobj = PyInt_FromLong(result);
+   }
+
+   return resultobj;
+}
+
      +
      + +

      +In this code, you can see how the typemap code has been inserted into +the function. You can also see how the special $ variables have been +expanded to match certain variable names inside the wrapper function. This is really the +whole idea behind typemaps--they simply let you insert arbitrary code into different +parts of the generated wrapper functions. Because arbitrary code can be inserted, it +possible to completely change the way in which values are converted. +

      + +

      10.1.3 Pattern matching

      + + +

      +As the name implies, the purpose of a typemap is to "map" C datatypes to +types in the target language. Once a typemap is defined for a C datatype, +it is applied to all future occurrences of that type in the input file. For example: +

      + +
      +
      +/* Convert from Perl --> C */
+%typemap(in) int {
+   $1 = SvIV($input);
+}
+
+...
+int factorial(int n);
+int gcd(int x, int y);
+int count(char *s, char *t, int max);
+
      +
      + +

      +The matching of typemaps to C datatypes is more than a simple textual match. In fact, +typemaps are fully built into the underlying type system. Therefore, typemaps are +unaffected by typedef, namespaces, and other declarations that might hide the +underlying type. For example, you could have code like this: +

      + +
      +
      +/* Convert from Ruby--> C */
+%typemap(in) int {
+   $1 = NUM2INT($input);
+}
+...
+typedef int Integer;
+namespace foo {
+    typedef Integer Number;
+};
+
+int foo(int x);
+int bar(Integer y);
+int spam(foo::Number a, foo::Number b);
+
      +
      + +

      +In this case, the typemap is still applied to the proper arguments even though typenames don't always +match the text "int". This ability to track types is a critical part of SWIG--in fact, all +of the target language modules work merely define a set of typemaps for the basic types. Yet, it +is never necessary to write new typemaps for typenames introduced by typedef. +

      + +

      +In addition to tracking typenames, typemaps may also be specialized to match against a specific argument name. For +example, you could write a typemap like this: +

      + +
      +
      +%typemap(in) double nonnegative {
+   $1 = PyFloat_AsDouble($input);
+   if ($1 < 0) {
+        PyErr_SetString(PyExc_ValueError,"argument must be nonnegative.");
+        return NULL;
+   }
+}
+
+...
+double sin(double x);
+double cos(double x);
+double sqrt(double nonnegative);
+
+typedef double Real;
+double log(Real nonnegative);
+...
+
      +
      + +

      +For certain tasks such as input argument conversion, typemaps can be defined for sequences of +consecutive arguments. For example: +

      + +
      +
      +%typemap(in) (char *str, int len) {
+    $1 = PyString_AsString($input);   /* char *str */
+    $2 = PyString_Size($input);       /* int len   */
+}
+...
+int count(char *str, int len, char c);
+
      +
      + +

      +In this case, a single input object is expanded into a pair of C arguments. This example also +provides a hint to the unusual variable naming scheme involving $1, $2, and so forth. +

      + +

      10.1.4 Reusing typemaps

      + + +

      +Typemaps are normally defined for specific type and argument name patterns. However, typemaps can also +be copied and reused. One way to do this is to use assignment like this: +

      + +
      +
      +%typemap(in) Integer = int;   
+%typemap(in) (char *buffer, int size) = (char *str, int len);
+
      +
      + +

      +A more general form of copying is found in the %apply directive like this: +

      + +
      +
      +%typemap(in) int {
+   /* Convert an integer argument */
+   ...
+}
+%typemap(out) int {
+   /* Return an integer value */
+   ...
+}
+
+/* Apply all of the integer typemaps to size_t */
+%apply int { size_t };    
+
      +
      + +

      +%apply merely takes all of the typemaps that are defined for one type and +applies them to other types. Note: you can include a comma separated set of types in the +{ ... } part of %apply. +

      + +

      +It should be noted that it is not necessary to copy typemaps for types that are related by typedef. +For example, if you have this, +

      + +
      +
      +typedef int size_t;
+
      +
      + +

      +then SWIG already knows that the int typemaps apply. You don't have to do anything. +

      + +

      10.1.5 What can be done with typemaps?

      + + +

      +The primary use of typemaps is for defining wrapper generation behavior at the level +of individual C/C++ datatypes. There are currently six general categories of problems that +typemaps address: +

      + +

      +Argument handling +

      + +
      +
      +int foo(int x, double y, char *s);
+
      +
      + +
        +
      • Input argument conversion ("in" typemap).
        • +
      • Input argument type checking ("typecheck" typemap).
        • +
      • Output argument handling ("argout" typemap).
        • +
      • Input argument value checking ("check" typemap).
        • +
      • Input argument initialization ("arginit" typemap).
        • +
      • Default arguments ("default" typemap).
        • +
      • Input argument resource management ("freearg" typemap).
        • +
      + +

      +Return value handling +

      + +
      +
      +int foo(int x, double y, char *s);
+
      +
      + +
        +
      • Function return value conversion ("out" typemap).
        • +
      • Return value resource management ("ret" typemap).
        • +
      • Resource management for newly allocated objects ("newfree" typemap).
        • +
      + +

      +Exception handling +

      + +
      +
      +int foo(int x, double y, char *s) throw(MemoryError, IndexError);
+
      +
      + +
        +
      • Handling of C++ exception specifications. ("throw" typemap).
        • +
      + +

      +Global variables +

      + +
      +
      +int foo;
+
      +
      + +
        +
      • Assignment of a global variable. ("varin" typemap).
        • +
      • Reading a global variable. ("varout" typemap).
        • +
      + +

      +Member variables +

      + +
      +
      +struct Foo {
+    int x[20];
+};
+
      +
      + +
        +
      • Assignment of data to a class/structure member. ("memberin" typemap).
        • +
      + +

      +Constant creation +

      + +
      +
      +#define FOO 3
+%constant int BAR = 42;
+enum { ALE, LAGER, STOUT };
+
      +
      + +
        +
      • Creation of constant values. ("consttab" or "constcode" typemap).
        • +
      + +

      +Details of each of these typemaps will be covered shortly. Also, certain language modules may define additional +typemaps that expand upon this list. For example, the Java module defines a variety of typemaps for controlling additional +aspects of the Java bindings. Consult language specific documentation for further details. +

      + +

      10.1.6 What can't be done with typemaps?

      + + +

      +Typemaps can't be used to define properties that apply to C/C++ declarations as a whole. For example, +suppose you had a declaration like this, +

      + +
      +
      +Foo *make_Foo();
+
      +
      + +

      +and you wanted to tell SWIG that make_Foo() returned a newly +allocated object (for the purposes of providing better memory +management). Clearly, this property of make_Foo() is +not a property that would be associated with the datatype +Foo * by itself. Therefore, a completely different SWIG +customization mechanism (%feature) is used for this purpose. Consult the Customization Features chapter for more +information about that. +

      + +

      +Typemaps also can't be used to rearrange or transform the order of arguments. For example, +if you had a function like this: +

      + +
      +
      +void foo(int, char *);
+
      +
      + +

      +you can't use typemaps to interchange the arguments, allowing you to call the +function like this: +

      + +
      +
      +foo("hello",3)          # Reversed arguments
+
      +
      + +

      +If you want to change the calling conventions of a function, write a helper +function instead. For example: +

      + +
      +
      +%rename(foo) wrap_foo;
+%inline %{
+void wrap_foo(char *s, int x) {
+   foo(x,s);
+}
+%}
+
      +
      + +

      10.1.7 The rest of this chapter

      + + +

      +The rest of this chapter provides detailed information for people who +want to write new typemaps. This information is of particular importance to anyone +who intends to write a new SWIG target language module. Power users can also +use this information to write application specific type conversion rules. +

      + +

      +Since typemaps are strongly tied to the underlying C++ type system, +subsequent sections assume that you are reasonably familiar with the +basic details of values, pointers, references, arrays, type qualifiers +(e.g., const), structures, namespaces, templates, and memory +management in C/C++. If not, you would be well-advised to consult a copy +of "The C Programming Language" by Kernighan and Ritchie or +"The C++ Programming Language" by Stroustrup before going any further. +

      + +

      10.2 Typemap specifications

      + + +

      +This section describes the behavior of the %typemap directive itself. +

      + +

      10.2.1 Defining a typemap

      + + +

      +New typemaps are defined using the %typemap declaration. The general form of +this declaration is as follows (parts enclosed in [ ... ] are optional): +

      + +
      +
      +%typemap(method [, modifiers]) typelist code ;
+
      +
      + +

      +method is a simply a name that specifies what kind of typemap is being defined. It +is usually a name like "in", "out", or "argout". The purpose of +these methods is described later. +

      + +

      +modifiers is an optional comma separated list of name="value" values. These +are sometimes to attach extra information to a typemap and is often target-language dependent. +

      + +

      +typelist is a list of the C++ type patterns that the typemap will match. The general form of +this list is as follows: +

      + +
      +
      +typelist    :  typepattern [, typepattern, typepattern, ... ] ;
+
+typepattern :  type [ (parms) ]
+            |  type name [ (parms) ]
+            |  ( typelist ) [ (parms) ]
+
+
      +
      + +

      +Each type pattern is either a simple type, a simple type and argument name, or a list of types in the +case of multi-argument typemaps. In addition, each type pattern can be parameterized with a list of temporary +variables (parms). The purpose of these variables will be explained shortly. +

      + +

      code specifies the code used in the typemap. +Usually this is C/C++ code, but in the statically typed target languages, such as Java and C#, this can contain target language code for certain typemaps. +It can take any one of the following forms: +

      + +
      +
      +code       : { ... }
+           | " ... "
+           | %{ ... %}
+
      +
      + +

      +Note that the preprocessor will expand code within the {} delimiters, but not in the last two styles of delimiters, +see Preprocessor and Typemaps. +Here are some examples of valid typemap specifications: +

      + +
      +
      +/* Simple typemap declarations */
+%typemap(in) int {
+   $1 = PyInt_AsLong($input);
+}
+%typemap(in) int "$1 = PyInt_AsLong($input);";
+%typemap(in) int %{ 
+   $1 = PyInt_AsLong($input);
+%}
+
+/* Typemap with extra argument name */
+%typemap(in) int nonnegative {
+   ...
+}
+
+/* Multiple types in one typemap */
+%typemap(in) int, short, long { 
+   $1 = SvIV($input);
+}
+
+/* Typemap with modifiers */
+%typemap(in,doc="integer") int "$1 = gh_scm2int($input);";
+
+/* Typemap applied to patterns of multiple arguments */
+%typemap(in) (char *str, int len),
+             (char *buffer, int size)
+{
+   $1 = PyString_AsString($input);
+   $2 = PyString_Size($input);
+}
+
+/* Typemap with extra pattern parameters */
+%typemap(in, numinputs=0) int *output (int temp),
+                          long *output (long temp)
+{
+   $1 = &temp;
+}
+
      +
      + +

      +Admittedly, it's not the most readable syntax at first glance. However, the purpose of the +individual pieces will become clear. +

      + +

      10.2.2 Typemap scope

      + + +

      +Once defined, a typemap remains in effect for all of the declarations that follow. A typemap may be redefined for +different sections of an input file. For example: +

      + +
      +
      +// typemap1
+%typemap(in) int {
+...
+}
+
+int fact(int);                    // typemap1
+int gcd(int x, int y);            // typemap1
+
+// typemap2
+%typemap(in) int {
+...
+}
+
+int isprime(int);                 // typemap2
+
      +
      + +

      +One exception to the typemap scoping rules pertains to the %extend declaration. %extend is used to attach +new declarations to a class or structure definition. Because of this, all of the declarations in an %extend block are +subject to the typemap rules that are in effect at the point where the class itself is defined. For example: +

      + +
      +
      +class Foo {
+   ...
+};
+
+%typemap(in) int {
+ ...
+}
+
+%extend Foo {
+   int blah(int x);    // typemap has no effect.  Declaration is attached to Foo which 
+                       // appears before the %typemap declaration.
+};
+
      +
      + +

      10.2.3 Copying a typemap

      + + +

      +A typemap is copied by using assignment. For example: +

      + +
      +
      +%typemap(in) Integer = int;
+
      +
      + +

      +or this: +

      + +
      +
      +%typemap(in) Integer, Number, int32_t = int;
+
      +
      + +

      +Types are often managed by a collection of different typemaps. For example: +

      + +
      +
      +%typemap(in)     int { ... }
+%typemap(out)    int { ... }
+%typemap(varin)  int { ... }
+%typemap(varout) int { ... }
+
      +
      + +

      +To copy all of these typemaps to a new type, use %apply. For example: +

      + +
      +
      +%apply int { Integer };            // Copy all int typemaps to Integer
+%apply int { Integer, Number };    // Copy all int typemaps to both Integer and Number
+
      +
      + +

      +The patterns for %apply follow the same rules as for %typemap. For example: +

      + +
      +
      +%apply int *output { Integer *output };                    // Typemap with name
+%apply (char *buf, int len) { (char *buffer, int size) };  // Multiple arguments
+
      +
      + +

      10.2.4 Deleting a typemap

      + + +

      +A typemap can be deleted by simply defining no code. For example: +

      + +
      +
      +%typemap(in) int;               // Clears typemap for int
+%typemap(in) int, long, short;  // Clears typemap for int, long, short
+%typemap(in) int *output;       
+
      +
      + +

      +The %clear directive clears all typemaps for a given type. +For example: +

      + +
      +
      +%clear int;                     // Removes all types for int
+%clear int *output, long *output;
+
      +
      + +

      +Note: Since SWIG's default behavior is defined by typemaps, clearing a fundamental type like +int will make that type unusable unless you also define a new set of typemaps immediately +after the clear operation. +

      + +

      10.2.5 Placement of typemaps

      + + +

      +Typemap declarations can be declared in the global scope, within a C++ namespace, and within a C++ class. For +example: +

      + +
      +
      +%typemap(in) int {
+   ...
+}
+
+namespace std {
+    class string;
+    %typemap(in) string {
+        ...
+    }
+}
+
+class Bar {
+public:
+    typedef const int & const_reference;
+    %typemap(out) const_reference {
+         ...
+    }
+};
+
      +
      + +

      +When a typemap appears inside a namespace or class, it stays in effect until the end of the SWIG input +(just like before). However, the typemap takes the local scope into account. Therefore, this +code +

      + +
      +
      +namespace std {
+    class string;
+    %typemap(in) string {
+       ...
+    }
+}
+
      +
      + +

      +is really defining a typemap for the type std::string. You could have code like this: +

      + +
      +
      +namespace std {
+    class string;
+    %typemap(in) string {          /* std::string */
+       ...
+    }
+}
+
+namespace Foo {
+    class string;
+    %typemap(in) string {          /* Foo::string */
+       ...
+    }
+}
+
      +
      + +

      +In this case, there are two completely distinct typemaps that apply to two completely different +types (std::string and Foo::string). +

      + +

      +It should be noted that for scoping to work, SWIG has to know that string is a typename defined +within a particular namespace. In this example, this is done using the class declaration class string. +

      + +

      10.3 Pattern matching rules

      + + +

      +The section describes the pattern matching rules by which C datatypes are associated with typemaps. +

      + +

      10.3.1 Basic matching rules

      + + +

      +Typemaps are matched using both a type and a name (typically the name of a argument). For a given +TYPE NAME pair, the following rules are applied, in order, to find a match. The first typemap found +is used. +

      + +
        +
      • Typemaps that exactly match TYPE and NAME. +
      • Typemaps that exactly match TYPE only. +
      + +

      +If TYPE includes qualifiers (const, volatile, etc.), they are stripped and the following +checks are made: +

      + +
        +
      • Typemaps that match the stripped TYPE and NAME. +
      • Typemaps that match the stripped TYPE only. +
      + +

      +If TYPE is an array. The following transformation is made: +

      + +
        +
      • Replace all dimensions to [ANY] and look for a generic array typemap. +
      + +

      +To illustrate, suppose that you had a function like this: +

      + +
      +
      +int foo(const char *s);
+
      +
      + +

      +To find a typemap for the argument const char *s, SWIG will search for the following typemaps: +

      + +
      +
      +const char *s           Exact type and name match
+const char *            Exact type match
+char *s                 Type and name match (stripped qualifiers)
+char *                  Type match (stripped qualifiers)
+
      +
      + +

      +When more than one typemap rule might be defined, only the first match +found is actually used. Here is an example that +shows how some of the basic rules are applied: +

      + +
      +%typemap(in) int *x {
+   ... typemap 1
+}
+
+%typemap(in) int * {
+   ... typemap 2
+}
+
+%typemap(in) const int *z {
+   ... typemap 3
+}
+
+%typemap(in) int [4] {
+   ... typemap 4
+}
+
+%typemap(in) int [ANY] {
+   ... typemap 5
+}
+
+void A(int *x);        // int *x rule    (typemap 1)
+void B(int *y);        // int * rule     (typemap 2)
+void C(const int *x);  // int *x rule    (typemap 1)
+void D(const int *z);  // int * rule     (typemap 3)
+void E(int x[4]);      // int [4] rule   (typemap 4)
+void F(int x[1000]);   // int [ANY] rule (typemap 5)
+
      +
      + +

      10.3.2 Typedef reductions

      + + +

      +If no match is found using the rules in the previous section, SWIG +applies a typedef reduction to the type and repeats the typemap search +for the reduced type. To illustrate, suppose you had code like this: +

      + +
      +
      +%typemap(in) int {
+   ... typemap 1
+}
+
+typedef int Integer;
+void blah(Integer x);
+
      +
      + +

      +To find the typemap for Integer x, SWIG will first search for the following +typemaps: +

      + +
      +
      +Integer x
+Integer
+
      +
      + +

      +Finding no match, it then applies a reduction Integer -> int to the type and +repeats the search. +

      + +
      +
      +int x
+int      --> match: typemap 1
+
      +
      + +

      +Even though two types might be the same via typedef, SWIG allows typemaps to be defined +for each typename independently. This allows for interesting customization possibilities based +solely on the typename itself. For example, you could write code like this: +

      + +
      +
      +typedef double  pdouble;     // Positive double
+
+// typemap 1
+%typemap(in) double {
+   ... get a double ...
+}
+// typemap 2
+%typemap(in) pdouble {
+   ... get a positive double ...
+}
+double sin(double x);           // typemap 1
+pdouble sqrt(pdouble x);        // typemap 2
+
      +
      + +

      +When reducing the type, only one typedef reduction is applied at a +time. The search process continues to apply reductions until a +match is found or until no more reductions can be made. +

      + +

      +For complicated types, the reduction process can generate a long list of patterns. Consider the following: +

      + +
      +
      +typedef int Integer;
+typedef Integer Row4[4];
+void foo(Row4 rows[10]);
+
      +
      + +

      +To find a match for the Row4 rows[10] argument, SWIG would +check the following patterns, stopping only when it found a match: +

      + +
      +
      +Row4 rows[10]
+Row4 [10]
+Row4 rows[ANY]
+Row4 [ANY]
+
+# Reduce Row4 --> Integer[4]
+Integer rows[10][4]
+Integer [10][4]
+Integer rows[ANY][ANY]
+Integer [ANY][ANY]
+
+# Reduce Integer --> int
+int rows[10][4]
+int [10][4]
+int rows[ANY][ANY]
+int [ANY][ANY]
+
      +
      + +

      +For parameterized types like templates, the situation is even more complicated. Suppose you had some declarations +like this: +

      + +
      +
      +typedef int Integer;
+typedef foo<Integer,Integer> fooii;
+void blah(fooii *x);
+
      +
      + +

      +In this case, the following typemap patterns are searched for the argument fooii *x: +

      + +
      +
      +fooii *x
+fooii *
+
+# Reduce fooii --> foo<Integer,Integer>
+foo<Integer,Integer> *x
+foo<Integer,Integer> *
+
+# Reduce Integer -> int
+foo<int, Integer> *x
+foo<int, Integer> *
+
+# Reduce Integer -> int
+foo<int, int> *x
+foo<int, int> *
+
      +
      + +

      +Typemap reductions are always applied to the left-most type that appears. Only when no reductions can be made to the left-most +type are reductions made to other parts of the type. This behavior means that you could define a typemap for +foo<int,Integer>, but a typemap for foo<Integer,int> would never be matched. Admittedly, this +is rather esoteric--there's little practical reason to write a typemap quite like that. Of course, you could rely on this +to confuse your coworkers even more. +

      + +

      10.3.3 Default typemaps

      + + +

      +Most SWIG language modules use typemaps to define the default behavior of the C primitive types. This +is entirely straightforward. For example, a set of typemaps are written like this: +

      + +
      +
      +%typemap(in) int   "convert an int";
+%typemap(in) short "convert a short";
+%typemap(in) float "convert a float";
+...
+
      +
      + +

      +Since typemap matching follows all typedef declarations, any sort of type that is +mapped to a primitive type through typedef will be picked up by one of these primitive typemaps. +

      + +

      +The default behavior for pointers, arrays, references, and other kinds of types are handled by +specifying rules for variations of the reserved SWIGTYPE type. For example: +

      + +
      +
      +%typemap(in) SWIGTYPE *            { ... default pointer handling ...         }
+%typemap(in) SWIGTYPE &            { ... default reference handling ...       }
+%typemap(in) SWIGTYPE []           { ... default array handling ...           }
+%typemap(in) enum SWIGTYPE         { ... default handling for enum values ... }
+%typemap(in) SWIGTYPE (CLASS::*)   { ... default pointer member handling ...  } 
+
      +
      + +

      +These rules match any kind of pointer, reference, or array--even when +multiple levels of indirection or multiple array dimensions are used. +Therefore, if you wanted to change SWIG's default handling for all +types of pointers, you would simply redefine the rule for SWIGTYPE +*. +

      + +

      +Finally, the following typemap rule is used to match against simple types that don't match any other rules: +

      + +
      +
      +%typemap(in) SWIGTYPE   { ... handle an unknown type ... }
+
      +
      + +

      +This typemap is important because it is the rule that gets triggered +when call or return by value is used. For instance, if you have a +declaration like this: +

      + +
      +
      +double dot_product(Vector a, Vector b);
+
      +
      + +

      +The Vector type will usually just get matched against +SWIGTYPE. The default implementation of SWIGTYPE is +to convert the value into pointers (as described in chapter 3). +

      + +

      +By redefining SWIGTYPE it may be possible to implement other +behavior. For example, if you cleared all typemaps for +SWIGTYPE, SWIG simply won't wrap any unknown datatype (which might +be useful for debugging). Alternatively, you might modify SWIGTYPE to marshal +objects into strings instead of converting them to pointers. +

      + +

      +The best way to explore the default typemaps is to look at the ones +already defined for a particular language module. Typemaps +definitions are usually found in the SWIG library in a file such as +python.swg, tcl8.swg, etc. +

      + +

      10.3.4 Mixed default typemaps

      + + +

      +The default typemaps described above can be mixed with const and with each other. +For example the SWIGTYPE * typemap is for default pointer handling, but if a const SWIGTYPE * typemap +is defined it will be used instead for constant pointers. Some further examples follow: +

      + +
      +
      +%typemap(in) enum SWIGTYPE &        { ... enum references ...                       }
+%typemap(in) const enum SWIGTYPE &  { ... const enum references ...                 }
+%typemap(in) SWIGTYPE *&            { ... pointers passed by reference ...          }
+%typemap(in) SWIGTYPE * const &     { ... constant pointers passed by reference ... }
+%typemap(in) SWIGTYPE[ANY][ANY]     { ... 2D arrays ...                             }
+
      +
      + +

      +Note that the the typedef reduction described earlier is also used with these mixed default typemaps. +For example, say the following typemaps are defined and SWIG is looking for the best match for the enum shown below: +

      + +
      +
      +%typemap(in) const Hello &          { ... }
+%typemap(in) const enum SWIGTYPE &  { ... }
+%typemap(in) enum SWIGTYPE &        { ... }
+%typemap(in) SWIGTYPE &             { ... }
+%typemap(in) SWIGTYPE               { ... }
+
+enum Hello {};
+const Hello &hi;
+
      +
      + +

      +The typemap at the top of the list will be chosen, not because it is defined first, but because it is the closest match for the type being wrapped. +If any of the typemaps in the above list were not defined, then the next one on the list would have precedence. +In other words the typemap chosen is the closest explicit match. +

      + +

      +Compatibility note: The mixed default typemaps were introduced in SWIG-1.3.23, but were not used much in this version. +Expect to see them being used more and more within the various libraries in later versions of SWIG. +

      + + +

      10.3.5 Multi-arguments typemaps

      + + +

      +When multi-argument typemaps are specified, they take precedence over +any typemaps specified for a single type. For example: +

      + +
      +
      +%typemap(in) (char *buffer, int len) {
+   // typemap 1
+}
+
+%typemap(in) char *buffer {
+   // typemap 2
+}
+
+void foo(char *buffer, int len, int count); // (char *buffer, int len)
+void bar(char *buffer, int blah);           // char *buffer
+
      +
      + +

      +Multi-argument typemaps are also more restrictive in the way that they are matched. +Currently, the first argument follows the matching rules described in the previous section, +but all subsequent arguments must match exactly. +

      + + +

      10.4 Code generation rules

      + + +

      +This section describes rules by which typemap code is inserted into +the generated wrapper code. +

      + +

      10.4.1 Scope

      + + +

      +When a typemap is defined like this: +

      + +
      +
      +%typemap(in) int {
+   $1 = PyInt_AsLong($input);
+}
+
      +
      + +

      +the typemap code is inserted into the wrapper function using a new block scope. In other words, the +wrapper code will look like this: +

      + +
      +
      +wrap_whatever() {
+    ...
+    // Typemap code
+    {                    
+       arg1 = PyInt_AsLong(obj1);
+    }
+    ...
+}
+
      +
      + +

      +Because the typemap code is enclosed in its own block, it is legal to declare temporary variables +for use during typemap execution. For example: +

      + +
      +
      +%typemap(in) short {
+   long temp;          /* Temporary value */
+   if (Tcl_GetLongFromObj(interp, $input, &temp) != TCL_OK) {
+      return TCL_ERROR;
+   }
+   $1 = (short) temp;
+}
+
      +
      + +

      +Of course, any variables that you declare inside a typemap are destroyed as soon as the typemap +code has executed (they are not visible to other parts of the wrapper function or other typemaps +that might use the same variable names). +

      + +

      +Occasionally, typemap code will be specified using a few alternative forms. For example: +

      + +
      +
      +%typemap(in) int "$1 = PyInt_AsLong($input);";
+%typemap(in) int %{
+$1 = PyInt_AsLong($input);
+%}
+
      +
      + +

      +These two forms are mainly used for cosmetics--the specified code is not enclosed inside +a block scope when it is emitted. This sometimes results in a less complicated looking wrapper function. +

      + +

      10.4.2 Declaring new local variables

      + + +

      +Sometimes it is useful to declare a new local variable that exists +within the scope of the entire wrapper function. A good example of this +might be an application in which you wanted to marshal strings. Suppose +you had a C++ function like this +

      + +
      +
      +int foo(std::string *s);
+
      +
      + +

      +and you wanted to pass a native string in the target language as an argument. For instance, +in Perl, you wanted the function to work like this: +

      + +
      +
      +$x = foo("Hello World");
+
      +
      + +

      +To do this, you can't just pass a raw Perl string as the std::string * argument. +Instead, you have to create a temporary std::string object, copy the Perl string data into it, and +then pass a pointer to the object. To do this, simply specify the typemap with an extra parameter like this: +

      + +
      +
      +%typemap(in) std::string * (std::string temp) {
+    unsigned int len;
+    char        *s;
+    s = SvPV($input,len);         /* Extract string data */
+    temp.assign(s,len);           /* Assign to temp */
+    $1 = &temp;                   /* Set argument to point to temp */
+}
+
      +
      + +

      +In this case, temp becomes a local variable in +the scope of the entire wrapper function. For example: +

      + +
      +
      +wrap_foo() {
+   std::string temp;    <--- Declaration of temp goes here
+   ...
+
+   /* Typemap code */
+   {
+      ...
+      temp.assign(s,len);
+      ...
+   } 
+   ...
+}
+
      +
      + +

      +When you set temp to a value, it +persists for the duration of the wrapper function and gets +cleaned up automatically on exit. +

      + +

      +It is perfectly safe to use more than one typemap involving local +variables in the same declaration. For example, you could declare a +function as :

      + +
      +void foo(std::string *x, std::string *y, std::string *z);
+
      + +

      +This is safely handled because SWIG actually renames all local +variable references by appending an argument number suffix. Therefore, the +generated code would actually look like this: +

      + +
      +
      +wrap_foo() {
+   int *arg1;    /* Actual arguments */
+   int *arg2;
+   int *arg3;
+   std::string temp1;    /* Locals declared in the typemap */
+   std::string temp2;
+   std::string temp3;
+   ...
+   {
+       char *s;
+       unsigned int len;
+       ...
+       temp1.assign(s,len);
+       arg1 = *temp1;
+   }
+   {
+       char *s;
+       unsigned int len;
+       ...
+       temp2.assign(s,len);
+       arg2 = &temp2;
+   }
+   {
+       char *s;
+       unsigned int len;
+       ...
+       temp3.assign(s,len);
+       arg3 = &temp3;
+   }
+   ...
+}
+
      +
      + +

      +Some typemaps do not recognize local variables (or they may simply not +apply). At this time, only typemaps that apply to argument conversion support this. +

      + +

      +Note: +

      + +

      +When declaring a typemap for multiple types, +each type must have its own local variable declaration. +

      + +
      +
      +%typemap(in) const std::string *, std::string * (std::string temp) // NO!
+// only std::string * has a local variable
+// const std::string * does not (oops)
+....
+
+%typemap(in) const std::string * (std::string temp), std::string * (std::string temp) // Correct
+....
+
      +
      + + +

      10.4.3 Special variables

      + + +

      +Within all typemaps, the following special variables are expanded. +This is by no means a complete list as some target languages have additional special variables which are documented in the language specific chapters. +

      + +
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      VariableMeaning
      $n +A C local variable corresponding to type n in the typemap +pattern. +
      $argnumArgument number. Only available in typemaps related to argument conversion
      $n_nameArgument name
      $n_typeReal C datatype of type n.
      $n_ltypeltype of type n
      $n_mangleMangled form of type n. For example _p_Foo
      $n_descriptorType descriptor structure for type n. For example +SWIGTYPE_p_Foo. This is primarily used when interacting with the +run-time type checker (described later).
      $*n_typeReal C datatype of type n with one pointer removed.
      $*n_ltypeltype of type n with one pointer removed.
      $*n_mangleMangled form of type n with one pointer removed.
      $*n_descriptorType descriptor structure for type n with one pointer removed. +
      $&n_typeReal C datatype of type n with one pointer added.
      $&n_ltypeltype of type n with one pointer added.
      $&n_mangleMangled form of type n with one pointer added.
      $&n_descriptorType descriptor structure for type n with one pointer added. +
      $n_basetypeBase typename with all pointers and qualifiers stripped. +
      +
      + +

      +Within the table, $n refers to a specific type within the typemap specification. For example, +if you write this +

      + +
      +
      +%typemap(in) int *INPUT {
+
+}
+
      +
      + +

      +then $1 refers to int *INPUT. If you have a typemap like this, +

      + +
      +
      +%typemap(in) (int argc, char *argv[]) {
+  ...
+}
+
      +
      + +

      +then $1 refers to int argc and $2 refers to char *argv[]. +

      + +

      +Substitutions related to types and names always fill in values from the actual code that was matched. +This is useful when a typemap might match multiple C datatype. For example: +

      + +
      +
      +%typemap(in)  int, short, long {
+   $1 = ($1_ltype) PyInt_AsLong($input);
+}
+
      +
      + +

      +In this case, $1_ltype is replaced with the datatype that is actually matched. +

      + + +

      +When typemap code is emitted, the C/C++ datatype of the special variables $1 and +$2 is always an "ltype." An "ltype" is simply a type that can legally appear +on the left-hand side of a C assignment operation. Here are a few examples of types +and ltypes: +

      + +
      +
      +type              ltype
+------            ----------------
+int               int
+const int         int
+const int *       int *
+int [4]           int *
+int [4][5]        int (*)[5]
+
      +
      + +

      +In most cases a ltype is simply the C datatype with qualifiers stripped off. In addition, +arrays are converted into pointers. +

      + +

      +Variables such as $&1_type and $*1_type are used to +safely modify the type by removing or adding pointers. Although not +needed in most typemaps, these substitutions are sometimes needed to properly +work with typemaps that convert values between pointers and values. +

      + +

      +If necessary, type related substitutions can also be used when declaring locals. For example: +

      + +
      +
      +%typemap(in) int * ($*1_type temp) {
+    temp = PyInt_AsLong($input);
+    $1 = &temp;
+}
+
      +
      + +

      +There is one word of caution about declaring local variables in this manner. If you declare a local variable +using a type substitution such as $1_ltype temp, it won't work like you expect for arrays and certain +kinds of pointers. For example, if you wrote this, +

      + +
      +
      +%typemap(in) int [10][20] {
+   $1_ltype temp;
+}
+
      +
      + +

      +then the declaration of temp will be expanded as +

      + +
      +
      +int (*)[20] temp;
+
      +
      + +

      +This is illegal C syntax and won't compile. There is currently no +straightforward way to work around this problem in SWIG due to the way +that typemap code is expanded and processed. However, one possible workaround +is to simply pick an alternative type such as void * and use +casts to get the correct type when needed. For example: +

      + +
      +
      +%typemap(in) int [10][20] {
+   void *temp;
+   ...
+   (($1_ltype) temp)[i][j] = x;    /* set a value */
+   ...
+}
+
      +
      + +

      +Another approach, which only works for arrays is to use the $1_basetype substitution. For example: +

      + +
      +
      +%typemap(in) int [10][20] {
+   $1_basetype temp[10][20];
+   ...
+   temp[i][j] = x;    /* set a value */
+   ...
+}
+
      +
      + +

      10.4.4 Special variable macros

      + + +

      +Special variable macros are like macro functions in that they take one or more input arguments +which are used for the macro expansion. +They look like macro/function calls but use the special variable $ prefix to the macro name. +Note that unlike normal macros, the expansion is not done by the preprocessor, +it is done during the SWIG parsing/compilation stages. +The following special variable macros are available across all language modules. +

      + +

      10.4.4.1 $descriptor(type)

      + + +

      +This macro expands into the type descriptor structure for any C/C++ type specified in type. +It behaves like the $1_descriptor special variable described above except that the type to expand is +taken from the macro argument rather than inferred from the typemap type. +For example, $descriptor(std::vector<int> *) will expand into SWIGTYPE_p_std__vectorT_int_t. +This macro is mostly used in the scripting target languages and is demonstrated later in the Run-time type checker usage section. +

      + +

      10.4.4.2 $typemap(method, typepattern)

      + + +

      +This macro uses the pattern matching rules described earlier to lookup and +then substitute the special variable macro with the code in the matched typemap. +The typemap to search for is specified by the arguments, where method is the typemap method name and +typepattern is a type pattern as per the %typemap specification in the Defining a typemap section. +

      + +

      +The special variables within the matched typemap are expanded into those for the matched typemap type, +not the typemap within which the macro is called. +In practice, there is little use for this macro in the scripting target languages. +It is mostly used in the target languages that are statically typed as a way to obtain the target language type given the C/C++ type and more commonly only when the C++ type is a template parameter. +

      + +

      +The example below is for C# only and uses some typemap method names documented in the C# chapter, but it shows some of the possible syntax variations. +

      + +
      +
      +%typemap(cstype) unsigned long    "uint"
+%typemap(cstype) unsigned long bb "bool"
+%typemap(cscode) BarClass %{
+  void foo($typemap(cstype, unsigned long aa) var1,
+           $typemap(cstype, unsigned long bb) var2,
+           $typemap(cstype, (unsigned long bb)) var3,
+           $typemap(cstype, unsigned long) var4)
+  {
+    // do something
+  }
+%}
+
      +
      + +

      +The result is the following expansion +

      + +
      +
      +%typemap(cstype) unsigned long    "uint"
+%typemap(cstype) unsigned long bb "bool"
+%typemap(cscode) BarClass %{
+  void foo(uint var1,
+           bool var2,
+           bool var3,
+           uint var4)
+  {
+    // do something
+  }
+%}
+
      +
      + +

      10.5 Common typemap methods

      + + +

      +The set of typemaps recognized by a language module may vary. However, +the following typemap methods are nearly universal: +

      + +

      10.5.1 "in" typemap

      + + +

      +The "in" typemap is used to convert function arguments from the target language +to C. For example: +

      + +
      +
      +%typemap(in) int {
+   $1 = PyInt_AsLong($input);
+}
+
      +
      + +

      +The following special variables are available: +

      + +
      +
      +$input            - Input object holding value to be converted.
+$symname          - Name of function/method being wrapped
+
      +
      + +

      +This is probably the most commonly redefined typemap because it can be used +to implement customized conversions. +

      + +

      +In addition, the "in" typemap allows the number of converted arguments to be +specified. The numinputs attributes facilitates this. For example: +

      + +
      +
      +// Ignored argument.
+%typemap(in, numinputs=0) int *out (int temp) {
+    $1 = &temp;
+}
+
      +
      + +

      +At this time, only zero or one arguments may be converted. +When numinputs is set to 0, the argument is effectively ignored and cannot be supplied from the target language. +The argument is still required when making the C/C++ call and the above typemap +shows the value used is instead obtained from a locally declared variable called temp. +Usually numinputs is not specified, whereupon the default value is 1, that is, there is a one to one mapping of the number of arguments when used from the target language to the C/C++ call. +Multi-argument typemaps provide a similar concept where the number of arguments mapped from the target language to C/C++ can be changed for more tha multiple adjacent C/C++ arguments. +

      + +

      +Compatibility note: Specifying numinputs=0 +is the same as the old "ignore" typemap. +

      + +

      10.5.2 "typecheck" typemap

      + + +

      +The "typecheck" typemap is used to support overloaded functions and methods. It merely checks an argument +to see whether or not it matches a specific type. For example: +

      + +
      +
      +%typemap(typecheck,precedence=SWIG_TYPECHECK_INTEGER) int {
+   $1 = PyInt_Check($input) ? 1 : 0;
+}
+
      +
      + +

      +For typechecking, the $1 variable is always a simple integer that is set to 1 or 0 depending on whether or not +the input argument is the correct type. +

      + +

      +If you define new "in" typemaps and your program uses overloaded methods, you should also define a collection of +"typecheck" typemaps. More details about this follow in a later section on "Typemaps and Overloading." +

      + +

      10.5.3 "out" typemap

      + + +

      +The "out" typemap is used to convert function/method return values from C +into the target language. For example: +

      + +
      +
      +%typemap(out) int {
+   $result = PyInt_FromLong($1);
+}
+
      +
      + +

      +The following special variables are available. +

      + +
      +
      +$result           - Result object returned to target language.
+$symname          - Name of function/method being wrapped
+
      +
      + +

      +The "out" typemap supports an optional attribute flag called "optimal". This is for code optimisation and is detailed in the Optimal code generation when returning by value section. +

      + +

      10.5.4 "arginit" typemap

      + + +

      +The "arginit" typemap is used to set the initial value of a function +argument--before any conversion has occurred. This is not normally +necessary, but might be useful in highly specialized applications. +For example: +

      + +
      +
      +// Set argument to NULL before any conversion occurs
+%typemap(arginit) int *data {
+   $1 = NULL;
+}
+
      +
      + +

      10.5.5 "default" typemap

      + + +

      +The "default" typemap is used to turn an argument into a default +argument. For example: +

      + +
      +
      +%typemap(default) int flags {
+   $1 = DEFAULT_FLAGS;
+}
+...
+int foo(int x, int y, int flags);
+
      +
      + +

      +The primary use of this typemap is to either change the wrapping of +default arguments or specify a default argument in a language where +they aren't supported (like C). Target languages that do not support +optional arguments, such as Java and C#, effectively ignore the value specified +by this typemap as all arguments must be given. +

      + +

      +Once a default typemap has been applied to an argument, all arguments +that follow must have default values. +See the Default/optional arguments section +for further information on default argument wrapping. +

      + +

      10.5.6 "check" typemap

      + + +

      +The "check" typemap is used to supply value checking code during argument +conversion. The typemap is applied after arguments have been +converted. For example: +

      + +
      +
      +%typemap(check) int positive {
+   if ($1 <= 0) {
+       SWIG_exception(SWIG_ValueError,"Expected positive value.");
+   }
+}
+
      +
      + +

      10.5.7 "argout" typemap

      + + +

      +The "argout" typemap is used to return values from arguments. This +is most commonly used to write wrappers for C/C++ functions that need +to return multiple values. The "argout" typemap is almost always combined +with an "in" typemap---possibly to ignore the input value. For example: +

      + +
      +
      +/* Set the input argument to point to a temporary variable */
+%typemap(in, numinputs=0) int *out (int temp) {
+   $1 = &temp;
+}
+
+%typemap(argout) int *out {
+   // Append output value $1 to $result
+   ...
+}
+
      +
      + +

      +The following special variables are available. +

      + +
      +
      +$result           - Result object returned to target language.
+$input            - The original input object passed.
+$symname          - Name of function/method being wrapped
+
      +
      + +

      +The code supplied to the "argout" typemap is always placed after +the "out" typemap. If multiple return values are used, the extra +return values are often appended to return value of the function. +

      + +

      +See the typemaps.i library for examples. +

      + +

      10.5.8 "freearg" typemap

      + + +

      +The "freearg" typemap is used to cleanup argument data. It is only +used when an argument might have allocated resources that need to be +cleaned up when the wrapper function exits. The "freearg" typemap +usually cleans up argument resources allocated by the "in" typemap. +For example: +

      + +
      +
      +// Get a list of integers
+%typemap(in) int *items {
+   int nitems = Length($input);    
+   $1 = (int *) malloc(sizeof(int)*nitems);
+}
+// Free the list 
+%typemap(freearg) int *items {
+   free($1);
+}
+
      +
      + +

      +The "freearg" typemap inserted at the end of the wrapper function, +just before control is returned back to the target language. This +code is also placed into a special variable $cleanup that may +be used in other typemaps whenever a wrapper function needs to abort +prematurely. +

      + +

      10.5.9 "newfree" typemap

      + + +

      +The "newfree" typemap is used in conjunction with the %newobject +directive and is used to deallocate memory used by the return result +of a function. For example: +

      + +
      +
      +%typemap(newfree) string * {
+   delete $1;
+}
+%typemap(out) string * {
+   $result = PyString_FromString($1->c_str());
+}
+...
+
+%newobject foo;
+...
+string *foo();
+
      +
      + +

      +See Object ownership and %newobject for further details. +

      + +

      10.5.10 "memberin" typemap

      + + +

      +The "memberin" typemap is used to copy data from an already converted input value +into a structure member. It is typically used to handle array members and other special +cases. For example: +

      + +
      +
      +%typemap(memberin) int [4] {
+   memmove($1, $input, 4*sizeof(int));
+}
+
      +
      + +

      +It is rarely necessary to write "memberin" typemaps---SWIG already provides +a default implementation for arrays, strings, and other objects. +

      + +

      10.5.11 "varin" typemap

      + + +

      +The "varin" typemap is used to convert objects in the target language to C for the +purposes of assigning to a C/C++ global variable. This is implementation specific. +

      + +

      10.5.12 "varout" typemap

      + + +

      +The "varout" typemap is used to convert a C/C++ object to an object in the target +language when reading a C/C++ global variable. This is implementation specific. +

      + +

      10.5.13 "throws" typemap

      + + +

      +The "throws" typemap is only used when SWIG parses a C++ method with an exception specification or has the %catches feature attached to the method. +It provides a default mechanism for handling C++ methods that have declared the exceptions they will throw. +The purpose of this typemap is to convert a C++ exception into an error or exception in the target language. +It is slightly different to the other typemaps as it is based around the exception type rather than the type of a parameter or variable. +For example: +

      + +
      +
      +%typemap(throws) const char * %{
+  PyErr_SetString(PyExc_RuntimeError, $1);
+  SWIG_fail;
+%}
+void bar() throw (const char *);
+
      +
      + +

      +As can be seen from the generated code below, SWIG generates an exception handler +with the catch block comprising the "throws" typemap content. +

      + +
      +
      +...
+try {
+    bar();
+}
+catch(char const *_e) {
+    PyErr_SetString(PyExc_RuntimeError, _e);
+    SWIG_fail;
+    
+}
+...
+
      +
      + +

      +Note that if your methods do not have an exception specification yet they do throw exceptions, SWIG cannot know how to deal with them. +For a neat way to handle these, see the Exception handling with %exception section. +

      + +

      10.6 Some typemap examples

      + + +

      +This section contains a few examples. Consult language module documentation +for more examples. +

      + +

      10.6.1 Typemaps for arrays

      + + +

      +A common use of typemaps is to provide support for C arrays appearing both as +arguments to functions and as structure members. +

      + +

      +For example, suppose you had a function like this: +

      + +
      +
      +void set_vector(int type, float value[4]);
+
      +
      + +

      +If you wanted to handle float value[4] as a list of floats, you might write a typemap +similar to this: +

      + +
      +
      +
+%typemap(in) float value[4] (float temp[4]) {
+  int i;
+  if (!PySequence_Check($input)) {
+    PyErr_SetString(PyExc_ValueError,"Expected a sequence");
+    return NULL;
+  }
+  if (PySequence_Length($input) != 4) {
+    PyErr_SetString(PyExc_ValueError,"Size mismatch. Expected 4 elements");
+    return NULL;
+  }
+  for (i = 0; i < 4; i++) {
+    PyObject *o = PySequence_GetItem($input,i);
+    if (PyNumber_Check(o)) {
+      temp[i] = (float) PyFloat_AsDouble(o);
+    } else {
+      PyErr_SetString(PyExc_ValueError,"Sequence elements must be numbers");      
+      return NULL;
+    }
+  }
+  $1 = temp;
+}
+
      +
      + +

      +In this example, the variable temp allocates a small array on the +C stack. The typemap then populates this array and passes it to the underlying C function. +

      + +

      +When used from Python, the typemap allows the following type of function call: +

      + +
      +
      +>>> set_vector(type, [ 1, 2.5, 5, 20 ])
+
      +
      + +

      +If you wanted to generalize the typemap to apply to arrays of all dimensions you might write this: +

      + +
      +
      +%typemap(in) float value[ANY] (float temp[$1_dim0]) {
+  int i;
+  if (!PySequence_Check($input)) {
+    PyErr_SetString(PyExc_ValueError,"Expected a sequence");
+    return NULL;
+  }
+  if (PySequence_Length($input) != $1_dim0) {
+    PyErr_SetString(PyExc_ValueError,"Size mismatch. Expected $1_dim0 elements");
+    return NULL;
+  }
+  for (i = 0; i < $1_dim0; i++) {
+    PyObject *o = PySequence_GetItem($input,i);
+    if (PyNumber_Check(o)) {
+      temp[i] = (float) PyFloat_AsDouble(o);
+    } else {
+      PyErr_SetString(PyExc_ValueError,"Sequence elements must be numbers");      
+      return NULL;
+    }
+  }
+  $1 = temp;
+}
+
      +
      + +

      +In this example, the special variable $1_dim0 is expanded with the actual +array dimensions. Multidimensional arrays can be matched in a similar manner. For example: +

      + +
      +
      +%typemap(in) float matrix[ANY][ANY] (float temp[$1_dim0][$1_dim1]) {
+   ... convert a 2d array ...
+}
+
      +
      + +

      +For large arrays, it may be impractical to allocate storage on the stack using a temporary variable +as shown. To work with heap allocated data, the following technique can be used. +

      + +
      +
      +%typemap(in) float value[ANY] {
+  int i;
+  if (!PySequence_Check($input)) {
+    PyErr_SetString(PyExc_ValueError,"Expected a sequence");
+    return NULL;
+  }
+  if (PySequence_Length($input) != $1_dim0) {
+    PyErr_SetString(PyExc_ValueError,"Size mismatch. Expected $1_dim0 elements");
+    return NULL;
+  }
+  $1 = (float *) malloc($1_dim0*sizeof(float));
+  for (i = 0; i < $1_dim0; i++) {
+    PyObject *o = PySequence_GetItem($input,i);
+    if (PyNumber_Check(o)) {
+      $1[i] = (float) PyFloat_AsDouble(o);
+    } else {
+      PyErr_SetString(PyExc_ValueError,"Sequence elements must be numbers");      
+      free($1);
+      return NULL;
+    }
+  }
+}
+%typemap(freearg) float value[ANY] {
+   if ($1) free($1);
+}
+
      +
      + +

      +In this case, an array is allocated using malloc. The freearg typemap is then used +to release the argument after the function has been called. +

      + +

      +Another common use of array typemaps is to provide support for array structure members. +Due to subtle differences between pointers and arrays in C, you can't just "assign" to +a array structure member. Instead, you have to explicitly copy elements into the array. +For example, suppose you had a structure like this: +

      + +
      +struct SomeObject {
+	float  value[4];
+        ...
+};
+
      + +

      +When SWIG runs, it won't produce any code to set the vec member. +You may even get a warning message like this: +

      + +
      +swig -python  example.i
+Generating wrappers for Python
+example.i:10.  Warning. Array member value will be read-only.
+
      + +

      +These warning messages indicate that SWIG does not know how you want +to set the vec field. +

      + +

      +To fix this, you can supply a special "memberin" typemap like this: +

      + +
      +%typemap(memberin) float [ANY] {
+  int i;
+  for (i = 0; i < $1_dim0; i++) {
+      $1[i] = $input[i];
+  }
+}
+
      + +

      +The memberin typemap is used to set a structure member from data that has already been converted +from the target language to C. In this case, $input is the local variable in which +converted input data is stored. This typemap then copies this data into the structure. +

      + +

      +When combined with the earlier typemaps for arrays, the combination of the "in" and "memberin" typemap allows +the following usage: +

      + +
      +
      +>>> s = SomeObject()
+>>> s.x = [1, 2.5, 5, 10]
+
      +
      + +

      +Related to structure member input, it may be desirable to return structure members as a new kind of +object. For example, in this example, you will get very odd program behavior where the structure member +can be set nicely, but reading the member simply returns a pointer: +

      + +
      +
      +>>> s = SomeObject()
+>>> s.x = [1, 2.5, 5, 10]
+>>> print s.x
+_1008fea8_p_float
+>>> 
+
      +
      + +

      +To fix this, you can write an "out" typemap. For example: +

      + +
      +
      +%typemap(out) float [ANY] {
+  int i;
+  $result = PyList_New($1_dim0);
+  for (i = 0; i < $1_dim0; i++) {
+    PyObject *o = PyFloat_FromDouble((double) $1[i]);
+    PyList_SetItem($result,i,o);
+  }
+}
+
      +
      + +

      +Now, you will find that member access is quite nice: +

      + +
      +
      +>>> s = SomeObject()
+>>> s.x = [1, 2.5, 5, 10]
+>>> print s.x
+[ 1, 2.5, 5, 10]
+
      +
      + +

      +Compatibility Note: SWIG1.1 used to provide a special "memberout" typemap. However, it was mostly +useless and has since been eliminated. To return structure members, simply use the "out" typemap. +

      + +

      10.6.2 Implementing constraints with typemaps

      + + +

      +One particularly interesting application of typemaps is the +implementation of argument constraints. This can be done with the +"check" typemap. When used, this allows you to provide code for +checking the values of function arguments. For example :

      + +
      +%module math
+
+%typemap(check) double posdouble {
+	if ($1 < 0) {
+		croak("Expecting a positive number");
+	}
+}
+
+...
+double sqrt(double posdouble);
+
+
      + +

      +This provides a sanity check to your wrapper function. If a negative +number is passed to this function, a Perl exception will be raised and +your program terminated with an error message.

      + +

      +This kind of checking can be particularly useful when working with +pointers. For example :

      + +
      +%typemap(check) Vector * {
+    if ($1 == 0) {
+        PyErr_SetString(PyExc_TypeError,"NULL Pointer not allowed");
+        return NULL;
+   }
+}
+
+
      + +

      +will prevent any function involving a Vector * from accepting +a NULL pointer. As a result, SWIG can often prevent a potential +segmentation faults or other run-time problems by raising an exception +rather than blindly passing values to the underlying C/C++ program.

      + +

      +Note: A more advanced constraint checking system is in development. Stay tuned. +

      + +

      10.7 Typemaps for multiple languages

      + + +

      +The code within typemaps is usually language dependent, +however, many languages support the same typemaps. +In order to distinguish typemaps across different languages, the preprocessor should be used. +For example, the "in" typemap for Perl and Ruby could be written as: +

      + +
      +#if defined(SWIGPERL)
+  %typemap(in) int "$1 = ($1_ltype) SvIV($input);"
+#elif defined(SWIGRUBY)
+  %typemap(in) int "$1 = NUM2INT($input);"
+#else
+  #warning no "in" typemap defined
+#endif
+
      + +

      +The full set of language specific macros is defined in the Conditional Compilation section. +The example above also shows a common approach of issuing a warning for an as yet unsupported language. +

      + +

      +Compatibility note: In SWIG-1.1 different languages could be distinguished with the language name being put within the %typemap directive, for example,
      +%typemap(ruby,in) int "$1 = NUM2INT($input);". +

      + +

      10.8 Optimal code generation when returning by value

      + + +

      +The "out" typemap is the main typemap for return types. +This typemap supports an optional attribute flag called "optimal", which is for reducing +temporary variables and the amount of generated code, thereby giving the compiler the opportunity to +use return value optimization for generating faster executing code. +It only really makes a difference when returning objects by value and has some limitations on usage, +as explained later on. +

      + +

      +When a function returns an object by value, SWIG generates code that instantiates the default +type on the stack then assigns the value returned by the function call to it. +A copy of this object is then made on the heap and this is what is ultimately stored and +used from the target language. +This will be clearer considering an example. +Consider running the following code through SWIG: +

      + +
      +
      +%typemap(out) SWIGTYPE %{
+  $result = new $1_ltype((const $1_ltype &)$1);
+%}
+
+%inline %{
+#include <iostream>
+using namespace std;
+
+struct XX {
+  XX() { cout << "XX()" << endl; }
+  XX(int i) { cout << "XX(" << i << ")" << endl; }
+  XX(const XX &other) { cout << "XX(const XX &)" << endl; }
+  XX & operator =(const XX &other) { cout << "operator=(const XX &)" << endl; return *this; }
+  ~XX() { cout << "~XX()" << endl; }
+  static XX create() { 
+    return XX(0);
+  }
+};
+%}
+
      +
      + +

      +The "out" typemap shown is the default typemap for C# when returning by objects by value. +When making a call to XX::create() from C#, the output is as follows: +

      + +
      +
      +XX()
+XX(0)
+operator=(const XX &)
+~XX()
+XX(const XX &)
+~XX()
+~XX()
+
      +
      + +

      +Note that three objects are being created as well as an assignment. +Wouldn't it be great if the XX::create() method was the only time a constructor was called? +As the method returns by value, this is asking a lot and the code that SWIG generates by default +makes it impossible for the compiler to use return value optimisation (RVO). +However, this is where the "optimal" attribute in the "out" typemap can help out. +If the typemap code is kept the same and just the "optimal" attribute specified like this: +

      + +
      +
      +%typemap(out, optimal="1") SWIGTYPE %{
+  $result = new $1_ltype((const $1_ltype &)$1);
+%}
+
      +
      + +

      +then when the code is run again, the output is simply: +

      + +
      +
      +XX(0)
+~XX()
+
      +
      + +

      +How the "optimal" attribute works is best explained using the generated code. +Without "optimal", the generated code is: +

      + +
      +
      +SWIGEXPORT void * SWIGSTDCALL CSharp_XX_create() {
+  void * jresult ;
+  XX result;
+  result = XX::create();
+  jresult = new XX((const XX &)result);
+  return jresult;
+}
+
+
      +
      + +

      +With the "optimal" attribute, the code is: +

      + +
      +
      +SWIGEXPORT void * SWIGSTDCALL CSharp_XX_create() {
+  void * jresult ;
+  jresult = new XX((const XX &)XX::create());
+  return jresult;
+}
+
      +
      + +

      +The major difference is the result temporary variable holding the value returned from XX::create() is no longer generated and instead the copy constructor call is made directly from +the value returned by XX::create(). +With modern compilers implementing RVO, the copy is not actually done, in fact the object is never created +on the stack in XX::create() at all, it is simply created directly on the heap. +In the first instance, the $1 special variable in the typemap is expanded into result. +In the second instance, $1 is expanded into XX::create() and this is essentially +what the "optimal" attribute is telling SWIG to do. +

      + +

      +The "optimal" attribute optimisation is not turned on by default as it has a number of restrictions. +Firstly, some code cannot be condensed into a simple call for passing into the copy constructor. +One common occurrence is when %exception is used. +Consider adding the following %exception to the example: +

      + +
      +
      +%exception XX::create() %{
+try {
+  $action
+} catch(const std::exception &e) {
+  cout << e.what() << endl;
+}
+%}
+
      +
      + +

      +SWIG can detect when the "optimal" attribute cannot be used and will ignore it and in this case will issue the following warning: +

      + +
      +
      +example.i:28: Warning(474): Method XX::create() usage of the optimal attribute in the out 
+typemap at example.i:14 ignored as the following cannot be used to generate optimal code: 
+try {
+  result = XX::create();
+} catch(const std::exception &e) {
+  cout << e.what() << endl;
+}
+
      +
      + +

      +It should be clear that the above code cannot be used as the argument to the copy constructor call, ie for the $1 substitution. +

      + +

      +Secondly, if the typemaps uses $1 more than once, then multiple calls to the wrapped function +will be made. Obviously that is not very optimal. +In fact SWIG attempts to detect this and will issue a warning something like: +

      + +
      +
      +example.i:21: Warning(475): Multiple calls to XX::create() might be generated due to 
+optimal attribute usage in the out typemap at example.i:7.
+
      +
      + +

      +However, it doesn't always get it right, for example when $1 is within some commented out code. +

      + +

      10.9 Multi-argument typemaps

      + + +

      +So far, the typemaps presented have focused on the problem of dealing with +single values. For example, converting a single input object to a single argument +in a function call. However, certain conversion problems are difficult to handle +in this manner. As an example, consider the example at the very beginning of this +chapter: +

      + +
      +
      +int foo(int argc, char *argv[]);
+
      +
      + +

      +Suppose that you wanted to wrap this function so that it accepted a single +list of strings like this: +

      + +
      +
      +>>> foo(["ale","lager","stout"])
+
      +
      + +

      +To do this, you not only need to map a list of strings to char *argv[], but the +value of int argc is implicitly determined by the length of the list. Using only simple +typemaps, this type of conversion is possible, but extremely painful. Therefore, SWIG1.3 +introduces the notion of multi-argument typemaps. +

      + +

      +A multi-argument typemap is a conversion rule that specifies how to +convert a single object in the target language to set of +consecutive function arguments in C/C++. For example, the following multi-argument +maps perform the conversion described for the above example: +

      + +
      +
      +%typemap(in) (int argc, char *argv[]) {
+  int i;
+  if (!PyList_Check($input)) {
+    PyErr_SetString(PyExc_ValueError, "Expecting a list");
+    return NULL;
+  }
+  $1 = PyList_Size($input);
+  $2 = (char **) malloc(($1+1)*sizeof(char *));
+  for (i = 0; i < $1; i++) {
+    PyObject *s = PyList_GetItem($input,i);
+    if (!PyString_Check(s)) {
+        free($2);
+        PyErr_SetString(PyExc_ValueError, "List items must be strings");
+        return NULL;
+    }
+    $2[i] = PyString_AsString(s);
+  }
+  $2[i] = 0;
+}
+
+%typemap(freearg) (int argc, char *argv[]) {
+   if ($2) free($2);
+}
+
      +
      + +

      +A multi-argument map is always specified by surrounding the arguments with parentheses as shown. +For example: +

      + +
      +
      +%typemap(in) (int argc, char *argv[]) { ... }
+
      +
      + +

      +Within the typemap code, the variables $1, $2, and so forth refer to each type +in the map. All of the usual substitutions apply--just use the appropriate $1 or $2 +prefix on the variable name (e.g., $2_type, $1_ltype, etc.) +

      + +

      +Multi-argument typemaps always have precedence over simple typemaps and SWIG always performs longest-match searching. +Therefore, you will get the following behavior: +

      + +
      +
      +%typemap(in) int argc                              { ... typemap 1 ... }
+%typemap(in) (int argc, char *argv[])              { ... typemap 2 ... }
+%typemap(in) (int argc, char *argv[], char *env[]) { ... typemap 3 ... }
+
+int foo(int argc, char *argv[]);                   // Uses typemap 2
+int bar(int argc, int x);                          // Uses typemap 1
+int spam(int argc, char *argv[], char *env[]);     // Uses typemap 3
+
      +
      + +

      +It should be stressed that multi-argument typemaps can appear anywhere in a function declaration and can +appear more than once. For example, you could write this: +

      + +
      +
      +%typemap(in) (int scount, char *swords[]) { ... }
+%typemap(in) (int wcount, char *words[]) { ... }
+
+void search_words(int scount, char *swords[], int wcount, char *words[], int maxcount);
+
      +
      + +

      +Other directives such as %apply and %clear also work with multi-argument maps. For example: +

      + +
      +
      +%apply (int argc, char *argv[]) {
+    (int scount, char *swords[]),
+    (int wcount, char *words[])
+};
+...
+%clear (int scount, char *swords[]), (int wcount, char *words[]);
+...
+
      +
      + +

      +Although multi-argument typemaps may seem like an exotic, little used feature, there +are several situations where they make sense. First, suppose you wanted to wrap +functions similar to the low-level read() and write() system calls. +For example: +

      + +
      +
      +typedef unsigned int size_t;
+
+int read(int fd, void *rbuffer, size_t len);
+int write(int fd, void *wbuffer, size_t len);
+
      +
      + +

      +As is, the only way to use the functions would be to allocate memory and pass some kind of pointer +as the second argument---a process that might require the use of a helper function. However, using +multi-argument maps, the functions can be transformed into something more natural. For example, you +might write typemaps like this: +

      + +
      +
      +// typemap for an outgoing buffer
+%typemap(in) (void *wbuffer, size_t len) {
+   if (!PyString_Check($input)) {
+       PyErr_SetString(PyExc_ValueError, "Expecting a string");
+       return NULL;
+   }
+   $1 = (void *) PyString_AsString($input);
+   $2 = PyString_Size($input);
+}
+
+// typemap for an incoming buffer
+%typemap(in) (void *rbuffer, size_t len) {
+   if (!PyInt_Check($input)) {
+       PyErr_SetString(PyExc_ValueError, "Expecting an integer");
+       return NULL;
+   }
+   $2 = PyInt_AsLong($input);
+   if ($2 < 0) {
+       PyErr_SetString(PyExc_ValueError, "Positive integer expected");
+       return NULL;
+   }
+   $1 = (void *) malloc($2);
+}
+
+// Return the buffer.  Discarding any previous return result
+%typemap(argout) (void *rbuffer, size_t len) {
+   Py_XDECREF($result);   /* Blow away any previous result */
+   if (result < 0) {      /* Check for I/O error */
+       free($1);
+       PyErr_SetFromErrno(PyExc_IOError);
+       return NULL;
+   }
+   $result = PyString_FromStringAndSize($1,result);
+   free($1);
+}
+
      +
      + +

      +(note: In the above example, $result and result are two different variables. +result is the real C datatype that was returned by the function. $result is the +scripting language object being returned to the interpreter.). +

      + +

      +Now, in a script, you can write code that simply passes buffers as strings like this: +

      + +
      +
      +>>> f = example.open("Makefile")
+>>> example.read(f,40)
+'TOP        = ../..\nSWIG       = $(TOP)/.'
+>>> example.read(f,40)
+'./swig\nSRCS       = example.c\nTARGET    '
+>>> example.close(f)
+0
+>>> g = example.open("foo", example.O_WRONLY | example.O_CREAT, 0644)
+>>> example.write(g,"Hello world\n")
+12
+>>> example.write(g,"This is a test\n")
+15
+>>> example.close(g)
+0
+>>>
+
      +
      + +

      +A number of multi-argument typemap problems also arise in libraries that +perform matrix-calculations--especially if they are mapped onto low-level Fortran +or C code. For example, you might have a function like this: +

      + +
      +
      +int is_symmetric(double *mat, int rows, int columns);
+
      +
      + +

      +In this case, you might want to pass some kind of higher-level object as an matrix. To do +this, you could write a multi-argument typemap like this: +

      + +
      +
      +%typemap(in) (double *mat, int rows, int columns) {
+    MatrixObject *a;
+    a = GetMatrixFromObject($input);     /* Get matrix somehow */
+
+    /* Get matrix properties */
+    $1 = GetPointer(a);
+    $2 = GetRows(a);
+    $3 = GetColumns(a);
+}
+
      +
      + +

      +This kind of technique can be used to hook into scripting-language matrix packages such as +Numeric Python. However, it should also be stressed that some care is in order. For example, +when crossing languages you may need to worry about issues such as row-major vs. column-major +ordering (and perform conversions if needed). +

      + +

      10.10 The run-time type checker

      + + +

      +Most scripting languages need type information at run-time. This type information +can include how to construct types, how to garbage collect types, and the inheritance +relationships between types. If the language interface does not provide its own type +information storage, the generated SWIG code needs to provide it. +

      + +

      +Requirements for the type system: +

      +
        +
      • Store inheritance and type equivalence information and be able to correctly +re-create the type pointer.
        • +
      • Share type information between modules.
        • +
      • Modules can be loaded in any order, irregardless of actual type +dependency.
        • +
      • Avoid the use of dynamically allocated memory, and library/system calls in general.
        • +
      • Provide a reasonably fast implementation, minimizing the lookup time for all +language modules.
        • +
      • Custom, language specific information can be attached to types.
        • +
      • Modules can be unloaded from the type system.
        • +
      + +

      10.10.1 Implementation

      + + +

      +The run-time type checker is used by many, but not all, of SWIG's supported target languages. +The run-time type checker features +are not required and are thus not used for strongly typed languages such as Java and C#. +The scripting and scheme based languages rely on it and it forms +a critical part of SWIG's operation for these languages. +

      + +

      +When pointers, arrays, and objects are wrapped by SWIG, they are normally converted +into typed pointer objects. For example, an instance of Foo * might be +a string encoded like this: +

      + +
      +
      +_108e688_p_Foo
+
      +
      + +

      +At a basic level, the type checker simply restores some type-safety to +extension modules. However, the type checker is also responsible for +making sure that wrapped C++ classes are handled +correctly---especially when inheritance is used. This is especially +important when an extension module makes use of multiple inheritance. +For example: +

      + +
      +
      +class Foo {
+   int x;
+};
+
+class Bar {
+   int y;
+};
+
+class FooBar : public Foo, public Bar {
+   int z;
+};
+
      +
      + +

      +When the class FooBar is organized in memory, it contains the contents +of the classes Foo and Bar as well as its own data members. For example: +

      + +
      +
      +FooBar --> | -----------|  <-- Foo
+           |   int x    |
+           |------------|  <-- Bar
+           |   int y    |
+           |------------|
+           |   int z    |
+           |------------|
+
      +
      + +

      +Because of the way that base class data is stacked together, the +casting of a Foobar * to either of the base classes may +change the actual value of the pointer. This means that it is +generally not safe to represent pointers using a simple integer or a +bare void *---type tags are needed to implement correct +handling of pointer values (and to make adjustments when needed). +

      + +

      +In the wrapper code generated for each language, pointers are handled through +the use of special type descriptors and conversion functions. For example, +if you look at the wrapper code for Python, you will see code like this: +

      + +
      +
      +if ((SWIG_ConvertPtr(obj0,(void **) &arg1, SWIGTYPE_p_Foo,1)) == -1) return NULL;
+
      +
      + +

      +In this code, SWIGTYPE_p_Foo is the type descriptor that +describes Foo *. The type descriptor is actually a pointer to a +structure that contains information about the type name to use in the +target language, a list of equivalent typenames (via typedef or +inheritance), and pointer value handling information (if applicable). +The SWIG_ConvertPtr() function is simply a utility function +that takes a pointer object in the target language and a +type-descriptor objects and uses this information to generate a C++ +pointer. However, the exact name and calling conventions of the conversion +function depends on the target language (see language specific chapters for details). +

      + +

      +The actual type code is in swigrun.swg, and gets inserted near the top of the generated +swig wrapper file. The phrase "a type X that can cast into a type Y" means +that given a type X, it can be converted into a type Y. In other words, X is a derived +class of Y or X is a typedef of Y. The structure to store type information looks like this: +

      + +
      +
      +/* Structure to store information on one type */
+typedef struct swig_type_info {
+  const char *name;             /* mangled name of this type */
+  const char *str;              /* human readable name for this type */
+  swig_dycast_func dcast;       /* dynamic cast function down a hierarchy */
+  struct swig_cast_info *cast;  /* Linked list of types that can cast into this type */
+  void *clientdata;             /* Language specific type data */
+} swig_type_info;
+
+/* Structure to store a type and conversion function used for casting */
+typedef struct swig_cast_info {
+  swig_type_info *type;          /* pointer to type that is equivalent to this type */
+  swig_converter_func converter; /* function to cast the void pointers */
+  struct swig_cast_info *next;   /* pointer to next cast in linked list */
+  struct swig_cast_info *prev;   /* pointer to the previous cast */
+} swig_cast_info;
+
      +
      + +

      +Each swig_type_info stores a linked list of types that it is equivalent to. Each entry in this +doubly linked list stores a pointer back to another swig_type_info structure, +along with a pointer to a conversion function. This conversion function is used +to solve the above problem of the FooBar class, correctly returning a pointer to +the type we want. +

      + +

      +The basic problem we need to solve is verifying and building arguments passed to functions. +So going back to the SWIG_ConvertPtr() function example from above, we are +expecting a Foo * and need to +check if obj0 is in fact a Foo *. From before, SWIGTYPE_p_Foo is just +a pointer to the swig_type_info structure describing Foo *. So we loop through the +linked list of swig_cast_info structures attached to SWIGTYPE_p_Foo. If we see that the type of obj0 is in the +linked list, we pass the object through the associated conversion function and +then return a positive. If we reach the end of the linked list without a match, +then obj0 can not be converted to a Foo * and an error is generated. +

      + +

      +Another issue needing to be addressed is sharing type information between multiple modules. +More explicitly, we need +to have ONE swig_type_info for each type. If two modules both use the type, the +second module loaded must lookup and use the swig_type_info structure from the module already loaded. +Because no dynamic memory is used and the circular dependencies of the +casting information, loading the type information is somewhat tricky, and not explained here. +A complete description is in the Lib/swiginit.swg file (and near the top of any generated file). +

      + +

      +Each module has one swig_module_info structure which looks like this: +

      + +
      +
      +/* Structure used to store module information
+ * Each module generates one structure like this, and the runtime collects
+ * all of these structures and stores them in a circularly linked list.*/
+typedef struct swig_module_info {
+  swig_type_info **types;         /* Array of pointers to swig_type_info structs in this module */
+  int size;                       /* Number of types in this module */
+  struct swig_module_info *next;  /* Pointer to next element in circularly linked list */
+  swig_type_info **type_initial;  /* Array of initially generated type structures */
+  swig_cast_info **cast_initial;  /* Array of initially generated casting structures */
+  void *clientdata;               /* Language specific module data */
+} swig_module_info;
+
      +
      + +

      +Each module stores an array of pointers to swig_type_info structures and the number of +types in this module. So when a second module is loaded, it finds the swig_module_info +structure for the first module and searches the array of types. If any of its own +types are in the first module and have already been loaded, it uses those swig_type_info +structures rather than creating new ones. These swig_module_info +structures are chained together in a circularly linked list. +

      + +

      10.10.2 Usage

      + + +

      This section covers how to use these functions from typemaps. To learn how to +call these functions from external files (not the generated _wrap.c file), see +the External access to the run-time system +section.

      + +

      When pointers are converted in a typemap, the typemap code often looks +similar to this: +

      + +
      +
      +%typemap(in) Foo * {
+  if ((SWIG_ConvertPtr($input, (void **) &$1, $1_descriptor)) == -1) return NULL;
+}
+
      +
      + +

      +The most critical part is the typemap is the use of the $1_descriptor +special variable. When placed in a typemap, this is expanded into the +SWIGTYPE_* type descriptor object above. As a general rule, +you should always use $1_descriptor instead of trying to +hard-code the type descriptor name directly. +

      + +

      +There is another reason why you should always use the +$1_descriptor variable. When this special variable is +expanded, SWIG marks the corresponding type as "in use." When +type-tables and type information is emitted in the wrapper file, +descriptor information is only generated for those datatypes that were +actually used in the interface. This greatly reduces the size of the +type tables and improves efficiency. +

      + +

      +Occasionally, you might need to write a typemap that needs to convert +pointers of other types. To handle this, the special variable macro +$descriptor(type) covered earlier can be used to generate the SWIG type +descriptor name for any C datatype. For example: +

      + +
      +
      +%typemap(in) Foo * {
+  if ((SWIG_ConvertPtr($input, (void **) &$1, $1_descriptor)) == -1) {
+     Bar *temp;
+     if ((SWIG_ConvertPtr($input, (void **) &temp, $descriptor(Bar *)) == -1) {
+         return NULL;
+     }
+     $1 = (Foo *) temp;
+  }
+}
+
      +
      + +

      +The primary use of $descriptor(type) is when writing typemaps for container +objects and other complex data structures. There are some restrictions on the argument---namely it must +be a fully defined C datatype. It can not be any of the special typemap variables. +

      + +

      +In certain cases, SWIG may not generate type-descriptors like you expect. For example, +if you are converting pointers in some non-standard way or working with an unusual +combination of interface files and modules, you may find that SWIG omits information +for a specific type descriptor. To fix this, you may need to use the %types directive. +For example: +

      + +
      +
      +%types(int *, short *, long *, float *, double *);
+
      +
      + +

      +When %types is used, SWIG generates type-descriptor +information even if those datatypes never appear elsewhere in the +interface file. +

      + +

      +Further details about the run-time type checking can be found in the documentation for +individual language modules. Reading the source code may also help. The file +Lib/swigrun.swg in the SWIG library contains all of the source code for +type-checking. This code is also included in every generated wrapped file so you +probably just look at the output of SWIG to get a better sense for how types are +managed. +

      + +

      10.11 Typemaps and overloading

      + + +

      +In many target languages, SWIG fully supports C++ overloaded methods and functions. For example, +if you have a collection of functions like this: +

      + +
      +
      +int foo(int x);
+int foo(double x);
+int foo(char *s, int y);
+
      +
      + +

      +You can access the functions in a normal way from the scripting interpreter: +

      + +
      +
      +# Python
+foo(3)           # foo(int)
+foo(3.5)         # foo(double)
+foo("hello",5)   # foo(char *, int)
+
+# Tcl
+foo 3            # foo(int)
+foo 3.5          # foo(double)
+foo hello 5      # foo(char *, int)
+
      +
      + +

      +To implement overloading, SWIG generates a separate wrapper function for each overloaded method. +For example, the above functions would produce something roughly like this: +

      + +
      +
      +// wrapper pseudocode
+_wrap_foo_0(argc, args[]) {       // foo(int)
+   int arg1;
+   int result;
+   ...
+   arg1 = FromInteger(args[0]);
+   result = foo(arg1);
+   return ToInteger(result);
+}
+
+_wrap_foo_1(argc, args[]) {       // foo(double)
+   double arg1;
+   int result;
+   ...
+   arg1 = FromDouble(args[0]);
+   result = foo(arg1);
+   return ToInteger(result);
+}
+
+_wrap_foo_2(argc, args[]) {       // foo(char *, int)
+   char *arg1;
+   int   arg2;
+   int result;
+   ...
+   arg1 = FromString(args[0]);
+   arg2 = FromInteger(args[1]);
+   result = foo(arg1,arg2);
+   return ToInteger(result);
+}
+
+
      +
      + +

      +Next, a dynamic dispatch function is generated: +

      + +
      +
      +_wrap_foo(argc, args[]) {
+   if (argc == 1) {
+       if (IsInteger(args[0])) {
+           return _wrap_foo_0(argc,args);
+       } 
+       if (IsDouble(args[0])) {
+           return _wrap_foo_1(argc,args);
+       }
+   }
+   if (argc == 2) {
+       if (IsString(args[0]) && IsInteger(args[1])) {
+          return _wrap_foo_2(argc,args);
+       }
+   }
+   error("No matching function!\n");
+}
+
      +
      + +

      +The purpose of the dynamic dispatch function is to select the appropriate C++ function based on +argument types---a task that must be performed at runtime in most of SWIG's target languages. +

      + +

      +The generation of the dynamic dispatch function is a relatively tricky affair. Not only must input typemaps +be taken into account (these typemaps can radically change the types of arguments accepted), but overloaded +methods must also be sorted and checked in a very specific order to resolve potential ambiguity. A high-level +overview of this ranking process is found in the "SWIG and C++" chapter. What isn't mentioned in that chapter +is the mechanism by which it is implemented---as a collection of typemaps. +

      + +

      +To support dynamic dispatch, SWIG first defines a general purpose type hierarchy as follows: +

      + +
      +
      +Symbolic Name                   Precedence Value
+------------------------------  ------------------
+SWIG_TYPECHECK_POINTER           0  
+SWIG_TYPECHECK_VOIDPTR           10 
+SWIG_TYPECHECK_BOOL              15 
+SWIG_TYPECHECK_UINT8             20 
+SWIG_TYPECHECK_INT8              25 
+SWIG_TYPECHECK_UINT16            30 
+SWIG_TYPECHECK_INT16             35 
+SWIG_TYPECHECK_UINT32            40 
+SWIG_TYPECHECK_INT32             45 
+SWIG_TYPECHECK_UINT64            50 
+SWIG_TYPECHECK_INT64             55 
+SWIG_TYPECHECK_UINT128           60 
+SWIG_TYPECHECK_INT128            65 
+SWIG_TYPECHECK_INTEGER           70 
+SWIG_TYPECHECK_FLOAT             80 
+SWIG_TYPECHECK_DOUBLE            90 
+SWIG_TYPECHECK_COMPLEX           100 
+SWIG_TYPECHECK_UNICHAR           110 
+SWIG_TYPECHECK_UNISTRING         120 
+SWIG_TYPECHECK_CHAR              130 
+SWIG_TYPECHECK_STRING            140 
+SWIG_TYPECHECK_BOOL_ARRAY        1015 
+SWIG_TYPECHECK_INT8_ARRAY        1025 
+SWIG_TYPECHECK_INT16_ARRAY       1035 
+SWIG_TYPECHECK_INT32_ARRAY       1045 
+SWIG_TYPECHECK_INT64_ARRAY       1055 
+SWIG_TYPECHECK_INT128_ARRAY      1065 
+SWIG_TYPECHECK_FLOAT_ARRAY       1080 
+SWIG_TYPECHECK_DOUBLE_ARRAY      1090 
+SWIG_TYPECHECK_CHAR_ARRAY        1130 
+SWIG_TYPECHECK_STRING_ARRAY      1140 
+
      +
      + +

      +(These precedence levels are defined in swig.swg, a library file that's included by all target language modules.) +

      + +

      +In this table, the precedence-level determines the order in which types are going to be checked. Low values +are always checked before higher values. For example, integers are checked before floats, single values are checked +before arrays, and so forth. +

      + +

      +Using the above table as a guide, each target language defines a collection of "typecheck" typemaps. +The follow excerpt from the Python module illustrates this: +

      + +
      +
      +/* Python type checking rules */
+/* Note:  %typecheck(X) is a macro for %typemap(typecheck,precedence=X) */
+
+%typecheck(SWIG_TYPECHECK_INTEGER)
+	 int, short, long,
+ 	 unsigned int, unsigned short, unsigned long,
+	 signed char, unsigned char,
+	 long long, unsigned long long,
+	 const int &, const short &, const long &,
+ 	 const unsigned int &, const unsigned short &, const unsigned long &,
+	 const long long &, const unsigned long long &,
+	 enum SWIGTYPE,
+         bool, const bool & 
+{
+  $1 = (PyInt_Check($input) || PyLong_Check($input)) ? 1 : 0;
+}
+
+%typecheck(SWIG_TYPECHECK_DOUBLE)
+	float, double,
+	const float &, const double &
+{
+  $1 = (PyFloat_Check($input) || PyInt_Check($input) || PyLong_Check($input)) ? 1 : 0;
+}
+
+%typecheck(SWIG_TYPECHECK_CHAR) char {
+  $1 = (PyString_Check($input) && (PyString_Size($input) == 1)) ? 1 : 0;
+}
+
+%typecheck(SWIG_TYPECHECK_STRING) char * {
+  $1 = PyString_Check($input) ? 1 : 0;
+}
+
+%typecheck(SWIG_TYPECHECK_POINTER) SWIGTYPE *, SWIGTYPE &, SWIGTYPE [] {
+  void *ptr;
+  if (SWIG_ConvertPtr($input, (void **) &ptr, $1_descriptor, 0) == -1) {
+    $1 = 0;
+    PyErr_Clear();
+  } else {
+    $1 = 1;
+  }
+}
+
+%typecheck(SWIG_TYPECHECK_POINTER) SWIGTYPE {
+  void *ptr;
+  if (SWIG_ConvertPtr($input, (void **) &ptr, $&1_descriptor, 0) == -1) {
+    $1 = 0;
+    PyErr_Clear();
+  } else {
+    $1 = 1;
+  }
+}
+
+%typecheck(SWIG_TYPECHECK_VOIDPTR) void * {
+  void *ptr;
+  if (SWIG_ConvertPtr($input, (void **) &ptr, 0, 0) == -1) {
+    $1 = 0;
+    PyErr_Clear();
+  } else {
+    $1 = 1;
+  }
+}
+
+%typecheck(SWIG_TYPECHECK_POINTER) PyObject *
+{
+  $1 = ($input != 0);
+}
+
      +
      + +

      +It might take a bit of contemplation, but this code has merely organized all of the basic C++ types, provided some simple type-checking +code, and assigned each type a precedence value. +

      + +

      +Finally, to generate the dynamic dispatch function, SWIG uses the following algorithm: +

      + +
        +
      • Overloaded methods are first sorted by the number of required arguments.
        • +
      • Methods with the same number of arguments are then sorted by precedence values of argument types.
        • +
      • Typecheck typemaps are then emitted to produce a dispatch function that checks arguments in the correct order.
        • +
      + +

      +If you haven't written any typemaps of your own, it is unnecessary to worry about the typechecking rules. +However, if you have written new input typemaps, you might have to supply a typechecking rule as well. +An easy way to do this is to simply copy one of the existing typechecking rules. +Here is an example, +

      + +
      +
      +// Typemap for a C++ string
+%typemap(in) std::string {
+    if (PyString_Check($input)) {
+         $1 = std::string(PyString_AsString($input));
+     } else {
+         SWIG_exception(SWIG_TypeError, "string expected");
+     }
+}
+// Copy the typecheck code for "char *".  
+%typemap(typecheck) std::string = char *;
+
      +
      + +

      +The bottom line: If you are writing new typemaps and you are using overloaded methods, you will probably +have to write typecheck code or copy existing code. Since this is a relatively new SWIG feature, there are +few examples to work with. However, you might look at some of the existing library files likes 'typemaps.i' for +a guide. +

      + +

      +Notes: +

      + +
        +
      • Typecheck typemaps are not used for non-overloaded methods. Because of this, it is +still always necessary to check types in any "in" typemaps. +
        • + +
      • The dynamic dispatch process is only meant to be a heuristic. There are many corner +cases where SWIG simply can't disambiguate types to the same degree as C++. The only way to +resolve this ambiguity is to use the %rename directive to rename one of the overloaded methods (effectively +eliminating overloading). +
        • + +
      • +Typechecking may be partial. For example, if working with arrays, the typecheck code might +simply check the type of the first array element and use that to dispatch to the correct function. +Subsequent "in" typemaps would then perform more extensive type-checking. +
        • + +
      • Make sure you read the section on overloading in the "SWIG and C++" chapter. +
        • +
      + +

      10.12 More about %apply and %clear

      + + +

      +In order to implement certain kinds of program behavior, it is sometimes necessary to +write sets of typemaps. For example, to support output arguments, one often writes +a set of typemaps like this: +

      + +
      +
      +%typemap(in,numinputs=0) int *OUTPUT (int temp) {
+   $1 = &temp;
+}
+%typemap(argout) int *OUTPUT {
+   // return value somehow
+}
+
      +
      + +

      +To make it easier to apply the typemap to different argument types and names, the %apply directive +performs a copy of all typemaps from one type to another. For example, if you specify this, +

      + +
      +
      +%apply int *OUTPUT { int *retvalue, int32 *output };
+
      +
      + +

      +then all of the int *OUTPUT typemaps are copied to int *retvalue and int32 *output. +

      + +

      +However, there is a subtle aspect of %apply that needs more description. Namely, %apply does not +overwrite a typemap rule if it is already defined for the target datatype. This behavior allows you to do two things: +

      + +
        +
      • You can specialize parts of a complex typemap rule by first defining a few typemaps and then using +%apply to incorporate the remaining pieces. +
        • + +
      • Sets of different typemaps can be applied to the same datatype using repeated %apply directives. +
        • +
      + +

      +For example: +

      + +
      +
      +%typemap(in) int *INPUT (int temp) {
+   temp = ... get value from $input ...;
+   $1 = &temp;
+}
+
+%typemap(check) int *POSITIVE {
+   if (*$1 <= 0) {
+      SWIG_exception(SWIG_ValueError,"Expected a positive number!\n");
+      return NULL;
+   }
+}
+
+...
+%apply int *INPUT     { int *invalue };
+%apply int *POSITIVE  { int *invalue };
+
      +
      + +

      +Since %apply does not overwrite or replace any existing rules, the only way to reset behavior is to +use the %clear directive. %clear removes all typemap rules defined for a specific datatype. For +example: +

      + +
      +
      +%clear int *invalue;
+
      +
      + +

      10.13 Reducing wrapper code size

      + + +

      +Since the code supplied to a typemap is inlined directly into wrapper functions, typemaps can result +in a tremendous amount of code bloat. For example, consider this typemap for an array: +

      + +
      +
      +%typemap(in) float [ANY] {
+  int i;
+  if (!PySequence_Check($input)) {
+    PyErr_SetString(PyExc_ValueError,"Expected a sequence");
+    return NULL;
+  }
+  if (PySequence_Length($input) != $1_dim0) {
+    PyErr_SetString(PyExc_ValueError,"Size mismatch. Expected $1_dim0 elements");
+    return NULL;
+  }
+  $1 = (float) malloc($1_dim0*sizeof(float));
+  for (i = 0; i < $1_dim0; i++) {
+    PyObject *o = PySequence_GetItem($input,i);
+    if (PyNumber_Check(o)) {
+      $1[i] = (float) PyFloat_AsDouble(o);
+    } else {
+      PyErr_SetString(PyExc_ValueError,"Sequence elements must be numbers");      
+      free(result);
+      return NULL;
+    }
+  }
+}
+
      +
      + +

      +If you had a large interface with hundreds of functions all accepting +array parameters, this typemap would be replicated +repeatedly--generating a huge amount of code. A better approach might +be to consolidate some of the typemap into a function. For example: +

      + +
      +
      +%{
+/* Define a helper function */
+static float *
+convert_float_array(PyObject *input, int size) {
+  int i;
+  float *result;
+  if (!PySequence_Check(input)) {
+    PyErr_SetString(PyExc_ValueError,"Expected a sequence");
+    return NULL;
+  }
+  if (PySequence_Length(input) != size) {
+    PyErr_SetString(PyExc_ValueError,"Size mismatch. ");
+    return NULL;
+  }
+  result = (float) malloc(size*sizeof(float));
+  for (i = 0; i < size; i++) {
+    PyObject *o = PySequence_GetItem(input,i);
+    if (PyNumber_Check(o)) {
+      result[i] = (float) PyFloat_AsDouble(o);
+    } else {
+      PyErr_SetString(PyExc_ValueError,"Sequence elements must be numbers");
+      free(result);       
+      return NULL;
+    }
+  }
+  return result;
+}
+%}
+
+%typemap(in) float [ANY] {
+    $1 = convert_float_array($input, $1_dim0);
+    if (!$1) return NULL;
+}
+%}
+
      +
      + +

      10.14 Passing data between typemaps

      + + +

      +It is also important to note that the primary use of local variables +is to create stack-allocated objects for temporary use inside a +wrapper function (this is faster and less-prone to error than +allocating data on the heap). In general, the variables are not intended +to pass information between different types of typemaps. However, this +can be done if you realize that local names have the argument number appended +to them. For example, you could do this: +

      + +
      +
      +%typemap(in) int *(int temp) {
+   temp = (int) PyInt_AsLong($input);
+   $1 = &temp;
+}
+
+%typemap(argout) int * {
+   PyObject *o = PyInt_FromLong(temp$argnum);
+   ...
+}
+
      +
      + +

      +In this case, the $argnum variable is expanded into the argument +number. Therefore, the code will reference the appropriate local +such as temp1 and temp2. It should be noted that there are +plenty of opportunities to break the universe here and that accessing locals +in this manner should probably be avoided. At the very least, you should make +sure that the typemaps sharing information have exactly the same types and names. +

      + + +

      10.15 C++ "this" pointer

      + + +

      +All the rules discussed for Typemaps apply to C++ as well as C. +However in addition C++ passes an extra parameter into every +non-static class method -- the this pointer. Occasionally it can be +useful to apply a typemap to this pointer (for example to check +and make sure this is non-null before deferencing). +Actually, C also has an the equivalent of the this pointer which is used +when accessing variables in a C struct. +

      +

      +In order to customise the this pointer handling, target a variable named self in your typemaps. +self is the name SWIG uses to refer to the extra parameter in wrapped functions. +

      +

      +For example, if wrapping for Java generation: +

      + +
      +
      +%typemap(check) SWIGTYPE *self %{
+if (!$1) {
+  SWIG_JavaThrowException(jenv, SWIG_JavaNullPointerException, "swigCPtr null");
+  return $null;
+}
+%}
+
      +
      + +

      +In the above case, the $1 variable is expanded into the argument +name that SWIG is using as the this pointer. + +SWIG will then insert the check code before the actual C++ class method +is called, and will raise an exception rather than crash +the Java virtual machine. + +The generated code will look something like: +

      + +
      +
      +  if (!arg1) {
+    SWIG_JavaThrowException(jenv, SWIG_JavaNullPointerException,
+      "invalid native object; delete() likely already called");
+    return ;
+  }
+  (arg1)->wrappedFunction(...);
+
      +
      + +

      +Note that if you have a parameter named self then it +will also match the typemap. One work around is to create an interface file that wraps +the method, but give the argument a name other than self. +

      + +

      10.16 Where to go for more information?

      + + +

      +The +best place to find out more information about writing typemaps is to +look in the SWIG library. Most language modules define all of their +default behavior using typemaps. These are found in files such as +python.swg, perl5.swg, tcl8.swg and so +forth. The typemaps.i file in the library also contains +numerous examples. You should look at these files to get a feel +for how to define typemaps of your own. +Some of the language modules support additional typemaps and further +information is available in the individual chapters for each target language. +There you may also find more hands-on practical examples. +

      + + + diff --git a/Doc/Manual/Varargs.html b/Doc/Manual/Varargs.html new file mode 100644 index 0000000..f40a1ff --- /dev/null +++ b/Doc/Manual/Varargs.html @@ -0,0 +1,925 @@ + + + +Variable Length Arguments + + + + +

      13 Variable Length Arguments

      + +
      + +
      + + + + +

      +(a.k.a, "The horror. The horror.") +

      + +

      +This chapter describes the problem of wrapping functions that take a +variable number of arguments. For instance, generating wrappers for +the C printf() family of functions. +

      + +

      +This topic is sufficiently advanced to merit its own chapter. In +fact, support for varargs is an often requested feature that was first +added in SWIG-1.3.12. Most other wrapper generation tools have +wisely chosen to avoid this issue. +

      + +

      13.1 Introduction

      + + +

      +Some C and C++ programs may include functions that accept a variable +number of arguments. For example, most programmers are +familiar with functions from the C library such as the following: +

      + +
      +
      +int printf(const char *fmt, ...)
+int fprintf(FILE *, const char *fmt, ...);
+int sprintf(char *s, const char *fmt, ...);
+
      +
      + +

      +Although there is probably little practical purpose in wrapping these +specific C library functions in a scripting language (what would be the +point?), a library may include its own set of special functions based +on a similar API. For example: +

      + +
      +
      +int  traceprintf(const char *fmt, ...);
+
      +
      + +

      +In this case, you may want to have some kind of access from the target language. +

      + +

      +Before describing the SWIG implementation, it is important to discuss +the common uses of varargs that you are likely to encounter in real +programs. Obviously, there are the printf() style output +functions as shown. Closely related to this would be +scanf() style input functions that accept a format string and a +list of pointers into which return values are placed. However, variable +length arguments are also sometimes used to write functions that accept a +NULL-terminated list of pointers. A good example of this would +be a function like this: +

      + +
      +
      +int execlp(const char *path, const char *arg1, ...);
+...
+
+/* Example */
+execlp("ls","ls","-l",NULL);
+
      +
      + +

      +In addition, varargs is sometimes used to fake default arguments in older +C libraries. For instance, the low level open() system call +is often declared as a varargs function so that it will accept two +or three arguments: +

      + +
      +
      +int open(const char *path, int oflag, ...);
+...
+
+/* Examples */
+f = open("foo", O_RDONLY);
+g = open("bar", O_WRONLY | O_CREAT, 0644);
+
      +
      + +

      +Finally, to implement a varargs function, recall that you have to use +the C library functions defined in <stdarg.h>. For +example: +

      + +
      +
      +List make_list(const char *s, ...) {
+    va_list ap;
+    List    x;
+    ...
+    va_start(ap, s);
+    while (s) {
+       x.append(s);
+       s = va_arg(ap, const char *);
+    }
+    va_end(ap);
+    return x;
+}
+
      +
      + +

      13.2 The Problem

      + + +

      +Generating wrappers for a variable length argument function presents a +number of special challenges. Although C provides support for +implementing functions that receive variable length arguments, there +are no functions that can go in the other direction. Specifically, +you can't write a function that dynamically creates a list of +arguments and which invokes a varargs function on your behalf. +

      + +

      +Although it is possible to write functions that accept the special +type va_list, this is something entirely different. You +can't take a va_list structure and pass it in place of the +variable length arguments to another varargs function. It just +doesn't work. +

      + +

      +The reason this doesn't work has to do with the way that function +calls get compiled. For example, suppose that your program has a function call like this: +

      + +
      +
      +printf("Hello %s. Your number is %d\n", name, num);
+
      +
      + +

      +When the compiler looks at this, it knows that you are calling +printf() with exactly three arguments. Furthermore, it knows +that the number of arguments as well are their types and sizes is +never going to change during program execution. Therefore, +this gets turned to machine code that sets up a three-argument stack +frame followed by a call to printf(). +

      + +

      +In contrast, suppose you attempted to make some kind of wrapper around +printf() using code like this: +

      + +
      +
      +int wrap_printf(const char *fmt, ...) {
+   va_list ap;
+   va_start(ap,fmt);
+   ...
+   printf(fmt,ap);
+   ...
+   va_end(ap);
+};
+
      +
      + +

      +Although this code might compile, it won't do what you expect. This is +because the call to printf() is compiled as a procedure call +involving only two arguments. However, clearly a two-argument +configuration of the call stack is completely wrong if your intent is +to pass an arbitrary number of arguments to the real +printf(). Needless to say, it won't work. +

      + +

      +Unfortunately, the situation just described is exactly the problem +faced by wrapper generation tools. In general, the number of passed +arguments will not be known until run-time. To make matters even +worse, you won't know the types and sizes of arguments until run-time +as well. Needless to say, there is no obvious way to make the C +compiler generate code for a function call involving an unknown number +of arguments of unknown types. +

      + +

      +In theory, it is possible to write a wrapper that does the right thing. +However, this involves knowing the underlying ABI for the target platform and language +as well as writing special purpose code that manually constructed the call stack before +making a procedure call. Unfortunately, both of these tasks require the use of inline +assembly code. Clearly, that's the kind of solution you would much rather avoid. +

      + +

      +With this nastiness in mind, SWIG provides a number of solutions to the varargs +wrapping problem. Most of these solutions are compromises that provide limited +varargs support without having to resort to assembly language. However, SWIG +can also support real varargs wrapping (with stack-frame manipulation) if you +are willing to get hands dirty. Keep reading. +

      + +

      13.3 Default varargs support

      + + +

      +When variable length arguments appear in an interface, the default +behavior is to drop the variable argument list entirely, replacing +them with a single NULL pointer. For example, if you had this +function, +

      + +
      +
      +void traceprintf(const char *fmt, ...);
+
      +
      + +

      +it would be wrapped as if it had been declared as follows: +

      + +
      +
      +void traceprintf(const char *fmt);
+
      +
      + +

      +When the function is called inside the wrappers, it is called as follows: +

      + +
      +
      +traceprintf(arg1, NULL);
+
      +
      + +

      +Arguably, this approach seems to defeat the whole point of variable length arguments. However, +this actually provides enough support for many simple kinds of varargs functions to still be useful. For +instance, you could make function calls like this (in Python): +

      + +
      +
      +>>> traceprintf("Hello World")
+>>> traceprintf("Hello %s. Your number is %d\n" % (name, num))
+
      +
      + +

      +Notice how string formatting is being done in Python instead of C. +

      + +

      13.4 Argument replacement using %varargs

      + + +

      +Instead of dropping the variable length arguments, an alternative approach is to replace +(...) with a set of suitable arguments. SWIG provides a special %varargs directive +that can be used to do this. For example, +

      + +
      +
      +%varargs(int mode = 0) open;
+...
+int open(const char *path, int oflags, ...);
+
      +
      + +

      +is equivalent to this: +

      + +
      +
      +int open(const char *path, int oflags, int mode = 0);
+
      +
      + +

      +In this case, %varargs is simply providing more specific information about the +extra arguments that might be passed to a function. +If the parameters to a varargs function are of uniform type, %varargs can also +accept a numerical argument count as follows: +

      + +
      +
      +%varargs(10,char *arg = NULL) execlp;
+...
+int execlp(const char *path, const char *arg1, ...);
+
      +
      + +

      +This would wrap execlp() as a function that accepted up to 10 optional arguments. +Depending on the application, this may be more than enough for practical purposes. +

      + +

      +Argument replacement is most appropriate in cases where the types of +the extra arguments is uniform and the maximum number of arguments is +known. When replicated argument replacement is used, at least one extra +argument is added to the end of the arguments when making the function call. +This argument serves as a sentinel to make sure the list is properly terminated. +It has the same value as that supplied to the %varargs directive. +

      + +

      +Argument replacement is not as useful when working with functions that accept +mixed argument types such as printf(). Providing general purpose +wrappers to such functions presents special problems (covered shortly). +

      + +

      13.5 Varargs and typemaps

      + + +

      +Variable length arguments may be used in typemap specifications. For example: +

      + +
      +
      +%typemap(in) (...) {
+    // Get variable length arguments (somehow)
+    ...
+}
+
+%typemap(in) (const char *fmt, ...) {
+    // Multi-argument typemap
+}
+
      +
      + +

      +However, this immediately raises the question of what "type" is actually used +to represent (...). For lack of a better alternative, the type of +(...) is set to void *. Since there is no +way to dynamically pass arguments to a varargs function (as previously described), +the void * argument value is intended to serve as a place holder +for storing some kind of information about the extra arguments (if any). In addition, the +default behavior of SWIG is to pass the void * value as an argument to +the function. Therefore, you could use the pointer to hold a valid argument value if you wanted. +

      + +

      +To illustrate, here is a safer version of wrapping printf() in Python: +

      + +
      +
      +%typemap(in) (const char *fmt, ...) {
+    $1 = "%s";                                /* Fix format string to %s */
+    $2 = (void *) PyString_AsString($input);  /* Get string argument */
+};
+...
+int printf(const char *fmt, ...);
+
      +
      + +

      +In this example, the format string is implicitly set to "%s". +This prevents a program from passing a bogus format string to the +extension. Then, the passed input object is decoded and placed in the +void * argument defined for the (...) argument. When the +actual function call is made, the underlying wrapper code will look roughly +like this: +

      + +
      +
      +wrap_printf() {
+   char *arg1;
+   void *arg2;
+   int   result;
+
+   arg1 = "%s";
+   arg2 = (void *) PyString_AsString(arg2obj);
+   ...
+   result = printf(arg1,arg2);
+   ...
+}
+
      +
      + +

      +Notice how both arguments are passed to the function and it does what you +would expect. +

      + +

      +The next example illustrates a more advanced kind of varargs typemap. +Disclaimer: this requires special support in the target language module and is not +guaranteed to work with all SWIG modules at this time. It also starts to illustrate +some of the more fundamental problems with supporting varargs in more generality. +

      + +

      +If a typemap is defined for any form of (...), many SWIG +modules will generate wrappers that accept a variable number of +arguments as input and will make these arguments available in some +form. The precise details of this depends on the language module +being used (consult the appropriate chapter for more details). +However, suppose that you wanted to create a Python wrapper for the +execlp() function shown earlier. To do this using a typemap +instead of using %varargs, you might first write a typemap +like this: +

      + +
      +
      +%typemap(in) (...)(char *args[10]) {
+    int i;
+    int argc;
+    for (i = 0; i < 10; i++) args[i] = 0;
+    argc = PyTuple_Size(varargs);
+    if (argc > 10) {
+       PyErr_SetString(PyExc_ValueError,"Too many arguments");
+       return NULL;
+    }
+    for (i = 0; i < argc; i++) {
+       PyObject *o = PyTuple_GetItem(varargs,i);
+       if (!PyString_Check(o)) {
+           PyErr_SetString(PyExc_ValueError,"Expected a string");
+           return NULL;
+       }
+       args[i] = PyString_AsString(o);
+    }
+    $1 = (void *) args;
+}
+
      +
      + +

      +In this typemap, the special variable varargs is a tuple +holding all of the extra arguments passed (this is specific to the +Python module). The typemap then pulls this apart and sticks the +values into the array of strings args. Then, the array is +assigned to $1 (recall that this is the void * +variable corresponding to (...)). However, this assignment +is only half of the picture----clearly this alone is not enough to +make the function work. To patch everything up, you have to rewrite the +underlying action code using the %feature directive like +this: +

      + +
      +
      +%feature("action") execlp {
+   char *args = (char **) arg3;
+   result = execlp(arg1, arg2, args[0], args[1], args[2], args[3], args[4],
+                   args[5],args[6],args[7],args[8],args[9], NULL);
+}
+
+int execlp(const char *path, const char *arg, ...);
+
      +
      + +

      +This patches everything up and creates a function that more or less +works. However, don't try explaining this to your coworkers unless +you know for certain that they've had several cups of coffee. If you +really want to elevate your guru status and increase your job +security, continue to the next section. +

      + +

      13.6 Varargs wrapping with libffi

      + + +

      +All of the previous examples have relied on features of SWIG that are +portable and which don't rely upon any low-level machine-level +details. In many ways, they have all dodged the real issue of variable +length arguments by recasting a varargs function into some weaker variation +with a fixed number of arguments of known types. In many cases, this +works perfectly fine. However, if you want more generality than this, +you need to bring out some bigger guns. +

      + +

      +One way to do this is to use a special purpose library such as libffi +(http://sources.redhat.com/libffi). +libffi is a library that allows you to dynamically construct +call-stacks and invoke procedures in a relatively platform independent +manner. Details about the library can be found in the libffi +distribution and are not repeated here. +

      + +

      +To illustrate the use of libffi, suppose that you really wanted to create a +wrapper for execlp() that accepted any number of +arguments. To do this, you might make a few adjustments to the previous +example. For example: +

      + +
      +
      +/* Take an arbitrary number of extra arguments and place into an array
+   of strings */
+
+%typemap(in) (...) {
+   char **argv;
+   int    argc;
+   int    i;
+
+   argc = PyTuple_Size(varargs);
+   argv = (char **) malloc(sizeof(char *)*(argc+1));
+   for (i = 0; i < argc; i++) {
+      PyObject *o = PyTuple_GetItem(varargs,i);
+      if (!PyString_Check(o)) {
+          PyErr_SetString(PyExc_ValueError,"Expected a string");
+	  free(argv);
+          return NULL;
+      }
+      argv[i] = PyString_AsString(o);
+   }
+   argv[i] = NULL;
+   $1 = (void *) argv;
+}
+
+/* Rewrite the function call, using libffi */    
+
+%feature("action") execlp {
+  int       i, vc;
+  ffi_cif   cif;
+  ffi_type  **types;
+  void      **values;
+  char      **args;
+
+  vc = PyTuple_Size(varargs);
+  types  = (ffi_type **) malloc((vc+3)*sizeof(ffi_type *));
+  values = (void **) malloc((vc+3)*sizeof(void *));
+  args   = (char **) arg3;
+
+  /* Set up path parameter */
+  types[0] = &ffi_type_pointer;
+  values[0] = &arg1;
+  
+  /* Set up first argument */
+  types[1] = &ffi_type_pointer;
+  values[1] = &arg2;
+
+  /* Set up rest of parameters */
+  for (i = 0; i <= vc; i++) {
+    types[2+i] = &ffi_type_pointer;
+    values[2+i] = &args[i];
+  }
+  if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, vc+3,
+                   &ffi_type_uint, types) == FFI_OK) {
+    ffi_call(&cif, (void (*)()) execlp, &result, values);
+  } else {
+    PyErr_SetString(PyExc_RuntimeError, "Whoa!!!!!");
+    free(types);
+    free(values);
+    free(arg3);
+    return NULL;
+  }
+  free(types);
+  free(values);
+  free(arg3);
+}
+
+/* Declare the function. Whew! */
+int execlp(const char *path, const char *arg1, ...);
+
      +
      + +

      +Looking at this example, you may start to wonder if SWIG is making +life any easier. Given the amount of code involved, you might also wonder +why you didn't just write a hand-crafted wrapper! Either that or you're wondering +"why in the hell am I trying to wrap this varargs function in the +first place?!?" Obviously, those are questions you'll have to answer for yourself. +

      + +

      +As a more extreme example of libffi, here is some code that attempts to wrap printf(), +

      + +
      +
      +/* A wrapper for printf() using libffi */
+
+%{
+/* Structure for holding passed arguments after conversion */
+  typedef struct {
+    int type;
+    union {
+      int    ivalue;
+      double dvalue;
+      void   *pvalue;
+    } val;
+  } vtype;
+  enum { VT_INT, VT_DOUBLE, VT_POINTER };
+%}
+
+%typemap(in) (const char *fmt, ...) {
+  vtype *argv;
+  int    argc;
+  int    i;
+
+  /* Format string */
+  $1 = PyString_AsString($input);
+
+  /* Variable length arguments */
+  argc = PyTuple_Size(varargs);
+  argv = (vtype *) malloc(argc*sizeof(vtype));
+  for (i = 0; i < argc; i++) {
+    PyObject *o = PyTuple_GetItem(varargs,i);
+    if (PyInt_Check(o)) {
+      argv[i].type = VT_INT;
+      argv[i].val.ivalue = PyInt_AsLong(o);
+    } else if (PyFloat_Check(o)) {
+      argv[i].type = VT_DOUBLE;
+      argv[i].val.dvalue = PyFloat_AsDouble(o);
+    } else if (PyString_Check(o)) {
+      argv[i].type = VT_POINTER;
+      argv[i].val.pvalue = (void *) PyString_AsString(o);
+    } else {
+      PyErr_SetString(PyExc_ValueError,"Unsupported argument type");
+      free(argv);
+      return NULL;
+    }
+  }
+  $2 = (void *) argv;
+}
+
+/* Rewrite the function call using libffi */    
+%feature("action") printf {
+  int       i, vc;
+  ffi_cif   cif;
+  ffi_type  **types;
+  void      **values;
+  vtype     *args;
+
+  vc = PyTuple_Size(varargs);
+  types  = (ffi_type **) malloc((vc+1)*sizeof(ffi_type *));
+  values = (void **) malloc((vc+1)*sizeof(void *));
+  args   = (vtype *) arg2;
+
+  /* Set up fmt parameter */
+  types[0] = &ffi_type_pointer;
+  values[0] = &arg1;
+
+  /* Set up rest of parameters */
+  for (i = 0; i < vc; i++) {
+    switch(args[i].type) {
+    case VT_INT:
+      types[1+i] = &ffi_type_uint;
+      values[1+i] = &args[i].val.ivalue;
+      break;
+    case VT_DOUBLE:
+      types[1+i] = &ffi_type_double;
+      values[1+i] = &args[i].val.dvalue;
+      break;
+    case VT_POINTER:
+      types[1+i] = &ffi_type_pointer;
+      values[1+i] = &args[i].val.pvalue;
+      break;
+    default:
+      abort();    /* Whoa! We're seriously hosed */
+      break;   
+    }
+  }
+  if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, vc+1,
+                   &ffi_type_uint, types) == FFI_OK) {
+    ffi_call(&cif, (void (*)()) printf, &result, values);
+  } else {
+    PyErr_SetString(PyExc_RuntimeError, "Whoa!!!!!");
+    free(types);
+    free(values);
+    free(args);
+    return NULL;
+  }
+  free(types);
+  free(values);
+  free(args);
+}
+
+/* The function */
+int printf(const char *fmt, ...);
+
      +
      + +

      +Much to your amazement, it even seems to work if you try it: +

      + +
      +
      +>>> import example
+>>> example.printf("Grade: %s   %d/60 = %0.2f%%\n", "Dave", 47, 47.0*100/60)
+Grade: Dave   47/60 = 78.33%
+>>>
+
      +
      + +

      +Of course, there are still some limitations to consider: +

      + +
      +
      +>>> example.printf("la de da de da %s", 42)
+Segmentation fault (core dumped)
+
      +
      + +

      +And, on this note, we leave further exploration of libffi to the reader as an exercise. Although Python has been used as an example, +most of the techniques in this section can be extrapolated to other language modules with a bit of work. The only +details you need to know is how the extra arguments are accessed in each target language. For example, in the Python +module, we used the special varargs variable to get these arguments. Modules such as Tcl8 and Perl5 simply +provide an argument number for the first extra argument. This can be used to index into an array of passed arguments to get +values. Please consult the chapter on each language module for more details. +

      + +

      13.7 Wrapping of va_list

      + + +

      +Closely related to variable length argument wrapping, you may encounter functions that accept a parameter +of type va_list. For example: +

      + +
      +
      +int vfprintf(FILE *f, const char *fmt, va_list ap);
+
      +
      + +

      +As far as we know, there is no obvious way to wrap these functions +with SWIG. This is because there is no documented way to assemble the +proper va_list structure (there are no C library functions to do it +and the contents of va_list are opaque). Not only that, the contents +of a va_list structure are closely tied to the underlying +call-stack. It's not clear that exporting a va_list would +have any use or that it would work at all. +

      + +

      13.8 C++ Issues

      + + +

      +Wrapping of C++ member functions that accept a variable number of +arguments presents a number of challenges. By far, the easiest way to +handle this is to use the %varargs directive. This is portable +and it fully supports classes much like the %rename directive. For example: +

      + +
      +
      +%varargs (10, char * = NULL) Foo::bar;
+
+class Foo {
+public:
+     virtual void bar(char *arg, ...);   // gets varargs above
+};
+
+class Spam: public Foo {
+public:
+     virtual void bar(char *arg, ...);   // gets varargs above
+};
+
      +
      + +

      +%varargs also works with constructors, operators, and any +other C++ programming construct that accepts variable arguments. +

      + +

      +Doing anything more advanced than this is likely to involve a serious +world of pain. In order to use a library like libffi, you will need +to know the underlying calling conventions and details of the C++ ABI. For +instance, the details of how this is passed to member +functions as well as any hidden arguments that might be used to pass +additional information. These details are implementation specific and +may differ between compilers and even different versions of the same +compiler. Also, be aware that invoking a member function is further +complicated if it is a virtual method. In this case, +invocation might require a table lookup to obtain the proper function address +(although you might be able to obtain an address by casting a bound +pointer to a pointer to function as described in the C++ ARM section +18.3.4). +

      + +

      +If you do decide to change the underlying action code, be aware that SWIG +always places the this pointer in arg1. Other arguments +are placed in arg2, arg3, and so forth. For example: +

      + +
      +
      +%feature("action") Foo::bar {
+   ...
+   result = arg1->bar(arg2, arg3, etc.);
+   ...
+}
+
      +
      + +

      +Given the potential to shoot yourself in the foot, it is probably easier to reconsider your +design or to provide an alternative interface using a helper function than it is to create a +fully general wrapper to a varargs C++ member function. +

      + +

      13.9 Discussion

      + + +

      +This chapter has provided a number of techniques that can be used to address the problem of variable length +argument wrapping. If you care about portability and ease of use, the %varargs directive is +probably the easiest way to tackle the problem. However, using typemaps, it is possible to do some very advanced +kinds of wrapping. +

      + +

      +One point of discussion concerns the structure of the libffi examples in the previous section. Looking +at that code, it is not at all clear that this is the easiest way to solve the problem. However, there +are a number of subtle aspects of the solution to consider--mostly concerning the way in which the +problem has been decomposed. First, the example is structured in a way that tries to maintain separation +between wrapper-specific information and the declaration of the function itself. The idea here is that +you might structure your interface like this: +

      + +
      +
      +%typemap(const char *fmt, ...) {
+   ...
+}
+%feature("action") traceprintf {
+   ...
+}
+
+/* Include some header file with traceprintf in it */
+%include "someheader.h"
+
      +
      + +

      +Second, careful scrutiny will reveal that the typemaps involving (...) have nothing +whatsoever to do with the libffi library. In fact, they are generic with respect to the way in which +the function is actually called. This decoupling means that it will be much easier to consider +other library alternatives for making the function call. For instance, if libffi wasn't supported on a certain +platform, you might be able to use something else instead. You could use conditional compilation +to control this: +

      + +
      +
      +#ifdef USE_LIBFFI
+%feature("action") printf {
+   ...
+}
+#endif
+#ifdef USE_OTHERFFI
+%feature("action") printf {
+...
+}
+#endif
+
      +
      + +

      +Finally, even though you might be inclined to just write a hand-written wrapper for varargs functions, +the techniques used in the previous section have the advantage of being compatible with all other features +of SWIG such as exception handling. +

      + +

      +As a final word, some C programmers seem to have the assumption that +the wrapping of variable length argument functions is an easily solved +problem. However, this section has hopefully dispelled some of these +myths. All things being equal, you are better off avoiding variable +length arguments if you can. If you can't avoid them, please consider +some of the simple solutions first. If you can't live with a simple +solution, proceed with caution. At the very least, make sure you +carefully read the section "A7.3.2 Function Calls" in Kernighan and +Ritchie and make sure you fully understand the parameter passing conventions used for varargs. +Also, be aware of the platform dependencies and reliability issues that +this will introduce. Good luck. +

      + + + diff --git a/Doc/Manual/Warnings.html b/Doc/Manual/Warnings.html new file mode 100644 index 0000000..95af1ec --- /dev/null +++ b/Doc/Manual/Warnings.html @@ -0,0 +1,580 @@ + + + +Warning Messages + + + + +

      14 Warning Messages

      + +
      + +
      + + + + +

      14.1 Introduction

      + + +

      +During compilation, SWIG may generate a variety of warning messages. For example: +

      + +
      +
      +example.i:16: Warning(501): Overloaded declaration ignored.  bar(double)
+example.i:15: Warning(501): Previous declaration is bar(int)
+
      +
      + +

      +Typically, warning messages indicate non-fatal problems with the input +where the generated wrapper code will probably compile, but it may not +work like you expect. +

      + +

      14.2 Warning message suppression

      + + +

      +All warning messages have a numeric code that is shown in the warning message itself. +To suppress the printing of a warning message, a number of techniques can be used. +First, you can run SWIG with the -w command line option. For example: +

      + +
      +
      +% swig -python -w501 example.i
+% swig -python -w501,505,401 example.i
+
      +
      + +

      +Alternatively, warnings can be suppressed by inserting a special preprocessor pragma +into the input file: +

      + +
      +
      +%module example
+#pragma SWIG nowarn=501
+#pragma SWIG nowarn=501,505,401
+
      +
      + +

      +Finally, code-generation warnings can be disabled on a declaration by declaration basis using +the %warnfilter directive. For example: +

      + +
      +
      +%module example
+%warnfilter(501) foo;
+...
+int foo(int);
+int foo(double);              // Silently ignored.
+
      +
      + +

      +The %warnfilter directive has the same semantics as other declaration modifiers like +%rename, %ignore and %feature, see the +%feature directive section. For example, if you wanted to +suppress a warning for a method in a class hierarchy, you could do this: +

      + +
      +
      +%warnfilter(501) Object::foo;
+class Object {
+public:
+   int foo(int);
+   int foo(double);      // Silently ignored
+   ...
+};
+
+class Derived : public Object {
+public:
+   int foo(int);
+   int foo(double);      // Silently ignored
+   ...
+};
+
      +
      + +

      +Warnings can be suppressed for an entire class by supplying a class name. For example: +

      + +
      +
      +%warnfilter(501) Object;
+
+class Object {
+public:
+   ...                      // All 501 warnings ignored in class
+};
+
      +
      + +

      +There is no option to suppress all SWIG warning messages. The warning messages are there +for a reason---to tell you that something may be broken in +your interface. Ignore the warning messages at your own peril. +

      + + +

      14.3 Enabling extra warnings

      + + +

      +Some warning messages are disabled by default and are generated only +to provide additional diagnostics. These warnings can be turned on using the +-Wextra option. For example: +

      + +
      +
      +% swig -Wextra -python example.i
+
      +
      + +

      +To selectively turn on extra warning messages, you can use the directives and options in the +previous section--simply add a "+" to all warning numbers. For example: +

      + +
      +
      +% swig -w+309,+452 example.i
+
      +
      + +

      +or in your interface file use either +

      + +
      +
      +#pragma SWIG nowarn=+309,+452
+
      +
      + +

      +or +

      + +
      +
      +%warnfilter(+309,+452) foo;
+
      +
      + +

      +Note: selective enabling of warnings with %warnfilter overrides any global settings you might have +made using -w or #pragma. +

      + +

      +You can of course also enable all warnings and suppress a select few, for example: +

      + +
      +
      +% swig -Wextra -w309,452 example.i
+
      +
      + +

      +The warnings on the right take precedence over the warnings on the left, so in the above example -Wextra adds numerous warnings including 452, but then -w309,452 overrides this and so 452 is suppressesed. +

      + +

      +If you would like all warnings to appear, regardless of the warning filters used, then use the -Wall option. +The -Wall option also turns on the extra warnings that -Wextra adds, however, it is subtely different. +When -Wall is used, it also disables all other warning filters, +that is, any warnings suppressed or added in %warnfilter, #pragma SWIG nowarn +or the -w option. +

      + +

      14.4 Issuing a warning message

      + + +

      +Warning messages can be issued from an interface file using a number of directives. The +%warn directive is the most simple: +

      + +
      +
      +%warn "900:This is your last warning!"
+
      +
      + +

      +All warning messages are optionally prefixed by the warning number to use. If you are generating +your own warnings, make sure you don't use numbers defined in the table at the end of this section. +

      + +

      +The %ignorewarn directive is the same as %ignore except that it issues a +warning message whenever a matching declaration is found. For example: +

      + +
      +
      +%ignorewarn("362:operator= ignored") operator=;
+
      +
      + +

      +Warning messages can be associated with typemaps using the +warning attribute of a typemap declaration. For example: +

      + +
      +
      +%typemap(in, warning="901:You are really going to regret this") blah * {
+   ...
+}
+
      +
      + +

      +In this case, the warning message will be printed whenever the typemap is actually used. +

      + +

      14.5 Symbolic symbols

      + + +

      +The swigwarn.swg file that is installed with SWIG contains symbol constants that could also be +used in %warnfilter and #pragma SWIG nowarn. +For example this file contains the following line: +

      + +
      +
      +%define SWIGWARN_TYPE_UNDEFINED_CLASS 401 %enddef
+
      +
      + +

      +so SWIGWARN_TYPE_UNDEFINED_CLASS could be used instead of 401, for example: +

      + +
      +
      +#pragma SWIG nowarn=SWIGWARN_TYPE_UNDEFINED_CLASS
+
      +
      + +

      +or +

      + +
      +
      +%warnfilter(SWIGWARN_TYPE_UNDEFINED_CLASS) Foo;
+
      +
      + +

      14.6 Commentary

      + + +

      +The ability to suppress warning messages is really only provided for +advanced users and is not recommended in normal use. You are advised +to modify your interface to fix the problems highlighted by the warnings +wherever possible instead of suppressing warnings. +

      + +

      +Certain types of SWIG problems are errors. These usually arise due to +parsing errors (bad syntax) or semantic problems for which there is +no obvious recovery. There is no mechanism for suppressing error +messages. +

      + +

      14.7 Warnings as errors

      + + +

      +Warnings can be handled as errors by using the -Werror command line +option. This will cause SWIG to exit with a non successful exit code if a +warning is encountered. +

      + +

      14.8 Message output format

      + + +

      +The output format for both warnings and errors can be selected for +integration with your favourite IDE/editor. Editors and IDEs can usually parse +error messages and if in the appropriate format will easily take you +directly to the source of the error. The standard format is used by +default except on Windows where the Microsoft format is used by default. +These can be overridden using command line options, for example: +

      + +
      +$ swig -python -Fstandard example.i
+example.i:4: Syntax error in input.
+$ swig -python -Fmicrosoft example.i
+example.i(4): Syntax error in input.
+
      + +

      14.9 Warning number reference

      + + +

      14.9.1 Deprecated features (100-199)

      + + +
        +
      • 101. Deprecated %extern directive. +
      • 102. Deprecated %val directive. +
      • 103. Deprecated %out directive. +
      • 104. Deprecated %disabledoc directive. +
      • 105. Deprecated %enabledoc directive. +
      • 106. Deprecated %doconly directive. +
      • 107. Deprecated %style directive. +
      • 108. Deprecated %localstyle directive. +
      • 109. Deprecated %title directive. +
      • 110. Deprecated %section directive. +
      • 111. Deprecated %subsection directive. +
      • 112. Deprecated %subsubsection directive. +
      • 113. Deprecated %addmethods directive. +
      • 114. Deprecated %readonly directive. +
      • 115. Deprecated %readwrite directive. +
      • 116. Deprecated %except directive. +
      • 117. Deprecated %new directive. +
      • 118. Deprecated %typemap(except). +
      • 119. Deprecated %typemap(ignore). +
      • 120. Deprecated command line option (-runtime, -noruntime). +
      • 121. Deprecated %name directive. +
      + +

      14.9.2 Preprocessor (200-299)

      + + +
        +
      • 201. Unable to find 'filename'. +
      • 202. Could not evaluate 'expr'. +
      + +

      14.9.3 C/C++ Parser (300-399)

      + + +
        +
      • 301. class keyword used, but not in C++ mode. +
      • 302. Identifier 'name' redefined (ignored). +
      • 303. %extend defined for an undeclared class 'name'. +
      • 304. Unsupported constant value (ignored). +
      • 305. Bad constant value (ignored). +
      • 306. 'identifier' is private in this context. +
      • 307. Can't set default argument value (ignored) +
      • 308. Namespace alias 'name' not allowed here. Assuming 'name' +
      • 309. [private | protected] inheritance ignored. +
      • 310. Template 'name' was already wrapped as 'name' (ignored) +
      • 311. Template partial specialization not supported. +
      • 312. Nested classes not currently supported (ignored). +
      • 313. Unrecognized extern type "name" (ignored). +
      • 314. 'identifier' is a lang keyword. +
      • 315. Nothing known about 'identifier'. +
      • 316. Repeated %module directive. +
      • 317. Specialization of non-template 'name'. +
      • 318. Instantiation of template name is ambiguous. Using templ at file:line +
      • 319. No access specifier given for base class name (ignored). +
      • 320. Explicit template instantiation ignored. +
      • 321. identifier conflicts with a built-in name. +
      • 322. Redundant redeclaration of 'name'. +
      • 350. operator new ignored. +
      • 351. operator delete ignored. +
      • 352. operator+ ignored. +
      • 353. operator- ignored. +
      • 354. operator* ignored. +
      • 355. operator/ ignored. +
      • 356. operator% ignored. +
      • 357. operator^ ignored. +
      • 358. operator& ignored. +
      • 359. operator| ignored. +
      • 360. operator~ ignored. +
      • 361. operator! ignored. +
      • 362. operator= ignored. +
      • 363. operator< ignored. +
      • 364. operator> ignored. +
      • 365. operator+= ignored. +
      • 366. operator-= ignored. +
      • 367. operator*= ignored. +
      • 368. operator/= ignored. +
      • 369. operator%= ignored. +
      • 370. operator^= ignored. +
      • 371. operator&= ignored. +
      • 372. operator|= ignored. +
      • 373. operator<< ignored. +
      • 374. operator>>ignored. +
      • 375. operator<<= ignored. +
      • 376. operator>>= ignored. +
      • 377. operator== ignored. +
      • 378. operator!= ignored. +
      • 379. operator<= ignored. +
      • 380. operator>= ignored. +
      • 381. operator&& ignored. +
      • 382. operator|| ignored. +
      • 383. operator++ ignored. +
      • 384. operator-- ignored. +
      • 385. operator, ignored. +
      • 386. operator-<* ignored. +
      • 387. operator-< ignored. +
      • 388. operator() ignored. +
      • 389. operator[] ignored. +
      • 390. operator+ ignored (unary). +
      • 391. operator- ignored (unary). +
      • 392. operator* ignored (unary). +
      • 393. operator& ignored (unary). +
      • 394. operator new[] ignored. +
      • 395. operator delete[] ignored. +
      + +

      14.9.4 Types and typemaps (400-499)

      + + +
        +
      • 401. Nothing known about class 'name'. Ignored. +
      • 402. Base class 'name' is incomplete. +
      • 403. Class 'name' might be abstract. +
      • 450. Deprecated typemap feature ($source/$target). +
      • 451. Setting const char * variable may leak memory. +
      • 452. Reserved +
      • 453. Can't apply (pattern). No typemaps are defined. +
      • 460. Unable to use type type as a function argument. +
      • 461. Unable to use return type type in function name. +
      • 462. Unable to set variable of type type. +
      • 463. Unable to read variable of type type. +
      • 464. Unsupported constant value. +
      • 465. Unable to handle type type. +
      • 466. Unsupported variable type type. +
      • 467. Overloaded declaration not supported (no type checking rule for 'type') +
      • 468. No 'throw' typemap defined for exception type type +
      • 469. No or improper directorin typemap defined for type +
      • 470. Thread/reentrant unsafe wrapping, consider returning by value instead. +
      • 471. Unable to use return type type in director method +
      • 474. Method method usage of the optimal attribute in the out typemap at file:line ignored as the following cannot be used to generate optimal code: code +
      • 475. Multiple calls to method might be generated due to optimal attribute usage in the out typemap at file:line. +
      + + + +

      14.9.5 Code generation (500-599)

      + + +
        +
      • 501. Overloaded declaration ignored. decl +
      • 502. Overloaded constructor ignored. decl +
      • 503. Can't wrap 'identifier' unless renamed to a valid identifier. +
      • 504. Function name must have a return type. +
      • 505. Variable length arguments discarded. +
      • 506. Can't wrap varargs with keyword arguments enabled. +
      • 507. Adding native function name not supported (ignored). +
      • 508. Declaration of 'name' shadows declaration accessible via operator->() at file:line. +
      • 509. Overloaded declaration is shadowed by declaration at file:line. +
      • 510. Friend function 'name' ignored. +
      • 511. Can't use keyword arguments with overloaded functions. +
      • 512. Overloaded declaration const ignored. Non-const method at file:line used. +
      • 513. Can't generate wrappers for unnamed struct/class. +
      • 514. +
      • 515. +
      • 516. Overloaded method declaration ignored. Method declaration at file:line used. +
      • 517. +
      • 518. Portability warning: File file1 will be overwritten by file2 on case insensitive filesystems such as Windows' FAT32 and NTFS unless the class/module name is renamed. +
      • 519. %template() contains no name. Template method ignored: declaration +
      + +

      14.9.6 Language module specific (800-899)

      + + +
        +
      • 801. Wrong name (corrected to 'name'). (Ruby). +
      + +
        +
      • 810. No jni typemap defined for type (Java). +
      • 811. No jtype typemap defined for type (Java). +
      • 812. No jstype typemap defined for type (Java). +
      • 813. Warning for classname: Base baseclass ignored. Multiple inheritance is not supported in Java. (Java). +
      • 814. +
      • 815. No javafinalize typemap defined for type (Java). +
      • 816. No javabody typemap defined for type (Java). +
      • 817. No javaout typemap defined for type (Java). +
      • 818. No javain typemap defined for type (Java). +
      • 819. No javadirectorin typemap defined for type (Java). +
      • 820. No javadirectorout typemap defined for type (Java). +
      • 821. +
      • 822. Covariant return types not supported in Java. Proxy method will return basetype (Java). +
      • 823. No javaconstruct typemap defined for type (Java). +
      • 824. Missing JNI descriptor in directorin typemap defined for type (Java). +
      + +
        +
      • 830. No ctype typemap defined for type (C#). +
      • 831. No cstype typemap defined for type (C#). +
      • 832. No cswtype typemap defined for type (C#). +
      • 833. Warning for classname: Base baseclass ignored. Multiple inheritance is not supported in C#. (C#). +
      • 834. +
      • 835. No csfinalize typemap defined for type (C#). +
      • 836. No csbody typemap defined for type (C#). +
      • 837. No csout typemap defined for type (C#). +
      • 838. No csin typemap defined for type (C#). +
      • 839. +
      • 840. +
      • 841. +
      • 842. Covariant return types not supported in C#. Proxy method will return basetype (C#). +
      • 843. No csconstruct typemap defined for type (C#). +
      • 844. C# exception may not be thrown - no $excode or excode attribute in typemap typemap. (C#). +
      • 845. Unmanaged code contains a call to a SWIG_CSharpSetPendingException method and C# code does not handle pending exceptions via the canthrow attribute. (C#). +
      + +
        +
      • 870. Warning for classname: Base baseclass ignored. Multiple inheritance is not supported in PHP. +
      • 871. Unrecognized pragma pragma. (Php). +
      + +

      14.9.7 User defined (900-999)

      + + +

      +These numbers can be used by your own application. +

      + +

      14.10 History

      + + +

      +The ability to control warning messages was first added to SWIG-1.3.12. +

      + + + diff --git a/Doc/Manual/Windows.html b/Doc/Manual/Windows.html new file mode 100644 index 0000000..5d16a8b --- /dev/null +++ b/Doc/Manual/Windows.html @@ -0,0 +1,377 @@ + + + +Getting started on Windows + + + + +

      3 Getting started on Windows

      + +
      + +
      + + + + +

      +This chapter describes SWIG usage on Microsoft Windows. +Installing SWIG and running the examples is covered as well as building the SWIG executable. +Usage within the Unix like environments MinGW and Cygwin is also detailed. +

      + + +

      3.1 Installation on Windows

      + + +

      +SWIG does not come with the usual Windows type installation program, however it is quite easy to get started. The main steps are: +

      +
        +
      • Download the swigwin zip package from the SWIG website and unzip into a directory. This is all that needs downloading for the Windows platform. +
      • Set environment variables as described in the SWIG Windows Examples section in order to run examples using Visual C++. +
      + +

      3.1.1 Windows Executable

      + + +

      +The swigwin distribution contains the SWIG Windows executable, swig.exe, which will run on 32 bit versions of Windows, ie Windows 95/98/ME/NT/2000/XP. +If you want to build your own swig.exe have a look at Building swig.exe on Windows. +

      + + +

      3.2 SWIG Windows Examples

      + + +

      +Using Microsoft Visual C++ is the most common approach to compiling and linking SWIG's output. +The Examples directory has a few Visual C++ project files (.dsp files). +These were produced by Visual C++ 6, although they should also work in Visual C++ 5. +Later versions of Visual Studio should also be able to open and convert these project files. +The C# examples come with .NET 2003 solution (.sln) and project files instead of Visual C++ 6 project files. +The project files have been set up to execute SWIG in a custom build rule for the SWIG interface (.i) file. +Alternatively run the examples using Cygwin. + +

      +More information on each of the examples is available with the examples distributed with SWIG (Examples/index.html). + +

      3.2.1 Instructions for using the Examples with Visual Studio

      + + +

      +Ensure the SWIG executable is as supplied in the SWIG root directory in order for the examples to work. +Most languages require some environment variables to be set before running Visual C++. +Note that Visual C++ must be re-started to pick up any changes in environment variables. +Open up an example .dsp file, Visual C++ will create a workspace for you (.dsw file). +Ensure the Release build is selected then do a Rebuild All from the Build menu. +The required environment variables are displayed with their current values. +

      +

      +The list of required environment variables for each module language is also listed below. +They are usually set from the Control Panel and System properties, but this depends on which flavour of Windows you are running. +If you don't want to use environment variables then change all occurrences of the environment variables in the .dsp files with hard coded values. +If you are interested in how the project files are set up there is explanatory information in some of the language module's documentation. +

      + +

      3.2.1.1 C#

      + + +

      +The C# examples do not require any environment variables to be set as a C# project file is included. +Just open up the .sln solution file in Visual Studio .NET 2003 or later, select Release Build, and do a Rebuild All from the Build menu. +The accompanying C# and C++ project files are automatically used by the solution file. +

      + + +

      3.2.1.2 Java

      + + +

      +JAVA_INCLUDE : Set this to the directory containing jni.h
      +JAVA_BIN : Set this to the bin directory containing javac.exe

      +Example using JDK1.3:
      + +JAVA_INCLUDE: D:\jdk1.3\include
      +JAVA_BIN: D:\jdk1.3\bin
      +       +

      + + +

      3.2.1.3 Perl

      + + +

      +PERL5_INCLUDE : Set this to the directory containing perl.h
      +PERL5_LIB : Set this to the Perl library including path for linking

      +Example using nsPerl 5.004_04:

      + +PERL5_INCLUDE: D:\nsPerl5.004_04\lib\CORE
      +PERL5_LIB: D:\nsPerl5.004_04\lib\CORE\perl.lib
      +       +

      + + +

      3.2.1.4 Python

      + + +

      +PYTHON_INCLUDE : Set this to the directory that contains python.h
      +PYTHON_LIB : Set this to the python library including path for linking

      +Example using Python 2.1.1:
      + +PYTHON_INCLUDE: D:\python21\include
      +PYTHON_LIB: D:\python21\libs\python21.lib
      +       +

      + + +

      3.2.1.5 TCL

      + + +

      +TCL_INCLUDE : Set this to the directory containing tcl.h
      +TCL_LIB : Set this to the TCL library including path for linking

      +Example using ActiveTcl 8.3.3.3
      + +TCL_INCLUDE: D:\tcl\include
      +TCL_LIB: D:\tcl\lib\tcl83.lib
      +       +

      + + +

      3.2.1.6 R

      + + +

      +R_INCLUDE : Set this to the directory containing R.h
      +R_LIB : Set this to the R library (Rdll.lib) including path for linking. The library needs to be built as described in the R README.packages file (the pexports.exe approach is the easiest).

      +Example using R 2.5.1:
      + +R_INCLUDE: C:\Program Files\R\R-2.5.1\include
      +R_LIB: C:\Program Files\R\R-2.5.1\bin\Rdll.lib
      +       +

      + + +

      3.2.1.7 Ruby

      + + +

      +RUBY_INCLUDE : Set this to the directory containing ruby.h
      +RUBY_LIB : Set this to the ruby library including path for linking

      +Example using Ruby 1.6.4:
      + +RUBY_INCLUDE: D:\ruby\lib\ruby\1.6\i586-mswin32
      +RUBY_LIB: D:\ruby\lib\mswin32-ruby16.lib
      +       +

      + + +

      3.2.2 Instructions for using the Examples with other compilers

      + + +

      +If you do not have access to Visual C++ you will have to set up project files / Makefiles for your chosen compiler. There is a section in each of the language modules detailing what needs setting up using Visual C++ which may be of some guidance. Alternatively you may want to use Cygwin as described in the following section. +

      + +

      3.3 SWIG on Cygwin and MinGW

      + + +

      +SWIG can also be compiled and run using Cygwin or MinGW which provides a Unix like front end to Windows and comes free with gcc, an ANSI C/C++ compiler. However, this is not a recommended approach as the prebuilt executable is supplied. +

      + +

      3.3.1 Building swig.exe on Windows

      + + +

      +If you want to replicate the build of swig.exe that comes with the download, follow the MinGW instructions below. +This is not necessary to use the supplied swig.exe. +This information is provided for those that want to modify the SWIG source code in a Windows environment. +Normally this is not needed, so most people will want to ignore this section. +

      + +

      3.3.1.1 Building swig.exe using MinGW and MSYS

      + + +

      +The short abbreviated instructions follow... +

      + +
        +
      • Install MinGW and MSYS from the MinGW site. This provides a Unix environment on Windows. +
      • Follow the usual Unix instructions in the README file in the SWIG root directory to build swig.exe from the MinGW command prompt. +
      + +

      +The step by step instructions to download and install MinGW and MSYS, then download and build the latest version of SWIG from SVN follow... +Note that the instructions for obtaining SWIG from SVN are also online at SWIG SVN. +

      + +

      +Pitfall note: +Execute the steps in the order shown and don't use spaces in path names. In fact it is best to use the default installation directories. +

      + +
        +
      1. + Download the following packages from the MinGW download page + or MinGW SourceForge download page. + Note that at the time of writing, the majority of these are in the Current + release list and some are in the Snapshot or Previous release list. +
          +
        • MinGW-3.1.0-1.exe
          • +
        • MSYS-1.0.11-2004.04.30-1.exe
          • +
        • msysDTK-1.0.1.exe
          • +
        • bison-2.0-MSYS.tar.gz
          • +
        • msys-autoconf-2.59.tar.bz2
          • +
        • msys-automake-1.8.2.tar.bz2
          • +
        +
        2. + +
      2. + Install MinGW-3.1.0-1.exe (C:\MinGW is default location.) +
        3. + +
      3. + Install MSYS-1.0.11-2004.04.30-1.exe. Make sure you install it on the same + windows drive letter as MinGW (C:\msys\1.0 is default). + In the post install script, +
          +
        • Answer y to the "do you wish to continue with the post install?"
          • +
        • Answer y to the "do you have MinGW installed?"
          • +
        • Type in the the folder in which you installed MinGW (C:/MinGW is default)
          • +
        +
        4. + +
      4. + Install msysDTK-1.0.1.exe to the same folder that you installed MSYS (C:\msys\1.0 is default). +
        5. + +
      5. + Copy the following to the MSYS install folder (C:\msys\1.0 is default): +
          +
        • msys-automake-1.8.2.tar.bz2
          • +
        • msys-autoconf-2.59.tar.bz2
          • +
        • bison-2.0-MSYS.tar.gz
          • +
        +
        6. + +
      6. + Start the MSYS command prompt and execute: +
        +cd /
+tar -jxf msys-automake-1.8.2.tar.bz2 
+tar -jxf msys-autoconf-2.59.tar.bz2
+tar -zxf bison-2.0-MSYS.tar.gz   
+
        +
        7. + +
      7. + To get the latest SWIG SVN (version from Subversion source control), type in the following: +
        +mkdir /usr/src
+cd /usr/src
+svn co https://swig.svn.sourceforge.net/svnroot/swig/trunk swig
+
        + + Pitfall note: +If you want to check out SWIG to a different folder to the proposed +/usr/src/swig, do not use MSYS emulated windows drive letters, because +the autotools will fail miserably on those. +
        8. + +
      8. + You are now ready to build SWIG. Execute the following commands to build swig.exe: +
        +cd /usr/src/swig
+./autogen.sh
+./configure
+make
+
        +
        9. +
      + + +

      3.3.1.2 Building swig.exe using Cygwin

      + + +

      +Note that SWIG can also be built using Cygwin. +However, SWIG will then require the Cygwin DLL when executing. +Follow the Unix instructions in the README file in the SWIG root directory. +Note that the Cygwin environment will also allow one to regenerate the autotool generated files which are supplied with the release distribution. +These files are generated using the autogen.sh script and will only need regenerating in circumstances such as changing the build system. +

      + +

      3.3.1.3 Building swig.exe alternatives

      + + +

      +If you don't want to install Cygwin or MinGW, use a different compiler to build +SWIG. For example, all the source code files can be added to a Visual C++ project +file in order to build swig.exe from the Visual C++ IDE. +

      + + +

      3.3.2 Running the examples on Windows using Cygwin

      + + +

      +The examples and test-suite work as successfully on Cygwin as on any other Unix operating system. +The modules which are known to work are Python, Tcl, Perl, Ruby, Java and C#. +Follow the Unix instructions in the README file in the SWIG root directory to build the examples. +

      + +

      3.4 Microsoft extensions and other Windows quirks

      + + +

      +A common problem when using SWIG on Windows are the Microsoft function calling conventions which are not in the C++ standard. +SWIG parses ISO C/C++ so cannot deal with proprietary conventions such as __declspec(dllimport), __stdcall etc. +There is a Windows interface file, windows.i, to deal with these calling conventions though. +The file also contains typemaps for handling commonly used Windows specific types such as __int64, BOOL, DWORD etc. +Include it like you would any other interface file, for example: +

      + +
      +%include <windows.i>
+
+__declspec(dllexport) ULONG __stdcall foo(DWORD, __int32);
+
      + + + + diff --git a/Doc/Manual/ch11.1.png b/Doc/Manual/ch11.1.png new file mode 100644 index 0000000..2cc2bec Binary files /dev/null and b/Doc/Manual/ch11.1.png differ diff --git a/Doc/Manual/ch11.2.png b/Doc/Manual/ch11.2.png new file mode 100644 index 0000000..e6d1b55 Binary files /dev/null and b/Doc/Manual/ch11.2.png differ diff --git a/Doc/Manual/ch11.3.png b/Doc/Manual/ch11.3.png new file mode 100644 index 0000000..54ee724 Binary files /dev/null and b/Doc/Manual/ch11.3.png differ diff --git a/Doc/Manual/ch12.1.png b/Doc/Manual/ch12.1.png new file mode 100644 index 0000000..2072f06 Binary files /dev/null and b/Doc/Manual/ch12.1.png differ diff --git a/Doc/Manual/ch2.1.png b/Doc/Manual/ch2.1.png new file mode 100644 index 0000000..1f5800e Binary files /dev/null and b/Doc/Manual/ch2.1.png differ diff --git a/Doc/Manual/ch9.table.2.png b/Doc/Manual/ch9.table.2.png new file mode 100644 index 0000000..ac6647e Binary files /dev/null and b/Doc/Manual/ch9.table.2.png differ diff --git a/Doc/Manual/chapters b/Doc/Manual/chapters new file mode 100644 index 0000000..bf180f1 --- /dev/null +++ b/Doc/Manual/chapters @@ -0,0 +1,36 @@ +Preface.html +Introduction.html +Windows.html +Scripting.html +SWIG.html +SWIGPlus.html +Preprocessor.html +Library.html +Arguments.html +Typemaps.html +Customization.html +Contract.html +Varargs.html +Warnings.html +Modules.html +CCache.html +Allegrocl.html +CSharp.html +Chicken.html +Guile.html +Java.html +Lisp.html +Lua.html +Modula3.html +Mzscheme.html +Ocaml.html +Octave.html +Perl5.html +Php.html +Pike.html +Python.html +Ruby.html +Tcl.html +R.html +Extending.html + diff --git a/Doc/Manual/fixstyle.py b/Doc/Manual/fixstyle.py new file mode 100644 index 0000000..1007d59 --- /dev/null +++ b/Doc/Manual/fixstyle.py @@ -0,0 +1,25 @@ +#!/usr/bin/python + +# Adds the SWIG stylesheet to the generated documentation on a single page + +import sys +import string + +filename = sys.argv[1] + +data = open(filename).read() +open(filename+".bak","w").write(data) + +swigstyle = "\n" + open("style.css").read() + +lines = data.splitlines() +result = [ ] +for s in lines: + if s == "