mirror of https://github.com/swig/swig
934 lines
26 KiB
HTML
934 lines
26 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<title>SWIG and Go</title>
|
|
<link rel="stylesheet" type="text/css" href="style.css">
|
|
</head>
|
|
<body bgcolor="#FFFFFF">
|
|
<H1><a name="Go"></a>23 SWIG and Go</H1>
|
|
<!-- INDEX -->
|
|
<div class="sectiontoc">
|
|
<ul>
|
|
<li><a href="#Go_overview">Overview</a>
|
|
<li><a href="#Go_examples">Examples</a>
|
|
<li><a href="#Go_running_swig">Running SWIG with Go</a>
|
|
<ul>
|
|
<li><a href="#Go_commandline">Additional Commandline Options</a>
|
|
<li><a href="#Go_outputs">Go Output Files</a>
|
|
</ul>
|
|
<li><a href="#Go_basic_tour">A tour of basic C/C++ wrapping</a>
|
|
<ul>
|
|
<li><a href="#Go_package">Go Package Name</a>
|
|
<li><a href="#Go_names">Go Names</a>
|
|
<li><a href="#Go_constants">Go Constants</a>
|
|
<li><a href="#Go_enumerations">Go Enumerations</a>
|
|
<li><a href="#Go_classes">Go Classes</a>
|
|
<ul>
|
|
<li><a href="#Go_class_memory">Go Class Memory Management</a>
|
|
<li><a href="#Go_class_inheritance">Go Class Inheritance</a>
|
|
</ul>
|
|
<li><a href="#Go_templates">Go Templates</a>
|
|
<li><a href="#Go_director_classes">Go Director Classes</a>
|
|
<li><a href="#Go_primitive_type_mappings">Default Go primitive type mappings</a>
|
|
<li><a href="#Go_output_arguments">Output arguments</a>
|
|
<li><a href="#Go_adding_additional_code">Adding additional go code</a>
|
|
<li><a href="#Go_typemaps">Go typemaps</a>
|
|
</ul>
|
|
</ul>
|
|
</div>
|
|
<!-- INDEX -->
|
|
|
|
|
|
|
|
<p>
|
|
This chapter describes SWIG's support of Go. For more information on
|
|
the Go programming language
|
|
see <a href="http://golang.org/">golang.org</a>.
|
|
</p>
|
|
|
|
<H2><a name="Go_overview"></a>23.1 Overview</H2>
|
|
|
|
|
|
<p>
|
|
Go is a compiled language, not a scripting language. However, it does
|
|
not support direct calling of functions written in C/C++. The cgo
|
|
program may be used to generate wrappers to call C code from Go, but
|
|
there is no convenient way to call C++ code. SWIG fills this gap.
|
|
</p>
|
|
|
|
<p>
|
|
There are (at least) two different Go compilers. One is the gc
|
|
compiler, normally invoked via the go tool. The other
|
|
is the gccgo compiler, which is a frontend to the gcc compiler suite.
|
|
The interface to C/C++ code is completely different for the two Go
|
|
compilers. SWIG supports both, selected by a command line option.
|
|
</p>
|
|
|
|
<p>
|
|
Because Go is a type-safe compiled language, SWIG's runtime type
|
|
checking and runtime library are not used with Go. This should be
|
|
borne in mind when reading the rest of the SWIG documentation.
|
|
</p>
|
|
|
|
<H2><a name="Go_examples"></a>23.2 Examples</H2>
|
|
|
|
|
|
<p>
|
|
Working examples can be found here:
|
|
</p>
|
|
<ul>
|
|
<li><a href="https://golang.org/misc/swig">Examples from the Go source tree</a>
|
|
<li><a href="https://github.com/swig/swig/tree/master/Examples/go">Examples from the SWIG source tree</a>
|
|
</ul>
|
|
<p>
|
|
The examples in the 2nd link are shipped with the SWIG distribution under the Examples/go directory.
|
|
</p>
|
|
|
|
|
|
<H2><a name="Go_running_swig"></a>23.3 Running SWIG with Go</H2>
|
|
|
|
|
|
<p>
|
|
To generate Go code, use the <tt>-go</tt> option with SWIG. By
|
|
default SWIG will generate code for the gc compilers. To generate
|
|
code for gccgo, you should also use the <tt>-gccgo</tt> option.
|
|
</p>
|
|
|
|
<H3><a name="Go_commandline"></a>23.3.1 Additional Commandline Options</H3>
|
|
|
|
|
|
<p>
|
|
These are the command line options for SWIG's Go module. They can
|
|
also be seen by using:
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
swig -go -help
|
|
</pre></div>
|
|
|
|
<table summary="Go specific options">
|
|
<tr>
|
|
<th>Go specific options</th>
|
|
</tr>
|
|
|
|
<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>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>-intgosize <s></td>
|
|
<td>Set the size for the Go type <tt>int</tt>. This controls the size
|
|
that the C/C++ code expects to see. The <s> argument should
|
|
be 32 or 64. This option is currently required during the
|
|
transition from Go 1.0 to Go 1.1, as the size of <tt>int</tt> on
|
|
64-bit x86 systems changes between those releases (from 32 bits to
|
|
64 bits). In the future the option may become optional, and SWIG
|
|
will assume that the size of <tt>int</tt> is the size of a C
|
|
pointer.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>-gccgo</td>
|
|
<td>Generate code for gccgo. The default is to generate code for
|
|
the gc compiler.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>-package <name></td>
|
|
<td>Set the name of the Go package to <name>. The default
|
|
package name is the SWIG module name.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>-use-shlib</td>
|
|
<td>Tell SWIG to emit code that uses a shared library. This is only
|
|
meaningful for the gc compiler, which needs to know at compile time
|
|
whether a shared library will be used.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>-soname <name></td>
|
|
<td>Set the runtime name of the shared library that the dynamic linker
|
|
should include at runtime. The default is the package name with
|
|
".so" appended. This is only used when generating code for
|
|
the gc compiler; when using gccgo, the equivalent name will be taken from
|
|
the <code>-soname</code> option passed to the linker. Using this
|
|
option implies the -use-shlib option.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>-go-pkgpath <pkgpath></td>
|
|
<td>When generating code for gccgo, set the pkgpath to use. This
|
|
corresponds to the <tt>-fgo-pkgpath</tt> option to gccgo.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>-go-prefix <prefix></td>
|
|
<td>When generating code for gccgo, set the prefix to use. This
|
|
corresponds to the <tt>-fgo-prefix</tt> option to gccgo.
|
|
If <tt>-go-pkgpath</tt> is used, <tt>-go-prefix</tt> will be
|
|
ignored.</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<H3><a name="Go_outputs"></a>23.3.2 Go Output Files</H3>
|
|
|
|
|
|
<p>There are two different approaches to generating output 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>
|
|
|
|
<p>With or without the <tt>-cgo</tt> option, SWIG will generate the
|
|
following files when generating Go code:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
MODULE.go will contain the Go functions that your Go code will call.
|
|
These functions will be wrappers for the C++ functions defined by your
|
|
module. This file should, of course, be compiled with the Go
|
|
compiler.
|
|
</li>
|
|
<li>
|
|
MODULE_wrap.c or MODULE_wrap.cxx will contain C/C++ functions will be
|
|
invoked by the Go wrapper code. This file should be compiled with the
|
|
usual C or C++ compiler.
|
|
</li>
|
|
<li>
|
|
MODULE_wrap.h will be generated if you use the directors feature. It
|
|
provides a definition of the generated C++ director classes. It is
|
|
generally not necessary to use this file, but in some special cases it
|
|
may be helpful to include it in your code, compiled with the usual C
|
|
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>
|
|
|
|
<ul>
|
|
<li>
|
|
MODULE_gc.c will contain C code which should be compiled with the C
|
|
compiler distributed as part of the gc compiler. It should then be
|
|
combined with the compiled MODULE.go using go tool pack.
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
Most Go programs are built using the go tool. The go tool has limited
|
|
support for SWIG. To use it, put your SWIG interface into a file with
|
|
the extension .swig, or, if you are wrapping C++ code, .swigcxx. Put
|
|
that file in a GOPATH/src directory as usual for Go sources. Put
|
|
other interface code in the same directory with extensions of .c and
|
|
.cxx. The <tt>go build</tt> and <tt>go install</tt> commands will
|
|
automatically run SWIG for you and will build the interface code.
|
|
</p>
|
|
|
|
<p>
|
|
You can also use SWIG directly yourself. When using
|
|
the <tt>-cgo</tt> option, SWIG will generate files that can be used
|
|
directly by <tt>go build</tt>. Put your SWIG input file in a
|
|
directory under GOPATH/src, and give it a name that does not end in
|
|
.swig or .swigcxx.
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
% swig -go -cgo example.i
|
|
% go install
|
|
</pre></div>
|
|
|
|
<p>
|
|
You will now have a Go package that you can import from other Go
|
|
packages as 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 gc compiler would look like this:
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
% swig -go example.i
|
|
% gcc -c code.c # The C library being wrapped.
|
|
% gcc -c example_wrap.c
|
|
% go tool 6g example.go
|
|
% go tool 6c example_gc.c
|
|
% go tool pack grc example.a example.6 example_gc.6 code.o example_wrap.o
|
|
% go tool 6g main.go
|
|
% go tool 6l main.6
|
|
</pre></div>
|
|
|
|
<p>
|
|
You can also put the wrapped code into a shared library, and when
|
|
using the Go versions before 1.2 this is the only supported option. A
|
|
typical command sequence for this approach would look like this:
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
% swig -go -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
|
|
% go tool 6g example.go
|
|
% go tool 6c example_gc.c
|
|
% go tool pack grc example.a example.6 example_gc.6
|
|
% go tool 6g main.go # your code, not generated by SWIG
|
|
% go tool 6l main.6
|
|
</pre></div>
|
|
|
|
<H2><a name="Go_basic_tour"></a>23.4 A tour of basic C/C++ wrapping</H2>
|
|
|
|
|
|
<p>
|
|
By default, SWIG attempts to build a natural Go interface to your
|
|
C/C++ code. However, the languages are somewhat different, so some
|
|
modifications have to occur. This section briefly covers the
|
|
essential aspects of this wrapping.
|
|
</p>
|
|
|
|
<H3><a name="Go_package"></a>23.4.1 Go Package Name</H3>
|
|
|
|
|
|
<p>
|
|
All Go source code lives in a package. The name of this package will
|
|
default to the name of the module from SWIG's <tt>%module</tt>
|
|
directive. You may override this by using SWIG's <tt>-package</tt>
|
|
command line option.
|
|
</p>
|
|
|
|
<H3><a name="Go_names"></a>23.4.2 Go Names</H3>
|
|
|
|
|
|
<p>
|
|
In Go, a function is only visible outside the current package if the
|
|
first letter of the name is uppercase. This is quite different from
|
|
C/C++. Because of this, C/C++ names are modified when generating the
|
|
Go interface: the first letter is forced to be uppercase if it is not
|
|
already. This affects the names of functions, methods, variables,
|
|
constants, enums, and classes.
|
|
</p>
|
|
|
|
<p>
|
|
C/C++ variables are wrapped with setter and getter functions in Go.
|
|
First the first letter of the variable name will be forced to
|
|
uppercase, and then <tt>Get</tt> or <tt>Set</tt> will be prepended.
|
|
For example, if the C/C++ variable is called <tt>var</tt>, then SWIG
|
|
will define the functions <tt>GetVar</tt> and <tt>SetVar</tt>. If a
|
|
variable is declared as <tt>const</tt>, or if
|
|
SWIG's <a href="SWIG.html#SWIG_readonly_variables">
|
|
<tt>%immutable</tt> directive</a> is used for the variable, then only
|
|
the getter will be defined.
|
|
</p>
|
|
|
|
<p>
|
|
C++ classes will be discussed further below. Here we'll note that the
|
|
first letter of the class name will be forced to uppercase to give the
|
|
name of a type in Go. A constructor will be named <tt>New</tt>
|
|
followed by that name, and the destructor will be
|
|
named <tt>Delete</tt> followed by that name.
|
|
</p>
|
|
|
|
<H3><a name="Go_constants"></a>23.4.3 Go Constants</H3>
|
|
|
|
|
|
<p>
|
|
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"></a>23.4.4 Go Enumerations</H3>
|
|
|
|
|
|
<p>
|
|
C/C++ enumeration types will cause SWIG to define an integer type with
|
|
the name of the enumeration (with first letter forced to uppercase as
|
|
usual). The values of the enumeration will become variables in Go;
|
|
code should avoid modifying those variables.
|
|
</p>
|
|
|
|
<H3><a name="Go_classes"></a>23.4.5 Go Classes</H3>
|
|
|
|
|
|
<p>
|
|
Go has interfaces, methods and inheritance, but it does not have
|
|
classes in the same sense as C++. This sections describes how SWIG
|
|
represents C++ classes represented in Go.
|
|
</p>
|
|
|
|
<p>
|
|
For a C++ class <tt>ClassName</tt>, SWIG will define two types in Go:
|
|
an underlying type, which will just hold a pointer to the C++ type,
|
|
and an interface type. The interface type will be
|
|
named <tt>ClassName</tt>. SWIG will define a
|
|
function <tt>NewClassName</tt> which will take any constructor
|
|
arguments and return a value of the interface
|
|
type <tt>ClassName</tt>. SWIG will also define a
|
|
destructor <tt>DeleteClassName</tt>.
|
|
</p>
|
|
|
|
<p>
|
|
SWIG will represent any methods of the C++ class as methods on the
|
|
underlying type, and also as methods of the interface type. Thus C++
|
|
methods may be invoked directly using the
|
|
usual <tt>val.MethodName</tt> syntax. Public members of the C++ class
|
|
will be given getter and setter functions defined as methods of the
|
|
class.
|
|
</p>
|
|
|
|
<p>
|
|
SWIG will represent static methods of C++ classes as ordinary Go
|
|
functions. SWIG will use names like <tt>ClassNameMethodName</tt>.
|
|
SWIG will give static members getter and setter functions with names
|
|
like <tt>GetClassName_VarName</tt>.
|
|
</p>
|
|
|
|
<p>
|
|
Given a value of the interface type, Go code can retrieve the pointer
|
|
to the C++ type by calling the <tt>Swigcptr</tt> method. This will
|
|
return a value of type <tt>SwigcptrClassName</tt>, which is just a
|
|
name for <tt>uintptr</tt>. A Go type conversion can be used to
|
|
convert this value to a different C++ type, but note that this
|
|
conversion will not be type checked and is essentially equivalent
|
|
to <tt>reinterpret_cast</tt>. This should only be used for very
|
|
special cases, such as where C++ would use a <tt>dynamic_cast</tt>.
|
|
</p>
|
|
|
|
<p>Note that C++ pointers to compound objects are represented in go as objects
|
|
themselves, not as go pointers. So, for example, if you wrap the following
|
|
function:</p>
|
|
<div class="code">
|
|
<pre>
|
|
class MyClass {
|
|
int MyMethod();
|
|
static MyClass *MyFactoryFunction();
|
|
};
|
|
|
|
</pre>
|
|
</div>
|
|
<p>You will get go code that looks like this:</p>
|
|
<div class="code">
|
|
<pre>
|
|
type MyClass interface {
|
|
Swigcptr() uintptr
|
|
SwigIsMyClass()
|
|
MyMethod() int
|
|
}
|
|
|
|
MyClassMyFactoryFunction() MyClass {
|
|
// swig magic here
|
|
}
|
|
</pre>
|
|
</div>
|
|
<p>Note that the factory function does not return a go pointer; it actually
|
|
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"></a>23.4.5.1 Go Class Memory Management</H4>
|
|
|
|
|
|
<p>
|
|
Calling <tt>NewClassName</tt> for some C++ class <tt>ClassName</tt>
|
|
will allocate memory using the C++ memory allocator. This memory will
|
|
not be automatically freed by Go's garbage collector as the object ownership is
|
|
not tracked. When you are done with the C++ object you must free it manually
|
|
using <tt>DeleteClassName</tt>.
|
|
</p>
|
|
|
|
<p>
|
|
A common technique is to store the C++ object into a Go object, and
|
|
use the Go function <tt>runtime.SetFinalizer</tt> to free the C++ object when
|
|
the Go object is freed. It is strongly recommended to read the
|
|
<a href="https://golang.org/pkg/runtime/#SetFinalizer">runtime.SetFinalizer</a>
|
|
documentation before using this technique to understand its limitations.
|
|
For example, if the SWIG package is imported as "wrap":
|
|
</p>
|
|
<div class="code">
|
|
<pre>
|
|
type GoClassName struct {
|
|
w wrap.ClassName
|
|
}
|
|
|
|
func NewGoClassName() *GoClassName {
|
|
r := &GoClassName{wrap.NewClassName()}
|
|
runtime.SetFinalizer(r,
|
|
func(r *GoClassName) {
|
|
wrap.DeleteClassName(r.w)
|
|
})
|
|
return r
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<H4><a name="Go_class_inheritance"></a>23.4.5.2 Go Class Inheritance</H4>
|
|
|
|
|
|
<p>
|
|
C++ class inheritance is automatically represented in Go due to its
|
|
use of interfaces. The interface for a child class will be a superset
|
|
of the interface of its parent class. Thus a value of the child class
|
|
type in Go may be passed to a function which expects the parent class.
|
|
Doing the reverse will require an explicit type assertion, which will
|
|
be checked dynamically.
|
|
</p>
|
|
|
|
<H3><a name="Go_templates"></a>23.4.6 Go Templates</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
|
|
the <tt>%template</tt> directive.
|
|
|
|
<H3><a name="Go_director_classes"></a>23.4.7 Go Director Classes</H3>
|
|
|
|
|
|
<p>
|
|
SWIG's director feature permits a Go type to act as the subclass of a
|
|
C++ class with virtual methods. This is complicated by the fact that
|
|
C++ and Go define inheritance differently. In Go, structs can inherit
|
|
methods via anonymous field embedding. However, when a method is
|
|
called for an embedded struct, if that method calls any other methods,
|
|
they are called for the embedded struct, not for the original type.
|
|
Therefore, SWIG must use Go interfaces to represent C++ inheritance.
|
|
</p>
|
|
|
|
<p>
|
|
In order to use the director feature in Go, you must define a type in
|
|
your Go code. You must then add methods for the type. Define a
|
|
method in Go for each C++ virtual function that you want to override.
|
|
You must then create a value of your new type, and pass a pointer to
|
|
it to the function <tt>NewDirectorClassName</tt>,
|
|
where <tt>ClassName</tt> is the name of the C++ class. That will
|
|
return a value of type <tt>ClassName</tt>.
|
|
</p>
|
|
|
|
<p>
|
|
For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
type GoClass struct { }
|
|
func (p *GoClass) VirtualFunction() { }
|
|
func MakeClass() ClassName {
|
|
return NewDirectorClassName(&GoClass{})
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Any call in C++ code to the virtual function will wind up calling the
|
|
method defined in Go. The Go code may of course call other methods on
|
|
itself, and those methods may be defined either in Go or in C++.
|
|
</p>
|
|
|
|
<H3><a name="Go_primitive_type_mappings"></a>23.4.8 Default Go primitive type mappings</H3>
|
|
|
|
|
|
<p>
|
|
The following table lists the default type mapping from C/C++ to Go.
|
|
This table will tell you which Go type to expect for a function which
|
|
uses a given C/C++ type.
|
|
</p>
|
|
|
|
<table BORDER summary="Go primitive type mappings">
|
|
<tr>
|
|
<td><b>C/C++ type</b></td>
|
|
<td><b>Go type</b></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>bool</td>
|
|
<td>bool</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>char</td>
|
|
<td>byte</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>signed char</td>
|
|
<td>int8</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>unsigned char</td>
|
|
<td>byte</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>short</td>
|
|
<td>int16</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>unsigned short</td>
|
|
<td>uint16</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>int</td>
|
|
<td>int</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>unsigned int</td>
|
|
<td>uint</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>long</td>
|
|
<td>int64</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>unsigned long</td>
|
|
<td>uint64</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>long long</td>
|
|
<td>int64</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>unsigned long long</td>
|
|
<td>uint64</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>float</td>
|
|
<td>float32</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>double</td>
|
|
<td>float64</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>char *<br>char []</td>
|
|
<td>string</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<p>
|
|
Note that SWIG wraps the C <tt>char</tt> type as a character. Pointers
|
|
and arrays of this type are wrapped as strings. The <tt>signed
|
|
char</tt> type can be used if you want to treat <tt>char</tt> as a
|
|
signed number rather than a character. Also note that all const
|
|
references to primitive types are treated as if they are passed by
|
|
value.
|
|
</p>
|
|
|
|
<p>
|
|
These type mappings are defined by the "gotype" typemap. You may change
|
|
that typemap, or add new values, to control how C/C++ types are mapped
|
|
into Go types.
|
|
</p>
|
|
|
|
<H3><a name="Go_output_arguments"></a>23.4.9 Output arguments</H3>
|
|
|
|
|
|
<p>Because of limitations in the way output arguments are processed in swig,
|
|
a function with output arguments will not have multiple return values.
|
|
Instead, you must pass a pointer into the C++ function to tell it where to
|
|
store the output value. In go, you supply a slice in the place of the output
|
|
argument.</p>
|
|
|
|
<p>For example, suppose you were trying to wrap the modf() function in the
|
|
C math library which splits x into integral and fractional parts (and
|
|
returns the integer part in one of its parameters):</p>
|
|
<div class="code">
|
|
<pre>
|
|
double modf(double x, double *ip);
|
|
</pre>
|
|
</div>
|
|
<p>You could wrap it with SWIG as follows:</p>
|
|
<div class="code">
|
|
<pre>
|
|
%include <typemaps.i>
|
|
double modf(double x, double *OUTPUT);
|
|
</pre>
|
|
</div>
|
|
<p>or you can use the <code>%apply</code> directive:</p>
|
|
<div class="code">
|
|
<pre>
|
|
%include <typemaps.i>
|
|
%apply double *OUTPUT { double *ip };
|
|
double modf(double x, double *ip);
|
|
</pre>
|
|
</div>
|
|
<p>In Go you would use it like this:</p>
|
|
<div class="code">
|
|
<pre>
|
|
ptr := []float64{0.0}
|
|
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
|
|
hide the ugly details.</p>
|
|
|
|
<p>There are no <code>char *OUTPUT</code> typemaps. However you can
|
|
apply the <code>signed char *</code> typemaps instead:</p>
|
|
<div class="code">
|
|
<pre>
|
|
%include <typemaps.i>
|
|
%apply signed char *OUTPUT {char *output};
|
|
void f(char *output);
|
|
</pre>
|
|
</div>
|
|
|
|
<H3><a name="Go_adding_additional_code"></a>23.4.10 Adding additional go code</H3>
|
|
|
|
|
|
<p>Often the APIs generated by swig are not very natural in go, especially if
|
|
there are output arguments. You can
|
|
insert additional go wrapping code to add new APIs
|
|
with <code>%insert(go_wrapper)</code>, like this:</p>
|
|
<div class="code">
|
|
<pre>
|
|
%include <typemaps.i>
|
|
// Change name of what swig generates to Wrapped_modf. This function will
|
|
// have the following signature in go:
|
|
// func Wrapped_modf(float64, []float64) float64
|
|
%rename(wrapped_modf) modf(double x, double *ip);
|
|
|
|
%apply double *OUTPUT { double *ip };
|
|
double modf(double x, double *ip);
|
|
|
|
%insert(go_wrapper) %{
|
|
|
|
// The improved go interface to this function, which has two return values,
|
|
// in the more natural go idiom:
|
|
func Modf(x float64) (fracPart float64, intPart float64) {
|
|
ip := []float64{0.0}
|
|
fracPart = Wrapped_modf(x, ip)
|
|
intPart = ip[0]
|
|
return
|
|
}
|
|
|
|
%}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>For classes, since swig generates an interface, you can add additional
|
|
methods by defining another interface that includes the swig-generated
|
|
interface. For example,</p>
|
|
<div class="code">
|
|
<pre>
|
|
%rename(Wrapped_MyClass) MyClass;
|
|
%rename(Wrapped_GetAValue) MyClass::GetAValue(int *x);
|
|
%apply int *OUTPUT { int *x };
|
|
|
|
class MyClass {
|
|
public:
|
|
MyClass();
|
|
int AFineMethod(const char *arg); // Swig's wrapping is fine for this one.
|
|
bool GetAValue(int *x);
|
|
};
|
|
|
|
%insert(go_wrapper) %{
|
|
|
|
type MyClass interface {
|
|
Wrapped_MyClass
|
|
GetAValue() (int, bool)
|
|
}
|
|
|
|
func (arg SwigcptrWrapped_MyClass) GetAValue() (int, bool) {
|
|
ip := []int{0}
|
|
ok := arg.Wrapped_GetAValue(ip)
|
|
return ip[0], ok
|
|
}
|
|
|
|
%}
|
|
</pre>
|
|
</div>
|
|
<p>Of course, if you have to rewrite most of the methods, instead of just a
|
|
few, then you might as well define your own struct that includes the
|
|
swig-wrapped object, instead of adding methods to the swig-generated object.</p>
|
|
|
|
<p>If you need to import other go packages, you can do this with
|
|
<code>%go_import</code>. For example,</p>
|
|
<div class="code">
|
|
<pre>
|
|
%go_import("fmt", _ "unusedPackage", rp "renamed/package")
|
|
|
|
%insert(go_wrapper) %{
|
|
|
|
func foo() {
|
|
fmt.Println("Some string:", rp.GetString())
|
|
}
|
|
|
|
// Importing the same package twice is permitted,
|
|
// Go code will be generated with only the first instance of the import.
|
|
%go_import("fmt")
|
|
|
|
%insert(go_wrapper) %{
|
|
|
|
func bar() {
|
|
fmt.Println("Hello world!")
|
|
}
|
|
|
|
%}
|
|
</pre>
|
|
</div>
|
|
|
|
<H3><a name="Go_typemaps"></a>23.4.11 Go typemaps</H3>
|
|
|
|
|
|
<p>
|
|
You can use the <tt>%typemap</tt> directive to modify SWIG's default
|
|
wrapping behavior for specific C/C++ types. You need to be familiar
|
|
with the material in the general
|
|
"<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter. That chapter
|
|
explains how to define a typemap. This section describes some
|
|
specific typemaps used for Go.
|
|
</p>
|
|
|
|
<p>
|
|
In general type conversion code may be written either in C/C++ or in
|
|
Go. The choice to make normally depends on where memory should be
|
|
allocated. To allocate memory controlled by the Go garbage collector,
|
|
write Go code. To allocate memory in the C/C++ heap, write C code.
|
|
</p>
|
|
|
|
<table BORDER summary="Go Typemaps">
|
|
<tr>
|
|
<td><b>Typemap</b></td>
|
|
<td><b>Description</b></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>gotype</td>
|
|
<td>
|
|
The Go type to use for a C++ type. This type will appear in the
|
|
generated Go wrapper function. If this is not defined SWIG will use a
|
|
default as <a href="#Go_primitive_type_mappings">described above</a>.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>imtype</td>
|
|
<td>
|
|
An intermediate Go type used by the "goin", "goout", "godirectorin",
|
|
and "godirectorout" typemaps. If this typemap is not defined for a
|
|
C/C++ type, the gotype typemape will be used. This is useful when
|
|
gotype is best converted to C/C++ using Go code.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>goin</td>
|
|
<td>
|
|
Go code to convert from gotype to imtype when calling a C/C++
|
|
function. SWIG will then internally convert imtype to a C/C++ type
|
|
and pass it down. If this is not defined, or is the empty string, no
|
|
conversion is done.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>in</td>
|
|
<td>
|
|
C/C++ code to convert the internally generated C/C++ type, based on
|
|
imtype, into the C/C++ type that a function call expects. If this is
|
|
not defined the value will simply be cast to the desired type.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>out</td>
|
|
<td>
|
|
C/C++ code to convert the C/C++ type that a function call returns into
|
|
the internally generated C/C++ type, based on imtype, that will be
|
|
returned to Go. If this is not defined the value will simply be cast
|
|
to the desired type.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>goout</td>
|
|
<td>
|
|
Go code to convert a value returned from a C/C++ function from imtype
|
|
to gotype. If this is not defined, or is the empty string, no
|
|
conversion is done.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>argout</td>
|
|
<td>
|
|
C/C++ code to adjust an argument value when returning from a function.
|
|
This is called after the real C/C++ function has run. This uses the
|
|
internally generated C/C++ type, based on imtype. This is only useful
|
|
for a pointer type of some sort. If this is not defined nothing will
|
|
be done.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>goargout</td>
|
|
<td>
|
|
Go code to adjust an argument value when returning from a function.
|
|
This is called after the real C/C++ function has run. The value will
|
|
be in imtype. This is only useful for a pointer type of some sort.
|
|
If this is not defined, or is the empty string, nothing will be done.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>directorin</td>
|
|
<td>
|
|
C/C++ code to convert the C/C++ type used to call a director method
|
|
into the internally generated C/C++ type, based on imtype, that will
|
|
be passed to Go. If this is not defined the value will simply be cast
|
|
to the desired type.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>godirectorin</td>
|
|
<td>
|
|
Go code to convert a value used to call a director method from imtype
|
|
to gotype. If this is not defined, or is the empty string, no
|
|
conversion is done.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>godirectorout</td>
|
|
<td>
|
|
Go code to convert a value returned from a director method from gotype
|
|
to imtype. If this is not defined, or is the empty string, no
|
|
conversion is done.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>directorout</td>
|
|
<td>
|
|
C/C++ code to convert a value returned from a director method from the
|
|
internally generated C/C++ type, based on imtype, into the type that
|
|
the method should return If this is not defined the value will simply
|
|
be cast to the desired type.
|
|
</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</body>
|
|
</html>
|