From d0e5f3e8f4d073cfdbc0cd64b457577a30d4aff0 Mon Sep 17 00:00:00 2001 From: Dave Beazley Date: Thu, 27 Nov 2003 04:40:22 +0000 Subject: [PATCH] *** empty log message *** git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@5425 626c5289-ae23-0410-ae9c-e8d60b6d4f22 --- SWIG/Doc/Manual/Introduction.html | 168 +++++++++++++----------------- SWIG/Doc/Manual/Preface.html | 13 ++- 2 files changed, 85 insertions(+), 96 deletions(-) diff --git a/SWIG/Doc/Manual/Introduction.html b/SWIG/Doc/Manual/Introduction.html index 8cc8a3acc..403c2486c 100644 --- a/SWIG/Doc/Manual/Introduction.html +++ b/SWIG/Doc/Manual/Introduction.html @@ -67,21 +67,47 @@ in scientific and engineering projects.

1.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: -Although C is great for high-performance number crunching and systems -programming, trying to make an interactive and highly flexible C -program is a pain. Even though it is possible to build a user -interface using command line options, a home grown command -interpreter, or a graphical user interface, this often results in a -program that is hard to extend, hard to modify, hard to port between -platforms, and hard to use. Furthermore, this sort of activity wastes -a lot of development time because it usually diverts everyone's attention away -from the real problem that they're trying to solve. + + +Next, let's list a few problems with C/C++ programming + + + +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.

-Many of the problems with C are due to the way in which -many programs are organized. For example, a lot of programs -are structured as follows: +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:

-

-In this case, the main() program may read command line -options or simple commands from stdin. However, modifying or -extending the program to do something new requires changing the C -code, recompiling, and testing. If you make a mistake, you need to -repeat this cycle until things work. Of course, as more and more -features are added, the program usually turns into a horrible mess -that is even more difficult to modify than before (although this -undoubtedly increases the job security of the programmer). +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.

-A common mistake is to assume that all of the problems with C can somehow be -fixed by using a better C---perhaps an undebuggable -language with unreadable syntax, complicated semantics, and nearly -infinite compilation time. This is an unfortunate. - -

-Perhaps a better approach is to place your application under the control -of a very high-level language such as a common scripting language -interpreter. High level languages excel at turning hard problems into -easy tasks. They also provide a nice framework for managing software components -and gluing different systems together. Not only that, they make it easy -for users to configure the software to their liking and to program it to perform -new tasks without ever having to touch a C/C++ compiler. - -

-SWIG simplifies the task of incorporating C++ code into a high-level -programming environment. Specifically, rather than creating a huge -monolithic package, SWIG allows you to restructure your application as -a collection of functions and variables that can be accessed from the -convenience of a high-level language. With this model, all of the -functionality of your C program is retained. The only difference is -that the high-level program logic and control is now driven by the -high-level language instead of a low level -main() function. - -

-SWIG tries to make the integration between scripting languages and C -as painless as possible. This allows you to focus on the underlying C -program and using the high-level scripting language interface, but not +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.

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

1.3 A SWIG example

@@ -289,46 +286,8 @@ print $example::My_variable + 4.5, "\n"; 7.5 -

1.3.6 Building libraries and modules

- - -In addition to generating wrapper code, SWIG provides extensive -support for handling multiple files and building interface -libraries. For example, our example.i file, could be used in -another interface as follows :

- -

-

%module foo
-%include example.i             // Get definitions from example.i
-
-... Now more declarations ...
-
-
-In a large system, an interface might be built from a variety of pieces like this :

-

-

%module package
-
-%include network.i
-%include file.i
-%include graphics.i
-%include objects.i
-%include simulation.i
-
-
- -SWIG comes with a library of existing functions known as the SWIG -library. The library contains a mix of language independent and -language dependent functionality. For example, the file -`array.i' provides access to C arrays while the file -`wish.i' includes specialized code for rebuilding the Tcl -wish interpreter. Using the library, you can use existing modules to -build up your own personalized environment for building interfaces. -If changes are made to any of the components, they will appear -automatically the next time SWIG is run.

-

1.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 @@ -348,7 +307,7 @@ major features include:
  • C++ smart pointers. -Currently, the only C++ feature not supported is nested classes--a limitation +Currently, the only major C++ feature not supported is nested classes--a limitation that will be removed in a future release.

    @@ -364,8 +323,7 @@ stresses the very limits of many C++ compilers.

    1.5 Non-intrusive interface building

    - -When used as intended, SWIG requires minimal modification to +When used as intended, SWIG requires minimal (if any) modification to existing C code. This makes SWIG extremely easy to use with existing packages and promotes software reuse and modularity. By making the C code independent of the high level interface, you can change the @@ -385,8 +343,32 @@ file. While this approach may limit flexibility for hard-core hackers, it allows others to forget about the low-level implementation details. +

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

    SWIG 1.3 - Last Modified : August 10, 2002
    - \ No newline at end of file + diff --git a/SWIG/Doc/Manual/Preface.html b/SWIG/Doc/Manual/Preface.html index fd970127f..11b27479f 100644 --- a/SWIG/Doc/Manual/Preface.html +++ b/SWIG/Doc/Manual/Preface.html @@ -105,7 +105,6 @@ about this can be obtained at:

    0.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 @@ -117,6 +116,15 @@ 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. +

    0.6 Organization of this manual

    @@ -180,7 +188,6 @@ port.

    0.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 @@ -194,4 +201,4 @@ can only fix bugs if we know about them.

    SWIG 1.3 - Last Modified : March 9, 2003
    - \ No newline at end of file +