Clang API。 開始する

自己記述C ++パーサーの時代は徐々に過去に向かっていると言っても過言ではありません。 Clangは本格的なC ++フロントエンドおよびコンパイラであり、ユーザーに豊富なAPIを提供しますが、ゆっくりと容赦なくシーンに登場します。 このAPIを使用して、ソースコードをC / C ++ / Objective-Cに解析し、そこからすべての必要な情報を抽出できます-トークンの単純な字句の意味から、シンボルテーブル、ASTツリー、さまざまな問題の静的コード分析の結果まで。 llvmと連携し、強い要望があれば、C ++をスクリプト言語として使用して、C ++プログラムをその場で解析および実行できます。 一般に、プログラマーに開かれた機会は豊富であり、それらを正しく使用する方法を理解する必要があります。 そして、ここで、それはしばしば起こります、そして、楽しみは始まります。

1. Clangまたはclang-c？

clang開発者が顧客に2種類のAPIを提供するという事実から始める必要があります。 1つ目は完全に「ポジティブ」ですが、...潜在的に不安定です（バージョンによって異なる可能性があるという意味で）。 2番目は安定していることが保証されていますが、...純粋に「syishnoe」です。 状況に応じて、またはclangに基づいて開発された製品のニーズに基づいて、どちらを優先するかを選択する必要があります。

1.1 clang-c API

clangソースツリーでは、このライブラリの実装はtoolsブランチにあります（clangコアの実装自体はlibにあります）。 このライブラリは、動的にロードされるモジュールにコンパイルされ、そのインターフェースはクライアントに多くの保証を提供します。

1. 安定性と下位互換性。 クライアントは、何かが落ちたり、さらに悪いことに収集を停止することを恐れることなく、独自のコードのために、clangのあるバージョンから別のバージョンに安全に切り替えることができます。
2. 実行時に、使用されたclang実装の機能を決定し、それらに適応する可能性があります。
3. 高いフォールトトレランス-clangカーネルの致命的なエラーは、クライアントクラッシュにつながりません。
4. 重いアクティビティ（解析など）の独自のフロー制御。
5. コンパイラとAPIのすべての機能は、動的にロードされる1つのライブラリの形式でアセンブルされるため、フロントエンド自体をコンパイルする必要はありません。

ただし、記載されている特典を利用するには支払いが必要です。 したがって、clang-c APIには次の一連の欠点があります。

1. 「ボトル入りの船」パターンに従って設計します。 このAPIのクライアントが対話するエンティティは、本質的にclang APIによって提供される元のクラスのラッパーです。
2. （結果として）手動のリソース管理。 C ++コードから便利に使用するには、RAIIを提供するラッパーを作成する必要があります。
3. 非常に「狭い」インターフェース。 クライアントには、カーネルと対話するためのCメソッドとタイプの小さなセットが提供されます。
4. （結果として）機能のかなり貧弱なセット。 clang APIによって提供されるツールの多くは、クライアントが単に利用できないか、簡略化された形式で提供されます。

既存の「プラス」のセットがクライアントコードに不可欠な場合に、このAPIオプションを使用することは理にかなっています。 まあ、または「短所」はそれほど基本的ではありません。 このAPIは、ソーステキスト（ASTの形式とソーステキスト内の各特定のトークンのセマンティックロードの形式の両方）からセマンティック情報を抽出するのに非常に適しています。タスク。 したがって、さまざまな種類のスタンドアロンのトランスレータ、メタ情報ジェネレータ、静的アナライザ、コード検証などに適しています。

また、このAPIは、より高いパフォーマンスが必要なタスク、またはコンパイラコアとのより緊密な相互作用にあまり適していません。

1.2 clang API

このバージョンのAPIは、本質的にコンパイラコア自体のインターフェイスです。 このAPIは純粋にC ++であり、clangカーネルのすべての機能への幅広いアクセスを提供します。 その利点は次のとおりです。

1. 既に述べたように、コンパイラのすべての機能への直接かつ便利なアクセス。
2. 便利な（少なくともclang-cと比較して）インターフェース。
3. 多数のさまざまなカスタマイズ。
4. わずかに高いパフォーマンス（clang-cと比較）。

そして、その結果の一部として、デメリット：

1. カーネル内部で発生する可能性のあるクラッシュによるクライアントの不安。
2. インターフェイスの下位互換性が保証されていません。
3. 静的ライブラリの形式で配信。 クライアントはカーネルに直接リンクするように強制され、その結果、構成のためにclangとllvmを収集します。
4. 「冗長性」。 （clang-c APIと比較して）多くのソースコードシナリオで、より多くが取得されます。
5. すべてが文書化されているわけではありません。
6. llvm APIとの高度な接続性。 llvmがないと、clangを使用できません。 我慢する必要があります。

