mohitmishra786/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)

-O3 vs -O2: -O3 adds aggressive loop transformations (-funswitch-loops, -fpeel-loops, -floop-interchange) and more aggressive inlining. Use -O3 only after benchmarking; it occasionally regresses due to i-cache pressure.

-Ofast: enables -ffast-math which breaks IEEE 754 semantics (NaN handling, associativity). Avoid unless the numerical domain explicitly permits it.

5. Link-time optimisation (LTO)

# Compile
gcc -O2 -flto -c foo.c -o foo.o
gcc -O2 -flto -c bar.c -o bar.o
# Link (must pass -flto again)
gcc -O2 -flto foo.o bar.o -o prog

Use gcc-ar / gcc-ranlib instead of ar / ranlib when archiving LTO objects into static libs.

For parallel LTO: -flto=auto (uses make-style jobserver) or -flto=N.

See references/flags.md for full flag reference. See skills/binaries/linkers-lto for linker-level LTO configuration.

6. Profile-guided optimisation (PGO)

# Step 1: instrument
gcc -O2 -fprofile-generate prog.c -o prog_inst
# Step 2: run with representative workload
./prog_inst < workload.input
# Step 3: optimise with profile
gcc -O2 -fprofile-use -fprofile-correction prog.c -o prog

-fprofile-correction handles profile data inconsistencies from multi-threaded runs.

7. Preprocessor and standards

• Inspect macro expansion: gcc -E file.c | less
• Dump predefined macros: gcc -dM -E - < /dev/null
• Force strict standard: -std=c11 -pedantic-errors
• Disable GNU extensions: -std=c11 (not -std=gnu11)

8. Common error triage

| Symptom | Likely cause | Fix | |---------|-------------|-----| | undefined reference to 'foo' | Missing -lfoo or wrong link order | Add -lfoo; move -l flags after object files | | multiple definition of 'x' | Variable defined (not just declared) in a header | Add extern in header, define in one .c | | implicit declaration of function | Missing #include | Add the header | | warning: incompatible pointer types | Wrong cast or missing prototype | Fix the type; check headers | | ABI errors with C++ | Mixed -std= or different libstdc++ | Unify -std= across all TUs | | relocation truncated | Overflow on a 32-bit relative relocation | Use -mcmodel=large or restructure code |

For sanitizer reports, use skills/runtimes/sanitizers.

9. Useful one-liners

# Show all flags enabled at -O2
gcc -Q --help=optimizers -O2 | grep enabled

# Preprocess only (check includes/macros)
gcc -E -dD src.c -o src.i

# Assembly output (Intel syntax)
gcc -S -masm=intel -O2 foo.c -o foo.s

# Show include search path
gcc -v -E - < /dev/null 2>&1 | grep -A20 '#include <...>'

# Check if a flag is supported
gcc -Q --help=target | grep march

For a complete flag cheatsheet, see references/flags.md. For common error patterns and examples, see references/examples.md.

Related skills

• Use skills/runtimes/sanitizers to add -fsanitize=* builds
• Use skills/compilers/clang when switching to clang/LLVM
• Use skills/binaries/linkers-lto for advanced LTO linker flags
• Use skills/debuggers/gdb for debugging GCC-built binaries