msvc-cl

MSVC cl.exe 和 clang-cl

用途

指导 Agent 在 Windows 上编译 C/C++：MSVC cl.exe、作为 MSVC 兼容驱动程序的 clang-cl、MSBuild 项目设置，以及运行时库的选择。

触发条件

• “如何从命令行使用 MSVC 编译？”
• “MSVC 中等效于 -O2 的选项是什么？”
• “/MT 和 /MD 应该用哪个？”
• “如何改用 clang-cl，而不是 cl.exe？”
• “我在 Windows 上遇到了 LNK 错误”
• “如何生成 PDB 文件？”

工作流

1. 设置环境

MSVC 需要 Visual Studio 环境变量。请使用 Developer Command Prompt，或手动设置：

REM x64 native
"C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvars64.bat"

REM x86 cross (host x64, target x86)
"...\vcvarsamd64_x86.bat"

REM Check compiler version
cl /?

在 CMake 中，使用 “Visual Studio 17 2022” 生成器，或传入 -DCMAKE_GENERATOR="Visual Studio 17 2022"。

2. 编译选项转换：GCC → MSVC

GCC/Clang	MSVC cl.exe	备注
-O0	/Od	调试，不进行优化
-O1	/O1	尽可能减小体积
-O2	/O2	尽可能提高速度
-O3	/Ox	完全优化
-Os	/Os	优先减小体积
-g	/Zi	PDB 调试信息
-g（嵌入式）	/Z7	将调试信息写入目标文件
-Wall	/W3 或 /W4	警告级别
-Werror	/WX	将警告视为错误
-std=c++17	/std:c++17	选择标准
-DFOO=1	/DFOO=1	预处理器定义
-I path	/I path	包含路径
-c	/c	仅编译（不链接）
-o out	/Fe:out.exe 或 /Fo:out.obj	输出文件
-shared	/LD	构建 DLL
-fPIC	（Windows 上隐式启用）	Windows 上不需要
-flto	/GL（编译）+ /LTCG（链接）	全程序优化

3. 选择运行时库

这是 Windows 上最常见的 LNK 错误来源。

标志	运行时	使用场景
/MD	MSVCRT.dll（动态）	Release、DLL 链接（推荐默认选项）
/MDd	MSVCRTd.dll（动态调试）	Debug 构建
/MT	静态 CRT	独立 exe；避免与 DLL 混用
/MTd	静态 CRT 调试版	Debug + 静态链接

规则： 链接中的所有目标文件和库必须使用相同的运行时。混用 /MT 和 /MD 会导致 LNK2038: mismatch detected。

4. clang-cl

clang-cl 是 Clang 的 MSVC 兼容驱动程序。它接受 cl.exe 风格的标志，并且可以在大多数 MSBuild/CMake 项目中替代 cl.exe。

REM Install: part of LLVM Windows release or VS "LLVM" component

REM Basic usage (MSVC-style flags)
clang-cl /O2 /std:c++17 /MD src.cpp /Fe:prog.exe

REM Pass Clang-native flags with /clang:
clang-cl /O2 /clang:-Rpass=inline src.cpp /Fe:prog.exe

REM Use in CMake
cmake -DCMAKE_C_COMPILER=clang-cl -DCMAKE_CXX_COMPILER=clang-cl ..

与 MSVC STL 兼容所需的最低 Clang 版本：Clang 8+。使用 MSVC STL 的 C++20 功能：Clang 14+。

来源：https://learn.microsoft.com/en-us/cpp/build/clang-support-msbuild

5. PDB 文件和调试

REM Compile with /Zi (external PDB) and /Fd (PDB name)
cl /Zi /Fd:prog.pdb /O2 src.cpp /link /DEBUG

REM /Z7: debug info embedded in .obj (no separate PDB for objects)
cl /Z7 /O2 src.cpp /link /DEBUG /PDB:prog.pdb

使用 WinDbg 或 VS 调试器时，请确保 PDB 与可执行文件位于同一目录，或设置符号路径。

6. 常见 LNK 错误

错误	原因	修复方法
LNK2019: unresolved external	缺少 .lib	在项目设置中添加库，或使用 /link foo.lib
LNK2038: mismatch detected for 'RuntimeLibrary'	混用了 /MT 和 /MD	统一使用 /MD 或 /MT
LNK1104: cannot open file 'foo.lib'	库不在搜索路径中	通过 /LIBPATH: 或 LIB 环境变量添加路径
LNK2005: already defined	多重定义	使用 __declspec(selectany)，或检查是否存在重复定义
LNK4098: defaultlib 'LIBCMT' conflicts	运行时不匹配	显式传入 /NODEFAULTLIB:LIBCMT，或统一运行时

7. 有用的 cl.exe 标志

REM Preprocessed output
cl /P src.cpp       # produces src.i

REM Assembly output
cl /FA /O2 src.cpp  # produces src.asm (MASM syntax)
cl /FAs             # interleave source + asm

REM Show include files
cl /showIncludes src.cpp

REM Compiler version
cl /?  2>&1 | findstr /i "version"

有关标志的详细信息，请参阅 references/flags.md。

相关技能

• 使用 skills/compilers/clang 获取 clang-cl 的 Clang 原生诊断
• 使用 skills/build-systems/cmake 配置 Windows 上的 CMake 工具链
• 使用 skills/debuggers/lldb 或 WinDbg 调试通过 MSVC 构建的二进制文件