Documentation Index
Fetch the complete documentation index at: https://mintlify.com/MicrosoftDocs/cpp-docs/llms.txt
Use this file to discover all available pages before exploring further.
cl.exe is the Microsoft C/C++ compiler and is the central tool in the MSVC toolchain. It preprocesses, compiles, and optionally links C and C++ source files into COFF object files (.obj) and executables. Compiler options are case-sensitive and may be prefixed with either / or -. This reference covers the most important options grouped by purpose, with real examples for common build scenarios.
cl.exe can only be run from a Visual Studio Developer Command Prompt or after calling vcvarsall.bat to configure the environment. See Building from the Command Line for environment setup instructions.Language Standard
Control which C++ standard is used to compile your code with the /std option.
| Option | Standard | Available Since |
|---|
/std:c++14 | ISO C++14 | VS 2015 Update 3 |
/std:c++17 | ISO C++17 | VS 2017 15.3 |
/std:c++20 | ISO C++20 | VS 2019 16.11 |
/std:c++23preview | ISO C++23 (preview) | VS 2022 17.13 |
/std:c++latest | Latest draft + experimental features | VS 2015 Update 3 |
/std:c11 | ISO C11 | VS 2019 16.8 |
/std:c17 | ISO C17 | VS 2019 16.8 |
# Compile with C++20
cl /std:c++20 /EHsc main.cpp
# Use the latest draft features
cl /std:c++latest /EHsc main.cpp
To make __cplusplus report the correct value (rather than 199711L), also pass /Zc:__cplusplus alongside /std:c++17 or later. For example: cl /std:c++17 /Zc:__cplusplus /EHsc main.cpp.
Optimization
Optimization options control the trade-off between code size, speed, and compile time.
| Option | Description | Expands To |
|---|
/Od | Disable optimization (default for Debug) | — |
/O1 | Minimize size | /Og /Os /Oy /Ob2 /GF /Gy |
/O2 | Maximize speed (default for Release) | /Og /Oi /Ot /Oy /Ob2 /GF /Gy |
/Ox | Maximum optimization (superset of /O2) | /Og /Oi /Ot /Oy /Ob2 |
/Og | Enable global optimizations | — |
/Oi | Generate intrinsic functions | — |
/Os | Favor small code | — |
/Ot | Favor fast code | — |
/Ob0 | Disable inlining | — |
/Ob1 | Inline only functions explicitly marked inline, __inline, or __forceinline | — |
/Ob2 | Inline any function the compiler deems suitable (default under /O1 and /O2) | — |
/Oy | Omit frame pointer (x86 only) | — |
# Debug build — no optimization
cl /Od /Zi /EHsc main.cpp
# Release build — maximum speed
cl /O2 /EHsc /DNDEBUG main.cpp
# Minimize binary size (e.g., for embedded or size-constrained builds)
cl /O1 /EHsc /DNDEBUG main.cpp
/GL) and profile-guided optimization (PGO).
Control the format and location of debugging symbols.
| Option | Debug Format | PDB? | Edit & Continue |
|---|
| (none) | No debug info | No | No |
/Z7 | Full symbols embedded in .obj | No (but linker can create one) | No |
/Zi | Separate PDB file | Yes | No |
/ZI | PDB with Edit and Continue support | Yes | Yes |
# Standard debug build with PDB
cl /Zi /Od /EHsc main.cpp
link /DEBUG /PDB:myapp.pdb main.obj
# Edit and Continue support (x86/x64 only)
cl /ZI /Od /EHsc main.cpp
# Embed debug info in object files (useful for static library distribution)
cl /Z7 /Od /EHsc main.cpp
/ZI (Edit and Continue) is incompatible with /GL (Whole Program Optimization) and /Ox. Use /Zi for release builds that still need debuggable PDBs.
Warning Levels
| Option | Description |
|---|
/W0 | Disable all warnings |
/W1 | Severe warnings only |
/W2 | Significant warnings |
/W3 | Production quality (default) |
/W4 | Informational warnings (recommended for new code) |
/Wall | All warnings including informational ones (very verbose) |
/WX | Treat all warnings as errors |
/wd<nnnn> | Disable specific warning number |
/we<nnnn> | Treat specific warning as an error |
/wo<nnnn> | Issue specific warning once |
# Recommended for new projects
cl /W4 /WX /EHsc /std:c++17 main.cpp
# Disable a specific noisy warning (e.g., C4100: unreferenced formal parameter)
cl /W4 /wd4100 /EHsc main.cpp
# Treat one specific warning as an error
cl /W3 /we4715 /EHsc main.cpp
Runtime Library (CRT Linking)
The /MD, /MT, and /LD options control how the C Runtime Library (CRT) is linked. All modules in a program must use the same runtime library option.
| Option | Library | CRT | Usage |
|---|
/MD | MSVCRT.lib | Dynamic (DLL) | Release builds linked to MSVCRT.dll |
/MDd | MSVCRTD.lib | Dynamic (DLL) — Debug | Debug builds, defines _DEBUG |
/MT | LIBCMT.lib | Static | Self-contained release builds, no CRT DLL dependency |
/MTd | LIBCMTD.lib | Static — Debug | Self-contained debug builds |
/LD | — | Implies /MT (unless /MD is also specified) | Create a DLL |
/LDd | — | Implies /MT — Debug | Create a debug DLL |
# Dynamic CRT — typical for applications and DLLs
cl /MD /EHsc main.cpp
# Static CRT — self-contained executable, no MSVCRT.dll dependency
cl /MT /EHsc main.cpp
# Debug build with dynamic CRT
cl /MDd /Zi /Od /EHsc main.cpp
Mixing runtime library options within a single linked binary (e.g., one .obj with /MD and another with /MT) causes linker errors and undefined behavior. Use the same option consistently across all source files and all libraries you link against.
Preprocessor Definitions
| Option | Description |
|---|
/D<name> | Define a preprocessor macro |
/D<name>=<value> | Define a macro with a value |
/U<name> | Undefine a macro |
# Common release build defines
cl /DNDEBUG /DWIN32 /D_WINDOWS /EHsc main.cpp
# Define a version string
cl /DAPP_VERSION=\"2.1.0\" /EHsc main.cpp
# Define an integer constant
cl /DMAX_CONNECTIONS=100 /EHsc main.cpp
# Undefine a macro set by the system headers
cl /UUNICODE /EHsc main.cpp
Output File Control
| Option | Controls | Example |
|---|
/Fe<name> | Executable output file name | /Fe:myapp.exe |
/Fo<name> | Object file output name or directory | /Fo:obj\ or /Fo:main.obj |
/Fp<name> | Precompiled header file name | /Fp:pch\stdafx.pch |
/Fd<name> | PDB file name (for compiler-generated PDB) | /Fd:debug\vc143.pdb |
/Fm<name> | Map file name | /Fm:myapp.map |
/Fa<name> | Assembly listing file | /Fa:main.asm |
# Place all output in a build directory
cl /EHsc /O2 /MD ^
/Fe:build\myapp.exe ^
/Fo:build\ ^
src\main.cpp src\engine.cpp
Exception Handling
| Option | Description |
|---|
/EHsc | Enable standard C++ exception handling with extern "C" assumed to not throw |
/EHa | Enable C++ exceptions and structured exception handling (SEH) |
/EHs | Enable C++ exceptions (assume extern "C" may throw) |
/EHr | Always generate noexcept runtime termination checks |
# Standard recommendation for most C++ code
cl /EHsc main.cpp
Always specify /EHsc for standard C++ code. Without an /EH option, stack-unwinding destructors may not be called on exception, leading to resource leaks.
| Option | Description |
|---|
/GR | Enable RTTI — allows dynamic_cast and typeid (default: ON) |
/GR- | Disable RTTI — reduces binary size, cannot use dynamic_cast or typeid |
# Explicitly enable RTTI (default)
cl /GR /EHsc main.cpp
# Disable RTTI for size-constrained builds
cl /GR- /EHsc main.cpp
Common Build Scenarios
Debug Build
Release Build
DLL Build
Size-Optimized
A typical debug build: no optimization, full debug symbols, dynamic CRT debug library.cl ^
/std:c++17 ^
/EHsc ^
/GR ^
/W4 ^
/Od ^
/ZI ^
/MDd ^
/DDEBUG ^
/D_DEBUG ^
/Fo:obj\debug\ ^
/Fe:bin\debug\myapp.exe ^
src\main.cpp src\engine.cpp src\utils.cpp
A typical release build: maximum speed, PDB for crash analysis, dynamic CRT.cl ^
/std:c++17 ^
/EHsc ^
/GR ^
/W4 ^
/WX ^
/O2 ^
/Zi ^
/MD ^
/DNDEBUG ^
/GL ^
/Fo:obj\release\ ^
/Fe:bin\release\myapp.exe ^
src\main.cpp src\engine.cpp src\utils.cpp
link ^
/OUT:bin\release\myapp.exe ^
/PDB:bin\release\myapp.pdb ^
/LTCG ^
/OPT:REF /OPT:ICF ^
/SUBSYSTEM:CONSOLE ^
obj\release\*.obj ^
kernel32.lib msvcrt.lib
Building a DLL with an import library.cl ^
/std:c++17 ^
/EHsc ^
/O2 ^
/Zi ^
/MD ^
/DNDEBUG ^
/DMYLIB_EXPORTS ^
/Fo:obj\dll\ ^
src\mylib.cpp
link ^
/DLL ^
/OUT:bin\mylib.dll ^
/IMPLIB:bin\mylib.lib ^
/PDB:bin\mylib.pdb ^
/EXPORT:MyFunction ^
/SUBSYSTEM:WINDOWS ^
obj\dll\mylib.obj ^
kernel32.lib msvcrt.lib
Smallest possible binary: static CRT, minimal optimizations, no RTTI.cl ^
/std:c++17 ^
/EHsc ^
/GR- ^
/O1 ^
/Zi ^
/MT ^
/DNDEBUG ^
/Fo:obj\small\ ^
src\main.cpp
link ^
/OUT:bin\myapp_small.exe ^
/OPT:REF /OPT:ICF ^
/SUBSYSTEM:CONSOLE ^
obj\small\main.obj
Compiler Options Quick Reference
| Category | Option | Summary |
|---|
| Language | /std:c++17 | C++17 standard |
| Language | /std:c++20 | C++20 standard |
| Language | /Zc:__cplusplus | Correct __cplusplus value |
| Language | /permissive- | Strict standards conformance |
| Optimization | /Od | Disable (Debug) |
| Optimization | /O1 | Minimize size |
| Optimization | /O2 | Maximize speed (Release default) |
| Optimization | /GL | Whole-program optimization |
| Debug | /Zi | PDB file |
| Debug | /ZI | PDB with Edit and Continue |
| Debug | /Z7 | Symbols in .obj |
| Warnings | /W4 | Level 4 (recommended) |
| Warnings | /WX | Warnings as errors |
| CRT | /MD | Dynamic CRT release |
| CRT | /MDd | Dynamic CRT debug |
| CRT | /MT | Static CRT release |
| CRT | /MTd | Static CRT debug |
| Exceptions | /EHsc | Standard C++ exceptions |
| RTTI | /GR | Enable dynamic_cast |
| Output | /Fe: | Name executable |
| Output | /Fo: | Name / directory for .obj |
| Preprocessor | /D | Define macro |
| Preprocessor | /U | Undefine macro |
| Includes | /I | Add include directory |
