Expose Your C/C++ Program's Internal API with a Quick SWIG

My previous installment, "Add Embedded Scripting to Your C++ Application," showed how you can use the C Scripting Language (CSL) to move your application from a strictly GUI- or command line-based system to one that fully embraces end-user programmability. In the spirit of a Zen koan, this article looks at an example of the "opposite" of adding scripting to your application: making your application's internal API callable from within Perl scripts. Fortunately, you can do this without resorting to obscure Interface Definition Languages (IDLs), CORBA, COM, RPC, stubs, or any of those legacy framework generators.

The Simplified Wrapper and Interface Generator (SWIG) is a software development tool that connects programs written in C and C++ with a variety of scripting languages. SWIG is used with different types of languages, including all your favorites: Perl, PHP, Python, Tcl, Ruby, and most recently Lua. The list of supported languages even includes non-scripting languages such as C#, Common Lisp variants, Scheme, Java, Modula-3, and Objective Caml. However, SWIG is most commonly used to create high-level interpreted or compiled programming environments, user interfaces, and as a tool for testing and prototyping C/C++ software. SWIG also can export its parse tree in the form of XML and Lisp s-expressions.

You can freely use, distribute, and modify SWIG for commercial and non-commercial use.

The Simplified Wrapper and Interface Generator

SWIG opens up a lot more possibilities than just API automation. Lok briefly at some these before digging into the details of making SWIG work for you:

  • Building more powerful C/C++ programs: By using SWIG, you can get rid of that clunky main() function and replace it with a scripting interpreter to control the application. This opens your app and makes it programmable. You immediately get a scripting interface allowing users and developers to modify the app without having to modify low-level C/C++ code. With some design forethought, you can eliminate the need for a custom macro language, config files, or another embedded scripting engine.
  • Rapid prototyping and QA automation: SWIG allows C/C++ programs to be placed in a scripting environment that can be used for testing and debugging. For example, you might test a library with a collection of scripts or use the scripting interpreter as an interactive debugger. Because SWIG requires no modifications to the underlying C/C++ code, you can use it even if the final product does not rely on scripting.
  • Integrating diverse systems: We all know that scripting languages work fairly well for controlling and gluing together loosely-coupled software components. By turning different C/C++ programs into scripting language extension modules, you can create new and never before possible apps. For example, game developers could write gameplay logic in Perl and yet still integrate advanced math and physics libraries from C++.

Your First SWIG: A Probability Library

Suppose you want to expose the functions in a Probability Library for use with a Perl script. The probability functions compute factorials, permutations, and probably a lot of other boring stuff. To show off a bit, you wrap the legendary Win32 API's MessageBox() function from the venerable user32.lib as well. Written in C, it looks like stats.c in Listing 1.

Listing 1. stats.c

double pi = 3.14159;    //not used yet

int factorial(int n) {
   if (n <= 1)
      return 1;
   else
      return n*factorial(n-1);
}

int permutation(n,r)
{
   return factorial(n) / factorial(n-r);
}

#include <windows.h>
int ShowAMessage(long hWnd, char *lpText, char *lpCaption,
                 unsigned int uType)
{
   //WIN32 API call
   return MessageBox(hWnd, lpText, lpCaption, uType);
}

Next, in lieu of an obfuscatory IDL, COM, CORBA, or other type specification of interfaces, you use (gasp!) the slightly enhanced header file (stats.i) shown in Listing 2.

Listing 2. stats.i Enhanced Header File

/* stats.i */
%module stats
%{
   /* Put header files here or function declarations like below */
   extern double pi;
   extern int factorial(int n);
   extern int permutation(int n,int r);
   extern int ShowAMessage(long hWnd, char *lpText,
                           char *lpCaption,
                           unsigned int uType);
%}

extern double pi;
extern int factorial(int n);
extern int permutation(int n,int r);
extern int ShowAMessage(long hWnd, char *lpText, char *lpCaption,
                        unsigned int uType);

Before you go any further, you need to install some form of SWIG. If you are working from a Windows or Mac platform, you probably want to start with some precompiled binaries from the SourceForge site. SWIG for Win32 (or SWIGWIN) doesn't come with a fancy installer: you simply unzip it and set some environment variables. You can retarget SWIG to the Cygwin or MinGW Unix-for-Windows environments by recompiling the system. I use Cygwin Perl for most workaday Perl scripting, but because you likely will be integrating with Visual Studio C++-built Win32 apps, I chose to try the nsPerl 5.005_03 that the docs recommended. For nsPerl, my environment is as follows:

