ハロゲン化物
Halide
Halide は、最新のマシン上で高性能の画像および配列処理コードを簡単に作成できるように設計されたプログラミング言語です。ハライドは現在以下をターゲットにしています:
Halide はスタンドアロンのプログラミング言語ではなく、C++ に組み込まれています。これは、Halide の C++ API を使用して Halide パイプラインのメモリ内表現を構築する C++ コードを作成することを意味します。その後、この表現をオブジェクト ファイルにコンパイルすることも、JIT コンパイルして同じプロセスで実行することもできます。 Halide は、C++ を使用せずに Python に埋め込まれた Halide を作成するための完全なサポートを提供する Python バインディングも提供します。
Halide を使用するには C++17 (またはそれ以降) が必要です。
Halide の詳細については、https://halide-lang.org を参照してください。
API ドキュメントについては、https://halide-lang.org/docs を参照してください。
コード例については、https://halide-lang.org/tutorials にあるオンラインのチュートリアルを読んでください。対応するコードは、 tutorials/ディレクトリにあります。より大きな例はapps/ディレクトリにあります。
完全なソース配布を入手し、Halide をビルドしたい場合は、以下の注意事項を参照してください。
Halide 19.0.0 では、PyPI でバイナリ ホイールを提供しています。 Halide は、C++ と Python のバインディングを提供します。 C++ から Halide を使用するだけの場合でも、pip が Halide のバイナリ ビルドを入手する最も簡単な方法である可能性があります。
完全なリリースは、次のようにpipを使用してインストールできます。
$ pip install halide mainへのすべてのコミットは開発バージョンとして Test PyPI に公開され、これらはいくつかの追加フラグとともにインストールされる場合があります。
$ pip install halide --pre --extra-index-url https://test.pypi.org/simple現在、Windows x86-64、macOS x86-64、macOS arm64、Linux x86-64 用のホイールを提供しています。 Linux ホイールは manylinux_2_28 用に構築されているため、幅広い互換性があります (Debian 10、Ubuntu 18.10、Fedora 29)。
C++ で pip パッケージを使用する場合: Linux および macOS では、CMake のfind_packageコマンドは、Halide をインストールしたのと同じ仮想環境にいる限り、Halide を見つける必要があります。 Windows では、仮想環境のルート ディレクトリをCMAKE_PREFIX_PATHに追加する必要があります。 。これを行うには、 cmdでset CMAKE_PREFIX_PATH=%VIRTUAL_ENV%を実行します。
他のビルド システムはpython -c "import halide; print(halide.install_dir())"を実行することで Halide ルート パスを見つけることができます。
あるいは、macOS を使用している場合は、次のように Homebrew 経由で Halide をインストールできます。
$ brew install halide
Halide の最新バージョンは、GitHub (https://github.com/halide/Halide/releases) でいつでも見つけることができます。
当社は、32/64 ビット x86 Windows、64 ビット x86/ARM macOS、32/64 ビット x86/ARM Ubuntu Linux など、多くの一般的なプラットフォームおよびアーキテクチャ向けのバイナリ リリースを提供しています。
macOS リリースは、Apple Clang 500.2.76 で XCode のコマンドライン ツールを使用して構築されています。これは、libstdc++ ではなく libc++ に対してリンクすることを意味します。デフォルトが libc++ ではない古い XCode を使用している場合は、それに応じてコンパイラ オプションを調整する必要がある場合があります。
Linux リリースの構築には、最新の Ubuntu LTS を使用しています。ディストリビューションが古すぎる場合は、必要な glibc が含まれていない可能性があります。
Halide の夜間ビルドと CI で使用する LLVM バージョンは、https://buildbot.halide-lang.org/ からも入手できます。
vcpkg を使用して依存関係を管理する場合は、次の方法で Halide をインストールできます。
$ vcpkg install halide:x64-windows # or x64-linux/x64-osx
1 つの注意点: vcpkg は、アクティブなプラットフォーム用のコードをコンパイルするために必要な最小限の Halide バックエンドのみをインストールします。すべてのバックエンドを含めたい場合は、代わりにhalide[target-all]:x64-windowsをインストールする必要があります。これにより LLVM が構築されるため、大量のディスク容量 (最大 100GB) が必要になることに注意してください。
私たちは、Halide を他の人気のあるパッケージ マネージャーや Linux ディストリビューション リポジトリに導入することに興味があります。この GitHub 号では、Halide のさまざまなディストリビューションのステータスを追跡します。パッケージの公開経験がある方は、喜んでご協力させていただきます。
Halide に関連するプラットフォーム要件には 2 つあります。1 つは JIT または AOT モードでコンパイラ ライブラリを実行するために必要な要件、もう 1 つは AOT コンパイラのバイナリ出力を実行するために必要な要件です。
これらは、Halide コンパイラ ライブラリを構築および実行するためのテスト済みのホスト ツールチェーンとプラットフォームの組み合わせです。
| コンパイラ | バージョン | OS | アーキテクチャ |
|---|---|---|---|
| GCC | 9.5 | Ubuntu Linux 20.04 LTS | x86、x64 |
| GCC | 11.4 | Ubuntu Linux 22.04 LTS | ARM32、ARM64 |
| MSVC | 2022年 (19.37) | Windows 11 (22631) | x86、x64 |
| アップルクラング | 15.0.0 | macOS 14.4.1 | x64 |
| アップルクラング | 14.0.0 | macOS 14.6 | ARM64 |
一部のユーザーは、Clang 9.0.0 以降を使用して Linux 用、ClangCL 11.0.0 以降を使用して Windows 用、MSVC とのクロスコンパイルにより Windows ARM64 用の Halide をビルドすることに成功しました。ただし、これらのシナリオは積極的にテストしていないため、実際の走行距離は異なる場合があります。
これらを超えて、元のベンダーから引き続きアクティブなファーストパーティの公的サポートを受けているプラットフォームとツールチェーンの組み合わせを (PR を受け入れることで) 喜んでサポートします。たとえば、この記事の執筆時点では、これには Windows 7 は含まれておらず、Ubuntu 18.04 LTS が含まれています。
コンパイルされた AOT パイプラインは、より広範なプラットフォームをサポートすることが期待されています。バイナリは C ABI を使用しており、準拠する C コンパイラであれば生成されたヘッダーを正しく使用できることが期待されます。現在、C++ バインディングには C++17 が必要です。生成されたパイプラインの互換性の問題を発見した場合は、問題を報告してください。
Halide をビルドするには、どの時点でも、LLVM の最新の安定バージョン、LLVM の以前の安定バージョン、またはトランクのいずれかが必要です。この記事の執筆時点では、バージョン 19、18、17 はサポートされていますが、16 はサポートされていないことを意味します。
Homebrew を使用して、macOS 上で LLVM のバイナリ リリースを入手するのが最も簡単です。 brew install llvm実行するだけです。 Linux の Debian フレーバーでは、LLVM APT リポジトリが最適です。提供されているインストール スクリプトを使用します。 Windows に適切な公式バイナリ リリースはわかっていませんが、CI で使用するバイナリ リリースは通常、https://buildbot.halide-lang.org にあり、テスト済みの他のプラットフォーム用の tarball も入手できます。さらに詳しいアドバイスについては、以下の Windows に関するセクションを参照してください。
OS に LLVM 用のパッケージがない場合、または構成をより詳細に制御したい場合は、LLVM を自分で構築できます。まずは GitHub から確認してください。
$ git clone --depth 1 --branch llvmorg-18.1.8 https://github.com/llvm/llvm-project.git (LLVM 18.1.8 は、この記事の執筆時点で最も最近リリースされた LLVM です。現在のトランクの場合は、代わりにmainを使用してください)
次に、次のようにビルドします。
$ cmake -G Ninja -S llvm-project/llvm -B build
-DCMAKE_BUILD_TYPE=Release
-DLLVM_ENABLE_PROJECTS= " clang;lld;clang-tools-extra "
-DLLVM_ENABLE_RUNTIMES=compiler-rt
-DLLVM_TARGETS_TO_BUILD= " WebAssembly;X86;AArch64;ARM;Hexagon;NVPTX;PowerPC;RISCV "
-DLLVM_ENABLE_ASSERTIONS=ON
-DLLVM_ENABLE_EH=ON
-DLLVM_ENABLE_RTTI=ON
-DLLVM_ENABLE_HTTPLIB=OFF
-DLLVM_ENABLE_LIBEDIT=OFF
-DLLVM_ENABLE_LIBXML2=OFF
-DLLVM_ENABLE_TERMINFO=OFF
-DLLVM_ENABLE_ZLIB=OFF
-DLLVM_ENABLE_ZSTD=OFF
-DLLVM_BUILD_32_BITS=OFF
$ cmake --build build
$ cmake --install build --prefix llvm-installこれにより$PWD/llvm-installに動作する LLVM インストールが作成されます。後でこのパスをLLVM_ROOTと呼びます。このインストール ツリーとビルド ツリーを混同しないでください。
LLVM はビルドに時間がかかるため、上記のコマンドでは Ninja を使用して並列処理を最大化しています。 -G Ninjaを省略することを選択した場合は、代わりに Makefile が生成されます。この場合、 cmake --build build -j NNNで並列処理を有効にします。ここでNNNは並列ジョブの数、つまり、所有している CPU の数です。
clangとlld LLVM_ENABLE_PROJECTSに追加する必要があり、 WebAssemblyとX86 LLVM_TARGETS_TO_BUILDに含める必要があることに注意してください。 LLVM_ENABLE_RUNTIMES=compiler-rtファズ テストを構築する場合にのみ必要であり、 clang-tools-extra Halide にコードを提供する予定がある場合にのみ必要です (プル リクエストでclang-tidy実行できるようにするため)。 Python バインディングが不要な場合は、例外処理 (EH) と RTTI を無効にすることができます。開発中のビルドを簡素化するために、フルセットを有効にすることをお勧めします。
これについては、BuildingHalideWithCMake.md で詳しく説明されています。 Halide をビルドするには、CMake バージョン 3.28 以降が必要です。
上記の手順に従って LLVM を構築するか、適切なバイナリ リリースを取得します。次に、ディレクトリを Halide リポジトリに変更して、次を実行します。
$ cmake -G Ninja -S . -B build -DCMAKE_BUILD_TYPE=Release -DHalide_LLVM_ROOT= $LLVM_ROOT
$ cmake --build build適切なシステム全体のバージョンがインストールされている場合、 -DHalide_LLVM_ROOT設定する必要はありません。ただし、複数の LLVM がインストールされている場合は、そのうちの LLVM を選択できます。
Visual Studio 2022 でビルドすることをお勧めします。以前のバージョンでは使用できる距離が異なる場合があります。 Visual Studio インストーラーで「C++ CMake tools for Windows」を必ずインストールしてください。 Visual Studio の古いバージョンの場合は、CMake ツールをインストールせず、それぞれのプロジェクト Web サイトから CMake と Ninja を入手してください。
これらの手順はD:ドライブから始まります。この git リポジトリはD:Halideに複製されると仮定します。また、シェル環境が正しく設定されていることも前提としています。 64 ビット ビルドの場合は、次を実行します。
D:> "C:Program Files (x86)Microsoft Visual Studio2022CommunityVCAuxiliaryBuildvcvarsall.bat" x64
32 ビット ビルドの場合は、次を実行します。
D:> "C:Program Files (x86)Microsoft Visual Studio2022CommunityVCAuxiliaryBuildvcvarsall.bat" x64_x86
Windows 上で互換性のある依存関係を取得する最良の方法は、vcpkg を使用することです。次のようにインストールします。
D:> git clone https://github.com/Microsoft/vcpkg.git
D:> cd vcpkg
D:vcpkg> .bootstrap-vcpkg.bat -disableMetrics
...
CMake projects should use: "-DCMAKE_TOOLCHAIN_FILE=D:/vcpkg/scripts/buildsystems/vcpkg.cmake"
ツールチェーン ファイルを使用すると、vcpkg は必要な依存関係をすべて自動的に構築します。ただし、上で述べたように、この方法で LLVM を取得すると、ビルド ツリーに 100 GB を超えるディスク領域が使用され、ビルドに非常に長い時間がかかる可能性があることに注意してください。後でビルド ツリーを手動で削除することもできますが、vcpkg はこれを自動的に削除しません。
LLVM以外のすべてに Vcpkg を使用する手順については、BuildingHalideWithCMake.md を参照してください。
別のビルド ツリーを作成し、vcpkg のツールチェーンを使用して CMake を呼び出します。これは、以前に実行された環境スクリプト ( vcvars ) に応じて、32 ビットまたは 64 ビットのいずれかでビルドされます。
D:Halide> cmake -G Ninja -S . -B build ^
--toolchain D:/vcpkg/scripts/buildsystems/vcpkg.cmake ^
-DCMAKE_BUILD_TYPE=Release
次に、次のようにしてビルドを実行します。
D:Halide> cmake --build build
すべてのテストを実行するには:
D:Halide> ctest --test-dir build --output-on-failure
テストのサブセットは-Lで選択でき、 tests/の下に、 correctness 、 generator 、 error 、およびその他のディレクトリ名が含まれます。
LLVM を自分で構築する場合は、次の手順に従ってください。まず、LLVM のソースをダウンロードします (これらの手順では 18.1.8 リリースを使用します)。
D:> git clone --depth 1 --branch llvm-org-18.1.8 https://github.com/llvm/llvm-project.git
上記と同様に、 vcvarsall.bat実行して x86 と x64 のどちらかを選択します。次に、次のコマンドを使用して LLVM を構成します (32 ビットの場合は、代わりに-DLLVM_BUILD_32_BITS=ONを設定します)。
D:> cmake -G Ninja -S llvm-projectllvm -B build ^
-DCMAKE_BUILD_TYPE=Release ^
-DLLVM_ENABLE_PROJECTS=clang;lld;clang-tools-extra ^
-DLLVM_ENABLE_RUNTIMES=compiler-rt ^
-DLLVM_TARGETS_TO_BUILD=WebAssembly;X86;AArch64;ARM;Hexagon;NVPTX;PowerPC;RISCV ^
-DLLVM_ENABLE_ASSERTIONS=ON ^
-DLLVM_ENABLE_EH=ON ^
-DLLVM_ENABLE_RTTI=ON ^
-DLLVM_ENABLE_HTTPLIB=OFF ^
-DLLVM_ENABLE_LIBEDIT=OFF ^
-DLLVM_ENABLE_LIBXML2=OFF ^
-DLLVM_ENABLE_TERMINFO=OFF ^
-DLLVM_ENABLE_ZLIB=OFF ^
-DLLVM_ENABLE_ZSTD=OFF ^
-DLLVM_BUILD_32_BITS=OFF
MSBuild: Ninja ではなく MSBuild で LLVM をビルドする場合は、 -G Ninjaの代わりに-G "Visual Studio 17 2022" -Thost=x64 -A x64または-G "Visual Studio 17 2022" -Thost=x64 -A Win32を使用します。 -G Ninja 。
最後に、ビルドを実行してローカル ディレクトリにインストールします。
D:> cmake --build build --config Release
D:> cmake --install build --prefix llvm-install
デバッグ ビルドが必要な場合は、上記のcmakeコマンドのReleaseをDebugに置き換えることができます。
これを Halide で使用しながら、vcpkg で他の依存関係を管理できるようにするには、Halide の CMake configure コマンド ラインに 2 つのフラグを追加する必要があります。まず、 -DVCPKG_OVERLAY_PORTS=cmake/vcpkgを使用して LLVM を無効にします。次に、 -DHalide_LLVM_ROOT=D:/llvm-installを使用して、CMake が新しく構築された Halide を指すようにします。
buildbot が行うことを実行します: https://buildbot.halide-lang.org/master/#/builders
ご使用のシステムに最もよく一致する行が赤色の場合は、問題が発生しているだけではない可能性があります。緑色の場合は、最新のビルドをクリックして、ビルド ボットが実行するコマンドを確認できます。ステップを開き (「Configure Halide」が便利です)、ビューアで「stdio」ログを確認します。これらのログには、実行された完全なコマンドと、それらの実行に使用された環境変数が含まれています。
警告
Makefile のサポートは提供しておりません。自由に使用できますが、何か問題が発生した場合は、CMake ビルドに切り替えてください。 Makefile では Python バインディングを構築したり、インストール パッケージを生成したりできないことにも注意してください。
TL;DR : LLVM 17 (またはそれ以降) をインストールし、リポジトリ (この README がある場所) のルート ディレクトリでmakeを実行します。
デフォルトでは、 make PATHにあるllvm-configツールを使用します。上記の手順に従ってカスタム構築されたものなど、別の LLVM を使用する場合は、次の環境変数を設定します。
$ export LLVM_CONFIG= " $LLVM_ROOT /bin/llvm-config "これで、Halide ソース ツリーのルート ディレクトリでmake実行できるようになります。 make run_tests JIT テスト スイートを実行し、 make test_appsすべてのアプリがコンパイルおよび実行されることを確認します (ただし、出力はチェックしません)。
テストを構築するとき、 HL_TARGET環境変数を使用して AOT コンパイル ターゲットを設定できます。
Halide を別のディレクトリにビルドしたい場合は、次のように実行できます。
$ cd ..
$ mkdir halide_build
$ cd halide_build
$ make -f ../Halide/MakefileHL_JIT_TARGET=... Halide の JIT コンパイル ターゲットを設定します。
HL_DEBUG_CODEGEN=1 Halide がコンパイルしているものの疑似コードを出力します。数値が大きいほど詳細が印刷されます。
HL_NUM_THREADS=...スレッド プールに作成するスレッドの数を指定します。非同期スケジューリング ディレクティブが使用される場合、この数よりも多くのスレッドが必要となり、割り当てられる可能性があります。最大 256 スレッドが許可されます。 (デフォルトでは、ホスト上のコアの数が使用されます。)
HL_TRACE_FILE=...トレース データをダンプするバイナリ ターゲット ファイルを指定します (ターゲットで少なくとも 1 つのtrace_機能が有効になっていない限り無視されます)。出力は、 utils/HalideTraceViz.cppのコードから開始してプログラムで解析できます。
doc/にはさらに多くのドキュメントがあります。次のリンクが役立つかもしれません。
| 書類 | 説明 |
|---|---|
| CMake ビルド | CMake を使用して Halide を構成およびビルドする方法。 |
| CMake パッケージ | Halide CMake パッケージを使用してコードをビルドする方法。 |
| 六角形 | Hexagon バックエンドの使用方法。 |
| パイソン | Python バインディングのドキュメント。 |
| ランジェン | RunGen インターフェイスを使用して任意のパイプラインを実行およびベンチマークする方法。 |
| バルカン | Halide Vulkan バックエンド (ベータ版) の使用方法 |
| Webアセンブリ | WebAssembly バックエンドの使用方法と、wabt の代わりに V8 を使用する方法。 |
| WebGPU | WebGPU パイプラインを実行する方法 (ベータ版) |
Halide にコードを貢献したい開発者にとって、次のリンクは非常に興味深いものです。
| 書類 | 説明 |
|---|---|
| CMake開発者 | 新しい CMake コードを作成するためのガイドライン。 |
| ファズテスト | Halide コンパイラ (パイプラインではなく) のファズ テストに関する情報。社内開発者を対象としています。 |
