Back to Details

msvc-cl

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

MSVC cl.exe and clang-cl

MSVC cl.exe 与 clang-cl

Purpose

用途

Guide agents through Windows C/C++ compilation: MSVC 
cl.exe
, 
clang-cl
as MSVC-compatible driver, MSBuild project settings, and runtime library choices.
指导使用者完成Windows平台C/C++编译相关操作：包括MSVC的
cl.exe
、作为MSVC兼容驱动的
clang-cl
、MSBuild项目设置以及运行时库的选择。

Triggers

触发场景

  • "How do I compile with MSVC from the command line?"
  • "What is the MSVC equivalent of 
    -O2
    ?"
  • "/MT vs /MD — which do I use?"
  • "How do I use clang-cl instead of cl.exe?"
  • "I'm getting LNK errors on Windows"
  • "How do I generate PDB files?"
  • "如何从命令行使用MSVC进行编译？"
  • "MSVC中与
    -O2
    等效的标志是什么？"
  • "/MT与/MD该选哪一个？"
  • "如何用clang-cl替代cl.exe？"
  • "我在Windows上遇到了LNK错误"
  • "如何生成PDB文件？"

Workflow

操作流程

1. Set up the environment

1. 环境配置

MSVC requires the Visual Studio environment variables. Use the Developer Command Prompt or set up manually:
cmd
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 /?
In CMake, use the "Visual Studio 17 2022" generator or pass 
-DCMAKE_GENERATOR="Visual Studio 17 2022"
.
MSVC需要配置Visual Studio环境变量。可使用开发者命令提示符，或手动配置：
cmd
REM 原生x64环境
"C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvars64.bat"

REM x86交叉编译（宿主x64，目标x86）
"...\vcvarsamd64_x86.bat"

REM 检查编译器版本
cl /?
在CMake中，使用"Visual Studio 17 2022"生成器，或传入
-DCMAKE_GENERATOR="Visual Studio 17 2022"
。

2. Flag translation: GCC → MSVC

2. 标志转换：GCC → MSVC

GCC/ClangMSVC cl.exeNotes
-O0
/Od
Debug, no optimisation
-O1
/O1
Minimise size
-O2
/O2
Maximise speed
-O3
/Ox
Full optimisation
-Os
/Os
Favour size
-g
/Zi
PDB debug info
-g
(embedded)
/Z7
Debug info in object file
-Wall
/W3
or 
/W4
Warning level
-Werror
/WX
Warnings as errors
-std=c++17
/std:c++17
Standard selection
-DFOO=1
/DFOO=1
Preprocessor define
-I path
/I path
Include path
-c
/c
Compile only (no link)
-o out
/Fe:out.exe
or 
/Fo:out.obj
Output file
-shared
/LD
Build DLL
-fPIC
(implicit on Windows)Not needed on Windows
-flto
/GL
(compile) + 
/LTCG
(link)		Whole program optimisation
GCC/ClangMSVC 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. Runtime library selection

3. 运行时库选择

This is the most common source of LNK errors on Windows.
FlagRuntimeUse case
/MD
MSVCRT.dll
(dynamic)		Release, DLL linkage (recommended default)
/MDd
MSVCRTd.dll
(debug dynamic)		Debug builds
/MT
Static CRTStandalone exe; avoid mixing with DLLs
/MTd
Static CRT debugDebug + static
Rule: All objects and libraries in a link must use the same runtime. Mixing 
/MT
and 
/MD
causes 
LNK2038: mismatch detected
.
这是Windows平台上LNK错误最常见的诱因。
标志运行时库使用场景
/MD
MSVCRT.dll
（动态）		发布版本，DLL链接（推荐默认选项）
/MDd
MSVCRTd.dll
（调试动态版）		调试构建
/MT
静态CRT独立可执行文件；避免与DLL混合使用
/MTd
静态CRT调试版调试+静态链接
规则： 链接过程中的所有目标文件和库必须使用相同的运行时库。混合使用
/MT
和
/MD
会触发
LNK2038: mismatch detected
错误。

4. clang-cl

4. clang-cl

clang-cl
is Clang's MSVC-compatible driver. It accepts 
cl.exe
-style flags and can replace 
cl.exe
in most MSBuild/CMake projects.
cmd
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 ..
Minimum Clang version for MSVC STL compatibility: Clang 8+. For C++20 features with MSVC STL: Clang 14+.
Source: https://learn.microsoft.com/en-us/cpp/build/clang-support-msbuild
clang-cl
是Clang提供的MSVC兼容驱动。它支持
cl.exe
风格的标志，可在大多数MSBuild/CMake项目中替代
cl.exe
。
cmd
REM 安装：属于LLVM Windows发行版或VS的"LLVM"组件

REM 基础用法（MSVC风格标志）
clang-cl /O2 /std:c++17 /MD src.cpp /Fe:prog.exe

REM 通过/clang:传递Clang原生标志
clang-cl /O2 /clang:-Rpass=inline src.cpp /Fe:prog.exe

REM 在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 files and debugging

5. PDB文件与调试

cmd
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
For WinDbg or VS debugger, ensure the PDB is alongside the executable or set the symbol path.
cmd
REM 使用/Zi（外部PDB）和/Fd（指定PDB名称）编译
cl /Zi /Fd:prog.pdb /O2 src.cpp /link /DEBUG

REM /Z7：调试信息嵌入.obj文件（目标文件无独立PDB）
cl /Z7 /O2 src.cpp /link /DEBUG /PDB:prog.pdb
对于WinDbg或VS调试器，需确保PDB文件与可执行文件同目录，或已设置符号路径。

6. Common LNK errors

6. 常见LNK错误

ErrorCauseFix
LNK2019: unresolved external
Missing 
.lib
Add library in project settings or 
/link foo.lib
LNK2038: mismatch detected for 'RuntimeLibrary'
Mixed 
/MT
and 
/MD
Unify all to 
/MD
or 
/MT
LNK1104: cannot open file 'foo.lib'
Library not in search pathAdd path via 
/LIBPATH:
or 
LIB
env var
LNK2005: already defined
Multiple definitionsUse 
__declspec(selectany)
or check for duplicate definitions
LNK4098: defaultlib 'LIBCMT' conflicts
Runtime mismatchExplicitly pass 
/NODEFAULTLIB:LIBCMT
or unify runtimes
错误原因修复方案
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. Useful cl.exe flags

7. 实用的cl.exe标志

cmd
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"
For flag details, see references/flags.md.
cmd
REM 生成预处理输出
cl /P src.cpp       # 生成src.i

REM 生成汇编输出
cl /FA /O2 src.cpp  # 生成src.asm（MASM语法）
cl /FAs             # 交错显示源码与汇编

REM 显示头文件包含情况
cl /showIncludes src.cpp

REM 查看编译器版本
cl /?  2>&1 | findstr /i "version"
标志详情请参考references/flags.md。

Related skills

相关技能

  • Use 
    skills/compilers/clang
    for clang-cl's Clang-native diagnostics
  • Use 
    skills/build-systems/cmake
    for CMake toolchain configuration on Windows
  • Use 
    skills/debuggers/lldb
    or WinDbg for debugging MSVC-built binaries
  • 若需clang-cl的Clang原生诊断功能，使用
    skills/compilers/clang
  • 若需在Windows上配置CMake工具链，使用
    skills/build-systems/cmake
  • 若需调试MSVC构建的二进制文件，使用
    skills/debuggers/lldb
    或WinDbg