SWIG - Generating language bindings for C/C++...
Transcript of SWIG - Generating language bindings for C/C++...
![Page 2: SWIG - Generating language bindings for C/C++ librariesen.opensuse.org/images/e/eb/Kkaempf_KnowledgeSharing_Swig.pdf · SWIG Generating language bindings for C/C++ libraries Klaus](https://reader034.fdocuments.in/reader034/viewer/2022052009/601de9d6accc8671081bb9f9/html5/thumbnails/2.jpg)
© Novell Inc. All rights reserved
2
What and why ?
SWIG is an interface compiler that connects programs written in C and C++ with scripting languages such as Perl, Python, Ruby, and Tcl.
• Building more powerful C/C++ programs
• Make C libraries 'object oriented'
• Rapid prototyping and debugging
• Systems integration
• Construction of scripting language extension modules
![Page 3: SWIG - Generating language bindings for C/C++ librariesen.opensuse.org/images/e/eb/Kkaempf_KnowledgeSharing_Swig.pdf · SWIG Generating language bindings for C/C++ libraries Klaus](https://reader034.fdocuments.in/reader034/viewer/2022052009/601de9d6accc8671081bb9f9/html5/thumbnails/3.jpg)
© Novell Inc. All rights reserved
3
About SWIG
• Homepage: http://www.swig.org
• # zypper in swig
• HistoryInitially started in July, 1995 at Los Alamos National Laboratory.
First alpha release: February, 1996.
Latest release: April 7, 2008. SWIG-1.3.35
• Active development3-4 releases per year
![Page 4: SWIG - Generating language bindings for C/C++ librariesen.opensuse.org/images/e/eb/Kkaempf_KnowledgeSharing_Swig.pdf · SWIG Generating language bindings for C/C++ libraries Klaus](https://reader034.fdocuments.in/reader034/viewer/2022052009/601de9d6accc8671081bb9f9/html5/thumbnails/4.jpg)
© Novell Inc. All rights reserved
4
Supported languages
Allegro Common Lisp CFFI (Common Lisp)
Chicken(Scheme)
CLisp
MzScheme
Octave
![Page 5: SWIG - Generating language bindings for C/C++ librariesen.opensuse.org/images/e/eb/Kkaempf_KnowledgeSharing_Swig.pdf · SWIG Generating language bindings for C/C++ libraries Klaus](https://reader034.fdocuments.in/reader034/viewer/2022052009/601de9d6accc8671081bb9f9/html5/thumbnails/5.jpg)
© Novell Inc. All rights reserved
5
How SWIG works
lib.h
lib.i
lib_wrap.cC/C++ header
Interface description
SWIG
Binding code
lib_wrap.so
GCC
Target languagemodule
![Page 6: SWIG - Generating language bindings for C/C++ librariesen.opensuse.org/images/e/eb/Kkaempf_KnowledgeSharing_Swig.pdf · SWIG Generating language bindings for C/C++ libraries Klaus](https://reader034.fdocuments.in/reader034/viewer/2022052009/601de9d6accc8671081bb9f9/html5/thumbnails/6.jpg)
© Novell Inc. All rights reserved
6
How SWIG works (cont.)
lib.solib_wrap.so
Python module Library
Python
demo.py
import 'call'
![Page 7: SWIG - Generating language bindings for C/C++ librariesen.opensuse.org/images/e/eb/Kkaempf_KnowledgeSharing_Swig.pdf · SWIG Generating language bindings for C/C++ libraries Klaus](https://reader034.fdocuments.in/reader034/viewer/2022052009/601de9d6accc8671081bb9f9/html5/thumbnails/7.jpg)
Using SWIG
![Page 8: SWIG - Generating language bindings for C/C++ librariesen.opensuse.org/images/e/eb/Kkaempf_KnowledgeSharing_Swig.pdf · SWIG Generating language bindings for C/C++ libraries Klaus](https://reader034.fdocuments.in/reader034/viewer/2022052009/601de9d6accc8671081bb9f9/html5/thumbnails/8.jpg)
© Novell Inc. All rights reserved
8
Example interface description
# Trivial example
%module example
%{
#include "satsolver/solver.h"
%}
%include satsolver/solver.h
![Page 9: SWIG - Generating language bindings for C/C++ librariesen.opensuse.org/images/e/eb/Kkaempf_KnowledgeSharing_Swig.pdf · SWIG Generating language bindings for C/C++ libraries Klaus](https://reader034.fdocuments.in/reader034/viewer/2022052009/601de9d6accc8671081bb9f9/html5/thumbnails/9.jpg)
© Novell Inc. All rights reserved
9
Running SWIG
● Generatingswig -ruby -I/usr/include example.i
● Compilinggcc -fPIC -I /usr/lib64/ruby/1.8/x86_64-linux -c example_wrap.c
● Linkinggcc -shared example_wrap.o -lsatsolver -o example.so
● Runningirb
irb(main):001:0> require "example"
=> true
irb(main):002:0> s = Example::Solver.new
=> #<Example::Solver:0x7ffd300d4de8>
![Page 10: SWIG - Generating language bindings for C/C++ librariesen.opensuse.org/images/e/eb/Kkaempf_KnowledgeSharing_Swig.pdf · SWIG Generating language bindings for C/C++ libraries Klaus](https://reader034.fdocuments.in/reader034/viewer/2022052009/601de9d6accc8671081bb9f9/html5/thumbnails/10.jpg)
© Novell Inc. All rights reserved
10
Structure of interface descriptions
Comment
Namespace
C/C++ code
Declarations
# Trivial example
%module example
%{
#include "satsolver/solver.h"
%}
%include satsolver/solver.h
• C syntax, no C compiler
• Only minimal syntax checking
![Page 11: SWIG - Generating language bindings for C/C++ librariesen.opensuse.org/images/e/eb/Kkaempf_KnowledgeSharing_Swig.pdf · SWIG Generating language bindings for C/C++ libraries Klaus](https://reader034.fdocuments.in/reader034/viewer/2022052009/601de9d6accc8671081bb9f9/html5/thumbnails/11.jpg)
© Novell Inc. All rights reserved
11
What does SWIG do for you ?
• Namespace
• Constants
• Type conversionFor simple types (int, float, char *, enum)
• Wraps complex typesPointers to structs and classes
• Exposes functions
• Memory managementConstructors, destructors
![Page 12: SWIG - Generating language bindings for C/C++ librariesen.opensuse.org/images/e/eb/Kkaempf_KnowledgeSharing_Swig.pdf · SWIG Generating language bindings for C/C++ libraries Klaus](https://reader034.fdocuments.in/reader034/viewer/2022052009/601de9d6accc8671081bb9f9/html5/thumbnails/12.jpg)
© Novell Inc. All rights reserved
12
%module yui%{#include "YaST2/yui/YUI.h"%}%include YUI.h
Example (Python)(taken from libyui-bindings)
class YUI
{
...
static YWidgetFactory * widgetFactory();
...
}
YaST2/yui/YUI.h demo.py
yui.i
import yui
factory = yui.YUI.widgetFactory()
dialog = factory.createPopupDialog()
vbox = factory.createVBox( dialog )
factory.createLabel( vbox, "Hello, World!" )
factory.createPushButton( vbox,
![Page 13: SWIG - Generating language bindings for C/C++ librariesen.opensuse.org/images/e/eb/Kkaempf_KnowledgeSharing_Swig.pdf · SWIG Generating language bindings for C/C++ libraries Klaus](https://reader034.fdocuments.in/reader034/viewer/2022052009/601de9d6accc8671081bb9f9/html5/thumbnails/13.jpg)
© Novell Inc. All rights reserved
13
Now how does it look like in ...
require 'yui'
factory = Yui::YUI::widget_factory
dialog = factory.create_popup_dialog
vbox = factory.create_vbox dialog
factory.create_label vbox, "Hello, World!"
Ruby
Perluse yui;
my $factory = yui::YUI::widgetFactory;
my $dialog = $factory->createPopupDialog;
my $vbox = $factory->createVBox( $dialog );
$factory->createLabel( $vbox, "Hello, World!" );
![Page 14: SWIG - Generating language bindings for C/C++ librariesen.opensuse.org/images/e/eb/Kkaempf_KnowledgeSharing_Swig.pdf · SWIG Generating language bindings for C/C++ libraries Klaus](https://reader034.fdocuments.in/reader034/viewer/2022052009/601de9d6accc8671081bb9f9/html5/thumbnails/14.jpg)
© Novell Inc. All rights reserved
14
Things to watch out for
• Function names (target language conventions)factory.create_popup_dialog
$factory->createPopupDialog;
• Comparing objectsSWIG wraps pointers to structs/classes, resulting in target
languages objects (Python: PyObject*, Ruby: VALUE)
'a == b' compares PyObject* (resp. VALUE), not the wrapped C++ object pointer
• Object ownershipNo explicit 'free' in e.g. Ruby and Python
![Page 15: SWIG - Generating language bindings for C/C++ librariesen.opensuse.org/images/e/eb/Kkaempf_KnowledgeSharing_Swig.pdf · SWIG Generating language bindings for C/C++ libraries Klaus](https://reader034.fdocuments.in/reader034/viewer/2022052009/601de9d6accc8671081bb9f9/html5/thumbnails/15.jpg)
Controlling the bindings
![Page 16: SWIG - Generating language bindings for C/C++ librariesen.opensuse.org/images/e/eb/Kkaempf_KnowledgeSharing_Swig.pdf · SWIG Generating language bindings for C/C++ libraries Klaus](https://reader034.fdocuments.in/reader034/viewer/2022052009/601de9d6accc8671081bb9f9/html5/thumbnails/16.jpg)
© Novell Inc. All rights reserved
16
Exposure
• Swig recognizes C/C++ declarations'struct' or 'class'
functions
• Hiding elements%ignore solver::noupdate;
%include “satsolver/solver.h”
• Hiding everythingtypedef struct solver {} Solver;
%extend Solver {
...
![Page 17: SWIG - Generating language bindings for C/C++ librariesen.opensuse.org/images/e/eb/Kkaempf_KnowledgeSharing_Swig.pdf · SWIG Generating language bindings for C/C++ libraries Klaus](https://reader034.fdocuments.in/reader034/viewer/2022052009/601de9d6accc8671081bb9f9/html5/thumbnails/17.jpg)
© Novell Inc. All rights reserved
17
Memory management
• Complex types (struct/class) as pointers
• SWIG runs constructor ('malloc (sizeof struct)')
• Might not be useful%nodefault solver;
• Explicit constructor/destructor%extend Solver {
Solver( Pool *pool, Repo *installed = NULL )
{ return solver_create( pool, installed ); }
~Solver()
{ solver_free( $self ); }
![Page 18: SWIG - Generating language bindings for C/C++ librariesen.opensuse.org/images/e/eb/Kkaempf_KnowledgeSharing_Swig.pdf · SWIG Generating language bindings for C/C++ libraries Klaus](https://reader034.fdocuments.in/reader034/viewer/2022052009/601de9d6accc8671081bb9f9/html5/thumbnails/18.jpg)
© Novell Inc. All rights reserved
18
Making C object-oriented
• Swig maps function calls 1:1, Ok for C++, bad for C void solver_solve(Solver *solv, Queue *job);
(Ruby)solver = Solver.new
solver_solve solver, job # Bad
solver.solve job # Good
• The power of %extend%extend Solver {
int solve( Queue *job )
{
solver_solve( $self, job);
return $self->problems.count == 0;
}
![Page 19: SWIG - Generating language bindings for C/C++ librariesen.opensuse.org/images/e/eb/Kkaempf_KnowledgeSharing_Swig.pdf · SWIG Generating language bindings for C/C++ libraries Klaus](https://reader034.fdocuments.in/reader034/viewer/2022052009/601de9d6accc8671081bb9f9/html5/thumbnails/19.jpg)
© Novell Inc. All rights reserved
19
Multiple target languages
• .i files are generic
• The target language is a SWIG runtime parameterswig -ruby bindings.i
• Use #if defined(SWIG<lang>)#if defined (SWIGRUBY)
...
#endif
![Page 20: SWIG - Generating language bindings for C/C++ librariesen.opensuse.org/images/e/eb/Kkaempf_KnowledgeSharing_Swig.pdf · SWIG Generating language bindings for C/C++ libraries Klaus](https://reader034.fdocuments.in/reader034/viewer/2022052009/601de9d6accc8671081bb9f9/html5/thumbnails/20.jpg)
© Novell Inc. All rights reserved
20
Useful commands
• Renaming%rename("to_s") asString();
%rename( "name=" ) set_name( const char *name );
%rename("empty?") empty();
• Aliasing%alias get "[]";
• Constants%constant int Script = C_CONSTANT;
• Defines%define YUILogComponent "bindings"
%enddef
%define %macro(PARAMETER)
...
![Page 21: SWIG - Generating language bindings for C/C++ librariesen.opensuse.org/images/e/eb/Kkaempf_KnowledgeSharing_Swig.pdf · SWIG Generating language bindings for C/C++ libraries Klaus](https://reader034.fdocuments.in/reader034/viewer/2022052009/601de9d6accc8671081bb9f9/html5/thumbnails/21.jpg)
© Novell Inc. All rights reserved
21
Type conversions
• SWIG has default conversions for most types
• Look at the SWIG 'library'/usr/share/swig/<version>
%include “carray.i”
• Typemaps#if defined(SWIGRUBY)
%typemap(in) (int bflag) {
$1 = RTEST( $input );
}
%typemap(out) int problems_found
"$result = ($1 != 0) ? Qtrue : Qfalse;";
%rename("problems?") problems_found();
#endif
![Page 22: SWIG - Generating language bindings for C/C++ librariesen.opensuse.org/images/e/eb/Kkaempf_KnowledgeSharing_Swig.pdf · SWIG Generating language bindings for C/C++ libraries Klaus](https://reader034.fdocuments.in/reader034/viewer/2022052009/601de9d6accc8671081bb9f9/html5/thumbnails/22.jpg)
© Novell Inc. All rights reserved
22
Target specifics
• Bypassing SWIG type conversion
• Use target-specific types
Ruby: VALUE
Python: PyObject *
• Example %rename( "attr?" ) attr_exists( VALUE attrname );
VALUE attr_exists( VALUE attrname )
{
...
![Page 23: SWIG - Generating language bindings for C/C++ librariesen.opensuse.org/images/e/eb/Kkaempf_KnowledgeSharing_Swig.pdf · SWIG Generating language bindings for C/C++ libraries Klaus](https://reader034.fdocuments.in/reader034/viewer/2022052009/601de9d6accc8671081bb9f9/html5/thumbnails/23.jpg)
© Novell Inc. All rights reserved
23
Generating Documentation
• SWIG can generate target-specific documentation
e.g. rdoc for Ruby, pydoc for Python
• Enable with %feature("autodoc","1");
• Converts C-style comments in .i files
• Needs fixing ...
![Page 24: SWIG - Generating language bindings for C/C++ librariesen.opensuse.org/images/e/eb/Kkaempf_KnowledgeSharing_Swig.pdf · SWIG Generating language bindings for C/C++ libraries Klaus](https://reader034.fdocuments.in/reader034/viewer/2022052009/601de9d6accc8671081bb9f9/html5/thumbnails/24.jpg)
Inversion of control
![Page 25: SWIG - Generating language bindings for C/C++ librariesen.opensuse.org/images/e/eb/Kkaempf_KnowledgeSharing_Swig.pdf · SWIG Generating language bindings for C/C++ libraries Klaus](https://reader034.fdocuments.in/reader034/viewer/2022052009/601de9d6accc8671081bb9f9/html5/thumbnails/25.jpg)
© Novell Inc. All rights reserved
25
Inversion of control
Daemon plug_wrap.so
Python moduleBinary
Python
demo.py
dlopen()
'call'
PyInitialize()PyImport_ImportModule()
PyObject_CallObject()
![Page 26: SWIG - Generating language bindings for C/C++ librariesen.opensuse.org/images/e/eb/Kkaempf_KnowledgeSharing_Swig.pdf · SWIG Generating language bindings for C/C++ libraries Klaus](https://reader034.fdocuments.in/reader034/viewer/2022052009/601de9d6accc8671081bb9f9/html5/thumbnails/26.jpg)
© Novell Inc. All rights reserved
26
Wrap up / Lessons learned
• SWIG is a tool, use it wisely
• Take the (script language) programmers viewHow should it look in Python/Ruby/Perl/... ?
• Tweak the bindings, not the target language
• Look at other SWIG code
• SWIG is very well documentedBut not without bugs ...
• Memory ownership is tricky
![Page 27: SWIG - Generating language bindings for C/C++ librariesen.opensuse.org/images/e/eb/Kkaempf_KnowledgeSharing_Swig.pdf · SWIG Generating language bindings for C/C++ libraries Klaus](https://reader034.fdocuments.in/reader034/viewer/2022052009/601de9d6accc8671081bb9f9/html5/thumbnails/27.jpg)
© Novell Inc. All rights reserved
27
Links for inspiration
• C++ Library
libyui-bindings (YaST user interface)http://svn.opensuse.org/svn/yast/trunk/libyui-bindings
• C Library
Sat-solver (package dependency resolver)http://svn.opensuse.org/svn/zypp/trunk/sat-solver/bindings
openwsman (Web Services for Management protocol)http://www.openwsman.org/trac/browser/openwsman/trunk/bindings
• Inversion of control
cmpi-bindings (CIM Provider interface)http://omc.svn.sourceforge.net/viewvc/omc/cmpi-bindings
![Page 28: SWIG - Generating language bindings for C/C++ librariesen.opensuse.org/images/e/eb/Kkaempf_KnowledgeSharing_Swig.pdf · SWIG Generating language bindings for C/C++ libraries Klaus](https://reader034.fdocuments.in/reader034/viewer/2022052009/601de9d6accc8671081bb9f9/html5/thumbnails/28.jpg)
![Page 29: SWIG - Generating language bindings for C/C++ librariesen.opensuse.org/images/e/eb/Kkaempf_KnowledgeSharing_Swig.pdf · SWIG Generating language bindings for C/C++ libraries Klaus](https://reader034.fdocuments.in/reader034/viewer/2022052009/601de9d6accc8671081bb9f9/html5/thumbnails/29.jpg)
![Page 30: SWIG - Generating language bindings for C/C++ librariesen.opensuse.org/images/e/eb/Kkaempf_KnowledgeSharing_Swig.pdf · SWIG Generating language bindings for C/C++ libraries Klaus](https://reader034.fdocuments.in/reader034/viewer/2022052009/601de9d6accc8671081bb9f9/html5/thumbnails/30.jpg)
Unpublished Work of Novell, Inc. All Rights Reserved.This work is an unpublished work and contains confidential, proprietary, and trade secret information of Novell, Inc. Access to this work is restricted to Novell employees who have a need to know to perform tasks within the scope of their assignments. No part of this work may be practiced, performed, copied, distributed, revised, modified, translated, abridged, condensed, expanded, collected, or adapted without the prior written consent of Novell, Inc. Any use or exploitation of this work without authorization could subject the perpetrator to criminal and civil liability.
General DisclaimerThis document is not to be construed as a promise by any participating company to develop, deliver, or market a product. It is not a commitment to deliver any material, code, or functionality, and should not be relied upon in making purchasing decisions. Novell, Inc. makes no representations or warranties with respect to the contents of this document, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. The development, release, and timing of features or functionality described for Novell products remains at the sole discretion of Novell. Further, Novell, Inc. reserves the right to revise this document and to make changes to its content, at any time, without obligation to notify any person or entity of such revisions or changes. All Novell marks referenced in this presentation are trademarks or registered trademarks of Novell, Inc. in the United States and other countries. All third-party trademarks are the property of their respective owners.