GCCGO(1)

🦋 gccgo: the manual, but make it bestie 🦋

Okay so this is the manual for gccgo, the GCC-based compiler for Go. It's lowkey iconic and you need to know all of it 💅✨

✨ NAME ✨

gccgo - 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 check below for the rest 🧚

📖 DESCRIPTION 📖

The gccgo command is a frontend to gcc, and it's giving family, because it supports a lot of the same options 🫶 This manual only covers the options that are specific to gccgo.

The gccgo command can compile Go source code into an object file, link a bunch of object files together, or do both in one go. Main character energy 👑

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, so you pass every file as an argument to gccgo. One invocation of gccgo can only compile a single package, so no multitasking here 💅

One Go package can "import" a different Go package. That imported package has to be compiled already, and gccgo reads the import data straight from the compiled package. When you link this package later, the compiled form of the package has to be in the link command too 🔗

Go programs should generally be compiled with debugging information, and -g1 is the default (more on that below) 🐛

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

🎀 OPTIONS 🎀

• -Idir — Pick a directory to search when looking for an import package at compile time 🍓
• -Ldir — When linking, set a library search directory, same as 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 that will import this package after it's installed. In other words, it's a pathname inside the directories you gave with 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 one program include more than one package with the same name in the package clause of the source file. The two packages still have to be imported with different pathnames though. 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, so that package can be imported like any other 💖
• -fgo-relative-import-path=dir — A relative import is one that starts with ./ or ../. With 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 you about functions that have one or more return parameters but no 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, dividing (or taking the modulos) by zero causes a panic. On Unix systems the runtime catches that through 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, you can use this option. You can also remove the checks with -fno-go-check-divide-zero. Right now this is on by default, but in the future it might be off by default on systems that don't need it 💅
• -fgo-check-divide-overflow — Adds explicit checks for division overflow. For example, overflow happens when you compute INT_MIN / -1. In Go, that should wrap around to INT_MIN. Some processors, like x86, trap on division overflow, so on those systems you can use this option. Or remove the checks with -fno-go-check-divide-overflow. This is on by default for now, but in the future it might be off by default on systems that don't need it 🔥
• -fno-go-optimize-allocs — Turns off escape analysis, the thing that tries to allocate objects on the stack instead of the heap 🧚
• -fgo-debug-escapen — Outputs escape analysis debugging info. Bigger values of n give you more info 🔍
• -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 matching the given suffix n. It's super useful for binary searching across functions to find escape analysis bugs 🕵️‍♀️
• -fgo-debug-optimization — Outputs optimization diagnostics 🌸
• -fgo-c-header=file — Writes top-level named Go struct definitions to file as C code. This gets 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 extra 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, the equivalent of the standard option -g1. Go programs need debugging info to get backtrace info. You can use an explicit -g0 to turn off debugging info generation, but then certain standard library functions, like runtime.Callers, won't work correctly 💀

Using -g0 means runtime.Callers and friends won't operate correctly. Be careful, bestie ⚠️

🔗 SEE ALSO 🔗

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

🧾 COPYRIGHT 🧾

Copyright (c) 2010-2020 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. 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 whole tea, bestie 🫶 Source: gcc-10, dated 2023-07-07. Go compile something iconic 💖🦋✨