[Go] Add -cgo option, required for Go version 1.5 and later.

Doc/Manual/Go.html

@@ -111,6 +111,14 @@ swig -go -help
 <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 &lt;s&gt;</td>
 <td>Set the size for the Go type <tt>int</tt>.  This controls the size
@@ -171,8 +179,13 @@ swig -go -help
 <H3><a name="Go_outputs"></a>23.3.2 Go Output Files</H3>
 
 
-<p> When generating Go code, SWIG will generate the following
-  files:</p>
+<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>
@@ -180,21 +193,30 @@ 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 and linked into a shared library.
+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>
-If using the gc compiler, 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 gopack.  This file will not be generated when using gccgo.
+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>
@@ -203,14 +225,33 @@ 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 go build command and go install commands will automatically
-run SWIG for you and will build the interface code.
+.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 gc compiler
-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
+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>
 
@@ -227,9 +268,8 @@ sequence when using the gc compiler would look like this:
 
 <p>
 You can also put the wrapped code into a shared library, and when
-using the gc compiler before version 1.2 this is the only supported
-option.  A typical command sequence for this approach would look like
-this:
+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>