Halogenid
Halide
Halide ist eine Programmiersprache, die das Schreiben von leistungsstarkem Bild- und Array-Verarbeitungscode auf modernen Maschinen erleichtern soll. Halide zielt derzeit auf Folgendes ab:
Halide ist keine eigenständige Programmiersprache, sondern in C++ eingebettet. Das bedeutet, dass Sie C++-Code schreiben, der mithilfe der C++-API von Halide eine speicherinterne Darstellung einer Halide-Pipeline erstellt. Sie können diese Darstellung dann in eine Objektdatei kompilieren oder sie JIT-kompilieren und im selben Prozess ausführen. Halide bietet außerdem eine Python-Bindung, die das Schreiben von in Python eingebettetem Halide ohne C++ vollständig unterstützt.
Für die Verwendung von Halide ist C++17 (oder höher) erforderlich.
Weitere Einzelheiten zu Halogenid finden Sie unter https://halide-lang.org.
Die API-Dokumentation finden Sie unter https://halide-lang.org/docs.
Einen Beispielcode finden Sie in den Tutorials online unter https://halide-lang.org/tutorials. Der entsprechende Code befindet sich im Verzeichnis tutorials/ . Größere Beispiele finden Sie im Verzeichnis apps/ .
Wenn Sie eine vollständige Quelldistribution erworben haben und Halide erstellen möchten, lesen Sie die folgenden Hinweise.
Ab Halide 19.0.0 stellen wir binäre Räder auf PyPI bereit. Halide stellt Bindungen für C++ und Python bereit. Selbst wenn Sie nur Halide aus C++ verwenden möchten, ist pip möglicherweise der einfachste Weg, einen binären Build von Halide zu erhalten.
Vollversionen können mit pip wie folgt installiert werden:
$ pip install halide Jeder Commit für main wird als Entwicklungsversion auf Test PyPI veröffentlicht und kann mit ein paar zusätzlichen Flags installiert werden:
$ pip install halide --pre --extra-index-url https://test.pypi.org/simpleDerzeit bieten wir Räder für: Windows x86-64, macOS x86-64, macOS arm64 und Linux x86-64. Die Linux-Räder sind für Manylinux_2_28 konzipiert, was sie weitgehend kompatibel macht (Debian 10, Ubuntu 18.10, Fedora 29).
Für C++-Nutzung des pip-Pakets: Unter Linux und macOS sollte der Befehl find_package von CMake Halide finden, solange Sie sich in derselben virtuellen Umgebung befinden, in der Sie es installiert haben. Unter Windows müssen Sie das Stammverzeichnis der virtuellen Umgebung zu CMAKE_PREFIX_PATH hinzufügen . Dies kann durch Ausführen von set CMAKE_PREFIX_PATH=%VIRTUAL_ENV% in cmd erfolgen.
Andere Build-Systeme können den Halide-Stammpfad finden, indem sie python -c "import halide; print(halide.install_dir())" ausführen.
Wenn Sie macOS verwenden, können Sie Halide alternativ wie folgt über Homebrew installieren:
$ brew install halide
Die neueste Version von Halide finden Sie immer auf GitHub unter https://github.com/halide/Halide/releases
Wir bieten Binärversionen für viele gängige Plattformen und Architekturen an, darunter 32/64-Bit-x86-Windows, 64-Bit-x86/ARM-MacOS und 32/64-Bit-x86/ARM-Ubuntu-Linux.
Die macOS-Versionen werden mit den Befehlszeilentools von XCode mit Apple Clang 500.2.76 erstellt. Das bedeutet, dass wir gegen libc++ statt gegen libstdc++ verlinken. Möglicherweise müssen Sie die Compileroptionen entsprechend anpassen, wenn Sie einen älteren XCode verwenden, der nicht standardmäßig libc++ verwendet.
Wir verwenden ein aktuelles Ubuntu LTS, um die Linux-Versionen zu erstellen; Wenn Ihre Distribution zu alt ist, verfügt sie möglicherweise nicht über die erforderliche Glibc.
Nightly Builds von Halide und den LLVM-Versionen, die wir in CI verwenden, sind auch unter https://buildbot.halide-lang.org/ verfügbar.
Wenn Sie vcpkg zum Verwalten von Abhängigkeiten verwenden, können Sie Halide über Folgendes installieren:
$ vcpkg install halide:x64-windows # or x64-linux/x64-osx
Eine Einschränkung: vcpkg installiert nur die minimal erforderlichen Halide-Backends, die zum Kompilieren von Code für die aktive Plattform erforderlich sind. Wenn Sie alle Backends einbinden möchten, sollten Sie stattdessen halide[target-all]:x64-windows installieren. Beachten Sie, dass dadurch LLVM erstellt wird und viel Speicherplatz (bis zu 100 GB) benötigt wird.
Wir sind daran interessiert, Halide in andere beliebte Paketmanager und Linux-Distributions-Repositorys zu integrieren! In dieser GitHub-Ausgabe verfolgen wir den Status verschiedener Distributionen von Halide. Wenn Sie Erfahrung im Veröffentlichen von Paketen haben, würden wir uns freuen, mit Ihnen zusammenzuarbeiten!
Es gibt zwei Gruppen von Plattformanforderungen, die für Halide relevant sind: diejenigen, die erforderlich sind, um die Compiler-Bibliothek entweder im JIT- oder AOT-Modus auszuführen, und diejenigen, die erforderlich sind, um die Binärausgaben des AOT-Compilers auszuführen.
Dies sind die getesteten Host-Toolchain- und Plattformkombinationen zum Erstellen und Ausführen der Halide-Compiler-Bibliothek.
| Compiler | Version | Betriebssystem | Architekturen |
|---|---|---|---|
| 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 |
| AppleClang | 15.0.0 | macOS 14.4.1 | x64 |
| AppleClang | 14.0.0 | macOS 14.6 | ARM64 |
Einige Benutzer haben Halide erfolgreich für Linux mit Clang 9.0.0+, für Windows mit ClangCL 11.0.0+ und für Windows ARM64 durch Cross-Kompilierung mit MSVC erstellt. Wir testen diese Szenarien jedoch nicht aktiv, sodass Ihr Kilometerstand variieren kann.
Darüber hinaus sind wir bereit, Plattform- und Toolchain-Kombinationen zu unterstützen (indem wir PRs dafür akzeptieren), die weiterhin aktive, öffentliche Erstanbieterunterstützung von ihren ursprünglichen Anbietern erhalten. Zum Zeitpunkt des Verfassens dieses Artikels schließt dies beispielsweise Windows 7 aus und umfasst Ubuntu 18.04 LTS.
Es wird erwartet, dass kompilierte AOT-Pipelines eine viel breitere Plattformunterstützung bieten. Die Binärdateien verwenden die C-ABI und wir gehen davon aus, dass jeder kompatible C-Compiler die generierten Header korrekt verwenden kann. Die C++-Bindungen erfordern derzeit C++17. Wenn Sie ein Kompatibilitätsproblem mit einer generierten Pipeline entdecken, öffnen Sie bitte ein Problem.
Für die Erstellung von Halide ist zu jedem Zeitpunkt entweder die neueste stabile Version von LLVM, die vorherige stabile Version von LLVM oder Trunk erforderlich. Zum Zeitpunkt des Schreibens bedeutet dies, dass die Versionen 19, 18 und 17 unterstützt werden, 16 jedoch nicht.
Am einfachsten ist es, mit Homebrew eine Binärversion von LLVM unter macOS zu erhalten. Führen Sie einfach brew install llvm aus. Für Debian-Linux-Varianten ist das LLVM APT-Repo am besten; Verwenden Sie das bereitgestellte Installationsskript. Wir kennen keine geeigneten offiziellen Binärversionen für Windows. Die von uns in CI verwendeten Versionen sind jedoch normalerweise unter https://buildbot.halide-lang.org zu finden, zusammen mit Tarballs für unsere anderen getesteten Plattformen. Weitere Hinweise finden Sie im folgenden Abschnitt zu Windows.
Wenn Ihr Betriebssystem keine Pakete für LLVM hat oder Sie mehr Kontrolle über die Konfiguration wünschen, können Sie es selbst erstellen. Schauen Sie es sich zunächst auf GitHub an:
$ git clone --depth 1 --branch llvmorg-18.1.8 https://github.com/llvm/llvm-project.git (LLVM 18.1.8 ist zum Zeitpunkt des Schreibens das aktuellste veröffentlichte LLVM. Für den aktuellen Trunk verwenden Sie stattdessen main .)
Dann baue es so auf:
$ 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 Dadurch wird eine funktionierende LLVM-Installation in $PWD/llvm-install erstellt. Wir bezeichnen diesen Pfad später als LLVM_ROOT . Verwechseln Sie diesen Installationsbaum nicht mit dem Build-Baum!
Die Erstellung von LLVM dauert lange, daher verwendet der obige Befehl Ninja, um die Parallelität zu maximieren. Wenn Sie -G Ninja weglassen, werden stattdessen Makefiles generiert. Aktivieren Sie in diesem Fall die Parallelität mit cmake --build build -j NNN wobei NNN die Anzahl der parallelen Jobs ist, also die Anzahl der CPUs, die Sie haben.
Beachten Sie, dass Sie clang und lld zu LLVM_ENABLE_PROJECTS hinzufügen müssen und WebAssembly und X86 in LLVM_TARGETS_TO_BUILD enthalten sein müssen . LLVM_ENABLE_RUNTIMES=compiler-rt ist nur zum Erstellen der Fuzz-Tests erforderlich, und clang-tools-extra ist nur erforderlich, wenn Sie planen, Code zu Halide beizutragen (damit Sie clang-tidy auf Ihren Pull-Anfragen ausführen können). Sie können die Ausnahmebehandlung (EH) und RTTI deaktivieren, wenn Sie die Python-Bindungen nicht möchten. Wir empfehlen, den vollständigen Satz zu aktivieren, um Builds während der Entwicklung zu vereinfachen.
Dies wird ausführlicher in BuildingHalideWithCMake.md erläutert. Zum Erstellen von Halide ist CMake Version 3.28+ erforderlich.
Befolgen Sie die obigen Anweisungen, um LLVM zu erstellen oder eine geeignete Binärversion zu erwerben. Wechseln Sie dann in das Halide-Repository und führen Sie Folgendes aus:
$ cmake -G Ninja -S . -B build -DCMAKE_BUILD_TYPE=Release -DHalide_LLVM_ROOT= $LLVM_ROOT
$ cmake --build build Die Einstellung -DHalide_LLVM_ROOT ist nicht erforderlich, wenn Sie eine geeignete systemweite Version installiert haben. Wenn Sie jedoch mehrere LLVMs installiert haben, kann zwischen diesen ausgewählt werden.
Wir empfehlen die Erstellung mit Visual Studio 2022. Ihr Kilometerstand kann von früheren Versionen abweichen. Stellen Sie sicher, dass Sie die „C++ CMake-Tools für Windows“ im Visual Studio-Installationsprogramm installieren. Installieren Sie für ältere Versionen von Visual Studio nicht die CMake-Tools, sondern erwerben Sie CMake und Ninja von den jeweiligen Projektwebsites.
Diese Anweisungen beginnen mit dem Laufwerk D: :. Wir gehen davon aus, dass dieses Git-Repo nach D:Halide geklont ist. Wir gehen außerdem davon aus, dass Ihre Shell-Umgebung korrekt eingerichtet ist. Führen Sie für einen 64-Bit-Build Folgendes aus:
D:> "C:Program Files (x86)Microsoft Visual Studio2022CommunityVCAuxiliaryBuildvcvarsall.bat" x64
Führen Sie für einen 32-Bit-Build Folgendes aus:
D:> "C:Program Files (x86)Microsoft Visual Studio2022CommunityVCAuxiliaryBuildvcvarsall.bat" x64_x86
Der beste Weg, kompatible Abhängigkeiten unter Windows zu erhalten, ist die Verwendung von vcpkg. Installieren Sie es wie folgt:
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"
Bei Verwendung der Toolchain-Datei erstellt vcpkg automatisch alle erforderlichen Abhängigkeiten. Beachten Sie jedoch, wie oben erwähnt, dass der Erwerb von LLVM auf diese Weise möglicherweise über 100 GB Speicherplatz für seine Build-Bäume beansprucht und der Build sehr lange dauert. Sie können die Build-Bäume anschließend manuell löschen, vcpkg führt dies jedoch nicht automatisch durch.
Anweisungen zur Verwendung von Vcpkg für alles außer LLVM finden Sie unter BuildingHalideWithCMake.md.
Erstellen Sie einen separaten Build-Baum und rufen Sie CMake mit der Toolchain von vcpkg auf. Abhängig vom Umgebungsskript ( vcvars ), das zuvor ausgeführt wurde, wird entweder eine 32-Bit- oder eine 64-Bit-Version erstellt.
D:Halide> cmake -G Ninja -S . -B build ^
--toolchain D:/vcpkg/scripts/buildsystems/vcpkg.cmake ^
-DCMAKE_BUILD_TYPE=Release
Führen Sie dann den Build aus mit:
D:Halide> cmake --build build
So führen Sie alle Tests aus:
D:Halide> ctest --test-dir build --output-on-failure
Teilmengen der Tests können mit -L ausgewählt werden und umfassen correctness , generator , error und die anderen Verzeichnisnamen unter tests/ .
Befolgen Sie diese Schritte, wenn Sie LLVM selbst erstellen möchten. Laden Sie zunächst die Quellen von LLVM herunter (diese Anweisungen verwenden die Version 18.1.8).
D:> git clone --depth 1 --branch llvm-org-18.1.8 https://github.com/llvm/llvm-project.git
Führen Sie wie oben vcvarsall.bat aus, um zwischen x86 und x64 zu wählen. Konfigurieren Sie dann LLVM mit dem folgenden Befehl (setzen Sie für 32-Bit stattdessen -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: Wenn Sie LLVM mit MSBuild statt mit Ninja erstellen möchten, verwenden Sie -G "Visual Studio 17 2022" -Thost=x64 -A x64 oder -G "Visual Studio 17 2022" -Thost=x64 -A Win32 anstelle von -G Ninja .
Führen Sie abschließend den Build aus und installieren Sie ihn in einem lokalen Verzeichnis:
D:> cmake --build build --config Release
D:> cmake --install build --prefix llvm-install
Sie können in den oben genannten cmake -Befehlen Debug durch Release ersetzen, wenn Sie einen Debug-Build wünschen.
Um dies mit Halide zu verwenden und vcpkg dennoch die Verwaltung anderer Abhängigkeiten zu ermöglichen, müssen Sie zwei Flags zur CMake-Konfigurationsbefehlszeile von Halide hinzufügen. Deaktivieren Sie zunächst LLVM mit -DVCPKG_OVERLAY_PORTS=cmake/vcpkg . Zweitens verweisen Sie CMake mit -DHalide_LLVM_ROOT=D:/llvm-install auf unser neu erstelltes Halide.
Machen Sie es wie die Buildbots: https://buildbot.halide-lang.org/master/#/builders
Wenn die Zeile, die am besten zu Ihrem System passt, rot ist, dann ist bei Ihnen vielleicht nicht alles kaputt. Wenn es grün ist, können Sie zum neuesten Build klicken und die Befehle sehen, die die Build-Bots ausführen. Öffnen Sie einen Schritt („Halogenid konfigurieren“ ist nützlich) und sehen Sie sich die „stdio“-Protokolle im Viewer an. Diese Protokolle enthalten die vollständigen Befehle, die ausgeführt wurden, sowie die Umgebungsvariablen, mit denen sie ausgeführt wurden.
Warnung
Wir bieten keinen Support für das Makefile. Sie können es gerne verwenden, aber wenn etwas schief geht, wechseln Sie zum CMake-Build. Beachten Sie auch, dass das Makefile keine Python-Bindungen erstellen oder Installationspakete erstellen kann.
TL;DR : Installieren Sie LLVM 17 (oder höher) und führen Sie make im Stammverzeichnis des Repositorys aus (wo sich diese README-Datei befindet).
Standardmäßig verwendet make das im PATH enthaltene Tool llvm-config . Wenn Sie eine andere LLVM verwenden möchten, beispielsweise eine benutzerdefinierte, indem Sie die obigen Anweisungen befolgen, legen Sie die folgende Umgebungsvariable fest:
$ export LLVM_CONFIG= " $LLVM_ROOT /bin/llvm-config " Jetzt sollten Sie einfach make im Stammverzeichnis des Halide-Quellbaums ausführen können. make run_tests führt die JIT-Testsuite aus und make test_apps stellt sicher, dass alle Apps kompiliert und ausgeführt werden (überprüft jedoch nicht ihre Ausgabe).
Beim Erstellen der Tests können Sie das AOT-Kompilierungsziel mit der Umgebungsvariablen HL_TARGET festlegen.
Wenn Sie Halide in einem separaten Verzeichnis erstellen möchten, können Sie das folgendermaßen tun:
$ cd ..
$ mkdir halide_build
$ cd halide_build
$ make -f ../Halide/Makefile HL_JIT_TARGET=... legt das JIT-Kompilierungsziel von Halide fest.
HL_DEBUG_CODEGEN=1 gibt Pseudocode für das aus, was Halide kompiliert. Bei höheren Zahlen werden mehr Details gedruckt.
HL_NUM_THREADS=... gibt die Anzahl der Threads an, die für den Thread-Pool erstellt werden sollen. Wenn die asynchrone Planungsanweisung verwendet wird, sind möglicherweise mehr Threads als diese Anzahl erforderlich und werden daher zugewiesen. Es sind maximal 256 Threads zulässig. (Standardmäßig wird die Anzahl der Kerne auf dem Host verwendet.)
HL_TRACE_FILE=... gibt eine binäre Zieldatei an, in die Ablaufverfolgungsdaten ausgegeben werden sollen (wird ignoriert, es sei denn, mindestens eine trace_ Funktion ist im Ziel aktiviert). Die Ausgabe kann programmgesteuert analysiert werden, indem mit dem Code in utils/HalideTraceViz.cpp begonnen wird.
Wir haben weitere Dokumentation in doc/ , die folgenden Links könnten hilfreich sein:
| Dokumentieren | Beschreibung |
|---|---|
| CMake-Build | So konfigurieren und erstellen Sie Halide mit CMake. |
| CMake-Paket | So verwenden Sie das Halide CMake-Paket zum Erstellen Ihres Codes. |
| Hexagon | So verwenden Sie das Hexagon-Backend. |
| Python | Dokumentation für die Python-Bindungen. |
| RunGen | So verwenden Sie die RunGen-Schnittstelle zum Ausführen und Benchmarken beliebiger Pipelines. |
| Vulkan | So verwenden Sie das Halide Vulkan-Backend (BETA) |
| WebAssembly | Verwendung des WebAssembly-Backends und Verwendung von V8 anstelle von wabt. |
| WebGPU | So führen Sie WebGPU-Pipelines aus (BETA) |
Die folgenden Links sind von größerem Interesse für Entwickler, die Code zu Halide beitragen möchten:
| Dokumentieren | Beschreibung |
|---|---|
| CMake-Entwickler | Richtlinien zum Verfassen von neuem CMake-Code. |
| FuzzTesting | Informationen zum Fuzz-Testen des Halide-Compilers (anstelle von Pipelines). Für interne Entwickler gedacht. |
