CMake で LLVM をビルドする

はじめに

CMake はクロスプラットフォームのビルドジェネレータツールです。CMake はプロジェクトをビルドするのではなく、LLVM をビルドするためのビルドツール (GNU make、Visual Studio など) で必要なファイルを生成します。

新規コントリビューター の方は、LLVM システム入門 ページから始めてください。このページは、従来の configure/make システムから移行する既存のコントリビューター向けです。

すぐにでも機能する LLVM ビルドを手に入れたい場合は、クイックスタート セクションに移動してください。CMake 初心者の方は、基本的な CMake の使い方 から始め、何をしているかを理解したら、クイックスタート セクションに戻ってください。オプションと変数 セクションは、ビルドをカスタマイズするためのリファレンスです。既に CMake の経験をお持ちの場合は、ここから始めることをお勧めします。

このページは、LLVM CMake ビルドのユーザー向けです。LLVM CMake ビルドシステムの変更に関する情報をお探しの場合は、CMake 入門 ページを参照してください。CMake 言語の基本的な概要が説明されています。

クイックスタート

ここでは、コマンドラインの非対話型 CMake インターフェースを使用します。

  1. CMake をダウンロードしてインストールします。バージョン 3.20.0 が最低限必要なバージョンです。

  2. シェルを開きます。開発ツールは、PATH 環境変数を介してこのシェルからアクセスできる必要があります。

  3. ビルドディレクトリを作成します。ソースディレクトリでの LLVM のビルドはサポートされていません。このディレクトリに cd します

    $ mkdir mybuilddir
$ cd mybuilddir

  4. シェルでこのコマンドを実行し、path/to/llvm/source/root を LLVM ソースツリーのルートへのパスに置き換えます。

    $ cmake path/to/llvm/source/root

    CMake は開発環境を検出し、一連のテストを実行し、LLVM のビルドに必要なファイルを生成します。CMake は、すべてのビルドパラメーターにデフォルト値を使用します。変更可能なビルドパラメーターのリストについては、オプションと変数 セクションを参照してください。

    CMake がツールセットを検出できない場合、または環境が十分に健全でないと判断した場合、これは失敗する可能性があります。この場合、使用する予定のツールセットがシェルからのみアクセス可能であり、シェル自体が開発環境に適していることを確認してください。たとえば、PATH 環境変数を介して POSIX シェルにアクセスできる場合、CMake は MinGW makefile のビルドを拒否します。CMake に特定のビルドツールを使用させることもできます。手順については、以下の 使い方 セクションを参照してください。また、LLVM が有効にするターゲット、またはビルドされる LLVM コンポーネントを制御することもできます。以下の よく使用される LLVM 関連の変数 を参照してください。

  5. CMake の実行が完了したら、IDE プロジェクトファイルを使用するか、ビルドディレクトリからビルドを開始します。

    $ cmake --build .

    --build オプションは、基礎となるビルドツール (make、ninja、xcodebuild、msbuild など) を呼び出すように cmake に指示します。

    もちろん、基礎となるビルドツールを直接呼び出すこともできますが、--build オプションは移植性があります。

  6. LLVM のビルドが完了したら、ビルドディレクトリからインストールします。

    $ cmake --build . --target install

    --build オプションに加えて、install パラメーターを指定した --target オプションは、install ターゲットをビルドするように cmake に指示します。

    ビルドディレクトリで生成された cmake_install.cmake スクリプトを呼び出すことで、インストール時に別のインストールプレフィックスを設定することができます。

    $ cmake -DCMAKE_INSTALL_PREFIX=/tmp/llvm -P cmake_install.cmake

基本的な CMake の使い方

このセクションでは、日常的な使用で必要となる可能性のある CMake の基本的な側面について説明します。

CMake には、html ファイルの形式で、および cmake 実行可能ファイル自体を介してアクセスできるオンラインヘルプとして、広範なドキュメントが付属しています。詳細なヘルプオプションについては、cmake --help を実行してください。