set PERL5_INCLUDE=D:\nsPerl5.005_03\lib\CORE
set PERL5_LIB=D:\nsPerl5.005_03\lib\CORE\perl.lib

Next, you need to discover which compiler flags your nsPerl was built with to produce linkable code later:

perl -MExtUtils::Embed -e ccopts

-Od -MD -DNDEBUG -DWIN32 -D_CONSOLE -DNO_STRICT -
IF:/nsPerl/netsite/nsPerl/WINNT/lib/nsPerl5.005_03\lib\
   MSWin32-x86/CORE

Now, you can invoke the SWIGWIN generator to produce the stats_wrap.c wrapper based on the stats.i interface file (from Listing 2):

swig -perl5 stats.i

Lastly, you compile and link both your original code and the wrapper code in one step, using the ccopts discovered above:

cl -Od -MD -DNDEBUG -DWIN32 -D_CONSOLE -DNO_STRICT stats.c
stats_wrap.c /link user32.lib d:\nsPerl5.005_03\lib\MSWin32-x86\
   CORE\perl.lib
/DLL /out:stats.dll

Calling Your C Functions from Perl

Now, step back and look at what you've actually produced so far. Based on your two input files (stats.c and stats.i), you have churned out the following:

  • stats_wrap.c: Perl-callable function stubs, which call through to stats.c
  • stats.dll: a DLL loadable by Perl
  • stats.pm: a Perl module, which painlessly imports the stats.dll for your Perl apps (see Listing 3)

Listing 3. Generated stats.pm File

# This file was automatically generated by SWIG:
package stats;
require Exporter;
require DynaLoader;
@ISA = qw(Exporter DynaLoader);
package stats;
bootstrap stats;
package stats;
@EXPORT = qw( );
1;

Now, you finally can have some fun and call your "new" stats library from Perl. Construct the simple Perl program in Listing 4, which should be obvious to any coder:

Listing 4. A Simple Perl Program for Our Stats Library

use stats;
$answer = stats::factorial(5);
stats::ShowAMessage(0,"5! is $answer","SWIG Testing",0);

The output is the dialog box shown below!

Give Your C/C++ Program's Internal API Full Exposure

What I've demonstrated thus far (I hope) is a relatively quick and painless way of exposing your C/C++ program's internal API to the machinations of any scripting language. Although I chose to use Perl, you could easily generate corresponding modules for Python, Java, and Lua in just a few minutes more.

SWIG covers the vast majority of C++ classes and language features: references, pointers to members, multiple inheritance, overloaded functions and operators, smart pointers, STL data types, namespaces, and much more. The only known hole currently is the wrapping of nested classes, but the nearly all C/C++ programs are eminently "SWIGable." So what are you waiting for?

About the Author

Victor Volkman has been writing for C/C++ Users Journal and other programming journals since the late 1980s. He is a graduate of Michigan Tech and a faculty advisor board member for Washtenaw Community College CIS department. Volkman is the editor of numerous books, including C/C++ Treasure Chest and is the owner of Loving Healing Press. He can help you in your quest for open source tools and libraries, just drop an e-mail to sysop@HAL9K.com.



About the Author

Victor Volkman

Victor Volkman has been writing for C/C++ Users Journal and other programming journals since the late 1980s. He is a graduate of Michigan Tech and a faculty advisor board member for Washtenaw Community College CIS department. Volkman is the editor of numerous books, including C/C++ Treasure Chest and is the owner of Loving Healing Press. He can help you in your quest for open source tools and libraries, just drop an e-mail to sysop@HAL9K.com.

