Gcc

GCC

Contract

Inputs

• Compiler version: required, from gcc --version. The current stable line is GCC 16.2; older lines lack some flags below and the skill checks each one.
• Build goal: required. One of debug, debuggable-optimized, release, size-constrained, or sanitizer.
• Language standard the project requires: required. Passed explicitly as -std=; C23 and C++23 are the current published standards, C++20 is the floor.
• The exact compiler or linker message when the request is a diagnosis: required.
• Build system in use (Make, CMake, shell script): optional; determines where flags go.

Procedure

1. Confirm the compiler: run gcc --version and record the major line. Done when: the GCC line is recorded.

2. Pick the build mode from the table and always add an explicit -std=; never rely on the implicit default dialect. Done when: one row is chosen and -std= is set.

   Goal	Flags
   Debug	-g -O0 -Wall -Wextra
   Debug with debuggable optimization	-g -Og -Wall -Wextra
   Release	-O2 -DNDEBUG -Wall
   Release, native machine only	-O3 -march=native -DNDEBUG
   Release, minimum size	-Os -DNDEBUG
   Sanitizer, development	-g -O1 -fsanitize=address,undefined

3. Set warning discipline: start from -Wall -Wextra, add -Wpedantic for standards conformance, and -Werror only in CI. Add targeted warnings where the code class warrants them: -Wshadow, -Wconversion, -Wdouble-promotion, -Wformat=2, -Wnull-dereference, -Wundef, -Wcast-qual; for C++ add -Wnon-virtual-dtor, -Woverloaded-virtual, -Wold-style-cast. Suppress a warning only in a narrow scope with #pragma GCC diagnostic push, #pragma GCC diagnostic ignored "-Wname", and #pragma GCC diagnostic pop. Use -w only for third-party headers as a last resort. Done when: the warning set is stated and any suppression is scoped.

4. Set debug information: -g emits DWARF at level 2; -g3 adds macro definitions for GDB macro expand; -ggdb selects GDB extensions; -gsplit-dwarf moves debug data to .dwo files and shortens link time; -gz compresses debug sections; -fdebug-prefix-map=old=new remaps paths for reproducible builds. Pair -g with -Og, not -O0, when the user needs readable optimized code under a debugger. Done when: the debug flags match the goal.

5. Decide the optimization level. -O3 adds loop transformations and more inlining over -O2; recommend it only after a benchmark, because larger code can lose on instruction-cache-bound workloads. -Ofast enables -ffast-math, which drops IEEE 754 guarantees (NaN handling, associativity); recommend it only when the numerical domain explicitly permits it. -march=native binds the binary to the build host. Show what a level enables with gcc -Q --help=optimizers -O2 | grep enabled. Done when: the level is chosen with its trade-off stated.

6. Configure LTO when the goal is release: compile every object with -flto and link with -flto again; use -flto=auto for jobserver parallelism or -flto=N for a fixed job count; archive LTO objects with gcc-ar and gcc-ranlib, not ar and ranlib. GCC has no -flto=thin; that spelling is Clang-only. Linker-side details: use linkers-lto. Done when: the LTO commands cover compile, link, and archive.

7. Configure PGO when a representative workload exists: build with -O2 -fprofile-generate, run the workload to produce .gcda files, then rebuild with -O2 -fprofile-use -fprofile-correction. -fprofile-correction reconciles counts from multi-threaded runs; include it. For the full two-stage flow, BOLT, and Clang's formats: use pgo. Done when: the three PGO steps are listed.

8. Answer preprocessor and standards questions with the exact command: gcc -E file.c to see expansion, gcc -dM -E - < /dev/null for predefined macros, -std=c11 -pedantic-errors for strict conformance, -std=cNN rather than -std=gnuNN to disable GNU extensions, gcc -v -E - < /dev/null for the include search path, gcc -S -masm=intel -O2 foo.c for Intel-syntax assembly. Done when: each question maps to one command.

9. Triage errors from the table; when the symptom is absent, reproduce it on a scratch file before naming a cause. Done when: every reported symptom has a cause and fix.

   Symptom	Cause	Fix
   undefined reference to 'foo'	Missing -lfoo or the library precedes the object that needs it	Add -lfoo after the object files
   multiple definition of 'x'	A variable is defined, not declared, in a header	extern in the header, one definition in a .c file
   implicit declaration of function	Missing #include	Add the header that declares it
   incompatible pointer types	Wrong cast or missing prototype	Fix the type; check the declaring header
   C++ ABI mismatch at link	Mixed -std= or different libstdc++ across TUs	One -std= and one toolchain for every TU
   relocation truncated to fit	A 32-bit relative relocation overflowed	-mcmodel=large or restructure the image

10. Confirm every flag in the answer against the installed compiler: gcc -Q --help=target | grep <flag> for target flags, or a scratch compile for the rest. Drop any flag the installed line rejects and say so. Done when: no unconfirmed flag remains in the answer.

Failure and recovery

Output

A chat report with three parts: the flag set for the build goal with each flag's purpose, the diagnosis table for every reported symptom, and a confirmation line naming the GCC line the flags were checked against and any flag dropped because that line rejected it.