Msvc Cl

MSVC cl.exe and clang-cl

Contract

Inputs

• Compiler: required. cl.exe from a Visual Studio install, or clang-cl from an LLVM release or the Visual Studio LLVM component. Current upstream Clang is 23.1.0.
• Target architecture: required. x64 or x86; selects the vcvars script.
• Build system: required. Command line, MSBuild, or CMake.
• The GCC or Clang flags being translated: required for translation requests.
• The exact LNK message: required for link diagnosis.

Procedure

1. Set up the environment. Open a Developer Command Prompt, or run "C:\Program Files\Microsoft Visual Studio\2022\<edition>\VC\Auxiliary\Build\vcvars64.bat" for x64 native and vcvarsamd64_x86.bat for an x86 target from an x64 host. Confirm with cl /?. With CMake, pass -G "Visual Studio 17 2022". Done when: cl runs from the shell.

2. Translate flags from the table. Done when: each requested flag has its MSVC spelling.

   GCC or Clang	cl.exe
   -O0	/Od
   -O1	/O1 (size)
   -O2	/O2 (speed)
   -O3	/Ox
   -Os	/Os
   -g	/Zi (external PDB) or /Z7 (in the object)
   -Wall	/W4; /Wall is far noisier than GCC's
   -Werror	/WX
   -Wno-xxxx	/wd<code>
   -std=c++20	/std:c++20; add /permissive- for conformance
   -DFOO=1	/DFOO=1
   -I dir	/I dir
   -c	/c
   -o out	/Fe:out.exe or /Fo:out.obj
   -shared	/LD
   -fPIC	Not needed on Windows
   -flto	/GL at compile and /LTCG at link

3. Choose the runtime library, the most common source of link errors: /MD (dynamic MSVCRT, the default for release), /MDd (dynamic debug), /MT (static LIBCMT), /MTd (static debug). Every object and library in one link must use the same choice. Done when: one runtime is chosen for the whole link.

4. Use clang-cl where wanted: it accepts cl.exe flags, so clang-cl /O2 /std:c++20 /MD src.cpp /Fe:prog.exe works, and /clang:<arg> passes a Clang-native flag through, for example /clang:-Rpass=inline. In CMake: -DCMAKE_C_COMPILER=clang-cl -DCMAKE_CXX_COMPILER=clang-cl. Microsoft documents Clang 8 as the minimum for its MSBuild integration; use the current LLVM release. Done when: the clang-cl command or CMake setting is stated.

5. Produce debug information. cl /Zi /Fd:prog.pdb /O2 src.cpp /link /DEBUG writes an external PDB; cl /Z7 /O2 src.cpp /link /DEBUG /PDB:prog.pdb embeds debug data in each object and lets the linker build the PDB. The linker's /DEBUG:FASTLINK links faster but needs the object PDBs present when debugging. Keep the PDB beside the executable or on the debugger's symbol path. Done when: the PDB flags match the workflow.

6. Diagnose LNK errors from the table. Done when: each code has a cause and fix.

   Error	Cause	Fix
   LNK2019: unresolved external	A .lib is missing from the link	Add it in project settings or /link foo.lib
   LNK2038: mismatch detected for 'RuntimeLibrary'	/MT and /MD objects mixed	One runtime for every object and library
   LNK1104: cannot open file 'foo.lib'	Library not on the search path	/LIBPATH:<dir> or the LIB variable
   LNK2005: already defined	A symbol defined in two objects	Remove the duplicate; __declspec(selectany) for intentionally repeated data
   LNK4098: defaultlib 'LIBCMT' conflicts	Runtime mismatch between libraries	Unify runtimes, or /NODEFAULTLIB:LIBCMT as documented for that warning

7. Answer inspection questions with the exact flag: /P writes preprocessed output to .i, /FA writes an assembly listing and /FAs interleaves source, /showIncludes prints the include tree, /analyze runs static analysis, /Za disables Microsoft extensions. Linker flags after /link: /SUBSYSTEM:CONSOLE or /SUBSYSTEM:WINDOWS, /DLL, /ENTRY:fn, /INCREMENTAL:NO, /LIBPATH:, /NODEFAULTLIB:. Done when: each question maps to one flag.

8. Confirm every flag: clang-cl /? lists the ones it accepts on any host; for cl.exe-only flags cite the Microsoft compiler-options reference. Done when: no unconfirmed flag remains.

Failure and recovery

Output

A chat report with the environment command, the translated flag set, the runtime choice with the rule that every object must match, the PDB flags, and the LNK entries that apply, each flag traced to clang-cl /? or the Microsoft reference.