msvc-cl

MSVC cl.exe と clang-cl

目的

Windows での C/C++ コンパイルについて、MSVC cl.exe、MSVC 互換ドライバーとしての clang-cl、MSBuild のプロジェクト設定、ランタイムライブラリの選択方法をエージェントに案内します。

トリガー

• 「コマンドラインから MSVC でコンパイルするにはどうすればよいですか？」
• 「-O2 に相当する MSVC のオプションは何ですか？」
• 「/MT と /MD のどちらを使えばよいですか？」
• 「cl.exe の代わりに clang-cl を使うにはどうすればよいですか？」
• 「Windows で LNK エラーが発生しています」
• 「PDB ファイルを生成するにはどうすればよいですか？」

ワークフロー

1. 環境を設定する

MSVC では Visual Studio の環境変数が必要です。開発者コマンド プロンプトを使うか、手動で設定します。

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 (動的)	リリース、DLL リンク（推奨されるデフォルト）
/MDd	MSVCRTd.dll (デバッグ動的)	デバッグビルド
/MT	静的 CRT	単独実行ファイル。DLL との混在は避けてください
/MTd	静的 CRT デバッグ	デバッグ + 静的

ルール： リンク時に使用するすべてのオブジェクトとライブラリで、同じランタイムを使う必要があります。/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 を参照してください。

関連スキル

• clang-cl の Clang ネイティブ診断には skills/compilers/clang を使います
• Windows での CMake ツールチェーン設定には skills/build-systems/cmake を使います
• MSVC でビルドしたバイナリのデバッグには skills/debuggers/lldb または WinDbg を使います