From patchwork Fri Nov 19 03:57:07 2010 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Ian Lance Taylor X-Patchwork-Id: 72198 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from sourceware.org (server1.sourceware.org [209.132.180.131]) by ozlabs.org (Postfix) with SMTP id 26C74B71BE for ; Fri, 19 Nov 2010 14:57:43 +1100 (EST) Received: (qmail 10447 invoked by alias); 19 Nov 2010 03:57:35 -0000 Received: (qmail 10061 invoked by uid 22791); 19 Nov 2010 03:57:27 -0000 X-SWARE-Spam-Status: No, hits=-3.4 required=5.0 tests=AWL, BAYES_50, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, RCVD_IN_DNSWL_HI, SPF_HELO_PASS, TW_BG, TW_CC, T_RP_MATCHES_RCVD, T_TVD_MIME_NO_HEADERS X-Spam-Check-By: sourceware.org Received: from smtp-out.google.com (HELO smtp-out.google.com) (74.125.121.35) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Fri, 19 Nov 2010 03:57:17 +0000 Received: from hpaq12.eem.corp.google.com (hpaq12.eem.corp.google.com [172.25.149.12]) by smtp-out.google.com with ESMTP id oAJ3vEOU022195 for ; Thu, 18 Nov 2010 19:57:14 -0800 Received: from yxj4 (yxj4.prod.google.com [10.190.3.68]) by hpaq12.eem.corp.google.com with ESMTP id oAJ3v3sp020187 for ; Thu, 18 Nov 2010 19:57:13 -0800 Received: by yxj4 with SMTP id 4so2467822yxj.39 for ; Thu, 18 Nov 2010 19:57:12 -0800 (PST) Received: by 10.151.78.12 with SMTP id f12mr2694307ybl.148.1290139032475; Thu, 18 Nov 2010 19:57:12 -0800 (PST) Received: from coign.google.com ([216.239.45.130]) by mx.google.com with ESMTPS id 55sm755631yhl.32.2010.11.18.19.57.09 (version=TLSv1/SSLv3 cipher=RC4-MD5); Thu, 18 Nov 2010 19:57:11 -0800 (PST) From: Ian Lance Taylor To: gcc-patches@gcc.gnu.org, gofrontend-dev@googlegroups.com Subject: [gccgo] Add documentation Date: Thu, 18 Nov 2010 19:57:07 -0800 Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/23.1 (gnu/linux) MIME-Version: 1.0 X-System-Of-Record: true X-IsSubscribed: yes Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Archive: List-Post: List-Help: Sender: gcc-patches-owner@gcc.gnu.org Delivered-To: mailing list gcc-patches@gcc.gnu.org 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. Ian Index: go/Make-lang.in =================================================================== --- go/Make-lang.in (revision 166883) +++ go/Make-lang.in (working copy) @@ -65,23 +65,58 @@ go1$(exeext): $(GO_OBJS) attribs.o $(BAC $(CXX) $(STATIC_LIBSTDCXX) $(ALL_CXXFLAGS) $(LDFLAGS) -o $@ \ $(GO_OBJS) attribs.o $(BACKEND) $(LIBS) $(BACKENDLIBS) +# Documentation. + +GO_TEXI_FILES = \ + go/gccgo.texi \ + $(gcc_docdir)/include/fdl.texi \ + $(gcc_docdir)/include/gpl_v3.texi \ + $(gcc_docdir)/include/gcc-common.texi \ + gcc-vers.texi + +doc/gccgo.info: $(GO_TEXI_FILES) + if test "x$(BUILD_INFO)" = xinfo; then \ + rm -f doc/gccgo.info*; \ + $(MAKEINFO) $(MAKEINFOFLAGS) -I $(gcc_docdir) \ + -I $(gcc_docdir)/include -o $@ $<; \ + else true; fi + +doc/gccgo.dvi: $(GO_TEXI_FILES) + $(TEXI2DVI) -I $(abs_docdir) -I $(abs_docdir)/include -o $@ $< + +doc/gccgo.pdf: $(GO_TEXI_FILES) + $(TEXI2PDF) -I $(abs_docdir) -I $(abs_docdir)/include -o $@ $< + +$(build_htmldir)/go/index.html: $(GO_TEXI_FILES) + $(mkinstalldirs) $(@D) + rm -f $(@D)/* + $(TEXI2HTML) -I $(gcc_docdir) -I $(gcc_docdir)/include \ + -I $(srcdir)/go -o $(@D) $< + +.INTERMEDIATE: gccgo.pod + +gccgo.pod: go/gccgo.texi + -$(TEXI2POD) -D gccgo < $< > $@ + # Build hooks. go.all.cross: gccgo$(exeext) go.start.encap: gccgo$(exeext) go.rest.encap: -go.info: -go.install-info: -go.dvi: -go.pdf: -go.install-pdf: -go.html: -go.install-html: -go.srcinfo: +go.info: doc/gccgo.info +go.dvi: doc/gccgo.dvi +go.pdf: doc/gccgo.pdf +go.html: $(build_htmldir)/go/index.html +go.srcinfo: doc/gccgo.info + -cp -p $^ $(srcdir)/doc go.srcextra: -go.tags: -go.man: -go.srcman: +go.tags: force + cd $(srcdir)/go; \ + etags -o TAGS.sub *.c *.h gofrontend/*.h gofrontend/*.cc; \ + etags --include TAGS.sub --include ../TAGS.sub +go.man: doc/gccgo.1 +go.srcman: doc/gccgo.1 + -cp -p $^ $(srcdir)/doc check-go: lang_checks += check-go @@ -100,10 +135,48 @@ go.install-common: installdirs fi go.install-plugin: -go.install-man: + +go.install-info: $(DESTDIR)$(infodir)/gccgo.info + +go.install-pdf: doc/gccgo.pdf + @$(NORMAL_INSTALL) + test -z "$(pdfdir)" || $(mkinstalldirs) "$(DESTDIR)$(pdfdir)/gcc" + @for p in doc/gccgo.pdf; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + f=$(pdf__strip_dir) \ + echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(pdfdir)/gcc/$$f'"; \ + $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(pdfdir)/gcc/$$f"; \ + done + +go.install-html: $(build_htmldir)/go + @$(NORMAL_INSTALL) + test -z "$(htmldir)" || $(mkinstalldirs) "$(DESTDIR)$(htmldir)" + @for p in $(build_htmldir)/go; do \ + if test -f "$$p" || test -d "$$p"; then d=""; else d="$(srcdir)/"; fi; \ + f=$(html__strip_dir) \ + if test -d "$$d$$p"; then \ + echo " $(mkinstalldirs) '$(DESTDIR)$(htmldir)/$$f'"; \ + $(mkinstalldirs) "$(DESTDIR)$(htmldir)/$$f" || exit 1; \ + echo " $(INSTALL_DATA) '$$d$$p'/* '$(DESTDIR)$(htmldir)/$$f'"; \ + $(INSTALL_DATA) "$$d$$p"/* "$(DESTDIR)$(htmldir)/$$f"; \ + else \ + echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(htmldir)/$$f'"; \ + $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(htmldir)/$$f"; \ + fi; \ + done + +go.install-man: $(DESTDIR)$(man1dir)/$(GCCGO_INSTALL_NAME)$(man1ext) + +$(DESTDIR)$(man1dir)/$(GCCGO_INSTALL_NAME)$(man1ext): doc/gccgo.1 installdirs + -rm -f $@ + -$(INSTALL_DATA) $< $@ + -chmod a-x $@ go.uninstall: - -rm -rf $(DESTDIR)/$(bindir)/$(GCCGO_INSTALL_NAME)$(exeext) + rm -rf $(DESTDIR)$(bindir)/$(GCCGO_INSTALL_NAME)$(exeext) + rm -rf $(DESTDIR)$(man1dir)/$(GCCGO_INSTALL_NAME)$(man1ext) + rm -rf $(DESTDIR)$(bindir)/$(GCCGO_TARGET_INSTALL_NAME)$(exeext) + rm -rf $(DESTDIR)$(infodir)/gccgo.info* # Clean hooks. @@ -113,6 +186,7 @@ go.mostlyclean: go.clean: go.distclean: go.maintainer-clean: + -rm -f $(docobjdir)/gccgo.1 # Stage hooks. Index: go/lang.opt =================================================================== --- go/lang.opt (revision 166883) +++ go/lang.opt (working copy) @@ -27,11 +27,11 @@ Go I Go Joined Separate --I Add a directory for import searching +; Documented in c.opt L Go Joined Separate --L Add a directory for import searching +; Not documented Wall Go Index: go/gccgo.texi =================================================================== --- go/gccgo.texi (revision 0) +++ go/gccgo.texi (revision 0) @@ -0,0 +1,348 @@ +\input texinfo @c -*-texinfo-*- +@setfilename gccgo.info +@settitle The GNU Go Compiler + +@c Merge the standard indexes into a single one. +@syncodeindex fn cp +@syncodeindex vr cp +@syncodeindex ky cp +@syncodeindex pg cp +@syncodeindex tp cp + +@include gcc-common.texi + +@c Copyright years for this manual. +@set copyrights-go 2010 + +@copying +@c man begin COPYRIGHT +Copyright @copyright{} @value{copyrights-go} Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, the Front-Cover Texts being (a) (see below), and +with the Back-Cover Texts being (b) (see below). +A copy of the license is included in the +@c man end +section entitled ``GNU Free Documentation License''. +@ignore +@c man begin COPYRIGHT +man page gfdl(7). +@c man end +@end ignore + +@c man begin COPYRIGHT + +(a) The FSF's Front-Cover Text is: + + A GNU Manual + +(b) The FSF's Back-Cover Text is: + + You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. +@c man end +@end copying + +@ifinfo +@format +@dircategory Software development +@direntry +* Gccgo: (gccgo). A GCC-based compiler for the Go language +@end direntry +@end format + +@insertcopying +@end ifinfo + +@titlepage +@title The GNU Go Compiler +@versionsubtitle +@author Ian Lance Taylor + +@page +@vskip 0pt plus 1filll +Published by the Free Software Foundation @* +51 Franklin Street, Fifth Floor@* +Boston, MA 02110-1301, USA@* +@sp 1 +@insertcopying +@end titlepage +@contents +@page + +@node Top +@top Introduction + +This manual describes how to use @command{gccgo}, the GNU compiler for +the Go programming language. This manual is specifically about +@command{gccgo}. For more information about the Go programming +language in general, including language specifications and standard +package documentation, see @uref{http://golang.org/}. + +@menu +* Copying:: The GNU General Public License. +* GNU Free Documentation License:: + How you can share and copy this manual. +* Invoking gccgo:: How to run gccgo. +* Import and Export:: Importing and exporting package data. +* C Interoperability:: Calling C from Go and vice-vera. +* Index:: Index. +@end menu + + +@include gpl_v3.texi + +@include fdl.texi + + +@node Invoking gccgo +@chapter Invoking gccgo + +@c man title gccgo A GCC-based compiler for the Go language + +@ignore +@c man begin SYNOPSIS gccgo +gccgo [@option{-c}|@option{-S}] + [@option{-g}] [@option{-pg}] [@option{-O}@var{level}] + [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}] + [@option{-o} @var{outfile}] @var{infile}@dots{} + +Only the most useful options are listed here; see below for the +remainder. +@c man end +@c man begin SEEALSO +gpl(7), gfdl(7), fsf-funding(7), gcc(1) +and the Info entries for @file{gccgo} and @file{gcc}. +@c man end +@end ignore + +@c man begin DESCRIPTION gccgo + +The @command{gccgo} command is a frontend to @command{gcc} and +supports many of the same options. @xref{Option Summary, , Option +Summary, gcc, Using the GNU Compiler Collection (GCC)}. This manual +only documents the options specific to @command{gccgo}. + +The @command{gccgo} command may be used to compile Go source code into +an object file, link a collection of object files together, or do both +in sequence. + +Go source code is compiled as packages. A package consists of one or +more Go source files. All the files in a single package must be +compiled together, by passing all the files as arguments to +@command{gccgo}. A single invocation of @command{gccgo} may only +compile a single package. + +One Go package may @code{import} a different Go package. The imported +package must have already been compiled; @command{gccgo} will read +the import data directly from the compiled package. When this package +is later linked, the compiled form of the package must be included in +the link command. + +@c man end + +@c man begin OPTIONS gccgo + +@table @gcctabopt +@item -I@var{dir} +@cindex @option{-I} +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}. When linking, specify a +library search directory, as with @command{gcc}. + +@item -fgo-prefix=@var{string} +@cindex @option{-fgo-prefix} +Go permits a single program to include more than one package with the +same name. This option is required to make this work with +@command{gccgo}. The argument to this option may be any string. Each +package with the same name must use a distinct @option{-fgo-prefix} +option. The argument is typically the full path under which the +package will be installed, as that must obviously be unique. + +@item -frequire-return-statement +@itemx -fno-require-return-statement +@cindex @option{-frequire-return-statement} +@cindex @option{-fno-require-return-statement} +By default @command{gccgo} will warn about functions which have one or +more return parameters but lack an explicit @code{return} statement. +This warning may be disabled using +@option{-fno-require-return-statement}. +@end table + +@c man end + +@node Import and Export +@chapter Import and Export + +When @command{gccgo} compiles a package which exports anything, the +export information will be stored directly in the object file. When a +package is imported, @command{gccgo} must be able to find the file. + +@cindex @file{.gox} +When Go code imports the package @file{gopackage}, @command{gccgo} +will look for the import data using the following filenames, using the +first one that it finds. + +@table @file +@item @var{gopackage}.gox +@item lib@var{gopackage}.so +@item lib@var{gopackage}.a +@item @var{gopackage}.o +@end table + +The compiler will search for these files in the directories named by +any @option{-I} or @option{-L} options, in order in which the +directories appear on the command line. The compiler will then search +several standard system directories. Finally the compiler will search +the current directory (to search the current directory earlier, use +@samp{-I.}). + +The compiler will extract the export information directly from the +compiled object file. The file @file{@var{gopackage}.gox} will +typically contain nothing but export data. This can be generated from +@file{@var{gopackage}.o} via + +@smallexample +objcopy -j .go_export @var{gopackage}.o @var{gopackage}.gox +@end smallexample + +For example, it may be desirable to extract the export information +from several different packages into their independent +@file{@var{gopackage}.gox} files, and then to combine the different +package object files together into a single shared library or archive. + +At link time you must explicitly tell @command{gccgo} which files to +link together into the executable, as is usual with @command{gcc}. +This is different from the behaviour of other Go compilers. + +@node C Interoperability +@chapter C Interoperability + +When using @command{gccgo} there is limited interoperability with C, +or with C++ code compiled using @code{extern "C"}. + +@menu +* C Type Interoperability:: How C and Go types match up. +* Function Names:: How Go functions are named. +@end menu + +@node C Type Interoperability +@section C Type Interoperability + +Basic types map directly: an @code{int} in Go is an @code{int} in C, +etc. Go @code{byte} is equivalent to C @code{unsigned char}. +Pointers in Go are pointers in C. A Go @code{struct} is the same as C +@code{struct} with the same field names and types. + +@cindex @code{string} in C +The Go @code{string} type is currently defined as a two-element +structure: + +@smallexample +struct __go_string @{ + const unsigned char *__data; + int __length; +@}; +@end smallexample + +You can't pass arrays between C and Go. However, a pointer to an +array in Go is equivalent to a C pointer to the equivalent of the +element type. For example, Go @code{*[10]int} is equivalent to C +@code{int*}, assuming that the C pointer does point to 10 elements. + +@cindex @code{slice} in C +A slice in Go is a structure. The current definition is: + +@smallexample +struct __go_slice @{ + void *__values; + int __count; + int __capacity; +@}; +@end smallexample + +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 + +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. + +@node Function Names +@section Function Names + +@cindex @code{__asm__} +Go code can call C functions directly using a Go extension implemented +in @command{gccgo}: a function declaration may be followed by +@code{__asm__ ("@var{name}")}. For example, here is how the C function +@code{open} can be declared in Go: + +@smallexample +func c_open(name *byte, mode int, perm int) int __asm__ ("open"); +@end smallexample + +The C function naturally expects a nul terminated string, which in Go +is equivalent to a pointer to an array (not a slice!) of @code{byte} +with a terminating zero byte. So a sample call from Go would look +like (after importing the @code{os} package): + +@smallexample +var name = [4]byte@{'f', 'o', 'o', 0@}; +i := c_open(&name[0], os.O_RDONLY, 0); +@end smallexample + +Note that this serves as an example only. To open a file in Go please +use Go's @code{os.Open} function instead. + +The name of Go functions accessed from C is subject to change. At +present the name of a Go function that does not have a receiver is +@code{prefix.package.Functionname}. The prefix is set by the +@option{-fgo-prefix} option used when the package is compiled; if the +option is not used, the default is simply @code{go}. To call the +function from C you must set the name using the @command{gcc} +extension similar to the @command{gccgo} extension. + +@smallexample +extern int go_function(int) __asm__ ("myprefix.mypackage.Function"); +@end smallexample + +@node Index +@unnumbered Index + +@printindex cp + +@bye Index: doc/sourcebuild.texi =================================================================== --- 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}. + @item libgomp The GNU OpenMP runtime library. Index: doc/standards.texi =================================================================== --- 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}. 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. + +@section References for other languages + @xref{Top, GNAT Reference Manual, About This Guide, gnat_rm, GNAT Reference Manual}, for information on standard conformance and compatibility of the Ada compiler. Index: doc/invoke.texi =================================================================== --- doc/invoke.texi (revision 166832) +++ doc/invoke.texi (working copy) @@ -1070,6 +1070,9 @@ Free form Fortran source code which shou Free form Fortran source code which must be preprocessed (with the traditional preprocessor). +@item @var{file}.go +Go source code. + @c FIXME: Descriptions of Java file types. @c @var{file}.java @c @var{file}.class @@ -1123,6 +1126,7 @@ objective-c++ objective-c++-header objec assembler assembler-with-cpp ada f77 f77-cpp-input f95 f95-cpp-input +go java @end smallexample Index: doc/contrib.texi =================================================================== --- doc/contrib.texi (revision 166832) +++ doc/contrib.texi (working copy) @@ -900,8 +900,8 @@ Jeff Sturm for Java porting help, bug fi Shigeya Suzuki for this fixes for the bsdi platforms. @item -Ian Lance Taylor for his mips16 work, general configury hacking, -fixincludes, etc. +Ian Lance Taylor for the Go frontend, the initial mips16 and mips64 +support, general configury hacking, fixincludes, etc. @item Holger Teutsch provided the support for the Clipper CPU@. Index: doc/frontends.texi =================================================================== --- doc/frontends.texi (revision 166832) +++ doc/frontends.texi (working copy) @@ -11,13 +11,14 @@ @cindex GNU C Compiler @cindex Ada @cindex Fortran +@cindex Go @cindex Java @cindex Objective-C @cindex Objective-C++ GCC stands for ``GNU Compiler Collection''. GCC is an integrated distribution of compilers for several major programming languages. These languages currently include C, C++, Objective-C, Objective-C++, Java, -Fortran, and Ada. +Fortran, Ada, and Go. The abbreviation @dfn{GCC} has multiple meanings in common use. The current official meaning is ``GNU Compiler Collection'', which refers Index: doc/install.texi =================================================================== --- doc/install.texi (revision 166832) +++ doc/install.texi (working copy) @@ -884,7 +884,7 @@ only for the listed packages. For other will be built. Package names currently recognized in the GCC tree are @samp{libgcc} (also known as @samp{gcc}), @samp{libstdc++} (not @samp{libstdc++-v3}), @samp{libffi}, @samp{zlib}, @samp{boehm-gc}, -@samp{ada}, @samp{libada}, @samp{libjava} and @samp{libobjc}. +@samp{ada}, @samp{libada}, @samp{libjava}, @samp{libgo}, and @samp{libobjc}. Note @samp{libiberty} does not support shared libraries at all. Use @option{--disable-shared} to build only static libraries. Note that @@ -1305,15 +1305,12 @@ their runtime libraries should be built. grep language= */config-lang.in @end smallexample Currently, you can use any of the following: -@code{all}, @code{ada}, @code{c}, @code{c++}, @code{fortran}, @code{java}, -@code{objc}, @code{obj-c++}. +@code{all}, @code{ada}, @code{c}, @code{c++}, @code{fortran}, +@code{go}, @code{java}, @code{objc}, @code{obj-c++}. Building the Ada compiler has special requirements, see below. If you do not pass this flag, or specify the option @code{all}, then all default languages available in the @file{gcc} sub-tree will be configured. -Ada and Objective-C++ are not default languages; the rest are. -Re-defining @code{LANGUAGES} when calling @samp{make} @strong{does not} -work anymore, as those language sub-directories might not have been -configured! +Ada, Go and Objective-C++ are not default languages; the rest are. @item --enable-stage1-languages=@var{lang1},@var{lang2},@dots{} Specify that a particular subset of compilers and their runtime