GCCGO(1)

📦 version 14.2.0, in ubuntu noble

🌸 GCCGO 💅

okay bestie, so you know the manual page for gccgo? It lives in the GNU manual set, and we're gonna walk through the whole thing together, no skips, no shortcuts. Every flag, every warning, every lil detail. Let's go. ✨

✨ NAME ✨

gccgo — a GCC-based compiler for the Go language 🦋

🎀 SYNOPSIS 🎀

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

ngl, that's only the most useful options listed up there. The rest? They're down in OPTIONS, keep scrolling. 👑

💖 DESCRIPTION 💖

The gccgo command is a frontend to gcc, and it supports many of the same options. Just so we're clear: this manual only documents the options that are specific to gccgo. Everything else? That's a gcc situation.

You can use the gccgo command to compile Go source code into an object file, to link a bunch of object files together, or to do both, one after the other. Multi-tasking icon behavior. 💅

Go source code gets compiled as packages. A package is made of one or more Go source files. And here's the thing — all the files in a single package must be compiled together, so you pass every single one of them as arguments to gccgo. Also, a single invocation of gccgo can only compile a single package. No sneaking a second one in there. 🚫

One Go package may "import" a different Go package. That imported package has to have already been compiled — gccgo reads the import data straight from the compiled package. And when this package gets linked later, the compiled form of the package has to be included in the link command. Fr fr, don't forget it. 😭

Go programs generally need to be compiled with debugging information, and -g1 is the default, as described below. And listen — stripping a Go program will generally cause it to misbehave or fail. So don't do that. Not the vibe. 💀

⭐ OPTIONS ⭐

  • -Idir — tell it a directory to search when it's looking for an import package at compile time. 🎀
  • -Ldir — when linking, this specifies a library search directory, just like with gcc.
  • -fgo-pkgpath=string — sets the package path to use. This sets the value returned by the PkgPath method of reflect.Type objects, and it's also used for the names of globally visible symbols. Normally, the argument you pass here should be the string that'll be used to import this package after it's installed — in other words, a pathname inside the directories you specified 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 produce the package path. And heads up: if -fgo-pkgpath is used, -fgo-prefix gets ignored. Bye. 👋

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

Using either -fgo-pkgpath or -fgo-prefix disables 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 an import that starts with ./ or ../. If you use this option, gccgo will use dir as a prefix for the relative import when searching for it. 🔍
  • -frequire-return-statement, -fno-require-return-statement — by default, gccgo warns about functions that have one or more return parameters but lack 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, dividing (or modulo-ing) by zero causes a panic. On Unix systems, this gets detected in the runtime by catching the "SIGFPE" signal. But some processors — PowerPC, for example — 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 may use this option. Or the checks can be removed via -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 require 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 be wrapped, to produce "INT_MIN". Some processors, like x86, generate a trap on division overflow. On those systems, you may use this option. Or the checks can be removed via -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 to debug escape analysis. n is a binary string. This runs escape analysis only on functions whose names hash to values that match the given suffix n. Super useful for binary searching across functions to uncover 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 is used when compiling the runtime package. 🌈
  • -fgo-compiling-runtime — applies special rules for compiling the runtime package. Implicit memory allocation is forbidden, and some additional compiler directives are supported. 😤
  • -fgo-embedcfg=file — identifies 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 go command to implement "//go:embed". 💜
  • -fgo-importcfg=file — identifies a file that provides mappings for import package paths found in the Go source files. The file can contain two commands: "importpath" to rename import paths for vendoring, and "packagefile" to map from package path to files containing export data. This option is intended for use by the go command. 🫶
  • -g — this is the standard gcc option, but it's mentioned here because by default gccgo turns on debugging information generation with the equivalent of the standard option -g1. Why? Because Go programs require debugging information to be available in order to get backtrace information. You can use an explicit -g0 to disable the generation of debugging information — but in that case, certain standard library functions, like "runtime.Callers", will not operate correctly. ⚠️
okay this one matters bestie, don't just yeet your debug info and then wonder why your backtraces are giving nothing. 😭

🌟 SEE ALSO 🌟

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

Copyright (c) 2010-2024 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 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.

and that's a wrap, bestie 🎀 this whole thing is from gcc-14, dated 2024-09-08 — go forth and compile, you absolute main character 👑✨

📦 where this page comes from