CMake では、ビルドツール (例: GNU make、Visual Studio、または Xcode) を指定できます。コマンドラインで指定しない場合、CMake は環境に基づいて、使用するビルドツールを推測しようとします。ビルドツールを特定すると、CMake は対応する *ジェネレータ* を使用して、ビルドツール用のファイル (例: Makefile または Visual Studio または Xcode プロジェクトファイル) を作成します。コマンドラインオプション -G "ジェネレータの名前" を使用して、ジェネレータを明示的に指定できます。システムで使用可能なジェネレータのリストを表示するには、次を実行します。

$ cmake --help

これにより、ヘルプテキストの最後にジェネレータ名が一覧表示されます。

ジェネレータの名前は大文字と小文字が区別され、スペースが含まれる場合があります。このため、cmake --help 出力にリストされているとおりに、引用符で囲んで正確に入力する必要があります。たとえば、Visual Studio 12 用に特別にプロジェクトファイルを生成するには、次を実行できます。

$ cmake -G "Visual Studio 12" path/to/llvm/source/root

特定の開発プラットフォームでは、複数の適切なジェネレータが存在する可能性があります。Visual Studio を使用する場合、"NMake Makefiles" は NMake を使用してビルドするために使用できるジェネレータです。デフォルトでは、CMake は開発環境でサポートされている最も具体的なジェネレータを選択します。別のジェネレータが必要な場合は、-G オプションを使用して CMake に指示する必要があります。

オプションと変数

変数は、ビルドがどのように生成されるかをカスタマイズします。オプションはブール変数で、可能な値は ON/OFF です。オプションと変数は、次のように CMake コマンドラインで定義されます。

$ cmake -DVARIABLE=value path/to/llvm/source

初期の CMake 呼び出し後に変数を設定して、その値を変更できます。変数の定義を解除することもできます。

$ cmake -UVARIABLE path/to/llvm/source

変数は CMake キャッシュに保存されます。これは、ビルドディレクトリのルートに保存され、cmake によって生成される CMakeCache.txt という名前のファイルです。自分で編集することはお勧めしません。

変数は、CMake キャッシュ内およびこのドキュメントで、変数名と型がコロンで区切られてリストされます。CMake コマンドラインで変数と型を指定することもできます。

$ cmake -DVARIABLE:TYPE=value path/to/llvm/source

よく使用される CMake 変数

これは、よく使用される CMake 変数の一部とその簡単な説明です。完全なドキュメントについては、CMake マニュアルを参照するか、cmake --help-variable VARIABLE_NAME を実行してください。LLVM の機能と有効化されたサブプロジェクトを制御する一般的に使用される変数については、以下の よく使用される LLVM 関連の変数 を参照してください。

CMAKE_BUILD_TYPE:STRING

これは、make または ninja ビルドの最適化レベルを構成します。

可能な値

ビルドタイプ

最適化

デバッグ情報

アサーション

最適な用途

リリース

速度優先

いいえ

いいえ

LLVM と Clang のユーザー

デバッグ

なし

はい

はい

LLVM の開発者

RelWithDebInfo

速度優先

はい

いいえ

デバッグも必要なユーザー

MinSizeRel

サイズ優先

いいえ

いいえ

ディスク容量が重要な場合

  • 最適化により LLVM/Clang の実行速度が向上しますが、ステップバイステップのデバッグの妨げになる可能性があります。

  • デバッグ情報を使用したビルドは、大量の RAM とディスク領域を使用する可能性があり、通常は実行に時間がかかります。lld を使用して RAM 使用量を改善できます。 LLVM_USE_LINKER オプションを参照してください。

  • アサーションは、バグを見つけるのに役立つ内部チェックです。有効にすると、通常、LLVM と Clang の速度が低下しますが、開発中に役立つ可能性があります。手動で LLVM_ENABLE_ASSERTIONS を設定して、CMAKE_BUILD_TYPE のデフォルトをオーバーライドできます。

Visual Studio や Xcode などの IDE を使用している場合は、IDE 設定を使用してビルドタイプを設定する必要があります。

注: Windows (MSVC または clang-cl でのビルド) では、CMake の RelWithDebInfo 設定は Release と同じ最適化を有効にしません。 LLVM_ENABLE_PDB を設定した Release ビルドタイプを使用する方が良い場合があります。

CMAKE_INSTALL_PREFIX:PATH

「install」ターゲットがビルドされたときに LLVM がインストールされるパス。

CMAKE_{C,CXX}_FLAGS:STRING

C および C++ ソースファイルをそれぞれコンパイルするときに使用する追加のフラグ。

CMAKE_{C,CXX}_COMPILER:STRING

使用する C および C++ コンパイラを指定します。複数のコンパイラがインストールされている場合、CMake が使用したいコンパイラをデフォルトにしないことがあります。

あまり使用されない CMake 変数

ここに、あまり使用されない CMake 変数とその簡単な説明と LLVM 関連のメモを示します。完全なドキュメントについては、CMake マニュアルを参照するか、cmake --help-variable VARIABLE_NAME を実行してください。

CMAKE_CXX_STANDARD:STRING

LLVM のビルド時に準拠する C++ 標準を設定します。可能な値は 17 と 20 です。LLVM には C++17 以上が必要です。デフォルトは 17 です。

CMAKE_INSTALL_BINDIR:PATH

CMAKE_INSTALL_PREFIX を基準とした、実行可能ファイルをインストールするパス。デフォルトは「bin」です。

CMAKE_INSTALL_DOCDIR:PATH

CMAKE_INSTALL_PREFIX を基準とした、ドキュメントをインストールするパス。デフォルトは「share/doc」です。

CMAKE_INSTALL_INCLUDEDIR:PATH

CMAKE_INSTALL_PREFIX を基準とした、ヘッダーファイルをインストールするパス。デフォルトは「include」です。

CMAKE_INSTALL_MANDIR:PATH

CMAKE_INSTALL_PREFIX を基準とした、man ページファイルをインストールするパス。デフォルトは「share/man」です。

CMakeキャッシュ

最近、LLVMとClangは、より複雑なビルドシステム機能を追加しています。これらの新機能を利用するには、コマンドラインで渡されるCMake変数の複雑なチェーンが必要になることがよくあります。Clangは、これらの機能をより簡単に利用できるように、CMakeキャッシュスクリプトのコレクションを提供しています。

CMakeキャッシュファイルは、CMakeの -C フラグを使用して利用します。

$ cmake -C <path to cache file> <path to sources>

CMakeキャッシュスクリプトは分離されたスコープで処理され、メイン構成が実行されるときにキャッシュされた変数のみが設定されたままになります。CMakeキャッシュ変数は、FORCEオプションが指定されていない限り、すでに設定されている変数をリセットしません。

CMakeキャッシュに関するいくつかの注意点

  • コマンドライン引数の順序は重要です。

    • -C の前に指定された -D 引数は、キャッシュが処理される前に設定され、キャッシュファイル内で読み取ることができます。

    • -C の後に指定された -D 引数は、キャッシュが処理された後に設定され、キャッシュファイル内では設定解除されます。

  • すべての -D 引数はキャッシュファイルの設定を上書きします。

  • CMAKE_TOOLCHAIN_FILE は、キャッシュファイルとコマンドライン引数の両方の後に評価されます。

  • すべての -D オプションは -C の *前* に指定することを推奨します。

キャッシュファイルを介してサポートされる高度なビルド構成の詳細については、高度なビルド構成を参照してください。

テストの実行

テストは、check-all ターゲットがビルドされたときに実行されます。たとえば、Makefilesを使用している場合は、ビルドディレクトリのルートで次のコマンドを実行します。

$ make check-all

Visual Studioでは、プロジェクト "check-all" をビルドすることでテストを実行できます。テストの詳細については、LLVMテストインフラストラクチャガイドを参照してください。

クロスコンパイル

CMakeでのクロスコンパイルの一般的な手順については、このWikiページを参照してください。詳細な説明がされており、難しく見えるかもしれませんが、そうではありません。Wikiページには、ツールチェーンファイルを含むいくつかの例があります。簡単な解決策については、Information how to set up various cross compiling toolchainsセクションに直接移動してください。

クロスコンパイル時に使用される変数については、LLVM関連の変数セクションも参照してください。

プロジェクトへのLLVMの埋め込み

LLVM 3.5以降、CMakeビルドシステムは、インポート可能なCMakeターゲットとしてLLVMライブラリをエクスポートします。つまり、LLVMのクライアントは、ビルド方法に関係なく、インストールされたLLVMバージョンに対して、CMakeを使用して独自のLLVMベースのプロジェクトを確実に開発できるようになりました。

以下は、LLVMライブラリをインポートし、それらを使用して単純なアプリケーションsimple-toolをビルドするCMakeLists.txtファイルの簡単な例です。

cmake_minimum_required(VERSION 3.20.0)
project(SimpleProject)

find_package(LLVM REQUIRED CONFIG)

message(STATUS "Found LLVM ${LLVM_PACKAGE_VERSION}")
message(STATUS "Using LLVMConfig.cmake in: ${LLVM_DIR}")

# Set your project compile flags.
# E.g. if using the C++ header files
# you will need to enable C++11 support
# for your compiler.

include_directories(${LLVM_INCLUDE_DIRS})
separate_arguments(LLVM_DEFINITIONS_LIST NATIVE_COMMAND ${LLVM_DEFINITIONS})
add_definitions(${LLVM_DEFINITIONS_LIST})

# Now build our tools
add_executable(simple-tool tool.cpp)

# Find the libraries that correspond to the LLVM components
# that we wish to use
llvm_map_components_to_libnames(llvm_libs support core irreader)

# Link against LLVM libraries
target_link_libraries(simple-tool ${llvm_libs})

CONFIGモードで使用される場合の find_package(...) ディレクティブは、（上記例のように）LLVMConfig.cmake ファイルをさまざまな場所で検索します（詳細についてはCMakeマニュアルを参照）。LLVMConfig.cmake が見つかったディレクトリを保存するために LLVM_DIR キャッシュエントリを作成するか、ユーザーがディレクトリを指定できるようにします（例：-DLLVM_DIR=/usr/lib/cmake/llvm を cmake コマンドに渡すか、ccmake または cmake-gui で直接設定するなど）。

このファイルは、2つの異なる場所にあります。

  • <LLVM_INSTALL_PACKAGE_DIR>/LLVMConfig.cmakeここで、<LLVM_INSTALL_PACKAGE_DIR> は、インストールされたLLVMの一部としてLLVM CMakeモジュールがインストールされる場所です。これは通常、libディレクトリ内の cmake/llvm/ です。Linuxでは、これは通常、/usr/lib/cmake/llvm/LLVMConfig.cmake です。

  • <LLVM_BUILD_ROOT>/lib/cmake/llvm/LLVMConfig.cmakeここで、<LLVM_BUILD_ROOT> はLLVMビルドツリーのルートです。**注：これは、CMakeでLLVMをビルドするときにのみ利用できます。**

LLVMがオペレーティングシステムの通常のインストールプレフィックス（例：Linuxでは通常 /usr/ ）にインストールされている場合、find_package(LLVM ...) はLLVMが正しくインストールされていれば自動的にLLVMを見つけます。LLVMがインストールされていない場合、またはLLVMビルドツリーに対して直接ビルドしたい場合は、前述のように LLVM_DIR を使用できます。

LLVMConfig.cmake ファイルは、さまざまな便利な変数を設定します。注目すべき変数には次のものがあります。

LLVM_CMAKE_DIR

LLVM CMakeディレクトリ（つまり、LLVMConfig.cmakeを含むディレクトリ）へのパス。

LLVM_DEFINITIONS

LLVMに対してビルドするときに使用する必要があるプリプロセッサ定義のリスト。

LLVM_ENABLE_ASSERTIONS

LLVMがアサーション付きでビルドされた場合はONに設定され、それ以外の場合はOFFに設定されます。

LLVM_ENABLE_EH

