gcc

GCC

Purpose

Guide agents through GCC invocation: flag selection, build modes, warning triage, PGO, LTO, and common error patterns. Assume the project uses GNU Make, CMake, or a shell script.

Triggers

• "What flags should I use for a release build?"
• "GCC is giving me a warning/error I don't understand"
• "How do I enable LTO / PGO with GCC?"
• "How do I compile with -fsanitize?"
• "My binary is too large / too slow"
• Undefined reference errors, ABI mismatch, missing symbols

Workflow

1. Choose a build mode

Goal	Recommended flags
Debug	-g -O0 -Wall -Wextra
Debug + debuggable optimisation	-g -Og -Wall -Wextra
Release	-O2 -DNDEBUG -Wall
Release (max perf, native only)	-O3 -march=native -DNDEBUG
Release (min size)	-Os -DNDEBUG
Sanitizer (dev)	-g -O1 -fsanitize=address,undefined

Always pass -std=c11 / -std=c++17 (or the required standard) explicitly. Never rely on the implicit default.

2. Warning discipline

Start with -Wall -Wextra. For stricter standards compliance add -Wpedantic. To treat all warnings as errors in CI: -Werror.

Suppress a specific warning only in a narrow scope:

#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wunused-parameter"
// ...
#pragma GCC diagnostic pop

Do not pass -w (silences everything) except as a last resort for third-party headers.

3. Debug information

• -g — DWARF debug info, default level 2
• -g3 — includes macro definitions (useful with GDB macro expand)
• -ggdb — DWARF extensions optimal for GDB
• -gsplit-dwarf — splits .dwo files; reduces link time, needed for debuginfod

Pair -g with -Og (not -O0) when you need readable optimised code in GDB.

4. Optimisation decision tree

Need max throughput on a fixed machine?
  yes -> -O3 -march=native -flto
  no  -> profiling available?
           yes -> -O2 -fprofile-use
           no  -> -O2
Size-constrained (embedded, shared lib)?
  yes -> -Os  (or -Oz with clang)