From 458dfd497bbda565f413bc5a6b27654f66ab379a Mon Sep 17 00:00:00 2001 From: Xavier Delacour Date: Wed, 31 Aug 2011 20:55:12 +0000 Subject: [PATCH] Updated bits of the documentation, mostly about the Octave-specific command-line arguments and the module command-line arguments that were added in swig 2.0.4, and the new module-loading behaviour. Also changed example_wrap.cxx to example_wrap.cpp, since mkoctfile doesn't recognise .cxx as a C++ extension. (thanks to Karl Wette) git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@12795 626c5289-ae23-0410-ae9c-e8d60b6d4f22 --- Doc/Manual/Octave.html | 112 ++++++++++++++++++++++++++++++++--------- 1 file changed, 88 insertions(+), 24 deletions(-) diff --git a/Doc/Manual/Octave.html b/Doc/Manual/Octave.html index 3c08d849b..fabc7b0c4 100644 --- a/Doc/Manual/Octave.html +++ b/Doc/Manual/Octave.html @@ -15,6 +15,7 @@
  • Preliminaries
  • Running SWIG @@ -61,6 +62,10 @@ Also, there are a dozen or so examples in the Examples/octave directory, and hun The SWIG implemention was first based on Octave 2.9.12, so this is the minimum version required. Testing has only been done on Linux.

    +

    +As of SWIG 2.0.5, the Octave module should work with Octave versions 3.0.5, 3.2.4, and 3.4.0. +

    +

    29.2 Running SWIG

    @@ -80,24 +85,43 @@ extern double Foo; To build an Octave module when wrapping C code, run SWIG using the -octave option:

    -
    $ swig -octave example.i
    +
    $ swig -octave -o example_wrap.cpp example.i

    The -c++ option is also required when wrapping C++ code:

    -
    $ swig -octave -c++ example.i
    +
    $ swig -octave -c++ -o example_wrap.cpp example.i

    -This creates a C++ source file example_wrap.cxx. A C++ file is generated even when wrapping C code as Octave is itself written in C++ and requires wrapper code to be in the same language. The generated C++ source file contains the low-level wrappers that need to be compiled and linked with the rest of your C/C++ application (in this case, the gcd implementation) to create an extension module. +This creates a C++ source file example_wrap.cpp. A C++ file is generated even when wrapping C code as Octave is itself written in C++ and requires wrapper code to be in the same language. The generated C++ source file contains the low-level wrappers that need to be compiled and linked with the rest of your C/C++ application (in this case, the gcd implementation) to create an extension module.

    +

    29.2.1 Command-line options

    +

    -The swig command line has a number of options you can use, like to redirect it's output. Use swig --help to learn about these. +The swig command line has a number of options you can use, like to redirect its output. Use swig -help to learn about these. +Options specific to the Octave module are:

    -

    29.2.1 Compiling a dynamic module

    +
    +
    $ swig -octave -help
+...
+Octave Options (available with -octave)
+     -global       - Load all symbols into the global namespace [default]
+     -globals name - Set name used to access C global variables [default: 'cvar']
+     -noglobal     - Do not load all symbols into the global namespace
+     -opprefix str - Prefix str for global operator functions [default: 'op_']
+
    + +

    +The -global and -noglobal options determine whether the Octave module will load all symbols into the global namespace in addition to the global namespace. +The -globals option sets the name of the variable which is the namespace for C global variables exported by the module. +The -opprefix options sets the prefix of the names of global/friend operator functions. +

    + +

    29.2.2 Compiling a dynamic module

    @@ -106,8 +130,8 @@ Building an oct file is usually done with the mkoctfile command (either within O 

    -$ swig -octave -c++ example.i -o example_wrap.cxx
-$ mkoctfile example_wrap.cxx example.c
+$ swig -octave -c++ -o example_wrap.cpp example.i
+$ mkoctfile example_wrap.cpp example.c

    @@ -124,7 +148,7 @@ $ mkoctfile example_wrap.cxx example.c 

    octave:1> example
    -

    29.2.2 Using your module

    +

    29.2.3 Using your module

    @@ -157,34 +181,70 @@ When Octave is asked to invoke example, it will try to find the .m or .

    -Giving this function a parameter "global" will cause it to load all symbols into the global namespace in addition to the example namespace. For example: +An Octave module takes three options, -global, -noglobal, and -globals, which behave the same as the corresponding swig command-line options. +Here are some example usages:

    - 
    $ octave -q
-octave:1> example("global")
-octave:2> gcd(4,6)
+    
    +octave:1> example -help
+usage: example [-global|-noglobal] [-globals <name>]
+octave:2> example -global
+octave:3> gcd(4,6)
 ans =  2
-octave:3> cvar.Foo
+octave:4> cvar.Foo
 ans =  3
-octave:4> cvar.Foo=4;
-octave:5> cvar.Foo
-ans =  4 
+octave:5> cvar.Foo=4;
+octave:6> cvar.Foo
+ans =  4
 
    
+
    
+    
    +octave:1> example -noglobal
+octave:2> gcd(6,9)
+ans =  3
+octave:3> cvar.Foo
+error: `cvar' undefined near line 3 column 1
+octave:3> example.cvar.Foo
+ans =  3
+
    
+
    
+    
    +octave:1> example -globals mycvar
+octave:2> cvar.Foo
+error: `cvar' undefined near line 2 column 1
+octave:2> mycvar.Foo
+ans =  3
+
    
+
 
    
-     It is also possible to rename the module namespace with an assignment, as in: 
    
-    
    octave:1> example;
+     It is also possible to rename the module / global variables namespaces with an assignment, as in: 
    
+    
    +octave:1> example
 octave:2> c=example;
 octave:3> c.gcd(10,4)
-ans =  2 
    
+ans =  2
+octave:4> some_vars = cvar;
+octave:5> some_vars.Foo
+ans =  3
+
    
 
 
    
-All global variables are put into the cvar namespace object. This is accessible either as my_module.cvar, or just cvar (if the module is imported into the global namespace).
-
    
-
    
-One can also rename it by simple assignment, e.g.,
+Modules can also be loaded from within functions, even before being loaded in the base context.
+If the module is also used in the base context, however, it must first be loaded again:
 
    
+
 
    -octave:1> some_vars = cvar;
+octave:1> function l = my_lcm(a,b)
+> example
+> l = abs(a*b)/example.gcd(a,b);
+> endfunction
+octave:2> my_lcm(4,6)
+ans =  12
+octave:3> example.gcd(4,6)
+error: can't perform indexing operations for <unknown type> type
+octave:3> example;
+octave:4> example.gcd(4,6)
+ans =  2
 
    
 
 
    29.3.2 Functions
    
@@ -580,6 +640,10 @@ On the C++ side, the default mappings are as follows:
 %rename(__brace)     *::operator[];
    +

    +Octave can also utilise friend (i.e. non-member) operators with a simple %rename: see the example in the Examples/octave/operator directory. +

    +

    29.3.10 Class extension with %extend