CbC/CbC_gcc: gcc/go/gccgo.texi comparison

comparison gcc/go/gccgo.texi @ 111:04ced10e8804

gcc 7

author	kono
date	Fri, 27 Oct 2017 22:46:09 +0900
parents
children	84e7813d76e9

comparison

equal deleted inserted replaced

-:561a7518be6b
+:04ced10e8804
+\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-2017
+@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.
+* Compiler Directives::         Comments to control compilation.
+* C Interoperability::          Calling C from Go and vice-versa.
+* 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.
+Go programs must generally be compiled with debugging information, and
+@option{-g1} is the default as described below.  Stripping a Go
+program will generally cause it to misbehave or fail.
+@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 linking, specify a library search directory, as with
+@command{gcc}.
+@item -fgo-pkgpath=@var{string}
+@cindex @option{-fgo-pkgpath}
+Set the package path to use.  This sets the value returned by the
+PkgPath method of reflect.Type objects.  It is also used for the names
+of globally visible symbols.  The argument to this option should
+normally be the string that will be used to import this package after
+it has been installed; in other words, a pathname within the
+directories specified by the @option{-I} option.
+@item -fgo-prefix=@var{string}
+@cindex @option{-fgo-prefix}
+An alternative to @option{-fgo-pkgpath}.  The argument will be
+combined with the package name from the source file to produce the
+package path.  If @option{-fgo-pkgpath} is used, @option{-fgo-prefix}
+will be ignored.
+Go permits a single program to include more than one package with the
+same name in the @code{package} clause in the source file, though
+obviously the two packages must be imported using different pathnames.
+In order for this to work with @command{gccgo}, either
+@option{-fgo-pkgpath} or @option{-fgo-prefix} must be specified when
+compiling a package.
+Using either @option{-fgo-pkgpath} or @option{-fgo-prefix} disables
+the special treatment of the @code{main} package and permits that
+package to be imported like any other.
+@item -fgo-relative-import-path=@var{dir}
+@cindex @option{-fgo-relative-import-path}
+A relative import is an import that starts with @file{./} or
+@file{../}.  If this option is used, @command{gccgo} will use
+@var{dir} as a prefix for the relative import when searching for it.
+@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}.
+@item -fgo-check-divide-zero
+@cindex @option{-fgo-check-divide-zero}
+@cindex @option{-fno-go-check-divide-zero}
+Add explicit checks for division by zero.  In Go a division (or
+modulos) by zero causes a panic.  On Unix systems this is detected in
+the runtime by catching the @code{SIGFPE} signal.  Some processors,
+such as PowerPC, do not generate a SIGFPE on division by zero.  Some
+runtimes do not generate a signal that can be caught.  On those
+systems, this option may be used.  Or the checks may be removed via
+@option{-fno-go-check-divide-zero}.  This option is currently on by
+default, but in the future may be off by default on systems that do
+not require it.
+@item -fgo-check-divide-overflow
+@cindex @option{-fgo-check-divide-overflow}
+@cindex @option{-fno-go-check-divide-overflow}
+Add explicit checks for division overflow.  For example, division
+overflow occurs when computing @code{INT_MIN / -1}.  In Go this should
+be wrapped, to produce @code{INT_MIN}.  Some processors, such as x86,
+generate a trap on division overflow.  On those systems, this option
+may be used.  Or the checks may be removed via
+@option{-fno-go-check-divide-overflow}.  This option is currently on
+by default, but in the future may be off by default on systems that do
+not require it.
+@item -fgo-optimize-allocs
+@cindex @option{-fgo-optimize-allocs}
+Use escape analysis to allocate objects on the stack rather than the
+heap when possible.  In the future this may be the default.
+@item -fgo-debug-escape@var{n}
+@cindex @option{-fgo-debug-escape}
+Output escape analysis debugging information.  Larger values of
+@var{n} generate more information.
+@item -fgo-c-header=@var{file}
+@cindex @option{-fgo-c-header}
+Write top-level named Go struct definitions to @var{file} as C code.
+This is used when compiling the runtime package.
+@item -fgo-compiling-runtime
+@cindex @option{-fgo-compiling-runtime}
+Apply special rules for compiling the runtime package.  Implicit
+memory allocation is forbidden.  Some additional compiler directives
+are supported.
+@item -g
+@cindex @option{-g for gccgo}
+This is the standard @command{gcc} option (@pxref{Debugging Options, ,
+Debugging Options, gcc, Using the GNU Compiler Collection (GCC)}).  It
+is mentioned here because by default @command{gccgo} turns on
+debugging information generation with the equivalent of the standard
+option @option{-g1}.  This is because Go programs require debugging
+information to be available in order to get backtrace information.  An
+explicit @option{-g0} may be used to disable the generation of
+debugging information, in which case certain standard library
+functions, such as @code{runtime.Callers}, will not operate correctly.
+@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{@var{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} 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 behavior of other Go compilers.
+@node Compiler Directives
+@chapter Compiler Directives
+The Go compiler supports a few compiler directives.  A compiler
+directive uses a @code{//} comment at the start of a line.  There must
+be no space between the @code{//} and the name of the directive.
+@table @code
+@item //line @var{file}:@var{line}
+The @code{//line} directive specifies that the source line that
+follows should be recorded as having come from the given file path and
+line number.  Successive lines are recorded using increasing line
+numbers, until the next directive.  This directive typically appears
+in machine-generated code, so that compilers and debuggers will show
+lines in the original input to the generator.
+@item //extern @var{extern_name}
+The @code{extern} directive sets the externally visible name of the
+next function declaration.  See @ref{Function Names}.
+@item //go:compile @var{go_name} @var{extern_name}
+The @code{go:compile} directives sets the externally visible name of a
+function definition or declaration.  See @ref{Function Names}.
+@item //go:noescape
+The @code{//go:noescape} directive specifies that the next declaration
+in the file, which must be a func without a body (meaning that it has
+an implementation not written in Go) does not allow any of the
+pointers passed as arguments to escape into the heap or into the
+values returned from the function. This information can be used during
+the compiler's escape analysis of Go code calling the function.
+@item //go:nosplit
+The @code{//go:nosplit} directive specifies that the next function
+declared in the file must not include a stack overflow check. This is
+most commonly used by low-level runtime sources invoked at times when
+it is unsafe for the calling goroutine to be preempted.
+@item //go:noinline
+The @code{//go:noinline} directive specifies that the next function
+defined in the file may not be inlined.
+@end table
+@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"}.
+This information is provided largely for documentation purposes.  For
+ordinary use it is best to build programs with the go tool and then
+use @code{import "C"}, as described at
+@url{http://golang.org/cmd/cgo}.
+@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{extern}
+@cindex external names
+Go code can call C functions directly using the @code{//extern} or
+@code{//go:linkname} compiler directives.  An @code{//extern}
+directive must be at the beginning of the line and must start with
+@code{//extern}.  This must be followed by a space and then the
+external name of the function.  The function declaration must be on
+the line immediately after the comment.  For example, here is how the
+C function @code{open} can be declared in Go:
+@smallexample
+//extern open
+func c_open(name *byte, mode int, perm int) int
+@end smallexample
+You can do the same thing using the @code{//go:linkname} compiler
+directive.  The @code{//go:linkname} directive must be at the start of
+the line.  It is followed by whitespace, the name of the Go function,
+more whitespace, and the external name of the function.  Unlike
+@code{//extern}, @code{//go:linkname} does not need to appear
+immediately adjacent to the function definition or declaration.
+@smallexample
+//go:linkname c_open open
+func c_open(name *byte, mode int, perm int) int
+@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(&amp;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{pkgpath.Functionname}.  The @var{pkgpath} is set by the
+@option{-fgo-pkgpath} option used when the package is compiled; if the
+option is not used, the default is @code{go.@var{packagename}}.  To
+call the function from C you must set the name using the @command{gcc}
+@code{__asm__} extension.
+@smallexample
+extern int go_function(int) __asm__ ("mypkgpath.Function");
+@end smallexample
+@node Index
+@unnumbered Index
+@printindex cp
+@bye

Mercurial > hg > CbC > CbC_gcc

comparison gcc/go/gccgo.texi @ 111:04ced10e8804