欠点がどれほど重要であり、それらが利点を上回るかどうか-状況を決定する必要があります。 私の意見では、clangを使用するこのオプションはどこでも選択する必要があり、良好なパフォーマンスまたはclang-cで利用できない特定の機能へのアクセスが必要です。 特に、IDEのオンザフライパーサーとしてclangを使用する場合、この特定のAPIバリアントを使用することは理にかなっています。

2.はじめに、またはソーステキストの解析

そして、なぜ、このclangが必要なのでしょうか？ 実際、開発者が関心のある情報をソースコードから抽出したり、バイトコードに変換したりするためにソースコードを解析することは、clangフロントエンドの主なタスクです。 この問題を解決するために、clangは豊富な機会を提供します。 おそらくあまりにも豊かです。 私が最初にclangの例の1つを開いたとき、私は少し驚いたことを認めなければなりません-それで行われた操作は、この非常に構文解析がどのように見えるべきかについての直感的なアイデアと一致しなかったため、黒魔術の領域から私には思えました。 最終的に、すべてが非常に論理的であることが判明しましたが、コマンドライン引数を記述する文字列の配列を渡すことによって解析オプションを設定することは、まだ私にとってややがっかりです。

2.1 clang-cを使用した解析

私のclangの知識が、このAPIに基づいて構築された例から始まる場合、それほど驚きはありません。 実際、ファイルの解析は2つの呼び出しで行われます。 最初はCXIndexオブジェクトのインスタンスを作成し、2番目はソーステキストの実際の分析とASTの構築を開始します。 ソースコードでは次のようになります。

#include <iostream> #include <clang-c/Index.h> int main (int argc, char** argv) { CXIndex index = clang_createIndex ( false, // excludeDeclarationFromPCH true // displayDiagnostics ); CXTranslationUnit unit = clang_parseTranslationUnit ( index, // CIdx "main.cpp", // source_filename argv + 1 , // command_line_args argc - 1 , // num_command_line_args 0, // unsave_files 0, // num_unsaved_files CXTranslationUnit_None // options ); if (unit != 0 ) std::cout << "Translation unit successfully created" << std::endl; else std::cout << "Translation unit was not created" << std::endl; clang_disposeTranslationUnit(unit); clang_disposeIndex(index); }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

最初のメソッド（ clang_createIndex ）は、翻訳単位（ CXTranslationUnit ）のインスタンスが作成および解析されるコンテキストを作成します。 2つのパラメーターが必要です。 最初の（ excludeDeclarationsFromPCH ）は、結果のASTのクロール中にプリコンパイル済みヘッダーから読み取られる広告の可視性を制御します。 値が1の場合、そのような広告は最終ASTから除外されます。 2番目のパラメーター（ displayDiagnostics ）は、コンソールへのブロードキャスト中に受信した診断の出力を制御します。

2番目のメソッド（ clang_parseTranslationUnit ）は、ソースファイル自体を解析します。 このメソッドには、次のパラメーターがあります。

• CIdxは、 clang_createIndexを呼び出して作成されたコンテキストへのポインターです。
• source_filename-解析するファイルへのパス。
• command_line_args-コンパイラオプションに変換されるコマンドライン引数。
• num_command_line_args-前のパラメーターとして渡されたコマンドラインの引数の数。
• unsaved_files-実際の内容がディスクではなくメモリにあるファイルのコレクション。
• num_unsaved_files-記録されていないファイルのコレクション内の要素の数。
• options-追加の解析オプション。

ご覧のとおり、すべてのパーサー構成は、パーサーのコマンドライン引数をテキスト形式で渡すことによって行われます。 unsaved_filesパラメーターは 、エディターまたはIDEからのclangスクリプトで役立ちます。 これを使用すると、ユーザーによって変更されたがまだディスクに保存されていないファイルをパーサーに転送できます。 これは、ファイル名、そのコンテンツ、およびコンテンツのサイズ（バイト単位）を含むCXUnsavedFile型の構造体のコレクションです。 名前と内容はCラインとして指定され、サイズは符号なし整数として指定されます。

最後のパラメーター（ options ）は、次のフラグのセットです。

