[Go] Reworked beginning of the documentation.
* Removed link to examples in the Go source tree as discussed in issue #418. * Reworded occurences of the 'gc tool' as it has been removed with Go 1.5. * Reworked chapter 23.3. This should make it easier for users to get started with SWIG as the chapter starts with how to use SWIG with the go tool. * Added helpful links.
This commit is contained in:
Michael Schaller
parent
1851b2fadf
commit
8d2f3403d2
1 changed files with 113 additions and 99 deletions
|
|
@ -13,8 +13,8 @@
|
|||
<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>
|
||||
<li><a href="#Go_commandline">Go-specific Commandline Options</a>
|
||||
<li><a href="#Go_outputs">Generated Wrapper Files</a>
|
||||
</ul>
|
||||
<li><a href="#Go_basic_tour">A tour of basic C/C++ wrapping</a>
|
||||
<ul>
|
||||
|
|
@ -60,38 +60,44 @@ see <a href="http://golang.org/">golang.org</a>.
|
|||
|
||||
|
||||
<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.
|
||||
Go does not support direct calling of functions written in C/C++. The
|
||||
<a href="https://golang.org/cmd/cgo/">cgo program</a> 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.
|
||||
There are (at least) two different Go compilers. The first is the Go compiler
|
||||
of the <a href="https://golang.org/doc/install">Go distribution</a>.
|
||||
Since Go 1.5 the Go compiler is part of the <a href="https://golang.org/cmd/go/">
|
||||
go tool</a>. Go 1.4 and earlier use the gc tool which is called by the go tool.
|
||||
The second Go compiler is the <a href="https://golang.org/doc/install/gccgo">
|
||||
gccgo compiler</a>, 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 Go compilers, selected by the <tt>-gccgo</tt> 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.
|
||||
Go is a type-safe compiled language and the wrapper code generated by SWIG is
|
||||
type-safe as well. In case of type issues the build will fail and hence SWIG's
|
||||
<a href="Modules.html#Modules_nn2">runtime library</a> and
|
||||
<a href="Typemaps.html#Typemaps_runtime_type_checker">runtime type checking</a>
|
||||
are not used.
|
||||
</p>
|
||||
|
||||
<H2><a name="Go_examples"></a>23.2 Examples</H2>
|
||||
|
||||
|
||||
<p>
|
||||
Working examples can be found here:
|
||||
Working examples can be found in the
|
||||
<a href="https://github.com/swig/swig/tree/master/Examples/go">SWIG source tree
|
||||
</a>.
|
||||
</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.
|
||||
Please note that the examples in the SWIG source tree use makefiles with the .i
|
||||
SWIG interface file extension for backwards compatibility with Go 1.
|
||||
</p>
|
||||
|
||||
|
||||
|
|
@ -99,12 +105,83 @@ The examples in the 2nd link are shipped with the SWIG distribution under the Ex
|
|||
|
||||
|
||||
<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.
|
||||
Most Go programs are built using the <a href="https://golang.org/cmd/go/">go
|
||||
tool</a>. Since Go 1.1 the go tool has support for SWIG. To use it, give your
|
||||
SWIG interface file the extension .swig (for C code) or .swigcxx (for C++ code).
|
||||
Put that file in a GOPATH/src directory as usual for Go sources. Put other
|
||||
C/C++ 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 compile the generated wrapper code. To check the SWIG command line
|
||||
options the go tool uses run <tt>go build -x</tt>. To access the automatically
|
||||
generated files run <tt>go build -work</tt>. You'll find the files under the
|
||||
temporary WORK directory.
|
||||
</p>
|
||||
|
||||
<H3><a name="Go_commandline"></a>23.3.1 Additional Commandline Options</H3>
|
||||
<p>
|
||||
To manually generate and compile C/C++ wrapper code for Go, use the <tt>-go</tt>
|
||||
option with SWIG. By default SWIG will generate code for the Go compiler of the
|
||||
Go distribution. To generate code for gccgo, you should also use the <tt>-gccgo
|
||||
</tt> option.
|
||||
</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.
|
||||
</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 Go compiler of
|
||||
the Go distribution 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>
|
||||
|
||||
|
||||
<H3><a name="Go_commandline"></a>23.3.1 Go-specific Commandline Options</H3>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -116,9 +193,9 @@ also be seen by using:
|
|||
swig -go -help
|
||||
</pre></div>
|
||||
|
||||
<table summary="Go specific options">
|
||||
<table summary="Go-specific options">
|
||||
<tr>
|
||||
<th>Go specific options</th>
|
||||
<th>Go-specific options</th>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
|
|
@ -144,7 +221,7 @@ swig -go -help
|
|||
<tr>
|
||||
<td>-gccgo</td>
|
||||
<td>Generate code for gccgo. The default is to generate code for
|
||||
the gc compiler.</td>
|
||||
the Go compiler of the Go distribution.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
|
|
@ -156,8 +233,8 @@ swig -go -help
|
|||
<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>
|
||||
meaningful for the Go compiler of the Go distribution, which needs to know at
|
||||
compile time whether a shared library will be used.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
|
|
@ -165,9 +242,9 @@ swig -go -help
|
|||
<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>
|
||||
the Go compiler of the Go distribution; 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>
|
||||
|
|
@ -186,16 +263,17 @@ swig -go -help
|
|||
|
||||
</table>
|
||||
|
||||
<H3><a name="Go_outputs"></a>23.3.2 Go Output Files</H3>
|
||||
|
||||
<H3><a name="Go_outputs"></a>23.3.2 Generated Wrapper Files</H3>
|
||||
|
||||
|
||||
<p>There are two different approaches to generating output files,
|
||||
<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>
|
||||
|
||||
<p>With or without the <tt>-cgo</tt> option, SWIG will generate the
|
||||
following files when generating Go code:</p>
|
||||
following files when generating wrapper code:</p>
|
||||
|
||||
<ul>
|
||||
<li>
|
||||
|
|
@ -229,70 +307,6 @@ 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>
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue