GCCGO(1)

📦
version 12.4.0 · 2 versions
, in ubuntu noble

✨ GCCGO(1) ✨

okay bestie, sit down, hydrate, because we're about to talk about the GNU gccgo compiler page 💖 (it's from the GNU manual, and it's genuinely iconic)

🌸 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 greatest-hits list. the rest is further down, keep scrolling bestie 👇

🦋 DESCRIPTION 🦋

So gccgo is a frontend to gcc, which means it speaks a lot of the same options as gcc does. But this manual? This manual is only about the options that are special to gccgo. the exclusive club, the VIP section 💅

gccgo can do three little jobs and honestly it slays at all of them: compile Go source code into an object file, link a bunch of object files together, or do both, back to back, in sequence 🔥

Now here's the vibe of Go: source code gets compiled as packages. A package = one or more Go source files. And the rule is ALL the files in one package must be compiled together, meaning you pass every single one of them as arguments to gccgo. Also — and this is important — a single invocation of gccgo may only compile a single package. one compiler call, one package, periodt ✋

One Go package can "import" a different Go package. But bestie, that imported package has to have already been compiled. gccgo reads the import data directly from the compiled package. And later, when you link this package, the compiled form of the imported package has to be included in the link command too. no skipping steps 💖

⚠️ Go programs must generally be compiled with debugging information, and -g1 is the default (more on that below, iykyk). Stripping a Go program will generally cause it to misbehave or fail. like, it'll just start acting unhinged. don't do it 🙈

💖 OPTIONS 💖

  • -Idir — tells gccgo which directory to look in when it's searching for an import package at compile time 🎀
  • -Ldir — when you're linking, this is how you specify a library search directory. same energy as 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. The argument here should normally be the string you'd use to import this package after it's been installed — in other words, a pathname within the directories specified 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 produce the package path. And heads up: if -fgo-pkgpath is used, -fgo-prefix will be ignored. 💀

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

Also: using either -fgo-pkgpath or -fgo-prefix disables the special treatment of the "main" package and lets that package be imported like any other. main character no longer getting special treatment, it's just one of the girls now 💅

  • -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 it goes searching for it. 🔍
  • -frequire-return-statement
  • -fno-require-return-statement — by default, gccgo will warn about functions which 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, like PowerPC, don't generate a SIGFPE on division by zero, and some runtimes don't generate a signal that can even be caught. On those systems, you use this option. Or you can remove the checks with -fno-go-check-divide-zero. Currently this option is 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. Example: overflow happens when you compute "INT_MIN / -1". In Go this should be wrapped, producing "INT_MIN". Some processors, like x86, generate a trap on division overflow, so on those systems you'd use this option. Or remove the checks with -fno-go-check-divide-overflow. Currently on by default, but in the future 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. Larger values of n generate more information. (more chaos, more data, love that for us) 💅
  • -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. You can use this to binary search across functions to uncover escape analysis bugs. detective mode activated 🔍✨
  • -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. 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 those patterns. That 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". 🫶
  • -g — this is the standard gcc option. 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. An explicit -g0 may be used to disable generation of debugging information, in which case certain standard library functions, such as "runtime.Callers", will not operate correctly. so like... don't 😭

🌈 SEE ALSO 🌈

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

Copyright (c) 2010-2022 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 the whole page bestie!! 🫶 this came from the gcc-12 era, dated 2024-07-11 — so go forth, compile responsibly, and keep your debugging info on. love u, bye 💖✨🎀🦋

📦 where this page comes from