• CXTranslationUnit_None-ここではすべてが明らかです。 特別な解析オプションは設定されていません。
• CXTranslationUnit_DetailedPreprocessingRecord-このオプションを設定すると、ソーステキストでプリプロセッサが使用される方法と場所に関する詳細情報をパーサーが生成する必要があることを示します。 ドキュメントに示されているように、めったに使用されないオプションは大量のメモリを消費し、そのような情報が本当に必要な場合にのみインストールする価値があります。
• CXTranslationUnit_Incomplete-このオプションを設定すると、 不完全な （ 不完全な ）翻訳単位が処理されていることを示します。 たとえば、ヘッダーファイル。 この場合、翻訳者は、ブロードキャストが終了する前にインスタンス化する必要があるパターンをインスタンス化しようとしません。
• CXTranslationUnit_PrecompiledPreamble-このオプションを設定すると、翻訳ユニットの先頭に含まれるすべてのヘッダーファイルに対して、パーサーがプリコンパイル済みヘッダーを自動的に作成する必要があることを示します。 このオプションは、ファイルが頻繁に再解析される場合（clang_reparseTranslationUnitメソッドを使用）に便利ですが、次のセクションで説明する独自の特性があります。
• CXTranslationUnit_CacheCompletionResults-このオプションを設定すると、その後の各再解析後に、コード補完の結果の一部が保存されるという事実につながります。
• CXTranslationUnit_SkipFunctionBodies-このオプションを設定すると、変換プロセス中に関数とメソッドの本体が処理されないという事実につながります。 特定のキャラクターのアナウンスや定義をすばやく検索するのに便利です。

フラグは、「|」操作を使用して結合できます。



最後の2つのメソッド（ clang_disposeTranslationUnitおよびclang_disposeIndex ）は、翻訳単位とコンテキストを記述する以前に作成されたハンドルを削除します。

このサンプルコードを正常にビルドするには、libclangライブラリを接続するだけです。

2.1 clang APIを使用した解析

clang APIを使用した同様の（機能）コードは次のとおりです。

 #include <vector> #include <iostream> #include <clang/Basic/Diagnostic.h> #include <clang/Frontend/DiagnosticOptions.h> #include <clang/Frontend/CompilerInstance.h> #include <clang/Frontend/CompilerInvocation.h> #include <clang/Frontend/Utils.h> #include <clang/Frontend/ASTUnit.h> int main(int argc, char ** argv) { using namespace clang ; using namespace llvm ; // Initialize compiler options list std::vector< const char *> args; for (int n = 1; n < argc; ++ n) args.push_back(argv[n]); args.push_back("main_clang.cpp" ); const char** opts = &args.front(); int opts_num = args.size(); // Create and setup diagnostic consumer DiagnosticOptions diagOpts; IntrusiveRefCntPtr< DiagnosticsEngine> diags(CompilerInstance::createDiagnostics( diagOpts, // Opts opts_num, // Argc opts, // Argv 0, // Client true, // ShouldOwnClient false // ShouldCloneClient )); // Create compiler invocation IntrusiveRefCntPtr< CompilerInvocation> compInvoke = clang::createInvocationFromCommandLine( makeArrayRef(opts, opts + opts_num), // Args diags // Diags ); if (!compInvoke) { std::cout << "Can't create compiler invocation for given args" ; return -1; } // Parse file clang::ASTUnit *tu = ASTUnit ::LoadFromCompilerInvocation( compInvoke.getPtr(), // CI diags, // Diags false, // OnlyLocalDecls true, // CaptureDiagnostics false, // PrecompilePreamble TU_Complete, // TUKind false // CacheCodeCompletionResults ); if (tu == 0 ) std::cout << "Translation unit was not created" ; else std::cout << "Translation unit successfully created" ; return 0; }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

さらに多くの文字があり、アセンブリには、 clangLex、clangBasic、clangAST、clangSerialization、clangEdit、clangAnalysis、clangFrontend、clangSema、clangDriver、clangParse、LLVMCore、LLVMMC 、およびLLVMSupportのセットが必要です。 Windowsでビルドする場合は、advapi32とshell32も追加する必要があります。 ただし、出力は、不必要な外部依存関係のない実行可能モジュールになります。

上記のコードは4つの部分に分けることができます。

1. コンパイラーのコマンド行パラメーターのコレクションの形成。 このバージョンのAPIでは、解析する必要があるファイルへのパスもコレクションの要素の1つとして送信されるため、この場合、argvとargcを直接渡すことはできません。
2. 診断エンジンのインスタンスを作成します。 このクラスのオブジェクトは、ソーステキストの解析プロセスでパーサーが生成できるすべてのエラーメッセージ、警告、およびその他の診断を収集および保存します。
3. コンパイラー呼び出しのインスタンスを作成します。
4. 実際にソーステキストを解析します。

コマンドライン引数のコレクションを構築する

上記で書いたように、clangを操作するためのオプションは、対応するクラスクラスにこれらの設定を記述する文字列のコレクションを渡すことで設定されます。 文字列はポインタの配列として渡され、中間ベクトルを使用してこれを行うのが最も便利です。 この場合、任意の数の外部から受け取った引数に追加できます。 特に、解析するファイルの名前。

診断エンジンの作成

