haluro
Halide
Halide es un lenguaje de programación diseñado para facilitar la escritura de código de procesamiento de matrices y imágenes de alto rendimiento en máquinas modernas. Halide actualmente apunta a:
En lugar de ser un lenguaje de programación independiente, Halide está integrado en C++. Esto significa que escribe código C++ que crea una representación en memoria de una canalización de Halide utilizando la API C++ de Halide. Luego puede compilar esta representación en un archivo objeto o compilarla JIT y ejecutarla en el mismo proceso. Halide también proporciona un enlace de Python que proporciona soporte completo para escribir Halide incrustado en Python sin C++.
Halide requiere C++ 17 (o posterior) para su uso.
Para obtener más detalles sobre qué es Halide, consulte https://halide-lang.org.
Para obtener documentación de API, consulte https://halide-lang.org/docs.
Para ver un código de ejemplo, lea los tutoriales en línea en https://halide-lang.org/tutorials. El código correspondiente está en el directorio tutorials/ . Hay ejemplos más grandes en el directorio apps/ .
Si adquirió una distribución de código fuente completa y desea compilar Halide, consulte las notas a continuación.
A partir de Halide 19.0.0, proporcionamos ruedas binarias en PyPI. Halide proporciona enlaces para C++ y Python. Incluso si solo tiene la intención de utilizar Halide de C++, pip puede ser la forma más fácil de obtener una compilación binaria de Halide.
Las versiones completas se pueden instalar con pip de la siguiente manera:
$ pip install halide Cada confirmación de main se publica en Test PyPI como una versión de desarrollo y se pueden instalar con algunas opciones adicionales:
$ pip install halide --pre --extra-index-url https://test.pypi.org/simpleActualmente, ofrecemos ruedas para: Windows x86-64, macOS x86-64, macOS arm64 y Linux x86-64. Las ruedas de Linux están diseñadas para manylinux_2_28, lo que las hace ampliamente compatibles (Debian 10, Ubuntu 18.10, Fedora 29).
Para el uso de C++ del paquete pip: en Linux y macOS, el comando find_package de CMake debería encontrar Halide siempre que esté en el mismo entorno virtual en el que lo instaló. En Windows, deberá agregar el directorio raíz del entorno virtual a CMAKE_PREFIX_PATH . Esto se puede hacer ejecutando set CMAKE_PREFIX_PATH=%VIRTUAL_ENV% en cmd .
Otros sistemas de compilación pueden encontrar la ruta raíz de Halide ejecutando python -c "import halide; print(halide.install_dir())" .
Alternativamente, si usas macOS, puedes instalar Halide a través de Homebrew de esta manera:
$ brew install halide
La última versión de Halide siempre se puede encontrar en GitHub en https://github.com/halide/Halide/releases
Proporcionamos versiones binarias para muchas plataformas y arquitecturas populares, incluidas Windows x86 de 32/64 bits, macOS x86/ARM de 64 bits y Ubuntu Linux x86/ARM de 32/64 bits.
Las versiones de macOS se crean utilizando las herramientas de línea de comandos de XCode con Apple Clang 500.2.76. Esto significa que vinculamos con libc++ en lugar de libstdc++. Es posible que deba ajustar las opciones del compilador en consecuencia si está utilizando un XCode anterior que no tiene por defecto libc++.
Usamos un Ubuntu LTS reciente para crear las versiones de Linux; Si su distribución es demasiado antigua, es posible que no tenga la glibc requerida.
Las compilaciones nocturnas de Halide y las versiones LLVM que utilizamos en CI también están disponibles en https://buildbot.halide-lang.org/
Si usa vcpkg para administrar dependencias, puede instalar Halide a través de:
$ vcpkg install halide:x64-windows # or x64-linux/x64-osx
Una advertencia: vcpkg instala solo los backends Halide mínimos necesarios para compilar el código para la plataforma activa. Si desea incluir todos los backends, debe instalar halide[target-all]:x64-windows en su lugar. Tenga en cuenta que, dado que esto generará LLVM, necesitará mucho espacio en disco (hasta 100 GB).
¡Estamos interesados en llevar Halide a otros administradores de paquetes y repositorios de distribución de Linux populares! Realizamos un seguimiento del estado de varias distribuciones de Halide en esta edición de GitHub. Si tiene experiencia publicando paquetes, ¡estaremos encantados de trabajar con usted!
Hay dos conjuntos de requisitos de plataforma relevantes para Halide: los necesarios para ejecutar la biblioteca del compilador en modo JIT o AOT, y los necesarios para ejecutar las salidas binarias del compilador AOT.
Estas son las combinaciones de plataforma y cadena de herramientas de host probadas para crear y ejecutar la biblioteca del compilador Halide.
| Compilador | Versión | SO | Arquitecturas |
|---|---|---|---|
| CCG | 9.5 | Ubuntu Linux 20.04 LTS | x86, x64 |
| CCG | 11.4 | Ubuntu Linux 22.04 LTS | ARM32, ARM64 |
| MSVC | 2022 (19,37) | Ventanas 11 (22631) | x86, x64 |
| AppleClang | 15.0.0 | MacOS 14.4.1 | x64 |
| AppleClang | 14.0.0 | macOS 14.6 | ARM64 |
Algunos usuarios han creado con éxito Halide para Linux usando Clang 9.0.0+, para Windows usando ClangCL 11.0.0+ y para Windows ARM64 mediante compilación cruzada con MSVC. Sin embargo, no probamos activamente estos escenarios, por lo que su kilometraje puede variar.
Más allá de esto, estamos dispuestos a respaldar (aceptando relaciones públicas para) combinaciones de plataforma y cadena de herramientas que aún reciban soporte público activo y propio de sus proveedores originales. Por ejemplo, al momento de escribir este artículo, esto excluye Windows 7 e incluye Ubuntu 18.04 LTS.
Se espera que los canales AOT compilados tengan un soporte de plataforma mucho más amplio. Los binarios usan C ABI y esperamos que cualquier compilador de C compatible pueda usar los encabezados generados correctamente. Los enlaces de C++ actualmente requieren C++17. Si descubre un problema de compatibilidad con una canalización generada, abra un problema.
En cualquier momento, la creación de Halide requiere la última versión estable de LLVM, la versión estable anterior de LLVM o el tronco. Al momento de escribir este artículo, esto significa que las versiones 19, 18 y 17 son compatibles, pero la 16 no.
La forma más sencilla de obtener una versión binaria de LLVM en macOS utilizando Homebrew. Simplemente ejecute brew install llvm . En las versiones Debian de Linux, el repositorio LLVM APT es el mejor; utilice el script de instalación proporcionado. No conocemos versiones binarias oficiales adecuadas para Windows; sin embargo, las que usamos en CI generalmente se pueden encontrar en https://buildbot.halide-lang.org, junto con archivos tar para nuestras otras plataformas probadas. Consulte la sección sobre Windows a continuación para obtener más consejos.
Si su sistema operativo no tiene paquetes para LLVM o desea tener más control sobre la configuración, puede crearlo usted mismo. Primero compruébalo desde GitHub:
$ git clone --depth 1 --branch llvmorg-18.1.8 https://github.com/llvm/llvm-project.git (LLVM 18.1.8 es el LLVM lanzado más recientemente al momento de escribir este artículo. Para el troncal actual, use main en su lugar)
Luego constrúyalo así:
$ 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 Esto producirá una instalación LLVM funcional en $PWD/llvm-install . Más adelante nos referiremos a esta ruta como LLVM_ROOT . ¡No confunda este árbol de instalación con el árbol de construcción!
LLVM tarda mucho en construirse, por lo que el comando anterior utiliza Ninja para maximizar el paralelismo. Si elige omitir -G Ninja , se generarán Makefiles en su lugar. En este caso, habilite el paralelismo con cmake --build build -j NNN donde NNN es el número de trabajos paralelos, es decir, el número de CPU que tiene.
Tenga en cuenta que debe agregar clang y lld a LLVM_ENABLE_PROJECTS y WebAssembly y X86 deben incluirse en LLVM_TARGETS_TO_BUILD . LLVM_ENABLE_RUNTIMES=compiler-rt solo es necesario para crear las pruebas fuzz, y clang-tools-extra solo es necesario si planeas contribuir con código a Halide (para que puedas ejecutar clang-tidy en tus solicitudes de extracción). Puede deshabilitar el manejo de excepciones (EH) y RTTI si no desea los enlaces de Python. Recomendamos habilitar el conjunto completo para simplificar las compilaciones durante el desarrollo.
Esto se analiza con mayor detalle en BuildingHalideWithCMake.md. Se requiere CMake versión 3.28+ para compilar Halide.
Siga las instrucciones anteriores para compilar LLVM o adquirir una versión binaria adecuada. Luego cambie el directorio al repositorio de Halide y ejecute:
$ cmake -G Ninja -S . -B build -DCMAKE_BUILD_TYPE=Release -DHalide_LLVM_ROOT= $LLVM_ROOT
$ cmake --build build No es necesario configurar -DHalide_LLVM_ROOT si tiene instalada una versión adecuada para todo el sistema. Sin embargo, si tiene varios LLVM instalados, puede elegir entre ellos.
Sugerimos compilar con Visual Studio 2022. Su kilometraje puede variar con versiones anteriores. Asegúrese de instalar las "herramientas C++ CMake para Windows" en el instalador de Visual Studio. Para versiones anteriores de Visual Studio, no instale las herramientas de CMake, sino que adquiera CMake y Ninja de los sitios web de sus respectivos proyectos.
Estas instrucciones comienzan desde la unidad D: :. Suponemos que este repositorio de git está clonado en D:Halide . También asumimos que su entorno de shell está configurado correctamente. Para una compilación de 64 bits, ejecute:
D:> "C:Program Files (x86)Microsoft Visual Studio2022CommunityVCAuxiliaryBuildvcvarsall.bat" x64
Para una compilación de 32 bits, ejecute:
D:> "C:Program Files (x86)Microsoft Visual Studio2022CommunityVCAuxiliaryBuildvcvarsall.bat" x64_x86
La mejor manera de obtener dependencias compatibles en Windows es utilizar vcpkg. Instálalo así:
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"
Al utilizar el archivo de cadena de herramientas, vcpkg creará automáticamente todas las dependencias necesarias. Sin embargo, como se indicó anteriormente, tenga en cuenta que adquirir LLVM de esta manera puede utilizar más de 100 GB de espacio en disco para sus árboles de compilación y llevar mucho tiempo compilarlo. Puede eliminar manualmente los árboles de compilación después, pero vcpkg no lo hará automáticamente.
Consulte BuildingHalideWithCMake.md para obtener instrucciones sobre cómo usar Vcpkg para todo excepto LLVM.
Cree un árbol de compilación independiente y llame a CMake con la cadena de herramientas de vcpkg. Esto se construirá en 32 o 64 bits según el script de entorno ( vcvars ) que se ejecutó anteriormente.
D:Halide> cmake -G Ninja -S . -B build ^
--toolchain D:/vcpkg/scripts/buildsystems/vcpkg.cmake ^
-DCMAKE_BUILD_TYPE=Release
Luego ejecuta la compilación con:
D:Halide> cmake --build build
Para ejecutar todas las pruebas:
D:Halide> ctest --test-dir build --output-on-failure
Los subconjuntos de las pruebas se pueden seleccionar con -L e incluyen correctness , generator , error y otros nombres de directorio en tests/ .
Siga estos pasos si desea crear LLVM usted mismo. Primero, descargue las fuentes de LLVM (estas instrucciones utilizan la versión 18.1.8).
D:> git clone --depth 1 --branch llvm-org-18.1.8 https://github.com/llvm/llvm-project.git
Como arriba, ejecute vcvarsall.bat para elegir entre x86 y x64. Luego configure LLVM con el siguiente comando (para 32 bits, configure -DLLVM_BUILD_32_BITS=ON en su lugar):
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 desea compilar LLVM con MSBuild en lugar de Ninja, use -G "Visual Studio 17 2022" -Thost=x64 -A x64 o -G "Visual Studio 17 2022" -Thost=x64 -A Win32 en lugar de -G Ninja .
Finalmente, ejecute la compilación e instálela en un directorio local:
D:> cmake --build build --config Release
D:> cmake --install build --prefix llvm-install
Puede sustituir Debug por Release en los comandos cmake anteriores si desea una compilación de depuración.
Para usar esto con Halide, pero aún así permitir que vcpkg administre otras dependencias, debe agregar dos indicadores a la línea de comando de configuración de CMake de Halide. Primero, deshabilite LLVM con -DVCPKG_OVERLAY_PORTS=cmake/vcpkg . En segundo lugar, apunte CMake a nuestro Halide recién creado con -DHalide_LLVM_ROOT=D:/llvm-install .
Haz lo que hacen los buildbots: https://buildbot.halide-lang.org/master/#/builders
Si la fila que mejor coincide con su sistema es roja, entonces tal vez las cosas no estén simplemente rotas para usted. Si está verde, puede hacer clic en la última versión y ver los comandos que ejecutan los robots de compilación. Abra un paso ("Configurar Halide" es útil) y observe los registros "stdio" en el visor. Estos registros contienen los comandos completos que se ejecutaron, así como las variables de entorno con las que se ejecutaron.
Advertencia
No brindamos soporte para Makefile. Siéntete libre de usarlo, pero si algo sale mal, cambia a la versión CMake. Tenga en cuenta también que Makefile no puede crear enlaces de Python ni producir paquetes de instalación.
TL;DR : Tenga instalado LLVM 17 (o superior) y ejecute make en el directorio raíz del repositorio (donde está este README).
De forma predeterminada, make utilizará la herramienta llvm-config que se encuentra en PATH . Si desea utilizar un LLVM diferente, como uno personalizado siguiendo las instrucciones anteriores, configure la siguiente variable de entorno:
$ export LLVM_CONFIG= " $LLVM_ROOT /bin/llvm-config " Ahora debería poder ejecutar make en el directorio raíz del árbol fuente de Halide. make run_tests ejecutará el conjunto de pruebas JIT y make test_apps se asegurará de que todas las aplicaciones se compilen y ejecuten (pero no verificará su salida).
Al crear las pruebas, puede establecer el objetivo de compilación de AOT con la variable de entorno HL_TARGET .
Si desea compilar Halide en un directorio separado, puede hacerlo así:
$ cd ..
$ mkdir halide_build
$ cd halide_build
$ make -f ../Halide/Makefile HL_JIT_TARGET=... establecerá el objetivo de compilación JIT de Halide.
HL_DEBUG_CODEGEN=1 imprimirá el pseudocódigo de lo que Halide está compilando. Los números más altos imprimirán más detalles.
HL_NUM_THREADS=... especifica el número de subprocesos que se crearán para el grupo de subprocesos. Cuando se utiliza la directiva de programación asíncrona, es posible que se requieran y, por lo tanto, se asignen más subprocesos que este número. Se permite un máximo de 256 subprocesos. (De forma predeterminada, se utiliza la cantidad de núcleos del host).
HL_TRACE_FILE=... especifica un archivo de destino binario en el que volcar los datos de seguimiento (ignorado a menos que al menos una característica trace_ esté habilitada en el destino). La salida se puede analizar mediante programación comenzando desde el código en utils/HalideTraceViz.cpp .
Tenemos más documentación en doc/ , los siguientes enlaces pueden ser útiles:
| Documento | Descripción |
|---|---|
| Chacer construir | Cómo configurar y construir Halide usando CMake. |
| Paquete CMake | Cómo utilizar el paquete Halide CMake para crear su código. |
| Hexágono | Cómo utilizar el backend de Hexagon. |
| Pitón | Documentación para los enlaces de Python. |
| EjecutarGen | Cómo utilizar la interfaz RunGen para ejecutar y comparar canalizaciones arbitrarias. |
| vulcano | Cómo utilizar el backend de Halide Vulkan (BETA) |
| Asamblea web | Cómo utilizar el backend de WebAssembly y cómo utilizar V8 en lugar de wabt. |
| WebGPU | Cómo ejecutar canalizaciones WebGPU (BETA) |
Los siguientes enlaces son de mayor interés para los desarrolladores que deseen contribuir con código a Halide:
| Documento | Descripción |
|---|---|
| Desarrollador CMake | Directrices para crear nuevo código CMake. |
| Pruebas difusas | Información sobre pruebas difusas del compilador Halide (en lugar de tuberías). Destinado a desarrolladores internos. |
