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

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

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

GCC Examples and Error Patterns

Table of Contents

1. Standard build recipes 2. Common error patterns 3. Preprocessor inspection 4. Assembly output

---

Standard build recipes

Debug build

gcc -std=c11 -g -Og -Wall -Wextra -Wpedantic -o prog src/*.c

Release build

gcc -std=c11 -O2 -DNDEBUG -Wall -fstack-protector-strong -D_FORTIFY_SOURCE=2 \
    -o prog src/*.c

Shared library

gcc -std=c11 -O2 -fPIC -Wall -shared -Wl,-soname,libfoo.so.1 \
    -o libfoo.so.1.0 foo.c
ln -sf libfoo.so.1.0 libfoo.so.1
ln -sf libfoo.so.1   libfoo.so

Freestanding (embedded)

arm-none-eabi-gcc -std=c11 -O2 -g -Wall \
    -mcpu=cortex-m4 -mthumb -mfloat-abi=hard -mfpu=fpv4-sp-d16 \
    -ffreestanding -nostdlib \
    -T linker.ld -o firmware.elf startup.s main.c

---

Common error patterns

undefined reference to 'foo'

Cause: Linker cannot find the symbol. Most common reasons:

1. Missing -lfoo flag 2. Library listed before the object that needs it

# Wrong: library before object
gcc main.o -lz -o prog       # if main.o uses zlib this can fail
# Correct
gcc main.o -o prog -lz       # -l flags go after objects

multiple definition of 'x'

A variable is defined (not just declared) in a header included by multiple TUs.

// header.h — wrong
int counter = 0;    // definition

// header.h — correct
extern int counter; // declaration only

// counter.c
int counter = 0;    // one definition

implicit declaration of function (C99+: error)

Missing #include. Add the header or forward-declare the function.

# Find which header declares a function
man 3 strdup | grep SYNOPSIS

relocation truncated to fit: R_X86_64_PC32

Binary exceeds 2 GB or a symbol is out of range for a 32-bit-relative relocation.

# Fix: use large code model
gcc -mcmodel=large -O2 -o prog ...

ABI mismatch (C++)

Mixing objects compiled with different -std=c++NN or different libstdc++ versions. Symptoms: std::string or std::list methods missing at link time.

Fix: compile all TUs with the same -std= and link against the same runtime.

Stack overflow / SIGSEGV in signal handler

Red zone use in signal handlers on x86-64. Fix: -mno-red-zone for kernel/signal code.

---

Preprocessor inspection

# Full preprocessed output
gcc -E src.c -o src.i

# Show all predefined macros
gcc -dM -E - < /dev/null

# Show macros + includes in order
gcc -dD -E src.c

# Check what __GNUC__ is
gcc -dM -E - < /dev/null | grep GNUC

# Find include search paths
gcc -v -E - < /dev/null 2>&1 | sed -n '/#include </,/End of search/p'

---

Assembly output

# Default (AT&T) syntax
gcc -S -O2 foo.c -o foo.s

# Intel syntax
gcc -S -masm=intel -O2 foo.c -o foo.s

# Interleaved C source + assembly
gcc -S -O2 -fverbose-asm foo.c -o foo.s

# From object: disassemble with objdump
objdump -d -M intel -S foo.o   # -S intermixes source (needs -g)

GCC Flag Reference

Source: <https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html> Source: <https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html> Source: <https://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html>

Table of Contents

1. Optimisation flags 2. Debug flags 3. Warning flags 4. Hardening flags 5. Code generation flags 6. LTO / PGO flags 7. Diagnostic flags

---

Optimisation flags

Key sub-flags (fine-tuning)

---

Debug flags

---

Warning flags

Recommended baseline

-Wall -Wextra -Wpedantic

Additional useful warnings

C++-specific

---

Hardening flags

For production binaries (defence-in-depth):

-D_FORTIFY_SOURCE=2          # Buffer overflow detection in libc calls
-fstack-protector-strong      # Stack canary (balanced: protects most frames)
-fstack-protector-all         # Every function (slower)
-fPIE -pie                    # Position-independent executable (ASLR)
-Wl,-z,relro -Wl,-z,now      # Read-only relocations, bind now (RELRO full)
-fcf-protection=full          # Intel CET shadow stack + IBT (x86 only)

Do NOT combine -fstack-protector-strong with -fno-stack-protector on the same TU.

---

Code generation flags

---

LTO / PGO flags

Use gcc-ar / gcc-ranlib when creating archives of LTO objects.

---

Diagnostic flags