GCCGO(1)

GCCGO(1) is the GNU manual page for gccgo, so let's get into it 💖

✨ NAME ✨

gccgo is a GCC-based compiler for the Go language 🧚

✨ SYNOPSIS ✨

gccgo [-c|-S]
      [-g] [-pg] [-Olevel]
      [-Idir...] [-Ldir...]
      [-o outfile] infile...

Only the most useful options are listed here, so think of this as the highlights reel 🎀 The rest are down below, so keep scrolling bestie.

✨ DESCRIPTION ✨

okay so gccgo is basically a frontend to gcc, and it shares a bunch of the same options with it 💅 This page only covers the options that are specific to gccgo.

You can use gccgo to compile Go source code into an object file, link a collection of object files together, or literally do both in sequence 🦋

Go source code gets compiled as packages. A package is one or more Go source files. All the files in a single package have to be compiled together, which means you pass every file as an argument to gccgo. One invocation of gccgo can only compile a single package, no exceptions 🙈

One Go package can "import" a different Go package. The imported package has to be compiled already, and gccgo reads the import data directly from that compiled package. Later, when the package gets linked, its compiled form has to be included in the link command 🫶

Go programs generally need to be compiled with debugging information, and -g1 is the default, as explained further down.

Stripping a Go program will generally cause it to misbehave or fail. Do not strip your Go programs, bestie 💀

✨ OPTIONS ✨

• -Idir — Tell it which directory to search when it's looking for an import package at compile time 🔍
• -Ldir — When linking, this sets a library search directory, just like with gcc 🌸
• -fgo-pkgpath=string — Sets the package path. This is the value returned by the PkgPath method of reflect.Type objects, and it's also used for the names of globally visible symbols. The argument should normally be the string you'll use to import this package after it's installed, which is a pathname inside the directories given by the -I option 🗺️
• -fgo-prefix=string — An alternative to -fgo-pkgpath. The argument gets combined with the package name from the source file to make the package path. If you use -fgo-pkgpath, then -fgo-prefix gets ignored 🙃

Go lets a single program include more than one package with the same name in the "package" clause of the source file, though the two packages obviously have to be imported using different pathnames. For this to work with gccgo, you must specify either -fgo-pkgpath or -fgo-prefix when compiling a package 👑

Using either -fgo-pkgpath or -fgo-prefix turns off the special treatment of the "main" package and lets that package be imported like any other 🦋

• -fgo-relative-import-path=dir — A relative import is one that starts with ./ or ../. If you use this option, gccgo uses dir as a prefix for the relative import when it searches for it 🧭
• -frequire-return-statement, -fno-require-return-statement — By default, gccgo warns about functions that have one or more return parameters but are missing an explicit "return" statement. You can turn that warning off with -fno-require-return-statement ⚠️
• -fgo-check-divide-zero — Adds explicit checks for division by zero. In Go, a division (or modulos) by zero causes a panic. On Unix systems this gets detected at runtime by catching the "SIGFPE" signal. Some processors, like PowerPC, don't generate a SIGFPE on division by zero, and some runtimes don't generate a signal that can be caught. On those systems, this option may be used. You can also remove the checks with -fno-go-check-divide-zero. This option is currently on by default, but in the future it may be off by default on systems that don't need it 🔥
• -fgo-check-divide-overflow — Adds explicit checks for division overflow. For example, division overflow happens when computing INT_MIN / -1. In Go this should wrap around and produce INT_MIN. Some processors, like x86, generate a trap on division overflow. On those systems, this option may be used. You can also remove the checks with -fno-go-check-divide-overflow. This option is currently on by default, but in the future it may be off by default on systems that don't require it 💅
• -fno-go-optimize-allocs — Disables escape analysis, which is the thing that tries to allocate objects on the stack instead of the heap 🧱
• -fgo-debug-escapen — Outputs escape analysis debugging information. Bigger values of n generate more information 📊
• -fgo-debug-escape-hash=n — A hash value for debugging escape analysis, where n is a binary string. This runs escape analysis only on functions whose names hash to values that match the given suffix n. It's useful for binary searching across functions to uncover escape analysis bugs 🕵️‍♀️
• -fgo-c-header=file — Writes top-level named Go struct definitions to file as C code. This is used when compiling the runtime package 🌈
• -fgo-compiling-runtime — Applies special rules for compiling the runtime package. Implicit memory allocation is forbidden here, and some additional compiler directives are supported 👑
• -g — This is the standard gcc option, and it's mentioned here because gccgo turns on debugging information generation by default, which is the equivalent of the standard -g1. That's because Go programs need debugging information available in order to get backtrace information. You can use an explicit -g0 to disable the generation of debugging information, but then certain standard library functions, like runtime.Callers, won't operate correctly 🐛

✨ SEE ALSO ✨

gpl(7), gfdl(7), fsf-funding(7), gcc(1), and the Info entries for gccgo and gcc 🎀

✨ COPYRIGHT ✨

Copyright (c) 2010-2019 Free Software Foundation, Inc. 🦋

You're allowed 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. There are no Invariant Sections, the Front-Cover Texts are (a) (see below), and the Back-Cover Texts are (b) (see below). A copy of the license is included in the man page gfdl(7).

(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.

---

That's the tea 🫶 This page came from gcc-9 and was dated 2022-05-27. Go write some packages, bestie 💖🌸