Halogénure
Halide
Halide est un langage de programmation conçu pour faciliter l'écriture de code de traitement d'images et de tableaux hautes performances sur des machines modernes. Halide cible actuellement :
Plutôt que d'être un langage de programmation autonome, Halide est intégré au C++. Cela signifie que vous écrivez du code C++ qui crée une représentation en mémoire d'un pipeline Halide à l'aide de l'API C++ de Halide. Vous pouvez ensuite compiler cette représentation dans un fichier objet, ou la compiler JIT et l'exécuter dans le même processus. Halide fournit également une liaison Python qui offre une prise en charge complète de l'écriture de Halide intégrée dans Python sans C++.
Halide nécessite C++ 17 (ou version ultérieure) pour être utilisé.
Pour plus de détails sur ce qu'est Halide, voir https://halide-lang.org.
Pour la documentation de l'API, voir https://halide-lang.org/docs.
Pour un exemple de code, lisez les didacticiels en ligne sur https://halide-lang.org/tutorials. Le code correspondant se trouve dans le répertoire tutorials/ . Des exemples plus grands se trouvent dans le répertoire apps/ .
Si vous avez acquis une distribution source complète et souhaitez créer Halide, consultez les notes ci-dessous.
Depuis Halide 19.0.0, nous fournissons des roues binaires sur PyPI. Halide fournit des liaisons pour C++ et Python. Même si vous avez uniquement l'intention d'utiliser Halide à partir de C++, pip peut être le moyen le plus simple d'obtenir une version binaire de Halide.
Les versions complètes peuvent être installées avec pip comme ceci :
$ pip install halide Chaque commit sur main est publié sur Test PyPI en tant que version de développement et ceux-ci peuvent être installés avec quelques indicateurs supplémentaires :
$ pip install halide --pre --extra-index-url https://test.pypi.org/simpleActuellement, nous proposons des roues pour : Windows x86-64, macOS x86-64, macOS arm64 et Linux x86-64. Les roues Linux sont conçues pour manylinux_2_28, ce qui les rend largement compatibles (Debian 10, Ubuntu 18.10, Fedora 29).
Pour une utilisation C++ du package pip : sous Linux et macOS, la commande find_package de CMake devrait trouver Halide tant que vous êtes dans le même environnement virtuel dans lequel vous l'avez installé. Sous Windows, vous devrez ajouter le répertoire racine de l'environnement virtuel à CMAKE_PREFIX_PATH . Cela peut être fait en exécutant set CMAKE_PREFIX_PATH=%VIRTUAL_ENV% dans cmd .
D'autres systèmes de build peuvent trouver le chemin racine de Halide en exécutant python -c "import halide; print(halide.install_dir())" .
Alternativement, si vous utilisez macOS, vous pouvez installer Halide via Homebrew comme ceci :
$ brew install halide
La dernière version de Halide est toujours disponible sur GitHub à l'adresse https://github.com/halide/Halide/releases
Nous fournissons des versions binaires pour de nombreuses plates-formes et architectures populaires, notamment Windows x86 32/64 bits, macOS x86/ARM 64 bits et Ubuntu Linux x86/ARM 32/64 bits.
Les versions macOS sont créées à l'aide des outils de ligne de commande de XCode avec Apple Clang 500.2.76. Cela signifie que nous établissons un lien avec libc++ au lieu de libstdc++. Vous devrez peut-être ajuster les options du compilateur en conséquence si vous utilisez un ancien XCode qui n'est pas par défaut libc++.
Nous utilisons un Ubuntu LTS récent pour créer les versions Linux ; si votre distribution est trop ancienne, il se peut qu'elle ne dispose pas de la glibc requise.
Les versions nocturnes de Halide et des versions LLVM que nous utilisons dans CI sont également disponibles sur https://buildbot.halide-lang.org/
Si vous utilisez vcpkg pour gérer les dépendances, vous pouvez installer Halide via :
$ vcpkg install halide:x64-windows # or x64-linux/x64-osx
Une mise en garde : vcpkg installe uniquement le minimum de backends Halide requis pour compiler le code pour la plate-forme active. Si vous souhaitez inclure tous les backends, vous devez plutôt installer halide[target-all]:x64-windows . Notez que puisque cela va construire LLVM, cela prendra beaucoup d'espace disque (jusqu'à 100 Go).
Nous souhaitons intégrer Halide à d’autres gestionnaires de packages et référentiels de distribution Linux populaires ! Nous suivons l'état de diverses distributions de Halide dans ce numéro GitHub. Si vous avez de l'expérience dans la publication de packages, nous serions heureux de travailler avec vous !
Il existe deux ensembles d'exigences de plate-forme pertinentes pour Halide : celles requises pour exécuter la bibliothèque du compilateur en mode JIT ou AOT, et celles requises pour exécuter les sorties binaires du compilateur AOT.
Il s'agit des combinaisons de chaîne d'outils hôte et de plate-forme testées pour créer et exécuter la bibliothèque du compilateur Halide.
| Compilateur | Version | Système d'exploitation | Architectures |
|---|---|---|---|
| CCG | 9.5 | Ubuntu Linux 20.04 LTS | x86, x64 |
| CCG | 11.4 | Ubuntu Linux 22.04 LTS | ARM32, ARM64 |
| MSVC | 2022 (19h37) | Windows 11 (22631) | x86, x64 |
| PommeClang | 15.0.0 | macOS 14.4.1 | x64 |
| PommeClang | 14.0.0 | MacOS 14.6 | ARM64 |
Certains utilisateurs ont réussi à créer Halide pour Linux à l'aide de Clang 9.0.0+, pour Windows à l'aide de ClangCL 11.0.0+ et pour Windows ARM64 par compilation croisée avec MSVC. Cependant, nous ne testons pas activement ces scénarios, votre kilométrage peut donc varier.
Au-delà de cela, nous sommes prêts à prendre en charge (en acceptant les PR pour) les combinaisons de plates-formes et de chaînes d'outils qui bénéficient toujours d'un support public actif de première partie de la part de leurs fournisseurs d'origine. Par exemple, au moment de la rédaction, cela exclut Windows 7 et inclut Ubuntu 18.04 LTS.
Les pipelines AOT compilés devraient bénéficier d’une prise en charge de plate-forme beaucoup plus large. Les binaires utilisent le C ABI, et nous nous attendons à ce que tout compilateur C conforme soit capable d'utiliser correctement les en-têtes générés. Les liaisons C++ nécessitent actuellement C++17. Si vous découvrez un problème de compatibilité avec un pipeline généré, veuillez ouvrir un ticket.
À tout moment, la construction de Halide nécessite soit la dernière version stable de LLVM, la version stable précédente de LLVM, soit le tronc. Au moment de la rédaction de cet article, cela signifie que les versions 19, 18 et 17 sont prises en charge, mais pas la 16.
Il est plus simple d'obtenir une version binaire de LLVM sur macOS en utilisant Homebrew. Exécutez simplement brew install llvm . Sur les versions Debian de Linux, le dépôt LLVM APT est le meilleur ; utilisez le script d'installation fourni. Nous ne connaissons aucune version binaire officielle appropriée pour Windows, mais celles que nous utilisons dans CI peuvent généralement être trouvées sur https://buildbot.halide-lang.org, ainsi que les archives tar de nos autres plates-formes testées. Consultez la section sur Windows ci-dessous pour plus de conseils.
Si votre système d'exploitation ne dispose pas de packages pour LLVM ou si vous souhaitez plus de contrôle sur la configuration, vous pouvez le créer vous-même. Vérifiez-le d’abord sur GitHub :
$ git clone --depth 1 --branch llvmorg-18.1.8 https://github.com/llvm/llvm-project.git (LLVM 18.1.8 est le LLVM le plus récent au moment de la rédaction. Pour le tronc actuel, utilisez plutôt main )
Ensuite, construisez-le comme ceci :
$ 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 Cela produira une installation LLVM fonctionnelle dans $PWD/llvm-install . Nous appellerons ce chemin LLVM_ROOT plus tard. Ne confondez pas cet arbre d'installation avec l'arbre de construction !
La construction de LLVM prend beaucoup de temps, donc la commande ci-dessus utilise Ninja pour maximiser le parallélisme. Si vous choisissez d'omettre -G Ninja , des Makefiles seront générés à la place. Dans ce cas, activez le parallélisme avec cmake --build build -j NNN où NNN est le nombre de tâches parallèles, c'est-à-dire le nombre de processeurs dont vous disposez.
Notez que vous devez ajouter clang et lld à LLVM_ENABLE_PROJECTS et WebAssembly et X86 doivent être inclus dans LLVM_TARGETS_TO_BUILD . LLVM_ENABLE_RUNTIMES=compiler-rt n'est requis que pour créer les tests fuzz, et clang-tools-extra n'est nécessaire que si vous envisagez de contribuer au code de Halide (afin que vous puissiez exécuter clang-tidy sur vos demandes d'extraction). Vous pouvez désactiver la gestion des exceptions (EH) et RTTI si vous ne souhaitez pas les liaisons Python. Nous vous recommandons d'activer l'ensemble complet pour simplifier les builds pendant le développement.
Ceci est abordé plus en détail dans BuildingHalideWithCMake.md. CMake version 3.28+ est requis pour construire Halide.
Suivez les instructions ci-dessus pour créer LLVM ou acquérir une version binaire appropriée. Changez ensuite de répertoire vers le référentiel Halide et exécutez :
$ cmake -G Ninja -S . -B build -DCMAKE_BUILD_TYPE=Release -DHalide_LLVM_ROOT= $LLVM_ROOT
$ cmake --build build Le paramètre -DHalide_LLVM_ROOT n'est pas requis si une version appropriée à l'échelle du système est installée. Cependant, si plusieurs LLVM sont installés, il peut choisir entre eux.
Nous vous suggérons de créer avec Visual Studio 2022. Votre kilométrage peut varier avec les versions antérieures. Assurez-vous d'installer les « outils C++ CMake pour Windows » dans le programme d'installation de Visual Studio. Pour les anciennes versions de Visual Studio, n'installez pas les outils CMake, mais acquérez plutôt CMake et Ninja à partir de leurs sites Web de projets respectifs.
Ces instructions partent du lecteur D: Nous supposons que ce dépôt git est cloné sur D:Halide . Nous supposons également que votre environnement shell est correctement configuré. Pour une version 64 bits, exécutez :
D:> "C:Program Files (x86)Microsoft Visual Studio2022CommunityVCAuxiliaryBuildvcvarsall.bat" x64
Pour une version 32 bits, exécutez :
D:> "C:Program Files (x86)Microsoft Visual Studio2022CommunityVCAuxiliaryBuildvcvarsall.bat" x64_x86
La meilleure façon d’obtenir des dépendances compatibles sous Windows est d’utiliser vcpkg. Installez-le comme ceci :
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"
Lors de l'utilisation du fichier de chaîne d'outils, vcpkg construira automatiquement toutes les dépendances nécessaires. Cependant, comme indiqué ci-dessus, sachez que l'acquisition de LLVM de cette manière peut utiliser plus de 100 Go d'espace disque pour ses arborescences de construction et prendre beaucoup de temps à construire. Vous pouvez ensuite supprimer manuellement les arborescences de construction, mais vcpkg ne le fera pas automatiquement.
Voir BuildingHalideWithCMake.md pour savoir comment utiliser Vcpkg pour tout sauf LLVM.
Créez une arborescence de construction distincte et appelez CMake avec la chaîne d'outils de vcpkg. Cela sera construit en 32 bits ou 64 bits en fonction du script d'environnement ( vcvars ) qui a été exécuté précédemment.
D:Halide> cmake -G Ninja -S . -B build ^
--toolchain D:/vcpkg/scripts/buildsystems/vcpkg.cmake ^
-DCMAKE_BUILD_TYPE=Release
Ensuite, lancez le build avec :
D:Halide> cmake --build build
Pour exécuter tous les tests :
D:Halide> ctest --test-dir build --output-on-failure
Des sous-ensembles de tests peuvent être sélectionnés avec -L et inclure correctness , generator , error et les autres noms de répertoire sous tests/ .
Suivez ces étapes si vous souhaitez créer vous-même LLVM. Tout d'abord, téléchargez les sources de LLVM (ces instructions utilisent la version 18.1.8).
D:> git clone --depth 1 --branch llvm-org-18.1.8 https://github.com/llvm/llvm-project.git
Comme ci-dessus, exécutez vcvarsall.bat pour choisir entre x86 et x64. Configurez ensuite LLVM avec la commande suivante (pour 32 bits, définissez plutôt -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 : si vous souhaitez créer LLVM avec MSBuild au lieu de Ninja, utilisez -G "Visual Studio 17 2022" -Thost=x64 -A x64 ou -G "Visual Studio 17 2022" -Thost=x64 -A Win32 à la place de -G Ninja .
Enfin, exécutez le build et installez-le dans un répertoire local :
D:> cmake --build build --config Release
D:> cmake --install build --prefix llvm-install
Vous pouvez remplacer Debug par Release dans les commandes cmake ci-dessus si vous souhaitez une version de débogage.
Pour l'utiliser avec Halide, tout en permettant à vcpkg de gérer d'autres dépendances, vous devez ajouter deux indicateurs à la ligne de commande CMake configure de Halide. Tout d'abord, désactivez LLVM avec -DVCPKG_OVERLAY_PORTS=cmake/vcpkg . Deuxièmement, pointez CMake vers notre Halide nouvellement construit avec -DHalide_LLVM_ROOT=D:/llvm-install .
Faites ce que font les buildbots : https://buildbot.halide-lang.org/master/#/builders
Si la ligne qui correspond le mieux à votre système est rouge, alors peut-être que les choses ne sont pas seulement cassées pour vous. S'il est vert, vous pouvez cliquer sur la dernière version et voir les commandes exécutées par les robots de build. Ouvrez une étape ("Configurer Halide" est utile) et regardez les journaux "stdio" dans la visionneuse. Ces journaux contiennent l'intégralité des commandes exécutées, ainsi que les variables d'environnement avec lesquelles elles ont été exécutées.
Avertissement
Nous ne fournissons pas de support pour le Makefile. N'hésitez pas à l'utiliser, mais si quelque chose ne va pas, passez à la version CMake. Notez également que le Makefile ne peut pas créer les liaisons Python ni produire de packages d'installation.
TL;DR : installez LLVM 17 (ou supérieur) et exécutez make dans le répertoire racine du référentiel (où se trouve ce README).
Par défaut, make utilisera l'outil llvm-config trouvé dans le PATH . Si vous souhaitez utiliser un LLVM différent, tel qu'un modèle personnalisé en suivant les instructions ci-dessus, définissez la variable d'environnement suivante :
$ export LLVM_CONFIG= " $LLVM_ROOT /bin/llvm-config " Vous devriez maintenant pouvoir simplement exécuter make dans le répertoire racine de l'arborescence des sources Halide. make run_tests exécutera la suite de tests JIT et make test_apps s'assurera que toutes les applications se compilent et s'exécutent (mais ne vérifiera pas leur sortie).
Lors de la construction des tests, vous pouvez définir la cible de compilation AOT avec la variable d'environnement HL_TARGET .
Si vous souhaitez construire Halide dans un répertoire séparé, vous pouvez le faire comme ceci :
$ cd ..
$ mkdir halide_build
$ cd halide_build
$ make -f ../Halide/Makefile HL_JIT_TARGET=... définira la cible de compilation JIT de Halide.
HL_DEBUG_CODEGEN=1 imprimera le pseudocode de ce que Halide est en train de compiler. Des nombres plus élevés imprimeront plus de détails.
HL_NUM_THREADS=... spécifie le nombre de threads à créer pour le pool de threads. Lorsque la directive de planification asynchrone est utilisée, plus de threads que ce nombre peuvent être requis et donc alloués. Un maximum de 256 threads est autorisé. (Par défaut, le nombre de cœurs sur l'hôte est utilisé.)
HL_TRACE_FILE=... spécifie un fichier cible binaire dans lequel vider les données de traçage (ignoré sauf si au moins une fonctionnalité trace_ est activée dans la cible). La sortie peut être analysée par programme en commençant à partir du code dans utils/HalideTraceViz.cpp .
Nous avons plus de documentation dans doc/ , les liens suivants peuvent être utiles :
| Document | Description |
|---|---|
| CMake construire | Comment configurer et créer Halide à l'aide de CMake. |
| Paquet CMake | Comment utiliser le package Halide CMake pour créer votre code. |
| Hexagone | Comment utiliser le backend Hexagon. |
| Python | Documentation pour les liaisons Python. |
| ExécuterGen | Comment utiliser l'interface RunGen pour exécuter et comparer des pipelines arbitraires. |
| Vulcan | Comment utiliser le backend Halide Vulkan (BETA) |
| Assemblage Web | Comment utiliser le backend WebAssembly et comment utiliser la V8 à la place de wabt. |
| WebGPU | Comment exécuter des pipelines WebGPU (BETA) |
Les liens suivants sont plus intéressants pour les développeurs souhaitant contribuer au code d'Halide :
| Document | Description |
|---|---|
| Développeur CMake | Lignes directrices pour la création d’un nouveau code CMake. |
| Tests de fuzz | Informations sur les tests fuzz du compilateur Halide (plutôt que des pipelines). Destiné aux développeurs internes. |
