GCCGO(1)

📦 version 15.3.0+git11272, in opensuse-leap 16.0

🦋 GCCGO(1) — the GNU manual, bestie edition 🦋

okay so you picked up the GNU manual page for gccgo, and honestly? iconic choice. let's get into it 💖

✨ NAME ✨

gccgo — a GCC-based compiler for the Go language. that's it, that's the tweet 🎀

🌸 SYNOPSIS 🌸

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

lowkey important disclaimer bestie: only the most useful options are listed up here. the rest? scroll down, they're all there, i promise 🙈

💅 DESCRIPTION 💅

so the gccgo command is a frontend to gcc, and it supports a whole bunch of the same options. but heads up — this manual only documents the options that are specific to gccgo. the rest live in gcc's own docs, iykyk.

what can you actually do with it? three things, pick your fighter:

  • compile Go source code into an object file
  • link a bunch of object files together
  • or do both, one after the other, in sequence ✨

Go source code gets compiled as packages. a package = one or more Go source files. and like… all the files in a single package have to be compiled together, by passing all of them as arguments to gccgo. one single invocation of gccgo may only compile a single package. no multitasking, no cap 🫶

one Go package may "import" a different Go package. the imported package must have already been compiled — gccgo will read the import data directly from the compiled package. and when that package is later linked, the compiled form of the package must be included in the link command. don't forget it, bestie 😭

Go programs must generally be compiled with debugging information, and -g1 is the default as described below. stripping a Go program will generally cause it to misbehave or fail. so like… don't do that 💀

🔥 OPTIONS 🔥

  • -Idir — tells the compiler which directory to search when it's looking for an import package at compile time. your "where are my imports" directory, basically 🔍
  • -Ldir — when linking, this specifies a library search directory, just like with gcc. same energy as gcc's -L, because it literally is 🎀
  • -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 to this option should normally be the string that will be used to import this package after it has been installed — in other words, a pathname within the directories specified by the -I option. so it's giving "future import path main character energy" 👑
  • -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 fr fr: if -fgo-pkgpath is used, -fgo-prefix will be ignored. bye girl 💅

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 that to work with gccgo, either -fgo-pkgpath or -fgo-prefix must be specified when compiling a package. no option, no vibes ✋

also: 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. main character no more 😔

  • -fgo-relative-import-path=dir — a relative import is an import that starts with ./ or ../. if this option is used, gccgo will use dir as a prefix for the relative import when searching for it. it's giving "home address for your relative imports" 🏡
  • -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. this warning may be disabled using -fno-require-return-statement. so if the warnings are jumping you, you know what to do 🫣
  • -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 is detected in the runtime by catching the "SIGFPE" signal. some processors, such as PowerPC, do not generate a SIGFPE on division by zero. some runtimes do not generate a signal that can be caught. on those systems, this option may be used. or the checks may be removed via -fno-go-check-divide-zero. this option is currently on by default, but in the future may be off by default on systems that do not require it. (yes, -fno-go-check-divide-zero has the extra go- in there, don't @ me, that's just how it is 🙈)
  • -fgo-check-divide-overflow — adds explicit checks for division overflow. for example, division overflow occurs when computing "INT_MIN / -1". in Go this should be wrapped, to produce "INT_MIN". some processors, such as x86, generate a trap on division overflow. on those systems, this option may be used. or the checks may be removed via -fno-go-check-divide-overflow. this option is currently on by default, but in the future may be off by default on systems that do not require it 🔥
  • -fno-go-optimize-allocs — disables escape analysis, which tries to allocate objects on the stack rather than the heap. yeah. it's trying its best 😭
  • -fgo-debug-escapen — outputs escape analysis debugging information. larger values of n generate more information. more n = more chaos 📈
  • -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 can be used to binary search across functions to uncover escape analysis bugs. detective mode activated 🕵️‍♀️
  • -fgo-debug-optimization — outputs optimization diagnostics. enjoy the lore 🍓
  • -fgo-c-header=file — writes top-level named Go struct definitions to file as C code. this is used when compiling the runtime package. slay, cross-language communication 🌈
  • -fgo-compiling-runtime — applies special rules for compiling the runtime package. implicit memory allocation is forbidden. some additional compiler directives are supported. runtime package gets the VIP treatment 👑
  • -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". the go command said "i'll handle this" and honestly, respect 🫶
  • -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. 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, -g0 is a choice, and that choice has consequences 💀

👑 SEE ALSO 👑

gpl(7), gfdl(7), fsf-funding(7), gcc(1) and the Info entries for gccgo and gcc. go read those too, bestie, that's the homework 📚

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

okay so that's the whole page, every last crumb of it, and now the cute lil sign-off: this lil beauty comes from source/version gcc-15, dated 2026-06-12 — and it's genuinely, officially GCCGO(1). bye bestie, go compile something iconic 🦋💖✨

📦 where this page comes from