2 Copyright 1988-2022 Free Software Foundation, Inc.
3 This is part of the GCC manual.
4 For copying conditions, see the copyright.rst file.
16 gccgo [ :option:`-c` | :option:`-S` ]
17 [ :option:`-g` ] [ :option:`-pg` ] [ :option:`-O`:samp:`{level}` ]
18 [ :option:`-I dir...` ] [ :option:`-L dir...` ]
19 [ :option:`-o` :samp:`{outfile}` ] :samp:`{infile}`...
24 Only the most useful options are listed here; see below for the
27 The :command:`gccgo` command is a frontend to :command:`gcc` and
28 supports many of the same options. See :ref:`gcc:option-summary`. This manual
29 only documents the options specific to :command:`gccgo`.
31 The :command:`gccgo` command may be used to compile Go source code into
32 an object file, link a collection of object files together, or do both
35 Go source code is compiled as packages. A package consists of one or
36 more Go source files. All the files in a single package must be
37 compiled together, by passing all the files as arguments to
38 :command:`gccgo`. A single invocation of :command:`gccgo` may only
39 compile a single package.
41 One Go package may ``import`` a different Go package. The imported
42 package must have already been compiled; :command:`gccgo` will read
43 the import data directly from the compiled package. When this package
44 is later linked, the compiled form of the package must be included in
47 Go programs must generally be compiled with debugging information, and
48 :option:`-g1` is the default as described below. Stripping a Go
49 program will generally cause it to misbehave or fail.
58 Specify a directory to use when searching for an import package at
65 When linking, specify a library search directory, as with
68 .. option:: -fgo-pkgpath=string
70 .. index:: -fgo-pkgpath
72 Set the package path to use. This sets the value returned by the
73 PkgPath method of reflect.Type objects. It is also used for the names
74 of globally visible symbols. The argument to this option should
75 normally be the string that will be used to import this package after
76 it has been installed; in other words, a pathname within the
77 directories specified by the :option:`-I` option.
79 .. option:: -fgo-prefix=string
81 .. index:: -fgo-prefix
83 An alternative to :option:`-fgo-pkgpath`. The argument will be
84 combined with the package name from the source file to produce the
85 package path. If :option:`-fgo-pkgpath` is used, :option:`-fgo-prefix`
88 Go permits a single program to include more than one package with the
89 same name in the ``package`` clause in the source file, though
90 obviously the two packages must be imported using different pathnames.
91 In order for this to work with :command:`gccgo`, either
92 :option:`-fgo-pkgpath` or :option:`-fgo-prefix` must be specified when
95 Using either :option:`-fgo-pkgpath` or :option:`-fgo-prefix` disables
96 the special treatment of the ``main`` package and permits that
97 package to be imported like any other.
99 .. option:: -fgo-relative-import-path=dir
101 .. index:: -fgo-relative-import-path
103 A relative import is an import that starts with :samp:`./` or
104 :samp:`../`. If this option is used, :command:`gccgo` will use
105 :samp:`{dir}` as a prefix for the relative import when searching for it.
107 .. option:: -frequire-return-statement
108 .. option:: -fno-require-return-statement
110 .. index:: -frequire-return-statement, -fno-require-return-statement
112 By default :command:`gccgo` will warn about functions which have one or
113 more return parameters but lack an explicit ``return`` statement.
114 This warning may be disabled using
115 :option:`-fno-require-return-statement`.
117 .. option:: -fgo-check-divide-zero
119 .. index:: -fgo-check-divide-zero, -fno-go-check-divide-zero
121 Add explicit checks for division by zero. In Go a division (or
122 modulos) by zero causes a panic. On Unix systems this is detected in
123 the runtime by catching the ``SIGFPE`` signal. Some processors,
124 such as PowerPC, do not generate a SIGFPE on division by zero. Some
125 runtimes do not generate a signal that can be caught. On those
126 systems, this option may be used. Or the checks may be removed via
127 :option:`-fno-go-check-divide-zero`. This option is currently on by
128 default, but in the future may be off by default on systems that do
131 .. option:: -fgo-check-divide-overflow
133 .. index:: -fgo-check-divide-overflow, -fno-go-check-divide-overflow
135 Add explicit checks for division overflow. For example, division
136 overflow occurs when computing ``INT_MIN / -1``. In Go this should
137 be wrapped, to produce ``INT_MIN``. Some processors, such as x86,
138 generate a trap on division overflow. On those systems, this option
139 may be used. Or the checks may be removed via
140 :option:`-fno-go-check-divide-overflow`. This option is currently on
141 by default, but in the future may be off by default on systems that do
144 .. option:: -fno-go-optimize-allocs
146 .. index:: -fno-go-optimize-allocs
148 Disable escape analysis, which tries to allocate objects on the stack
149 rather than the heap.
151 .. option:: -fgo-debug-escapen
153 .. index:: -fgo-debug-escape
155 Output escape analysis debugging information. Larger values of
156 :samp:`{n}` generate more information.
158 .. option:: -fgo-debug-escape-hash=n
160 .. index:: -fgo-debug-escape-hash
162 A hash value to debug escape analysis. :samp:`{n}` is a binary string.
163 This runs escape analysis only on functions whose names hash to values
164 that match the given suffix :samp:`{n}`. This can be used to binary
165 search across functions to uncover escape analysis bugs.
167 .. option:: -fgo-debug-optimization
169 .. index:: -fgo-debug-optimization, -fno-go-debug-optimization
171 Output optimization diagnostics.
173 .. option:: -fgo-c-header=file
175 .. index:: -fgo-c-header
177 Write top-level named Go struct definitions to :samp:`{file}` as C code.
178 This is used when compiling the runtime package.
180 .. option:: -fgo-compiling-runtime
182 .. index:: -fgo-compiling-runtime
184 Apply special rules for compiling the runtime package. Implicit
185 memory allocation is forbidden. Some additional compiler directives
188 .. option:: -fgo-embedcfg=file
190 .. index:: -fgo-embedcfg
192 Identify a JSON file used to map patterns used with special
193 ``//go:embed`` comments to the files named by the patterns. The
194 JSON file should have two components: ``Patterns`` maps each
195 pattern to a list of file names, and ``Files`` maps each file name
196 to a full path to the file. This option is intended for use by the
197 :command:`go` command to implement ``//go:embed``.
201 .. index:: -g for gccgo
203 This is the standard :command:`gcc` option (see :ref:`gcc:debugging-options`). It
204 is mentioned here because by default :command:`gccgo` turns on
205 debugging information generation with the equivalent of the standard
206 option :option:`-g1`. This is because Go programs require debugging
207 information to be available in order to get backtrace information. An
208 explicit :option:`-g0` may be used to disable the generation of
209 debugging information, in which case certain standard library
210 functions, such as ``runtime.Callers``, will not operate correctly.
214 .. include:: copyright.rst