Галид
Halide
Halide — это язык программирования, разработанный для упрощения написания высокопроизводительного кода обработки изображений и массивов на современных машинах. В настоящее время компания Halide нацелена на:
Halide не является отдельным языком программирования и встроен в C++. Это означает, что вы пишете код C++, который создает в памяти представление конвейера Halide, используя API C++ Halide. Затем вы можете скомпилировать это представление в объектный файл или JIT-компилировать его и запустить в том же процессе. Halide также предоставляет привязку Python, которая обеспечивает полную поддержку написания Halide, встроенного в Python, без C++.
Для использования 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. Даже если вы собираетесь использовать Halide только из C++, 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 созданы для многих Linux_2_28, что делает их широко совместимыми (Debian 10, Ubuntu 18.10, Fedora 29).
Для использования пакета pip на C++: в Linux и macOS команда CMake find_package должна найти Halide, если вы находитесь в той же виртуальной среде, в которой вы его установили. В Windows вам нужно будет добавить корневой каталог виртуальной среды в CMAKE_PREFIX_PATH . Это можно сделать, запустив set CMAKE_PREFIX_PATH=%VIRTUAL_ENV% в cmd .
Другие системы сборки могут найти корневой путь Halide, запустив python -c "import halide; print(halide.install_dir())" .
Альтернативно, если вы используете macOS, вы можете установить Halide через Homebrew следующим образом:
$ 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 создаются с использованием инструментов командной строки XCode с Apple Clang 500.2.76. Это означает, что мы связываемся с libc++ вместо libstdc++. Возможно, вам придется соответствующим образом настроить параметры компилятора, если вы используете более старую версию XCode, которая по умолчанию не использует libc++.
Для сборки выпусков Linux мы используем последнюю версию Ubuntu LTS; если ваш дистрибутив слишком старый, возможно, в нем нет необходимой библиотеки glibc.
Ночные сборки Halide и версии LLVM, которые мы используем в CI, также доступны по адресу https://buildbot.halide-lang.org/.
Если вы используете vcpkg для управления зависимостями, вы можете установить Halide через:
$ vcpkg install halide:x64-windows # or x64-linux/x64-osx
Одно предостережение: vcpkg устанавливает только минимальное количество бэкендов Halide, необходимых для компиляции кода для активной платформы. Если вы хотите включить все серверные части, вместо этого вам следует установить halide[target-all]:x64-windows . Обратите внимание: поскольку при этом будет собрана LLVM, потребуется много дискового пространства (до 100 ГБ).
Мы заинтересованы в добавлении Halide в другие популярные менеджеры пакетов и репозитории дистрибутивов Linux! Мы отслеживаем статус различных дистрибутивов Halide в этом выпуске GitHub. Если у вас есть опыт публикации пакетов, мы будем рады с вами поработать!
Существует два набора требований к платформе, относящихся к Halide: те, которые необходимы для запуска библиотеки компилятора в режиме JIT или AOT, и те, которые необходимы для запуска двоичных выходных данных компилятора AOT.
Это протестированные комбинации хост-инструментариев и платформ для создания и запуска библиотеки компилятора Halide.
| Компилятор | Версия | ОС | Архитектуры |
|---|---|---|---|
| GCC | 9,5 | Убунту Линукс 20.04 ЛТС | х86, х64 |
| GCC | 11.4 | Убунту Линукс 22.04 ЛТС | АРМ32, АРМ64 |
| МСВК | 2022 (19.37) | Windows 11 (22631) | х86, х64 |
| AppleClang | 15.0.0 | macOS 14.4.1 | х64 |
| AppleClang | 14.0.0 | macOS 14.6 | ARM64 |
Некоторые пользователи успешно собрали Halide для Linux с использованием Clang 9.0.0+, для Windows с использованием ClangCL 11.0.0+ и для Windows ARM64 путем кросс-компиляции с MSVC. Однако мы не тестируем эти сценарии активно, поэтому ваш результат может отличаться.
Помимо этого, мы готовы поддерживать (принимая заявки на поставку) комбинации платформ и наборов инструментов, которые по-прежнему получают активную публичную поддержку от своих первоначальных поставщиков. Например, на момент написания это исключало Windows 7 и включало Ubuntu 18.04 LTS.
Ожидается, что скомпилированные конвейеры AOT будут иметь гораздо более широкую поддержку платформ. В двоичных файлах используется C ABI, и мы ожидаем, что любой совместимый компилятор C сможет правильно использовать сгенерированные заголовки. Привязки C++ в настоящее время требуют C++17. Если вы обнаружите проблему совместимости с сгенерированным конвейером, откройте проблему.
В любой момент времени для сборки Halide требуется либо последняя стабильная версия LLVM, либо предыдущая стабильная версия LLVM, либо транк. На момент написания это означает, что версии 19, 18 и 17 поддерживаются, а 16 — нет.
Проще всего получить двоичную версию LLVM на macOS с помощью Homebrew. Просто запустите brew install llvm . В версиях Linux Debian лучше всего использовать репозиторий LLVM APT; используйте предоставленный сценарий установки. Нам неизвестны подходящие официальные двоичные версии для Windows, однако те, которые мы используем в CI, обычно можно найти на https://buildbot.halide-lang.org вместе с архивами для других протестированных нами платформ. Дополнительные советы см. в разделе «Windows» ниже.
Если в вашей ОС нет пакетов для 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 Это создаст рабочую установку LLVM в $PWD/llvm-install . Позже мы будем называть этот путь LLVM_ROOT . Не путайте это дерево установки с деревом сборки!
Сборка LLVM занимает много времени, поэтому приведенная выше команда использует Ninja для максимизации параллелизма. Если вы решите опустить -G Ninja , вместо этого будут созданы файлы Makefile. В этом случае включите параллелизм с помощью cmake --build build -j NNN , где NNN — это количество параллельных заданий, то есть количество имеющихся у вас процессоров.
Обратите внимание, что вы должны добавить clang и lld в LLVM_ENABLE_PROJECTS , а WebAssembly и X86 должны быть включены в LLVM_TARGETS_TO_BUILD . LLVM_ENABLE_RUNTIMES=compiler-rt требуется только для создания нечетких тестов, а clang-tools-extra необходим только в том случае, если вы планируете добавлять код в Halide (чтобы вы могли запускать clang-tidy в своих запросах на включение). Вы можете отключить обработку исключений (EH) и RTTI, если вам не нужны привязки Python. Мы рекомендуем включить полный набор, чтобы упростить сборку во время разработки.
Более подробно это обсуждается в 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, вы можете выбирать между ними.
Мы предлагаем использовать Visual Studio 2022. Ваш опыт может отличаться от предыдущих версий. Обязательно установите «Инструменты C++ CMake для Windows» в установщике Visual Studio. Для более старых версий Visual Studio не устанавливайте инструменты CMake, а приобретите 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 ГБ дискового пространства для деревьев сборки и занять очень много времени. После этого вы можете вручную удалить деревья сборки, но vcpkg не сделает этого автоматически.
См. BuildingHalideWithCMake.md, чтобы узнать, как использовать Vcpkg для всего, кроме LLVM.
Создайте отдельное дерево сборки и вызовите CMake с помощью набора инструментов vcpkg. Это будет либо 32-битная, либо 64-битная версия, в зависимости от сценария среды ( vcvars ), который был запущен ранее.
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 и включать в себя correctness , generator , error и другие имена каталогов в tests/ .
Выполните следующие действия, если вы хотите собрать 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: если вы хотите собрать LLVM с помощью MSBuild вместо 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
Вы можете заменить Debug на Release в приведенных выше командах cmake , если вам нужна отладочная сборка.
Чтобы использовать это с Halide, но при этом разрешить vcpkg управлять другими зависимостями, необходимо добавить два флага в командную строку настройки CMake Halide. Сначала отключите LLVM с помощью -DVCPKG_OVERLAY_PORTS=cmake/vcpkg . Во-вторых, укажите CMake на наш недавно созданный Halide с помощью -DHalide_LLVM_ROOT=D:/llvm-install .
Делайте то, что делают боты-строители: https://buildbot.halide-lang.org/master/#/builders
Если строка, которая лучше всего соответствует вашей системе, красная, возможно, у вас все не так просто. Если он зеленый, вы можете перейти к последней сборке и просмотреть команды, которые запускают боты сборки. Откройте шаг (полезно «Настроить Halide») и посмотрите логи «stdio» в средстве просмотра. Эти журналы содержат полные данные о выполненных командах, а также переменные среды, с которыми они выполнялись.
Предупреждение
Мы не предоставляем поддержку Makefile. Не стесняйтесь использовать его, но если что-то пойдет не так, переключитесь на сборку CMake. Также обратите внимание, что Makefile не может создавать привязки Python или создавать установочные пакеты.
TL;DR : Установите LLVM 17 (или более позднюю версию) и запустите make в корневом каталоге репозитория (где находится этот README).
По умолчанию make будет использовать инструмент llvm-config расположенный в PATH . Если вы хотите использовать другую LLVM, например созданную по индивидуальному заказу, следуя приведенным выше инструкциям, установите следующую переменную среды:
$ export LLVM_CONFIG= " $LLVM_ROOT /bin/llvm-config " Теперь вы сможете просто запустить make в корневом каталоге дерева исходного кода Halide. make run_tests запустит набор тестов JIT, а make test_apps обеспечит компиляцию и запуск всех приложений (но не будет проверять их выходные данные).
При построении тестов вы можете установить цель компиляции AOT с помощью переменной среды HL_TARGET .
Если вы хотите собрать Halide в отдельном каталоге, вы можете сделать это следующим образом:
$ cd ..
$ mkdir halide_build
$ cd halide_build
$ make -f ../Halide/Makefile HL_JIT_TARGET=... установит цель JIT-компиляции Halide.
HL_DEBUG_CODEGEN=1 распечатает псевдокод того, что компилирует Halide. Чем выше число, тем больше деталей будет напечатано.
HL_NUM_THREADS=... указывает количество потоков, которые необходимо создать для пула потоков. При использовании директивы асинхронного планирования может потребоваться больше потоков, чем это число, и поэтому они будут выделены. Разрешается максимум 256 потоков. (По умолчанию используется количество ядер хоста.)
HL_TRACE_FILE=... указывает двоичный целевой файл, в который будут сбрасываться данные трассировки (игнорируется, если в целевом объекте не включена хотя бы одна функция trace_ ). Вывод можно проанализировать программно, начав с кода в utils/HalideTraceViz.cpp .
У нас есть дополнительная документация в doc/ , следующие ссылки могут быть полезны:
| Документ | Описание |
|---|---|
| Сборка CMake | Как настроить и собрать Halide с помощью CMake. |
| Пакет CMake | Как использовать пакет Halide CMake для создания кода. |
| Шестиугольник | Как использовать бэкэнд Hexagon. |
| Питон | Документация по привязкам Python. |
| RunGen | Как использовать интерфейс RunGen для запуска и тестирования произвольных конвейеров. |
| Вулкан | Как использовать серверную часть Halide Vulkan (БЕТА) |
| Веб-сборка | Как использовать серверную часть WebAssembly и как использовать V8 вместо wabt. |
| Веб-графический процессор | Как запустить конвейеры WebGPU (БЕТА) |
Следующие ссылки представляют больший интерес для разработчиков, желающих добавить код в Halide:
| Документ | Описание |
|---|---|
| CMake-разработчик | Рекомендации по созданию нового кода CMake. |
| Фазз-тестирование | Информация о фазз-тестировании компилятора Halide (а не конвейеров). Предназначен для внутренних разработчиков. |
