Clangd and Compilation Databases

clangd は仮想コンパイラーコマンドで開いている各ファイルを解析し、C および C++ の言語サーバー機能を提供します。 補完、診断、ナビゲーション、リファクタリングが信頼できるのは、そのコマンドが実際のビルドコンテキスト （作業ディレクトリ、コンパイラードライバー、ターゲット、言語モード、インクルードパス、プリプロセッサー定義、生成ヘッダー）を表している場合だけです。

コンパイルコマンドの指定 #

コンパイルデータベースが推奨される唯一の基準です。compile_commands.json には各翻訳単位のコマンドと作業ディレクトリが含まれます。 CMake はビルドツリー向けにこれを出力できます。

cmake -S . -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
clangd --compile-commands-dir=build

[
  {
    "directory": "/work/project",
    "file": "src/main.cc",
    "command": "clang++ -Iinclude -std=c++20 -c src/main.cc"
  }
]

--compile-commands-dir を指定しない場合、clangd は開いたファイルのディレクトリから親ディレクトリへ向かって compile_commands.json または compile_flags.txt を検索します。compile_flags.txt はより単純な代替手段であり、 すべてのファイルに 1 行 1 フラグを適用するため、翻訳単位ごとにフラグが異なるターゲットは表現できません。

-Iinclude
-std=c++20
-Wall

正式なビルドからデータベースを生成し、ワークスペースから発見できるようにします。リポジトリルートからのシンボリックリンク、 エディター設定、--compile-commands-dir のいずれも有効です。コピーすると古いコマンドが残る危険があります。 ネイティブ対応のないビルドシステムでは Bear のようなツールでクリーンビルドを観測できますが、 生成されたコマンドは開発者が開く設定を依然として記述していなければなりません。

ヘッダー、新規ファイル、フラグ調整 #

ビルドシステムはヘッダーを直接コンパイルしません。ヘッダーについて clangd はまず、それをインクルードする開いたソースのコマンドを再利用し、 それがなければファイル名が似たデータベースエントリを選択します。マルチプラットフォームのツリーでは、このヒューリスティックが誤ったターゲットを選ぶ可能性があります。 まずインクルード元のソースを開くか、主要ソースと一貫した名前をヘッダーに付けるか、プロジェクト設定で意図したコンテキストを明確にします。

データベースにないファイルにはフォールバックコマンドが適用されます。フォールバックで解析はできますが、 ビルドが提供するターゲット固有のインクルードパス、マクロ、生成ヘッダー、言語モードはありません。 診断は暫定的なものとして扱い、新しいターゲットを編集する前にソースをビルドへ追加するか設定を提供します。

.clangd can adjust commands without duplicating the database:

CompileFlags:
  Add: [-Ithird_party/api, -DMY_EDITOR_BUILD=1]
  Remove: [-Werror]

調整はエディター専用の補正や clangd が利用できないフラグに使い、ビルドコマンドを手作業で再構築するためには使いません。 可能な限りコンパイラー実行ファイルを維持してください。その場所と名前が標準ライブラリの既定検索や言語選択に影響するためです。

誤ったコンテキストの診断 #

Run a single-file check and inspect the selected command:

clangd --check=src/main.cc --log=verbose

詳細ログには、コンパイルデータベース、作業ディレクトリ、調整後のコマンドが示されます。 ヘッダーが見つからない場合は、-I、-isystem、sysroot、生成ヘッダーのパスを実際のコンパイル呼び出しと比較します。 解析で誤った方言が使われる場合は、-x、-std=、Objective-C と C++ の違い、コンパイラードライバーを確認します。 組み込み型や ABI 依存型が異なる場合は、--target、ツールチェーンのパス、SDK フラグを確認します。

ビルドオプション、依存関係、生成ソースを変更した後はデータベースを再生成します。 clangd が出力を使用する前にコード生成器が実行されるようにするか、生成されたインクルードディレクトリとコミット済みのインターフェースヘッダーを提供します。 LSP サーバーを追加の clangd フラグ 付きで起動することと、ファイルの コンパイルコマンド を変更することは別です。 ソースの意味論には後者を使います。