DEの作成は、ソーステキストの解析プロセスで生成されるパーサーclangからさまざまな診断情報を受信するために必要です。 表示されるエラーの最大数、表示するエラー/警告などのパラメーター。DEはコマンドラインから取得し、2番目と3番目のパラメーターによって送信されます。 最後の3つのパラメーターは、「診断クライアント」を説明しています。 これは、ユーザーclangに固有の方法でさらに処理するためにDEがパーサーメッセージを（発生時に）送る特別なクラスです。 DEはクライアントの存続期間を制御したり、転送されたオブジェクトのクローンを操作したりできます。 これにより、さまざまなクライアント実装シナリオを使用できます-静的/自動オブジェクトの形式、ヒープ上のオブジェクトの形式、clang APIを操作するメソッドを持つクラスの一部など

コンパイラー呼び出しの作成

実際、このステップでは、解析が実行されるコンテキストが作成されます。 転送されたコマンドラインのすべてのパラメーター、環境変数が分析され、内部インフラストラクチャ全体が（これらのパラメーターに従って）作成され、診断エンジンが接続されます。 その後、clangは最後のパラメーターとして渡されたファイルを解析する準備が完全に整います。

ソーステキストの解析

これは、clangクラスの静的メソッドの1つであるASTUnitを呼び出すことで実行されます。 そのような方法はいくつかあり、さまざまなシナリオに合わせて強化されています。 この例は、可能なオプションの1つを示しています。 この場合、コンパイラー呼び出しインスタンスはパーサー（パーサーは後で削除します！）、診断エンジンインスタンス（そのパーサーは自動的に削除されません）、およびパーサーの動作を制御するいくつかのパラメーターに渡されます。

• OnlyLocalDecls-解析された翻訳単位からの宣言のみが最終ASTに含まれます。 PCHおよび添付ヘッダーファイルからの宣言は除外されます。
• CaptureDiagnostic-診断の収集方法を制御します。 このパラメーターとしてfalseが渡された場合、収集されたすべての診断は、診断エンジンの作成時に指定された診断クライアントに渡されます。 それ以外の場合、診断はASTUnitの内部構造に保存されます。
• PrecompilePreamble-前述のように、このオプションを有効にすると、パーサーはソーステキストに含まれるすべてのヘッダーに対してPCHを自動的に作成します。 はい、そうです。 繰り返し解析に役立ちます。 しかし、判明したように、いくつかの非常に楽しい瞬間はありません。 まず、実際には、結果のASTUnitインスタンスに対してASTUnit :: Reparseメソッドが最初に呼び出されたときにPCHが作成されます。 第二に、＃ifdef-guardsを含むヘッダーファイルが解析された場合、悲しいかな、何も作成されません。
• TUKind-翻訳単位のタイプ。 ここでは次のオプションが可能です。
  
  
  • TU_Complete-完全に完成した翻訳単位が解析されます。 この場合、ソーステキストで使用されるテンプレートのすべてのインスタンスも最終ASTに配置されます。
  • TU_Prefix- 「翻訳単位のプレフィックス」が解析されます。この場合、ソーステキストは完全とは見なされません。
  • TU_Module-一部の「モジュール」が解析されます。 それは何ですか-ドキュメントはサイレントです。
• CacheCodeCompletionResults-解析中にコード補完結果がキャッシュされます。 後続のコード完了要求に本当に役立ちます。

3.オプションセットの小さなコツ

私の最初の実験（宣言を抽出するためのヘッダーファイルの解析でした）では、解析が多くのエラーで終了した理由を長い間理解していませんでした。 最終的に、すべてが非常にシンプルであることが判明しました。 そのため、役立つオプション：

• -x language-解析するファイルの特定のタイプを指定します。 同様のgccコンパイラオプションと互換性があります。
• -std = standard-ソーステキストが対応する標準を指定します。 gccコンパイラオプションと互換性があります。
• -ferror-limit = N-解析が完了するまでのエラーの最大数をNに設定します。 エラーを完全に無視してファイルを解析する場合、Nは0に等しくなければなりません。
• -include <prefix-file> -メインファイルを解析する前に解析するファイル（通常はヘッダー）を指定します。 一般に、このオプションは元々PCHヘッダーを含めることを目的としていますが、ファイルを解析するとき、たとえばさまざまなマクロを定義するのに役立ちます。

これに関して、clang APIの最初の知識は完全であると考えることができます。 clang-c APIの詳細については、公式のclang Webサイトclang.llvm.org/doxygen/group__CINDEX.htmlをご覧ください。

ここで 、clang APIクラスの階層全体に慣れることができます。 残念ながら、ドキュメントはアップストリームのclangから自動的に生成されるため、ドキュメントと共にWebサイトで説明されている関数のシグネチャやそのセットなどは、特定のリリースで提示されているものと異なる場合があります。



次の記事では、clangで作成されたASTから宣言ツリーを取得する方法について説明します。