| Executive Summary |
| |
| <p> |
| <img src="images/exec.png" alt="Executive Summary"> |
| |
| <p> |
| SWIG is an interface compiler that connects programs written in C and |
| C++ with scripting languages such as Perl, Python, Ruby, and Tcl. It |
| works by taking the declarations found in C/C++ header files and using |
| them to generate the wrapper code that scripting languages need to |
| access the underlying C/C++ code. In addition, SWIG provides a |
| variety of customization features that let you tailor the wrapping |
| process to suit your application. |
| |
| <p> |
| John Ousterhout (creator of Tcl) has written a |
| <a href="http://home.pacbell.net/ouster/scripting.html">paper</a> |
| that describes the |
| benefits of scripting languages. SWIG makes it fairly easy to connect scripting |
| languages with C/C++ code. |
| |
| <p>SWIG is used in a number of ways: |
| |
| <ul> |
| <li><p><b>Building more powerful C/C++ programs</b>. Using SWIG, you can |
| replace the main() function of a C program with a scripting |
| interpreter from which you can control the application. This adds |
| quite a lot of flexibility and makes the program "programmable." That |
| is, the scripting interface allows users and developers to easily |
| modifiy the behavior of the program without having to modify low-level |
| C/C++ code. The benefits of this are numerous. In fact think of all |
| of the large software packages that you use every day---nearly all of |
| them include special a macro language, configuration language, or even |
| a scripting engine that allows users to make customizations. |
| |
| <li><p><b>Rapid prototyping and debugging</b>. 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. Since SWIG requires no modifications to the |
| underlying C/C++ code, it can be used even if the final product does not rely upon scripting. |
| |
| <li><p><b>Systems integration</b>. Scripting languages work fairly well |
| for controlling and gluing loosely-coupled software components |
| together. With SWIG, different C/C++ programs can be turned into |
| scripting language extension modules. These modules can then be |
| combined together to create new and interesting applications. |
| |
| <li><p><b>Construction of scripting language extension modules</b>. SWIG |
| can be used to turn common C/C++ libraries into components for use in |
| popular scripting languages. Of course, you will still want to make |
| sure that no-one else has already created a module before doing this. |
| </ul> |
| |
| SWIG is sometimes compared to interface definition language (IDL) |
| compilers such as those you find with systems such as CORBA and COM. |
| Although there are a few similarities, the whole point of SWIG is to |
| make it so you don't have to add an extra layer of IDL specifications |
| to your application. If anything, it's much more of a rapid |
| application development and prototyping tool. Specifically: |
| |
| <ul> |
| <li><p><b>ANSI C/C++ syntax</b>. SWIG parses ANSI C++ that has been |
| extended with a number of special directives. As a result, interfaces |
| are usually built by grabbing a header file and tweaking it a little |
| bit. This particular approach is especially useful when the |
| underlying C/C++ program undergoes frequent modification. |
| |
| <li><p><b>SWIG is not a stub generator</b>. SWIG produces code that you |
| simply compile and run. You don't have to fill in any stubs or write |
| special client/server code as you do with RPC-like systems. |
| |
| <li><p><b>SWIG does not define a protocol nor is it a component |
| framework.</b> SWIG does not define mechanisms or enforce rules |
| regarding the way in which software components are supposed to |
| interact with each other. Nor is it a specialized runtime library |
| or alternative scripting language API. SWIG is merely a code generator |
| that provides the glue necessary to hook C/C++ to other languages. |
| |
| <li><p><b>Designed to work with existing C/C++ code</b>. SWIG |
| requires little, if any, modifications to existing code. For the most |
| part, it encourages you to keep a clean separation between C/C++ and |
| its scripting interface. |
| |
| <li><p><b>Extensibility</b>. SWIG provides a variety of customization options that |
| allow you to blow your whole leg off if that's what you want to do. |
| SWIG is not here to enforce programming morality. |
| </ul> |
| |
| Finally, it is worth noting that even though SWIG is occasionally compared |
| to other more specialized scripting language extension building tools |
| (e.g., Perl XS, Python bgen, etc.), its primary audience is C/C++ |
| programmers who want to add a scripting language component to their |
| applications. Because of this, SWIG tends to have a slightly |
| different focus than tools designed to build small modules for |
| widespread use in a scripting language distribution. applications. |
| |
| <p> |
| A number of <a href="doc.html">papers and tutorials</a> describing SWIG are available. |
| You can also view a simple <a href="tutorial.html">tutorial</a> to see an |
| example of SWIG in action, or check out how other people are using SWIG |
| in their <a href="projects.html">projects</a>. |
| |
| <p> |
| SWIG has been freely available in various forms since February, 1996 |
| and a large number of developers have made contributions. Today, SWIG |
| remains an all-volunteer effort. Approximately 875 people subscribe |
| to the <a href="mail.html">swig</a> mailing list and a public CVS |
| repository is available at SourceForge. Versions of |
| SWIG can now be found in most Linux distributions (however, you'll almost |
| certainly want to get the latest version here). |
| |
| |