jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

[Go] Reworked beginning of the documentation.

Browse source 
* 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 2015-08-21 15:09:42 +02:00
commit 8d2f3403d2
1 changed files with 113 additions and 99 deletions
Download patch file Download diff file Expand all files Collapse all files

212
Doc/Manual/Go.html
View file

@ -13,8 +13,8 @@
<li><a href="#Go_examples">Examples</a> <li><a href="#Go_examples">Examples</a>
<li><a href="#Go_running_swig">Running SWIG with Go</a> <li><a href="#Go_running_swig">Running SWIG with Go</a>
<ul> <ul>
<li><a href="#Go_commandline">Additional Commandline Options</a> <li><a href="#Go_commandline">Go-specific Commandline Options</a>
<li><a href="#Go_outputs">Go Output Files</a> <li><a href="#Go_outputs">Generated Wrapper Files</a>
</ul> </ul>
<li><a href="#Go_basic_tour">A tour of basic C/C++ wrapping</a> <li><a href="#Go_basic_tour">A tour of basic C/C++ wrapping</a>
<ul> <ul>
@ -60,38 +60,44 @@ see <a href="http://golang.org/">golang.org</a>.
<p> <p>
Go is a compiled language, not a scripting language. However, it does Go does not support direct calling of functions written in C/C++. The
not support direct calling of functions written in C/C++. The cgo <a href="https://golang.org/cmd/cgo/">cgo program</a> may be used to generate
program may be used to generate wrappers to call C code from Go, but wrappers to call C code from Go, but there is no convenient way to call C++
there is no convenient way to call C++ code. SWIG fills this gap. code. SWIG fills this gap.
</p> </p>
<p> <p>
There are (at least) two different Go compilers. One is the gc There are (at least) two different Go compilers. The first is the Go compiler
compiler, normally invoked via the go tool. The other of the <a href="https://golang.org/doc/install">Go distribution</a>.
is the gccgo compiler, which is a frontend to the gcc compiler suite. Since Go 1.5 the Go compiler is part of the <a href="https://golang.org/cmd/go/">
The interface to C/C++ code is completely different for the two Go go tool</a>. Go 1.4 and earlier use the gc tool which is called by the go tool.
compilers. SWIG supports both, selected by a command line option. 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>
<p> <p>
Because Go is a type-safe compiled language, SWIG's runtime type Go is a type-safe compiled language and the wrapper code generated by SWIG is
checking and runtime library are not used with Go. This should be type-safe as well. In case of type issues the build will fail and hence SWIG's
borne in mind when reading the rest of the SWIG documentation. <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> </p>
<H2><a name="Go_examples"></a>23.2 Examples</H2> <H2><a name="Go_examples"></a>23.2 Examples</H2>
<p> <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> </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> <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> </p>
@ -99,12 +105,83 @@ The examples in the 2nd link are shipped with the SWIG distribution under the Ex
<p> <p>
To generate Go code, use the <tt>-go</tt> option with SWIG. By Most Go programs are built using the <a href="https://golang.org/cmd/go/">go
default SWIG will generate code for the gc compilers. To generate tool</a>. Since Go 1.1 the go tool has support for SWIG. To use it, give your
code for gccgo, you should also use the <tt>-gccgo</tt> option. 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> </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> <p>
@ -116,9 +193,9 @@ also be seen by using:
swig -go -help swig -go -help
</pre></div> </pre></div>
<table summary="Go specific options"> <table summary="Go-specific options">
<tr> <tr>
<th>Go specific options</th> <th>Go-specific options</th>
</tr> </tr>
<tr> <tr>
@ -144,7 +221,7 @@ swig -go -help
<tr> <tr>
<td>-gccgo</td> <td>-gccgo</td>
<td>Generate code for gccgo. The default is to generate code for <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>
<tr> <tr>
@ -156,8 +233,8 @@ swig -go -help
<tr> <tr>
<td>-use-shlib</td> <td>-use-shlib</td>
<td>Tell SWIG to emit code that uses a shared library. This is only <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 meaningful for the Go compiler of the Go distribution, which needs to know at
whether a shared library will be used.</td> compile time whether a shared library will be used.</td>
</tr> </tr>
<tr> <tr>
@ -165,9 +242,9 @@ swig -go -help
<td>Set the runtime name of the shared library that the dynamic linker <td>Set the runtime name of the shared library that the dynamic linker
should include at runtime. The default is the package name with should include at runtime. The default is the package name with
".so" appended. This is only used when generating code for ".so" appended. This is only used when generating code for
the gc compiler; when using gccgo, the equivalent name will be taken from the Go compiler of the Go distribution; when using gccgo, the equivalent name
the <code>-soname</code> option passed to the linker. Using this will be taken from the <code>-soname</code> option passed to the linker.
option implies the -use-shlib option.</td> Using this option implies the -use-shlib option.</td>
</tr> </tr>
<tr> <tr>
@ -186,16 +263,17 @@ swig -go -help
</table> </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 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 works with Go version 1.2 or later. It is required when using Go
version 1.5 or later.</p> version 1.5 or later.</p>
<p>With or without the <tt>-cgo</tt> option, SWIG will generate the <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> <ul>
<li> <li>
@ -229,70 +307,6 @@ combined with the compiled MODULE.go using go tool pack.
</li> </li>
</ul> </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> <H2><a name="Go_basic_tour"></a>23.4 A tour of basic C/C++ wrapping</H2>