From 8d2f3403d285f448d3e50d56449ecaa82f554cdd Mon Sep 17 00:00:00 2001
From: Michael Schaller <michael@5challer.de>
Date: Fri, 21 Aug 2015 15:09:42 +0200
Subject: [PATCH] [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.
---
 Doc/Manual/Go.html | 212 ++++++++++++++++++++++++---------------------
 1 file changed, 113 insertions(+), 99 deletions(-)

diff --git a/Doc/Manual/Go.html b/Doc/Manual/Go.html
index ca12410ad..7531a218c 100644
--- a/Doc/Manual/Go.html
+++ b/Doc/Manual/Go.html
@@ -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>