diff options
Diffstat (limited to 'Doc/Manual/Go.html')
| -rw-r--r-- | Doc/Manual/Go.html | 142 |
1 files changed, 78 insertions, 64 deletions
diff --git a/Doc/Manual/Go.html b/Doc/Manual/Go.html index f25e9850b..c28cc03e1 100644 --- a/Doc/Manual/Go.html +++ b/Doc/Manual/Go.html @@ -6,7 +6,7 @@ <meta http-equiv="content-type" content="text/html; charset=UTF-8"> </head> <body bgcolor="#FFFFFF"> -<H1><a name="Go">23 SWIG and Go</a></H1> +<H1><a name="Go">24 SWIG and Go</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -57,7 +57,7 @@ the Go programming language see <a href="http://golang.org/">golang.org</a>. </p> -<H2><a name="Go_overview">23.1 Overview</a></H2> +<H2><a name="Go_overview">24.1 Overview</a></H2> <p> @@ -86,7 +86,7 @@ type-safe as well. In case of type issues the build will fail and hence SWIG's are not used. </p> -<H2><a name="Go_examples">23.2 Examples</a></H2> +<H2><a name="Go_examples">24.2 Examples</a></H2> <p> @@ -101,7 +101,7 @@ SWIG interface file extension for backwards compatibility with Go 1. </p> -<H2><a name="Go_running_swig">23.3 Running SWIG with Go</a></H2> +<H2><a name="Go_running_swig">24.3 Running SWIG with Go</a></H2> <p> @@ -125,16 +125,15 @@ Go distribution. To generate code for gccgo, you should also use the </p> <p> -When using the <tt>-cgo</tt> option, SWIG will generate files that can be used -directly by <tt>go build</tt>. Starting with the Go 1.5 distribution the -<tt>-cgo</tt> option has to be given. Put your SWIG interface file in a -directory under GOPATH/src, and give it a name that does <b>not</b> end in the -.swig or .swigcxx extension. Typically the SWIG interface file extension is .i -in this case. +By default SWIG will generate files that can be used directly +by <tt>go build</tt>. This requires Go 1.2 or later. Put your SWIG +interface file in a directory under GOPATH/src, and give it a name +that does <b>not</b> end in the .swig or .swigcxx extension. +Typically the SWIG interface file extension is .i in this case. </p> <div class="code"><pre> -% swig -go -cgo example.i +% swig -go example.i % go install </pre></div> @@ -144,15 +143,16 @@ usual. </p> <p> -To use SWIG without the <tt>-cgo</tt> option, more steps are required. Recall -that this only works with Go versions before 1.5. When using Go version 1.2 or -later, or when using gccgo, the code generated by SWIG can be linked directly -into the Go program. A typical command sequence when using the Go compiler of -the Go distribution would look like this: +SWIG can be used without cgo, via the <tt>-no-cgo</tt> option, but +more steps are required. This only works with Go versions before 1.5. +When using Go version 1.2 or later, or when using gccgo, the code +generated by SWIG can be linked directly into the Go program. A +typical command sequence when using the Go compiler of the Go +distribution would look like this: </p> <div class="code"><pre> -% swig -go example.i +% swig -go -no-cgo example.i % gcc -c code.c # The C library being wrapped. % gcc -c example_wrap.c % go tool 6g example.go @@ -169,7 +169,7 @@ sequence for this approach would look like this: </p> <div class="code"><pre> -% swig -go -use-shlib example.i +% swig -go -no-cgo -use-shlib example.i % gcc -c -fpic example.c % gcc -c -fpic example_wrap.c % gcc -shared example.o example_wrap.o -o example.so @@ -181,7 +181,7 @@ sequence for this approach would look like this: </pre></div> -<H3><a name="Go_commandline">23.3.1 Go-specific Commandline Options</a></H3> +<H3><a name="Go_commandline">24.3.1 Go-specific Commandline Options</a></H3> <p> @@ -200,10 +200,15 @@ swig -go -help <tr> <td>-cgo</td> -<td>Generate files to be used as input for the Go cgo tool. This - option is required for Go 1.5 and later, and works for Go 1.2 and - later. In the future this option will likely become the - default.</td> +<td>Generate files to be used as input for the Go cgo tool. This is + the default.</td> +</tr> + +<tr> +<td>-no-cgo</td> +<td>Generate files that can be used directly, rather than via the Go + cgo tool. This option does not work with Go 1.5 or later. It is + required for versions of Go before 1.2.</td> </tr> <tr> @@ -261,18 +266,25 @@ swig -go -help ignored.</td> </tr> +<tr> +<td>-import-prefix <prefix></td> +<td>A prefix to add when turning a %import prefix in the SWIG + interface file into an import statement in the Go file. For + example, with <code>-import-prefix mymodule</code>, a SWIG + interface file <code>%import mypackage</code> will become a Go + import statement <code>import "mymodule/mypackage"</code>.</td> </table> -<H3><a name="Go_outputs">23.3.2 Generated Wrapper Files</a></H3> +<H3><a name="Go_outputs">24.3.2 Generated Wrapper Files</a></H3> <p>There are two different approaches to generating wrapper files, - controlled by SWIG's <tt>-cgo</tt> option. The <tt>-cgo</tt> option - works with Go version 1.2 or later. It is required when using Go - version 1.5 or later.</p> + controlled by SWIG's <tt>-no-cgo</tt> option. The <tt>-no-cgo</tt> + option only works with version of Go before 1.5. It is required + when using versions of Go before 1.2.</p> -<p>With or without the <tt>-cgo</tt> option, SWIG will generate the +<p>With or without the <tt>-no-cgo</tt> option, SWIG will generate the following files when generating wrapper code:</p> <ul> @@ -296,8 +308,8 @@ or C++ compiler. </li> </ul> -<p>When neither the <tt>-cgo</tt> nor the <tt>-gccgo</tt> option is - used, SWIG will also generate an additional file:</p> +<p>When the <tt>-no-cgo</tt> option is used, and the <tt>-gccgo</tt> + option is not used, SWIG will also generate an additional file:</p> <ul> <li> @@ -308,7 +320,7 @@ combined with the compiled MODULE.go using go tool pack. </ul> -<H2><a name="Go_basic_tour">23.4 A tour of basic C/C++ wrapping</a></H2> +<H2><a name="Go_basic_tour">24.4 A tour of basic C/C++ wrapping</a></H2> <p> @@ -318,7 +330,7 @@ modifications have to occur. This section briefly covers the essential aspects of this wrapping. </p> -<H3><a name="Go_package">23.4.1 Go Package Name</a></H3> +<H3><a name="Go_package">24.4.1 Go Package Name</a></H3> <p> @@ -328,7 +340,7 @@ directive. You may override this by using SWIG's <tt>-package</tt> command line option. </p> -<H3><a name="Go_names">23.4.2 Go Names</a></H3> +<H3><a name="Go_names">24.4.2 Go Names</a></H3> <p> @@ -360,7 +372,7 @@ followed by that name, and the destructor will be named <tt>Delete</tt> followed by that name. </p> -<H3><a name="Go_constants">23.4.3 Go Constants</a></H3> +<H3><a name="Go_constants">24.4.3 Go Constants</a></H3> <p> @@ -368,7 +380,7 @@ C/C++ constants created via <tt>#define</tt> or the <tt>%constant</tt> directive become Go constants, declared with a <tt>const</tt> declaration. -<H3><a name="Go_enumerations">23.4.4 Go Enumerations</a></H3> +<H3><a name="Go_enumerations">24.4.4 Go Enumerations</a></H3> <p> @@ -378,7 +390,7 @@ usual). The values of the enumeration will become variables in Go; code should avoid modifying those variables. </p> -<H3><a name="Go_classes">23.4.5 Go Classes</a></H3> +<H3><a name="Go_classes">24.4.5 Go Classes</a></H3> <p> @@ -456,7 +468,7 @@ returns a go interface. If the returned pointer can be null, you can check for this by calling the Swigcptr() method. </p> -<H4><a name="Go_class_memory">23.4.5.1 Go Class Memory Management</a></H4> +<H4><a name="Go_class_memory">24.4.5.1 Go Class Memory Management</a></H4> <p> @@ -471,7 +483,7 @@ The most Go idiomatic way to manage the memory for some C++ class is to call <tt><a href="https://golang.org/doc/effective_go.html#defer">defer</a></tt> of the <tt>DeleteClassName</tt> call. Using <tt>defer</tt> ensures that the memory of the C++ object is freed as soon as the function containing the <tt>defer</tt> -statement returns. Furthemore <tt>defer</tt> works great for short-lived +statement returns. Furthermore <tt>defer</tt> works great for short-lived objects and fits nicely C++'s RAII idiom. Example: </p> <div class="code"> @@ -512,7 +524,7 @@ func main() { <p> Using <tt>defer</tt> has limitations though, especially when it comes to -long-lived C++ objects whichs lifetimes are hard to predict. For such C++ +long-lived C++ objects whose lifetimes are hard to predict. For such C++ objects a common technique is to store the C++ object into a Go object, and to use the Go function <tt>runtime.SetFinalizer</tt> to add a finalizer which frees the C++ object when the Go object is freed. It is strongly recommended to read @@ -578,7 +590,7 @@ func (o *GoClassName) Close() { </pre> </div> -<H4><a name="Go_class_inheritance">23.4.5.2 Go Class Inheritance</a></H4> +<H4><a name="Go_class_inheritance">24.4.5.2 Go Class Inheritance</a></H4> <p> @@ -590,16 +602,16 @@ Doing the reverse will require an explicit type assertion, which will be checked dynamically. </p> -<H3><a name="Go_templates">23.4.6 Go Templates</a></H3> +<H3><a name="Go_templates">24.4.6 Go Templates</a></H3> <p> In order to use C++ templates in Go, you must tell SWIG to create -wrappers for a particular template instantation. To do this, use +wrappers for a particular template instantiation. To do this, use the <tt>%template</tt> directive. -<H3><a name="Go_director_classes">23.4.7 Go Director Classes</a></H3> +<H3><a name="Go_director_classes">24.4.7 Go Director Classes</a></H3> <p> @@ -611,13 +623,13 @@ work is necessary. </p> <p> -This subchapter gives a step by step guide how to properly sublass a C++ class +This subchapter gives a step by step guide how to properly subclass a C++ class with a Go type. In general it is strongly recommended to follow this guide completely to avoid common pitfalls with directors in Go. </p> -<H4><a name="Go_director_example_cpp_code">23.4.7.1 Example C++ code</a></H4> +<H4><a name="Go_director_example_cpp_code">24.4.7.1 Example C++ code</a></H4> <p> @@ -639,12 +651,12 @@ public: virtual ~FooBarAbstract() {}; std::string FooBar() { - return this->Foo() + ", " + this->Bar(); + return this->Foo() + ", " + this->Bar(); }; protected: virtual std::string Foo() { - return "Foo"; + return "Foo"; }; virtual std::string Bar() = 0; @@ -689,7 +701,7 @@ be found in <a href="#Go_director_foobargo_class">the end of the guide</a>. </p> -<H4><a name="Go_director_enable">23.4.7.2 Enable director feature</a></H4> +<H4><a name="Go_director_enable">24.4.7.2 Enable director feature</a></H4> <p> @@ -724,7 +736,7 @@ documentation on directors. </p> -<H4><a name="Go_director_ctor_dtor">23.4.7.3 Constructor and destructor</a></H4> +<H4><a name="Go_director_ctor_dtor">24.4.7.3 Constructor and destructor</a></H4> <p> @@ -777,7 +789,7 @@ embedding</a>. </p> -<H4><a name="Go_director_overriding">23.4.7.4 Override virtual methods</a></H4> +<H4><a name="Go_director_overriding">24.4.7.4 Override virtual methods</a></H4> <p> @@ -785,10 +797,12 @@ In order to override virtual methods on a C++ class with Go methods the <tt>NewDirectorClassName</tt> constructor functions receives a <tt>DirectorInterface</tt> argument. The methods in the <tt> DirectorInterface</tt> are a subset of the public and protected virtual methods -of the C++ class. If the <tt>DirectorInterface</tt> contains a method with a +of the C++ class. +Virtual methods that have a final specifier are unsurprisingly excluded. +If the <tt>DirectorInterface</tt> contains a method with a matching signature to a virtual method of the C++ class then the virtual C++ method will be overwritten with the Go method. As Go doesn't support protected -methods all overriden protected virtual C++ methods will be public in Go. +methods all overridden protected virtual C++ methods will be public in Go. </p> <p> @@ -843,7 +857,7 @@ the Go methods. </p> -<H4><a name="Go_director_base_methods">23.4.7.5 Call base methods</a></H4> +<H4><a name="Go_director_base_methods">24.4.7.5 Call base methods</a></H4> <p> @@ -880,7 +894,7 @@ be found in <a href="#Go_director_foobargo_class">the end of the guide</a>. </p> -<H4><a name="Go_director_subclass">23.4.7.6 Subclass via embedding</a></H4> +<H4><a name="Go_director_subclass">24.4.7.6 Subclass via embedding</a></H4> <p> @@ -941,14 +955,14 @@ methods of the <tt>FooBarAbstract</tt> C++ class by means of embedding. The public <tt>FooBarGo</tt> interface type includes the <tt>FooBarAbstract</tt> interface and hence <tt>FooBarGo</tt> can be used as a drop in replacement for <tt>FooBarAbstract</tt> while the reverse isn't possible and would raise a -compile time error. Furthemore the constructor and destructor functions <tt> +compile time error. Furthermore the constructor and destructor functions <tt> NewFooBarGo</tt> and <tt>DeleteFooBarGo</tt> take care of all the director specifics and to the user the class appears as any other SWIG wrapped C++ class. </p> -<H4><a name="Go_director_finalizer">23.4.7.7 Memory management with runtime.SetFinalizer</a></H4> +<H4><a name="Go_director_finalizer">24.4.7.7 Memory management with runtime.SetFinalizer</a></H4> <p> @@ -1013,7 +1027,7 @@ before using <tt>runtime.SetFinalizer</tt> to know all of its gotchas. </p> -<H4><a name="Go_director_foobargo_class">23.4.7.8 Complete FooBarGo example class</a></H4> +<H4><a name="Go_director_foobargo_class">24.4.7.8 Complete FooBarGo example class</a></H4> <p> @@ -1054,7 +1068,7 @@ type overwrittenMethodsOnFooBarAbstract struct { fb FooBarAbstract // If additional constructor arguments have been given they are typically - // stored here so that the overriden methods can use them. + // stored here so that the overridden methods can use them. } func (om *overwrittenMethodsOnFooBarAbstract) Foo() string { @@ -1081,7 +1095,7 @@ func NewFooBarGo() FooBarGo { // The memory of the FooBarAbstract director object instance can be // automatically freed once the FooBarGo instance is garbage collected by // uncommenting the following line. Please make sure to understand the - // runtime.SetFinalizer specific gotchas before doing this. Furthemore + // runtime.SetFinalizer specific gotchas before doing this. Furthermore // DeleteFooBarGo should be deleted if a finalizer is in use or the fooBarGo // struct needs additional data to prevent double deletion. // runtime.SetFinalizer(fbgs, FooBarGo.deleteFooBarAbstract) @@ -1142,7 +1156,7 @@ SWIG/Examples/go/director/</a>. </p> -<H3><a name="Go_primitive_type_mappings">23.4.8 Default Go primitive type mappings</a></H3> +<H3><a name="Go_primitive_type_mappings">24.4.8 Default Go primitive type mappings</a></H3> <p> @@ -1249,7 +1263,7 @@ that typemap, or add new values, to control how C/C++ types are mapped into Go types. </p> -<H3><a name="Go_output_arguments">23.4.9 Output arguments</a></H3> +<H3><a name="Go_output_arguments">24.4.9 Output arguments</a></H3> <p>Because of limitations in the way output arguments are processed in swig, @@ -1289,7 +1303,7 @@ fraction := modulename.Modf(5.0, ptr) </pre> </div> <p>Since this is ugly, you may want to wrap the swig-generated API with -some <a href="#Embedded_go_code">additional functions written in go</a> that +some <a href="#Go_adding_additional_code">additional functions written in go</a> that hide the ugly details.</p> <p>There are no <code>char *OUTPUT</code> typemaps. However you can @@ -1302,7 +1316,7 @@ void f(char *output); </pre> </div> -<H3><a name="Go_adding_additional_code">23.4.10 Adding additional go code</a></H3> +<H3><a name="Go_adding_additional_code">24.4.10 Adding additional go code</a></H3> <p>Often the APIs generated by swig are not very natural in go, especially if @@ -1397,7 +1411,7 @@ func bar() { </pre> </div> -<H3><a name="Go_typemaps">23.4.11 Go typemaps</a></H3> +<H3><a name="Go_typemaps">24.4.11 Go typemaps</a></H3> <p> |