LLVMが例外処理（EH）を有効にしてビルドされた場合はONに設定され、それ以外の場合はOFFに設定されます。

LLVM_ENABLE_RTTI

LLVMが実行時型情報（RTTI）でビルドされた場合はONに設定され、それ以外の場合はOFFに設定されます。

LLVM_INCLUDE_DIRS

LLVMヘッダーファイルを含むディレクトリへのインクルードパスのリスト。

LLVM_PACKAGE_VERSION

LLVMバージョン。この文字列は、CMake条件付きで使用できます。たとえば、if (${LLVM_PACKAGE_VERSION} VERSION_LESS "3.5") などです。

LLVM_TOOLS_BINARY_DIR

LLVMツール（例：llvm-as）を含むディレクトリへのパス。

上記の例では、simple-tool をいくつかのLLVMライブラリに対してリンクしていることに注意してください。ライブラリのリストは、llvm_map_components_to_libnames() CMake関数を使用して決定されます。利用可能なコンポーネントのリストについては、llvm-config --components の実行結果を参照してください。

LLVM < 3.5 の場合、llvm_map_components_to_libraries() は llvm_map_components_to_libnames() の代わりに使用されていました。これは現在非推奨であり、将来のバージョンのLLVMで削除されます。

ソース外でのLLVMパスの開発

LLVMのソースツリー外（つまり、インストール済みまたはビルド済みのLLVMに対して）でLLVMパスを開発することができます。プロジェクトレイアウトの例を以下に示します。

<project dir>/
    |
    CMakeLists.txt
    <pass name>/
        |
        CMakeLists.txt
        Pass.cpp
        ...

<project dir>/CMakeLists.txt の内容

find_package(LLVM REQUIRED CONFIG)

separate_arguments(LLVM_DEFINITIONS_LIST NATIVE_COMMAND ${LLVM_DEFINITIONS})
add_definitions(${LLVM_DEFINITIONS_LIST})
include_directories(${LLVM_INCLUDE_DIRS})

add_subdirectory(<pass name>)

<project dir>/<pass name>/CMakeLists.txt の内容

add_library(LLVMPassname MODULE Pass.cpp)

このパスを将来LLVMソースツリーにマージする場合は、代わりにLLVMの内部 add_llvm_library 関数を MODULE 引数で使用するのがより適切かもしれません。具体的には…

<project dir>/CMakeLists.txt に（find_package(LLVM ...) の後）以下を追加します。

list(APPEND CMAKE_MODULE_PATH "${LLVM_CMAKE_DIR}")
include(AddLLVM)

次に、<project dir>/<pass name>/CMakeLists.txt を以下のように変更します。

add_llvm_library(LLVMPassname MODULE
  Pass.cpp
  )

パスの開発が完了したら、LLVMソースツリーに統合することができます。これは、2つの簡単なステップで実現できます。

  1. <pass name> フォルダを <LLVM root>/lib/Transforms ディレクトリにコピーします。

  2. add_subdirectory(<pass name>) 行を <LLVM root>/lib/Transforms/CMakeLists.txt に追加します。

コンパイラ/プラットフォーム固有のトピック

特定のコンパイラやプラットフォームに関する注意点。

Windows

LLVM_COMPILER_JOBS:STRING

msbuildまたはVisual Studioでビルドする場合に、プロジェクトごとに使用する並列コンパイラジョブの最大数を指定します。Visual Studio 2010 CMakeジェネレーターでのみサポートされます。0はすべてのプロセッサを使用することを意味します。デフォルトは0です。

CMAKE_MT:STRING

clang-clでコンパイルする場合、最近のCMakeバージョンでは、Microsoftの mt.exe の代わりにマニフェストツールとして llvm-mt を選択するのがデフォルトになります。これにより、次のようなエラーが発生することがよくあります。

-- Check for working C compiler: [...]clang-cl.exe - broken
[...]
    MT: command [...] failed (exit code 0x1) with the following output:
    llvm-mt: error: no libxml2
    ninja: build stopped: subcommand failed.

このエラーを回避するには、CMAKE_MT=mt を設定します。