GCCGO(1)

📦
version 13.3.0 · 2 versions
, in ubuntu noble

💖 GCCGO(1) — the GNU manual, but make it make sense 💖

okay bestie, sit down, hydrate, because we're about to talk about gccgo, a GCC-based compiler for the Go language, and it's genuinely iconic. this is the GNU manual energy, so you know it's official. ✨

🌸 NAME 🌸

gccgo — a GCC-based compiler for the Go language. yes that's the whole vibe. it compiles Go. it's built on GCC. slay.

🎀 SYNOPSIS 🎀

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

lowkey important note: only the most useful options are listed right here — the rest are chilling down in OPTIONS, so keep scrolling, bestie, don't be lazy. 👑

🦋 DESCRIPTION 🦋

so gccgo is a frontend to gcc, and it supports a lot of the same options as gcc does. but heads up: this manual only documents the options that are specific to gccgo. everything else? that's a gcc(1) situation, iykyk.

you can use gccgo to:

  • compile Go source code into an object file
  • link a bunch of object files together
  • or do BOTH, one after the other, main character energy fr fr 💅

here's the thing about Go that trips people up: Go source code is compiled as packages. a package is made of one or more Go source files. and the rule is strict — all the files in a single package have to be compiled together, which means you pass all of them as arguments to gccgo. and no, you can't multitask: a single invocation of gccgo may only compile a single package. one package per run, periodt.

now, one Go package can "import" a different Go package. for that to work, the imported package must already be compiled — gccgo reads the import data straight out of the compiled package. and then when you later link this package, the compiled form of the imported package has to be included in the link command. no skipping steps, bestie. 🫶

also super important: Go programs must generally be compiled with debugging information, and -g1 is the default, as described below. and if you strip a Go program? it will generally misbehave or fail. not a vibe. do not do that. 💀

✨ OPTIONS ✨

  • -Idir — tells it which directory to search when it's looking for an import package at compile time.
  • -Ldir — when linking, this specifies a library search directory, same as 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. the argument here should normally be the string you'll use to import this package after it's been installed — in other words, a pathname inside the directories you specified with the -I option. 👑
  • -fgo-prefix=string — an alternative to -fgo-pkgpath. this argument gets combined with the package name from the source file to produce the package path. and if -fgo-pkgpath is used, -fgo-prefix will be ignored. so pick one, bestie, don't be messy.

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

using either -fgo-pkgpath or -fgo-prefix disables the special treatment of the "main" package and permits that package to be imported like any other. that's the plot twist. 🌀

  • -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's searching for it.
  • -frequire-return-statement / -fno-require-return-statement — by default gccgo will warn 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 modulos-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, do not generate a SIGFPE on division by zero, and some runtimes don't generate a signal that can be caught at all. on those systems, this option may be used. or you can 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 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, and on those systems this option may be used. or the checks may be removed 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. rip to the optimization, honestly. 😭
  • -fgo-debug-escapen — outputs escape analysis debugging information. larger values of n generate more information. yes, n is a number, go wild. 🍓
  • -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. this is how you 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, and some additional compiler directives are supported. special treatment only for the runtime package, no cap. 👑
  • -fgo-embedcfg=file — identifies a JSON file used to map patterns used with special "//go:embed" comments to the files named by the 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 the generation of debugging information, in which case certain standard library functions, such as "runtime.Callers", will not operate correctly. so like… your call, but read the fine print. 🙈
ngl the -g situation is the most dramatic part of this entire manpage and i respect it.

👑 SEE ALSO 👑

go read these too, bestie, they're the extended universe:

Copyright (c) 2010-2023 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 thing, bestie. 🌈 this page is from the gcc-13 era, dated 2024-09-04, and it goes by the name GCCGO(1). now go compile something cute. 💅✨🦋

📦 where this page comes from