From 191dbc35688262c9c2bb1d623950a197eff80b80 Mon Sep 17 00:00:00 2001 From: Martin Liska Date: Sun, 13 Nov 2022 22:03:35 +0100 Subject: Revert "sphinx: copy files from texi2rst-generated repository" This reverts commit c63539ffe4c0e327337a1a51f638d9c8c958cb26. --- gcc/go/doc/c-interoperability.rst | 23 --- gcc/go/doc/c-type-interoperability.rst | 77 --------- gcc/go/doc/compiler-directives.rst | 47 ------ gcc/go/doc/conf.py | 30 ---- gcc/go/doc/copyright.rst | 24 --- gcc/go/doc/function-names.rst | 61 -------- gcc/go/doc/general-public-license-3.rst | 6 - gcc/go/doc/gnu-free-documentation-license.rst | 6 - gcc/go/doc/import-and-export.rst | 50 ------ gcc/go/doc/index.rst | 23 --- gcc/go/doc/indices-and-tables.rst | 1 - gcc/go/doc/introduction.rst | 8 - gcc/go/doc/invoking-gccgo.rst | 214 -------------------------- 13 files changed, 570 deletions(-) delete mode 100644 gcc/go/doc/c-interoperability.rst delete mode 100644 gcc/go/doc/c-type-interoperability.rst delete mode 100644 gcc/go/doc/compiler-directives.rst delete mode 100644 gcc/go/doc/conf.py delete mode 100644 gcc/go/doc/copyright.rst delete mode 100644 gcc/go/doc/function-names.rst delete mode 100644 gcc/go/doc/general-public-license-3.rst delete mode 100644 gcc/go/doc/gnu-free-documentation-license.rst delete mode 100644 gcc/go/doc/import-and-export.rst delete mode 100644 gcc/go/doc/index.rst delete mode 100644 gcc/go/doc/indices-and-tables.rst delete mode 100644 gcc/go/doc/introduction.rst delete mode 100644 gcc/go/doc/invoking-gccgo.rst (limited to 'gcc/go') diff --git a/gcc/go/doc/c-interoperability.rst b/gcc/go/doc/c-interoperability.rst deleted file mode 100644 index 8eaaf00..0000000 --- a/gcc/go/doc/c-interoperability.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. - Copyright 1988-2022 Free Software Foundation, Inc. - This is part of the GCC manual. - For copying conditions, see the copyright.rst file. - -.. _c-interoperability: - -C Interoperability ------------------- - -When using :command:`gccgo` there is limited interoperability with C, -or with C++ code compiled using ``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 ``import "C"``, as described at -https://golang.org/cmd/cgo. - -.. toctree:: - :maxdepth: 2 - - c-type-interoperability - function-names \ No newline at end of file diff --git a/gcc/go/doc/c-type-interoperability.rst b/gcc/go/doc/c-type-interoperability.rst deleted file mode 100644 index fb2acc9..0000000 --- a/gcc/go/doc/c-type-interoperability.rst +++ /dev/null @@ -1,77 +0,0 @@ -.. - Copyright 1988-2022 Free Software Foundation, Inc. - This is part of the GCC manual. - For copying conditions, see the copyright.rst file. - -.. _c-type-interoperability: - -C Type Interoperability -*********************** - -Basic types map directly: an ``int`` in Go is an ``int`` in C, -etc. Go ``byte`` is equivalent to C ``unsigned char``. -Pointers in Go are pointers in C. A Go ``struct`` is the same as C -``struct`` with the same field names and types. - -.. index:: string in C - -The Go ``string`` type is currently defined as a two-element -structure: - -.. code-block:: c++ - - struct __go_string { - const unsigned char *__data; - int __length; - }; - -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 ``*[10]int`` is equivalent to C -``int*``, assuming that the C pointer does point to 10 elements. - -.. index:: slice in C - -A slice in Go is a structure. The current definition is: - -.. code-block:: c++ - - struct __go_slice { - void *__values; - int __count; - int __capacity; - }; - -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: - -.. code-block:: c++ - - func GoFunction(int) (int, float) - struct { int i; float f; } CFunction(int) - -A pointer to a Go function is equivalent to a pointer to a C function -when the functions have equivalent types. - -Go ``interface``, ``channel``, and ``map`` types have no -corresponding C type (``interface`` is a two-element struct and -``channel`` and ``map`` are pointers to structs in C, but the -structs are deliberately undocumented). C ``enum`` types -correspond to some integer type, but precisely which one is difficult -to predict in general; use a cast. C ``union`` types have no -corresponding Go type. C ``struct`` types containing bitfields -have no corresponding Go type. C++ ``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. \ No newline at end of file diff --git a/gcc/go/doc/compiler-directives.rst b/gcc/go/doc/compiler-directives.rst deleted file mode 100644 index 1567d64..0000000 --- a/gcc/go/doc/compiler-directives.rst +++ /dev/null @@ -1,47 +0,0 @@ -.. - Copyright 1988-2022 Free Software Foundation, Inc. - This is part of the GCC manual. - For copying conditions, see the copyright.rst file. - -.. _compiler-directives: - -Compiler Directives -------------------- - -The Go compiler supports a few compiler directives. A compiler -directive uses a ``//`` comment at the start of a line. There must -be no space between the ``//`` and the name of the directive. - -:samp:`//line {file}:{line}` - The ``//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. - -:samp:`//extern {extern_name}` - The ``extern`` directive sets the externally visible name of the - next function declaration. See :ref:`function-names`. - -:samp:`//go:compile {go_name}{extern_name}` - The ``go:compile`` directives sets the externally visible name of a - function definition or declaration. See :ref:`function-names`. - -``//go:noescape`` - The ``//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. - -``//go:nosplit`` - The ``//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. - -``//go:noinline`` - The ``//go:noinline`` directive specifies that the next function - defined in the file may not be inlined. \ No newline at end of file diff --git a/gcc/go/doc/conf.py b/gcc/go/doc/conf.py deleted file mode 100644 index 9157fba..0000000 --- a/gcc/go/doc/conf.py +++ /dev/null @@ -1,30 +0,0 @@ -# Configuration file for the Sphinx documentation builder. - -import sys -sys.path.append('../../..//doc') - -from baseconf import * - -name = 'gccgo' -project = 'The GNU Go Compiler' -copyright = '2010-2022 Free Software Foundation, Inc.' -authors = 'Ian Lance Taylor' - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -latex_documents = [ - ('index', f'{name}.tex', project, authors, 'manual'), -] - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - ('invoking-gccgo', name, 'A GCC-based compiler for the Go language', [authors], 1), -] - -texinfo_documents = [ - ('index', name, project, authors, None, None, None, True) -] - -set_common(name, globals()) \ No newline at end of file diff --git a/gcc/go/doc/copyright.rst b/gcc/go/doc/copyright.rst deleted file mode 100644 index fa61190..0000000 --- a/gcc/go/doc/copyright.rst +++ /dev/null @@ -1,24 +0,0 @@ -.. - Copyright 1988-2022 Free Software Foundation, Inc. - This is part of the GCC manual. - For copying conditions, see the GPL license file - -Copyright -^^^^^^^^^ - -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 :ref:`gnu_fdl`. - -(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. \ No newline at end of file diff --git a/gcc/go/doc/function-names.rst b/gcc/go/doc/function-names.rst deleted file mode 100644 index 1ed5760..0000000 --- a/gcc/go/doc/function-names.rst +++ /dev/null @@ -1,61 +0,0 @@ -.. - Copyright 1988-2022 Free Software Foundation, Inc. - This is part of the GCC manual. - For copying conditions, see the copyright.rst file. - -.. index:: extern, external names - -.. _function-names: - -Function Names -************** - -Go code can call C functions directly using the ``//extern`` or -``//go:linkname`` compiler directives. An ``//extern`` -directive must be at the beginning of the line and must start with -``//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 ``open`` can be declared in Go: - -.. code-block:: c++ - - //extern open - func c_open(name *byte, mode int, perm int) int - -You can do the same thing using the ``//go:linkname`` compiler -directive. The ``//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 -``//extern``, ``//go:linkname`` does not need to appear -immediately adjacent to the function definition or declaration. - -.. code-block:: c++ - - //go:linkname c_open open - func c_open(name *byte, mode int, perm int) int - -The C function naturally expects a nul terminated string, which in Go -is equivalent to a pointer to an array (not a slice!) of ``byte`` -with a terminating zero byte. So a sample call from Go would look -like (after importing the ``os`` package): - -.. code-block:: c++ - - var name = [4]byte{'f', 'o', 'o', 0}; - i := c_open(&name[0], os.O_RDONLY, 0); - -Note that this serves as an example only. To open a file in Go please -use Go's ``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 -``pkgpath.Functionname``. The :samp:`{pkgpath}` is set by the -:option:`-fgo-pkgpath` option used when the package is compiled; if the -option is not used, the default is ``go.packagename``. To -call the function from C you must set the name using the :command:`gcc` -``__asm__`` extension. - -.. code-block:: c++ - - extern int go_function(int) __asm__ ("mypkgpath.Function"); \ No newline at end of file diff --git a/gcc/go/doc/general-public-license-3.rst b/gcc/go/doc/general-public-license-3.rst deleted file mode 100644 index becda77..0000000 --- a/gcc/go/doc/general-public-license-3.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. - Copyright 1988-2022 Free Software Foundation, Inc. - This is part of the GCC manual. - For copying conditions, see the copyright.rst file. - -.. include:: ../../../doc/gpl-3.0.rst \ No newline at end of file diff --git a/gcc/go/doc/gnu-free-documentation-license.rst b/gcc/go/doc/gnu-free-documentation-license.rst deleted file mode 100644 index 1de809b..0000000 --- a/gcc/go/doc/gnu-free-documentation-license.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. - Copyright 1988-2022 Free Software Foundation, Inc. - This is part of the GCC manual. - For copying conditions, see the copyright.rst file. - -.. include:: ../../../doc/gnu_free_documentation_license.rst \ No newline at end of file diff --git a/gcc/go/doc/import-and-export.rst b/gcc/go/doc/import-and-export.rst deleted file mode 100644 index 285fb5f..0000000 --- a/gcc/go/doc/import-and-export.rst +++ /dev/null @@ -1,50 +0,0 @@ -.. - Copyright 1988-2022 Free Software Foundation, Inc. - This is part of the GCC manual. - For copying conditions, see the copyright.rst file. - -.. _import-and-export: - -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. - -.. index:: .gox - -When Go code imports the package :samp:`{gopackage}`, :command:`gccgo` -will look for the import data using the following filenames, using the -first one that it finds. - -.. code-block:: - - gopackage.gox - libgopackage.so - libgopackage.a - gopackage.o - -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 :samp:`{gopackage}.gox` will -typically contain nothing but export data. This can be generated from -:samp:`{gopackage}.o` via - -.. code-block:: c++ - - objcopy -j .go_export gopackage.o gopackage.gox - -For example, it may be desirable to extract the export information -from several different packages into their independent -:samp:`{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. \ No newline at end of file diff --git a/gcc/go/doc/index.rst b/gcc/go/doc/index.rst deleted file mode 100644 index 76951a4..0000000 --- a/gcc/go/doc/index.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. - Copyright 1988-2022 Free Software Foundation, Inc. - This is part of the GCC manual. - For copying conditions, see the copyright.rst file. - -The GNU Go Compiler -=================== - -.. only:: html - - Contents: - -.. toctree:: - - copyright - introduction - invoking-gccgo - import-and-export - compiler-directives - c-interoperability - general-public-license-3 - gnu-free-documentation-license - indices-and-tables \ No newline at end of file diff --git a/gcc/go/doc/indices-and-tables.rst b/gcc/go/doc/indices-and-tables.rst deleted file mode 100644 index 6c215a3..0000000 --- a/gcc/go/doc/indices-and-tables.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../../doc/indices-and-tables.rst \ No newline at end of file diff --git a/gcc/go/doc/introduction.rst b/gcc/go/doc/introduction.rst deleted file mode 100644 index c38ff7d..0000000 --- a/gcc/go/doc/introduction.rst +++ /dev/null @@ -1,8 +0,0 @@ -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 http://golang.org/. \ No newline at end of file diff --git a/gcc/go/doc/invoking-gccgo.rst b/gcc/go/doc/invoking-gccgo.rst deleted file mode 100644 index ccca40e..0000000 --- a/gcc/go/doc/invoking-gccgo.rst +++ /dev/null @@ -1,214 +0,0 @@ -.. - Copyright 1988-2022 Free Software Foundation, Inc. - This is part of the GCC manual. - For copying conditions, see the copyright.rst file. - -.. _invoking-gccgo: - -Invoking gccgo --------------- - -.. only:: man - - Synopsis - ^^^^^^^^ - - gccgo [ :option:`-c` | :option:`-S` ] - [ :option:`-g` ] [ :option:`-pg` ] [ :option:`-O`:samp:`{level}` ] - [ :option:`-I dir...` ] [ :option:`-L dir...` ] - [ :option:`-o` :samp:`{outfile}` ] :samp:`{infile}`... - -Description -^^^^^^^^^^^ - -Only the most useful options are listed here; see below for the -remainder. - -The :command:`gccgo` command is a frontend to :command:`gcc` and -supports many of the same options. See :ref:`gcc:option-summary`. 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 ``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. - -Options -^^^^^^^ - -.. option:: -Idir - - .. index:: -I - - Specify a directory to use when searching for an import package at - compile time. - -.. option:: -Ldir - - .. index:: -L - - When linking, specify a library search directory, as with - :command:`gcc`. - -.. option:: -fgo-pkgpath=string - - .. index:: -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. - -.. option:: -fgo-prefix=string - - .. index:: -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 ``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 ``main`` package and permits that - package to be imported like any other. - -.. option:: -fgo-relative-import-path=dir - - .. index:: -fgo-relative-import-path - - A relative import is an import that starts with :samp:`./` or - :samp:`../`. If this option is used, :command:`gccgo` will use - :samp:`{dir}` as a prefix for the relative import when searching for it. - -.. option:: -frequire-return-statement -.. option:: -fno-require-return-statement - - .. index:: -frequire-return-statement, -fno-require-return-statement - - By default :command:`gccgo` will warn about functions which have one or - more return parameters but lack an explicit ``return`` statement. - This warning may be disabled using - :option:`-fno-require-return-statement`. - -.. option:: -fgo-check-divide-zero - - .. index:: -fgo-check-divide-zero, -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 ``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. - -.. option:: -fgo-check-divide-overflow - - .. index:: -fgo-check-divide-overflow, -fno-go-check-divide-overflow - - Add explicit checks for division overflow. For example, division - overflow occurs when computing ``INT_MIN / -1``. In Go this should - be wrapped, to produce ``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. - -.. option:: -fno-go-optimize-allocs - - .. index:: -fno-go-optimize-allocs - - Disable escape analysis, which tries to allocate objects on the stack - rather than the heap. - -.. option:: -fgo-debug-escapen - - .. index:: -fgo-debug-escape - - Output escape analysis debugging information. Larger values of - :samp:`{n}` generate more information. - -.. option:: -fgo-debug-escape-hash=n - - .. index:: -fgo-debug-escape-hash - - A hash value to debug escape analysis. :samp:`{n}` is a binary string. - This runs escape analysis only on functions whose names hash to values - that match the given suffix :samp:`{n}`. This can be used to binary - search across functions to uncover escape analysis bugs. - -.. option:: -fgo-debug-optimization - - .. index:: -fgo-debug-optimization, -fno-go-debug-optimization - - Output optimization diagnostics. - -.. option:: -fgo-c-header=file - - .. index:: -fgo-c-header - - Write top-level named Go struct definitions to :samp:`{file}` as C code. - This is used when compiling the runtime package. - -.. option:: -fgo-compiling-runtime - - .. index:: -fgo-compiling-runtime - - Apply special rules for compiling the runtime package. Implicit - memory allocation is forbidden. Some additional compiler directives - are supported. - -.. option:: -fgo-embedcfg=file - - .. index:: -fgo-embedcfg - - Identify a JSON file used to map patterns used with special - ``//go:embed`` comments to the files named by the patterns. The - JSON file should have two components: ``Patterns`` maps each - pattern to a list of file names, and ``Files`` maps each file name - to a full path to the file. This option is intended for use by the - :command:`go` command to implement ``//go:embed``. - -.. option:: -g - - .. index:: -g for gccgo - - This is the standard :command:`gcc` option (see :ref:`gcc:debugging-options`). 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 ``runtime.Callers``, will not operate correctly. - -.. only:: man - - .. include:: copyright.rst \ No newline at end of file -- cgit v1.1