Comments

  • wheloltabotly PumeSonee Phobereurce 2954035

    Posted by TizefaTaNaday on 06/14/2013 04:49pm

    BeldPeedlibia airjordanxiforsale.holidaygiving.org Mopilsspusapy cheapairjordanfusionshoes.holidaygiving.org Empockece

    Reply
  • wheloltabotly PumeSonee Phobereurce 2093782

    Posted by TizefaTaNaday on 05/16/2013 03:46pm

    LotaELodo http://www.havenfordogs.org/images/404.php?burberry-check-chronograph-watch-cc998-for-any-stylish-working-professional.html UnabbedaMew http://www.qusheying.com/ask/u.phplouis-vuitton-without-makeup-louis-vuitton-sale-coupon.html PerInegeMag

    Reply
  • Reproduction Cartier Designer watches allow the woman's to apperceive during which by yourself you will become your ex Mr. Perfect

    Posted by poeriepah on 03/07/2013 11:40am

    After i jogging opportunity along with my cousin I came to be encourage with this top quality brand. Like the rr, Cartier as well as any various other high end brand name on the planet. As well as my mate tells me that it's not only our hope and also much more folks globally. Added buyers use a desire A day they're going to individual this specific high-class One particular. Not merely quite producer by themselves and also the standing up that patterns. Nevertheless, you it's a evening dream if you ask me and much more frequent consumers. As a result, initially it is extremely challenging will individual this unique top end until eventually my partner and i have the Duplicate Cartier Timepieces. Your mood My spouse and i research the internet, I've found an internet getting, and i also uncover this kind of notice is indeed layout and chic. And also the shocking would it be gives a quantity of sequence, you might select the shade you desire in addition to virtually any Processing Cartier Designer watches have their own special style. The design type in addition to the refreshing design forces you to incredible within it. Probably the most essential is this fact just inside affordable tagging. Hence, it can be unquestionably will choose the notion. Prior to I actually receive this particular Look-alike Cartier Designer watches, I never at any time get one factor online; mainly because My spouse and i reckon that on the web purchasing is just not protected. Look-alike Cartier Timepieces, My partner and i level I became drastically wrong. Your on the internet getting is absolutely comfort and ease for bait and we're in a position to determine the actual pleasant one particular. Copy Cartier Designer watches make our desire become a reality by just it is kind fashion in addition to high-end. These kinds of Look-alike Cartier Designer watches is actually well-designed together with mess with, you can view reality fashion inside and you'll enjoy the excellent top quality. Once the view is just not don't use anything but pertaining to seeing enough time, the actual Look-alike Cartier Designer watches with the staff of style style and design, that may provides you with the refreshing design you will need for this style planet. Plus the perform within the to line of Copy Cartier Wrist watches, many people is able to see the particular performance into it. The specific Identical Cartier Watches moves pertaining to plenty of quite a while; you can see the record as well as the standing on the idea. In a lot of observe creating company, the actual Copy Cartier Designer watches is now your key about it. and its increased reputation is definitely check their finest to satisfy men and women requirement, together with attain their very own luxurious wonderland. Perhaps I came to be blessed to possess this opportunity to non-public this kind of high-class Replica Cartier Wrist watches in this affordable. Nonetheless it may be trustworthy for those; many individuals might personal your thing in addition to good quality Identical Cartier Wrist watches, exactly like many of us private this particular magnificent. [url=http://soppaeir.blogspace.fr/]best cheap watches[/url]|

    Reply
  • SWIG Interfaces for 3rd party dll - Testing - with no source code

    Posted by hiradhu on 03/09/2006 01:54am

    Hi, The article is good. I have been working on using SWIG with 3rd party dlls where no source will be given. I was able to do it successfully but still needs some minimal programming or understanding capability of libs & dlls. Can u pls highlight if u have any easy method of using 3rd party dlls along with SWIG for testing purpose?

    • Where to go for help

      Posted by Victor Volkman on 03/09/2006 08:05am

      I only know the most basic usage of SWIG. Please sign up for this mailing list to get your questions answered http://lists.sourceforge.net/lists/listinfo/swig-user

      Reply
    Reply
Leave a Comment
  • Your email address will not be published. All fields are required.

Top White Papers and Webcasts

  • With JRebel, developers get to see their code changes immediately, fine-tune their code with incremental changes, debug, explore and deploy their code with ease (both locally and remotely), and ultimately spend more time coding instead of waiting for the dreaded application redeploy to finish. Every time a developer tests a code change it takes minutes to build and deploy the application. JRebel keeps the app server running at all times, so testing is instantaneous and interactive.

  • By providing complete access control with granular permissions, deployment flexibility, mapped drive support, and ability to transfer large files, Egnyte provides a more robust, secure and an affordable file sharing solution for the business than Box

Most Popular Programming Stories

More for Developers

Latest Developer Headlines

RSS Feeds