diff options
Diffstat (limited to 'Doc/Manual/Extending.html')
| -rw-r--r-- | Doc/Manual/Extending.html | 120 |
1 files changed, 70 insertions, 50 deletions
diff --git a/Doc/Manual/Extending.html b/Doc/Manual/Extending.html index c554d9f05..c6e006033 100644 --- a/Doc/Manual/Extending.html +++ b/Doc/Manual/Extending.html @@ -6,7 +6,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Extending"></a>36 Extending SWIG to support new languages</H1> +<H1><a name="Extending"></a>37 Extending SWIG to support new languages</H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -75,7 +75,7 @@ -<H2><a name="Extending_nn2"></a>36.1 Introduction</H2> +<H2><a name="Extending_nn2"></a>37.1 Introduction</H2> <p> @@ -91,7 +91,7 @@ Also, this chapter is not meant to be a hand-holding tutorial. As a starting po you should probably look at one of SWIG's existing modules. </p> -<H2><a name="Extending_nn3"></a>36.2 Prerequisites</H2> +<H2><a name="Extending_nn3"></a>37.2 Prerequisites</H2> <p> @@ -121,7 +121,7 @@ obvious, but almost all SWIG directives as well as the low-level generation of wrapper code are driven by C++ datatypes. </p> -<H2><a name="Extending_nn4"></a>36.3 The Big Picture</H2> +<H2><a name="Extending_nn4"></a>37.3 The Big Picture</H2> <p> @@ -158,7 +158,7 @@ role in making the system work. For example, both typemaps and declaration anno based on pattern matching and interact heavily with the underlying type system. </p> -<H2><a name="Extending_nn5"></a>36.4 Execution Model</H2> +<H2><a name="Extending_nn5"></a>37.4 Execution Model</H2> <p> @@ -203,7 +203,7 @@ latter stage of compilation. The next few sections briefly describe some of these stages. </p> -<H3><a name="Extending_nn6"></a>36.4.1 Preprocessing</H3> +<H3><a name="Extending_nn6"></a>37.4.1 Preprocessing</H3> <p> @@ -284,7 +284,7 @@ been expanded as well as everything else that goes into the low-level construction of the wrapper code. </p> -<H3><a name="Extending_nn7"></a>36.4.2 Parsing</H3> +<H3><a name="Extending_nn7"></a>37.4.2 Parsing</H3> <p> @@ -385,7 +385,7 @@ returning a <tt>foo</tt> and taking types <tt>a</tt> and <tt>b</tt> as arguments). </p> -<H3><a name="Extending_nn8"></a>36.4.3 Parse Trees</H3> +<H3><a name="Extending_nn8"></a>37.4.3 Parse Trees</H3> <p> @@ -640,7 +640,7 @@ $ swig -c++ -python -debug-module 4 example.i </pre> </div> -<H3><a name="Extending_nn9"></a>36.4.4 Attribute namespaces</H3> +<H3><a name="Extending_nn9"></a>37.4.4 Attribute namespaces</H3> <p> @@ -659,7 +659,7 @@ that matches the name of the target language. For example, <tt>python:foo</tt> <tt>perl:foo</tt>. </p> -<H3><a name="Extending_nn10"></a>36.4.5 Symbol Tables</H3> +<H3><a name="Extending_nn10"></a>37.4.5 Symbol Tables</H3> <p> @@ -750,7 +750,7 @@ example.i:5. Previous declaration is foo_i(int ) </pre> </div> -<H3><a name="Extending_nn11"></a>36.4.6 The %feature directive</H3> +<H3><a name="Extending_nn11"></a>37.4.6 The %feature directive</H3> <p> @@ -806,7 +806,7 @@ For example, the exception code above is simply stored without any modifications. </p> -<H3><a name="Extending_nn12"></a>36.4.7 Code Generation</H3> +<H3><a name="Extending_nn12"></a>37.4.7 Code Generation</H3> <p> @@ -928,7 +928,7 @@ public : The role of these functions is described shortly. </p> -<H3><a name="Extending_nn13"></a>36.4.8 SWIG and XML</H3> +<H3><a name="Extending_nn13"></a>37.4.8 SWIG and XML</H3> <p> @@ -941,7 +941,7 @@ internal data structures, it may be useful to keep XML in the back of your mind as a model. </p> -<H2><a name="Extending_nn14"></a>36.5 Primitive Data Structures</H2> +<H2><a name="Extending_nn14"></a>37.5 Primitive Data Structures</H2> <p> @@ -987,7 +987,7 @@ typedef Hash Typetab; </pre> </div> -<H3><a name="Extending_nn15"></a>36.5.1 Strings</H3> +<H3><a name="Extending_nn15"></a>37.5.1 Strings</H3> <p> @@ -1128,7 +1128,7 @@ Returns the number of replacements made (if any). </div> -<H3><a name="Extending_nn16"></a>36.5.2 Hashes</H3> +<H3><a name="Extending_nn16"></a>37.5.2 Hashes</H3> <p> @@ -1205,7 +1205,7 @@ Returns the list of hash table keys. </div> -<H3><a name="Extending_nn17"></a>36.5.3 Lists</H3> +<H3><a name="Extending_nn17"></a>37.5.3 Lists</H3> <p> @@ -1294,7 +1294,7 @@ If <tt>t</tt> is not a standard object, it is assumed to be a <tt>char *</tt> and is used to create a String object. </div> -<H3><a name="Extending_nn18"></a>36.5.4 Common operations</H3> +<H3><a name="Extending_nn18"></a>37.5.4 Common operations</H3> The following operations are applicable to all datatypes. @@ -1349,7 +1349,7 @@ objects and report errors. Gets the line number associated with <tt>x</tt>. </div> -<H3><a name="Extending_nn19"></a>36.5.5 Iterating over Lists and Hashes</H3> +<H3><a name="Extending_nn19"></a>37.5.5 Iterating over Lists and Hashes</H3> To iterate over the elements of a list or a hash table, the following functions are used: @@ -1394,7 +1394,7 @@ for (j = First(j); j.item; j= Next(j)) { </div> -<H3><a name="Extending_nn20"></a>36.5.6 I/O</H3> +<H3><a name="Extending_nn20"></a>37.5.6 I/O</H3> Special I/O functions are used for all internal I/O. These operations @@ -1531,7 +1531,7 @@ Similarly, the preprocessor and parser all operate on string-files. </div> -<H2><a name="Extending_nn21"></a>36.6 Navigating and manipulating parse trees</H2> +<H2><a name="Extending_nn21"></a>37.6 Navigating and manipulating parse trees</H2> Parse trees are built as collections of hash tables. Each node is a hash table in which @@ -1665,7 +1665,7 @@ Deletes a node from the parse tree. Deletion reconnects siblings and properly u the parent so that sibling nodes are unaffected. </div> -<H2><a name="Extending_nn22"></a>36.7 Working with attributes</H2> +<H2><a name="Extending_nn22"></a>37.7 Working with attributes</H2> <p> @@ -1782,7 +1782,7 @@ the attribute is optional. <tt>Swig_restore()</tt> must always be called after function. </div> -<H2><a name="Extending_nn23"></a>36.8 Type system</H2> +<H2><a name="Extending_nn23"></a>37.8 Type system</H2> <p> @@ -1791,7 +1791,7 @@ pointers, references, and pointers to members. A detailed discussion of type theory is impossible here. However, let's cover the highlights. </p> -<H3><a name="Extending_nn24"></a>36.8.1 String encoding of types</H3> +<H3><a name="Extending_nn24"></a>37.8.1 String encoding of types</H3> <p> @@ -1892,7 +1892,7 @@ make the final type, the two parts are just joined together using string concatenation. </p> -<H3><a name="Extending_nn25"></a>36.8.2 Type construction</H3> +<H3><a name="Extending_nn25"></a>37.8.2 Type construction</H3> <p> @@ -2061,7 +2061,7 @@ Returns the prefix of a type. For example, if <tt>ty</tt> is <tt>ty</tt> is unmodified. </div> -<H3><a name="Extending_nn26"></a>36.8.3 Type tests</H3> +<H3><a name="Extending_nn26"></a>37.8.3 Type tests</H3> <p> @@ -2148,7 +2148,7 @@ Checks if <tt>ty</tt> is a varargs type. Checks if <tt>ty</tt> is a templatized type. </div> -<H3><a name="Extending_nn27"></a>36.8.4 Typedef and inheritance</H3> +<H3><a name="Extending_nn27"></a>37.8.4 Typedef and inheritance</H3> <p> @@ -2250,7 +2250,7 @@ Fully reduces <tt>ty</tt> according to typedef rules. Resulting datatype will consist only of primitive typenames. </div> -<H3><a name="Extending_nn28"></a>36.8.5 Lvalues</H3> +<H3><a name="Extending_nn28"></a>37.8.5 Lvalues</H3> <p> @@ -2287,7 +2287,7 @@ Literal y; // type = 'Literal', ltype='p.char' </pre> </div> -<H3><a name="Extending_nn29"></a>36.8.6 Output functions</H3> +<H3><a name="Extending_nn29"></a>37.8.6 Output functions</H3> <p> @@ -2349,7 +2349,7 @@ SWIG, but is most commonly associated with type-descriptor objects that appear in wrappers (e.g., <tt>SWIGTYPE_p_double</tt>). </div> -<H2><a name="Extending_nn30"></a>36.9 Parameters</H2> +<H2><a name="Extending_nn30"></a>37.9 Parameters</H2> <p> @@ -2448,7 +2448,7 @@ included. Used to emit prototypes. Returns the number of required (non-optional) arguments in <tt>p</tt>. </div> -<H2><a name="Extending_nn31"></a>36.10 Writing a Language Module</H2> +<H2><a name="Extending_nn31"></a>37.10 Writing a Language Module</H2> <p> @@ -2463,7 +2463,7 @@ describes the creation of a minimal Python module. You should be able to extra this to other languages. </p> -<H3><a name="Extending_nn32"></a>36.10.1 Execution model</H3> +<H3><a name="Extending_nn32"></a>37.10.1 Execution model</H3> <p> @@ -2473,7 +2473,7 @@ the parsing of command line options, all aspects of code generation are controll different methods of the <tt>Language</tt> that must be defined by your module. </p> -<H3><a name="Extending_starting_out"></a>36.10.2 Starting out</H3> +<H3><a name="Extending_starting_out"></a>37.10.2 Starting out</H3> <p> @@ -2581,7 +2581,7 @@ that activates your module. For example, <tt>swig -python foo.i</tt>. The messages from your new module should appear. </p> -<H3><a name="Extending_nn34"></a>36.10.3 Command line options</H3> +<H3><a name="Extending_nn34"></a>37.10.3 Command line options</H3> <p> @@ -2640,7 +2640,7 @@ to mark the option as valid. If you forget to do this, SWIG will terminate wit unrecognized command line option error. </p> -<H3><a name="Extending_nn35"></a>36.10.4 Configuration and preprocessing</H3> +<H3><a name="Extending_nn35"></a>37.10.4 Configuration and preprocessing</H3> <p> @@ -2689,7 +2689,7 @@ an implementation file <tt>python.cxx</tt> and a configuration file <tt>python.swg</tt>. </p> -<H3><a name="Extending_nn36"></a>36.10.5 Entry point to code generation</H3> +<H3><a name="Extending_nn36"></a>37.10.5 Entry point to code generation</H3> <p> @@ -2747,7 +2747,7 @@ int Python::top(Node *n) { </pre> </div> -<H3><a name="Extending_nn37"></a>36.10.6 Module I/O and wrapper skeleton</H3> +<H3><a name="Extending_nn37"></a>37.10.6 Module I/O and wrapper skeleton</H3> <!-- please report bugs in this section to mgossage --> @@ -2895,7 +2895,7 @@ functionWrapper : void Shape_y_set(Shape *self,double y) </pre> </div> -<H3><a name="Extending_nn38"></a>36.10.7 Low-level code generators</H3> +<H3><a name="Extending_nn38"></a>37.10.7 Low-level code generators</H3> <!-- please report bugs in this section to mgossage --> @@ -3049,7 +3049,7 @@ but without the typemaps, there is still work to do. </p> -<H3><a name="Extending_configuration_files"></a>36.10.8 Configuration files</H3> +<H3><a name="Extending_configuration_files"></a>37.10.8 Configuration files</H3> <!-- please report bugs in this section to ttn --> @@ -3193,7 +3193,7 @@ politely displays the ignoring language message. </dl> -<H3><a name="Extending_nn40"></a>36.10.9 Runtime support</H3> +<H3><a name="Extending_nn40"></a>37.10.9 Runtime support</H3> <p> @@ -3202,7 +3202,7 @@ Discuss the kinds of functions typically needed for SWIG runtime support (e.g. the SWIG files that implement those functions. </p> -<H3><a name="Extending_nn41"></a>36.10.10 Standard library files</H3> +<H3><a name="Extending_nn41"></a>37.10.10 Standard library files</H3> <p> @@ -3221,7 +3221,7 @@ The following are the minimum that are usually supported: Please copy these and modify for any new language. </p> -<H3><a name="Extending_nn42"></a>36.10.11 User examples</H3> +<H3><a name="Extending_nn42"></a>37.10.11 User examples</H3> <p> @@ -3250,7 +3250,7 @@ during this process, see the section on <a href="#Extending_configuration_files" files</a>. </p> -<H3><a name="Extending_test_suite"></a>36.10.12 Test driven development and the test-suite</H3> +<H3><a name="Extending_test_suite"></a>37.10.12 Test driven development and the test-suite</H3> <p> @@ -3309,7 +3309,7 @@ It is therefore essential that the runtime tests are written in a manner that di but error/exception out with an error message on stderr on failure. </p> -<H4><a name="Extending_running_test_suite"></a>36.10.12.1 Running the test-suite</H4> +<H4><a name="Extending_running_test_suite"></a>37.10.12.1 Running the test-suite</H4> <p> @@ -3477,7 +3477,25 @@ A debugger can also be invoked easily on an individual test, for example gdb: make ret_by_value.ctest RUNTOOL="gdb --args" </pre></div> -<H3><a name="Extending_nn43"></a>36.10.13 Documentation</H3> +<p> +SWIG reads the <tt>SWIG_FEATURES</tt> environment variable to obtain options in addition to those passed on the command line. +This is particularly useful as the entire test-suite or a particular testcase can be run customized by using additional +arguments, for example the -O optimization flag can be added in, as shown below for the bash shell: +</p> + +<div class="shell"><pre> +env SWIG_FEATURES=-O make check-python-test-suite +</pre></div> + +<p> +The syntax for setting environment variables varies from one shell to the next, but it also works as shown in the example below, where some typemap debugging is added in: +</p> + +<div class="shell"><pre> +make ret_by_value.ctest SWIG_FEATURES="-debug-tmsearch" +</pre></div> + +<H3><a name="Extending_nn43"></a>37.10.13 Documentation</H3> <p> @@ -3509,7 +3527,7 @@ Some topics that you'll want to be sure to address include: if available. </ul> -<H3><a name="Extending_prerequisites"></a>36.10.14 Prerequisites for adding a new language module to the SWIG distribution</H3> +<H3><a name="Extending_prerequisites"></a>37.10.14 Prerequisites for adding a new language module to the SWIG distribution</H3> <p> @@ -3566,7 +3584,7 @@ should be added should there be an area not already covered by the existing tests. </p> -<H3><a name="Extending_coding_style_guidelines"></a>36.10.15 Coding style guidelines</H3> +<H3><a name="Extending_coding_style_guidelines"></a>37.10.15 Coding style guidelines</H3> <p> @@ -3590,7 +3608,7 @@ The generated C/C++ code should also follow this style as close as possible. How should be avoided as unlike the SWIG developers, users will never have consistent tab settings. </p> -<H2><a name="Extending_debugging_options"></a>36.11 Debugging Options</H2> +<H2><a name="Extending_debugging_options"></a>37.11 Debugging Options</H2> <p> @@ -3609,13 +3627,15 @@ There are various command line options which can aid debugging a SWIG interface -debug-top <n> - Display entire parse tree at stages 1-4, <n> is a csv list of stages -debug-typedef - Display information about the types and typedefs in the interface -debug-typemap - Display information for debugging typemaps +-debug-tmsearch - Display typemap search debugging information +-debug-tmused - Display typemaps used debugging information </pre></div> <p> The complete list of command line options for SWIG are available by running <tt>swig -help</tt>. </p> -<H2><a name="Extending_nn46"></a>36.12 Guide to parse tree nodes</H2> +<H2><a name="Extending_nn46"></a>37.12 Guide to parse tree nodes</H2> <p> @@ -4023,7 +4043,7 @@ extern "X" { ... } declaration. </pre> </div> -<H2><a name="Extending_further_info"></a>36.13 Further Development Information</H2> +<H2><a name="Extending_further_info"></a>37.13 Further Development Information</H2> <p> |