Re: [gccgo] Add documentation

[Ralf Wildenhues <Ralf dot Wildenhues at gmx dot de>]

* Ian Lance Taylor wrote on Fri, Nov 19, 2010 at 04:57:07AM CET:
> This patch adds documentation to the gccgo branch, following the
> checklist in sourcebuild.texi.  This adds a new small manual for gccgo.
> I also fixed the various Make-lang.in targets to do the right thing.
> Committed to gccgo branch.

> --- go/gccgo.texi	(revision 0)
> +++ go/gccgo.texi	(revision 0)

> +@c man begin OPTIONS gccgo
> +
> +@table @gcctabopt
> +@item -I@var{dir}
> +@cindex @option{-I}

FWIW, gcc.texi uses a separate option index, and indexes options with
leading - or -- removed, so in the PDF they don't all sort under the
same character.  Might this be useful for this manual, too, or do you
expect the size to remain small so this isn't a problem?

> +Specify a directory to use when searching for an import package at
> +compile time.
> +
> +@item -L@var{dir}
> +@cindex @option{-L}
> +When compiling, synonymous with @option{-I}.

Interesting.  Why?

> When linking, specify a
> +library search directory, as with @command{gcc}.
[...]

> +@node C Type Interoperability
> +@section C Type Interoperability

> +The type of a Go function with no receiver is equivalent to a C
> +function whose parameter types are equivalent.  When a Go function
> +returns more than one value, the C function returns a struct.  For
> +example, these functions have equivalent types:
> +
> +@smallexample
> +func GoFunction(int) (int, float)
> +struct @{ int i; float f; @} CFunction(int)
> +@end smallexample

Since IIUC in C99 two struct types are only equivalent if both member
types are compatible and member names are the same, is there a canonical
way to create the member names here?

> +A pointer to a Go function is equivalent to a pointer to a C function
> +when the functions have equivalent types.
> +
> +Go @code{interface}, @code{channel}, and @code{map} types have no
> +corresponding C type (@code{interface} is a two-element struct and
> +@code{channel} and @code{map} are pointers to structs in C, but the
> +structs are deliberately undocumented).  C @code{enum} types
> +correspond to some integer type, but precisely which one is difficult
> +to predict in general; use a cast.  C @code{union} types have no
> +corresponding Go type.  C @code{struct} types containing bitfields
> +have no corresponding Go type.  C++ @code{class} types have no
> +corresponding Go type.
> +
> +Memory allocation is completely different between C and Go, as Go uses
> +garbage collection.  The exact guidelines in this area are
> +undetermined, but it is likely that it will be permitted to pass a
> +pointer to allocated memory from C to Go.  The responsibility of
> +eventually freeing the pointer will remain with C side, and of course
> +if the C side frees the pointer while the Go side still has a copy the
> +program will fail.  When passing a pointer from Go to C, the Go
> +function must retain a visible copy of it in some Go variable.
> +Otherwise the Go garbage collector may delete the pointer while the C
> +function is still using it.

> --- doc/sourcebuild.texi	(revision 166832)
> +++ doc/sourcebuild.texi	(working copy)
> @@ -81,6 +81,10 @@ The GCC runtime library.
>  @item libgfortran
>  The Fortran runtime library.
>  
> +@item libgo
> +The Go runtime library.  The bulk of this library is mirrored from the
> +master Go repository at @uref{http://code.google.com/p/go}.

I'd suggest:
  ... is mirrored from the @uref{http://code.google.com/@/p/@/go, master
  Go repository}.

for nice PDF URL rendering and line wrapping.

>  @item libgomp
>  The GNU OpenMP runtime library.

> --- doc/standards.texi	(revision 166832)
> +++ doc/standards.texi	(working copy)
> @@ -271,6 +271,18 @@ The authoritative manual on Objective-C 
>  For more information concerning the history of Objective-C that is
>  available online, see @uref{http://gcc.gnu.org/readings.html}
>  
> +@section Go language
> +
> +The Go language continues to evolve as of this writing.  The Go
> +language specification may be found at
> +@uref{http://golang.org/doc/go_spec.html}.

Similarly:
  The Go language continues to evolve as of this writing, see the
  @uref{http://golang.org/@/doc/@/go_spec.html, current language
  specifications}.

> At present there are no
> +specific versions of Go, and there is no way to describe the language
> +supported by GCC in terms of a specific version.  In general GCC
> +tracks the evolving specification closely, and any given release will
> +support the language as of the date that the release was frozen.

Cheers,
Ralf