Back to Details

gcc

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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.
指导Agent完成GCC调用相关操作：标志选择、构建模式、警告分类、PGO、LTO以及常见错误模式。假设项目使用GNU Make、CMake或Shell脚本。

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
  • "我应该为发布构建使用哪些标志？"
  • "GCC报了一个我看不懂的警告/错误"
  • "如何使用GCC启用LTO/PGO？"
  • "如何使用
    -fsanitize
    编译？"
  • "我的二进制文件太大/太慢"
  • 未定义引用错误、ABI不匹配、缺失符号

Workflow

工作流程

1. Choose a build mode

1. 选择构建模式

GoalRecommended 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.
目标推荐标志
调试
-g -O0 -Wall -Wextra
调试+可调试优化
-g -Og -Wall -Wextra
发布
-O2 -DNDEBUG -Wall
发布（极致性能，仅原生架构）
-O3 -march=native -DNDEBUG
发布（最小体积）
-Os -DNDEBUG
Sanitizer（开发环境）
-g -O1 -fsanitize=address,undefined
始终显式传递
-std=c11
/ 
-std=c++17
（或所需的标准）。永远不要依赖隐式默认值。

2. Warning discipline

2. 警告规范

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:
c
#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.
从
-Wall -Wextra
开始。若要更严格的标准合规性，添加
-Wpedantic
。在CI环境中要将所有警告视为错误：
-Werror
。
仅在窄范围内抑制特定警告：
c
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wunused-parameter"
// ...
#pragma GCC diagnostic pop
除非是处理第三方头文件的最后手段，否则不要传递
-w
（会屏蔽所有内容）。

3. Debug information

3. 调试信息

  • -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.
  • -g
    — DWARF调试信息，默认级别2
  • -g3
    — 包含宏定义（与GDB的
    macro expand
    配合使用很有用）
  • -ggdb
    — 针对GDB优化的DWARF扩展
  • -gsplit-dwarf
    — 拆分
    .dwo
    文件；减少链接时间，是
    debuginfod
    所需的
当你需要在GDB中查看可读的优化代码时，将
-g
与
-Og
（而非
-O0
）配合使用。

4. Optimisation decision tree

4. 优化决策树

text
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.
text
需要在固定机器上实现最大吞吐量？
  是 -> -O3 -march=native -flto
  否 -> 有剖面数据可用？
           是 -> -O2 -fprofile-use
           否 -> -O2
受体积限制（嵌入式、共享库）？
  是 -> -Os （或使用Clang的-Oz）
-O3
vs 
-O2
：
-O3
添加了激进的循环转换（
-funswitch-loops
、
-fpeel-loops
、
-floop-interchange
）以及更激进的内联。仅在基准测试后使用
-O3
；由于指令缓存压力，它偶尔会导致性能退化。
-Ofast
：启用
-ffast-math
，这会破坏IEEE 754语义（NaN处理、结合性）。除非数值领域明确允许，否则避免使用。

5. Link-time optimisation (LTO)

5. 链接时优化（LTO）

bash
undefined
bash
undefined

Compile

编译

gcc -O2 -flto -c foo.c -o foo.o gcc -O2 -flto -c bar.c -o bar.o
gcc -O2 -flto -c foo.c -o foo.o gcc -O2 -flto -c bar.c -o bar.o

Link (must pass -flto again)

链接（必须再次传递-flto）

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](references/flags.md) for full flag reference. See `skills/binaries/linkers-lto` for linker-level LTO configuration.
gcc -O2 -flto foo.o bar.o -o prog

将LTO对象归档到静态库时，使用`gcc-ar` / `gcc-ranlib`而非`ar` / `ranlib`。

对于并行LTO：`-flto=auto`（使用`make`风格的任务服务器）或`-flto=N`。

有关完整标志参考，请参见[references/flags.md](references/flags.md)。有关链接器级别的LTO配置，请参见`skills/binaries/linkers-lto`。

6. Profile-guided optimisation (PGO)

6. 基于剖面的优化（PGO）

bash
undefined
bash
undefined

Step 1: instrument

步骤1：插装

gcc -O2 -fprofile-generate prog.c -o prog_inst
gcc -O2 -fprofile-generate prog.c -o prog_inst

Step 2: run with representative workload

步骤2：使用代表性工作负载运行

./prog_inst < workload.input
./prog_inst < workload.input

Step 3: optimise with profile

步骤3：使用剖面数据优化

gcc -O2 -fprofile-use -fprofile-correction prog.c -o prog

`-fprofile-correction` handles profile data inconsistencies from multi-threaded runs.
gcc -O2 -fprofile-use -fprofile-correction prog.c -o prog

`-fprofile-correction`处理多线程运行时剖面数据的不一致性。

7. Preprocessor and standards

7. 预处理器与标准

  • 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
    )
  • 检查宏展开：
    gcc -E file.c | less
  • 转储预定义宏：
    gcc -dM -E - < /dev/null
  • 强制严格标准：
    -std=c11 -pedantic-errors
  • 禁用GNU扩展：
    -std=c11
    （而非
    -std=gnu11
    ）

8. Common error triage

8. 常见错误分类

SymptomLikely causeFix
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 headerAdd 
extern
in header, define in one 
.c
implicit declaration of function
Missing 
#include
Add the header
warning: incompatible pointer types
Wrong cast or missing prototypeFix 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 relocationUse 
-mcmodel=large
or restructure code
For sanitizer reports, use 
skills/runtimes/sanitizers
.
症状可能原因修复方法
undefined reference to 'foo'
缺少
-lfoo
或链接顺序错误		添加
-lfoo
；将
-l
标志移至目标文件之后
multiple definition of 'x'
变量在头文件中定义（而非仅声明）在头文件中添加
extern
，在一个
.c
文件中定义
implicit declaration of function
缺少
#include
添加对应的头文件
warning: incompatible pointer types
错误的类型转换或缺失原型修正类型；检查头文件
C++的ABI错误混合使用不同的
-std=
或
libstdc++
版本		统一所有编译单元的
-std=
relocation truncated
32位相对重定位溢出使用
-mcmodel=large
或重构代码
有关Sanitizer报告的处理，请使用
skills/runtimes/sanitizers
。

9. Useful one-liners

9. 实用单行命令

bash
undefined
bash
undefined

Show all flags enabled at -O2

显示-O2级别下启用的所有标志

gcc -Q --help=optimizers -O2 | grep enabled
gcc -Q --help=optimizers -O2 | grep enabled

Preprocess only (check includes/macros)

仅预处理（检查头文件/宏）

gcc -E -dD src.c -o src.i
gcc -E -dD src.c -o src.i

Assembly output (Intel syntax)

生成汇编输出（Intel语法）

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

Show include search path

显示头文件搜索路径

gcc -v -E - < /dev/null 2>&1 | grep -A20 '#include <...>'
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](references/flags.md).
For common error patterns and examples, see [references/examples.md](references/examples.md).
gcc -Q --help=target | grep march

有关完整标志速查表，请参见[references/flags.md](references/flags.md)。
有关常见错误模式和示例，请参见[references/examples.md](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
  • 使用
    skills/runtimes/sanitizers
    添加
    -fsanitize=*
    构建
  • 切换到Clang/LLVM时使用
    skills/compilers/clang
  • 高级LTO链接器标志请使用
    skills/binaries/linkers-lto
  • 调试GCC构建的二进制文件请使用
    skills/debuggers/gdb