Haleto
Halide
Halide é uma linguagem de programação projetada para facilitar a gravação de código de processamento de imagens e matrizes de alto desempenho em máquinas modernas. Halide atualmente tem como alvo:
Em vez de ser uma linguagem de programação independente, o Halide é incorporado em C++. Isso significa que você escreve código C++ que cria uma representação na memória de um pipeline Halide usando a API C++ do Halide. Você pode então compilar essa representação em um arquivo de objeto ou compilá-la JIT e executá-la no mesmo processo. Halide também fornece uma ligação Python que fornece suporte completo para escrever Halide incorporado em Python sem C++.
Halide requer C++ 17 (ou posterior) para ser usado.
Para obter mais detalhes sobre o que é Halide, consulte https://halide-lang.org.
Para documentação da API, consulte https://halide-lang.org/docs.
Para obter alguns exemplos de código, leia os tutoriais online em https://halide-lang.org/tutorials. O código correspondente está no diretório tutorials/ . Exemplos maiores estão no diretório apps/ .
Se você adquiriu uma distribuição de código-fonte completa e deseja construir o Halide, veja as notas abaixo.
A partir do Halide 19.0.0, fornecemos rodas binárias no PyPI. Halide fornece ligações para C++ e Python. Mesmo que você pretenda usar apenas o Halide do C++, o pip pode ser a maneira mais fácil de obter uma compilação binária do Halide.
Versões completas podem ser instaladas com pip assim:
$ pip install halide Cada commit no main é publicado no Test PyPI como uma versão de desenvolvimento e pode ser instalado com alguns sinalizadores extras:
$ pip install halide --pre --extra-index-url https://test.pypi.org/simpleAtualmente, fornecemos rodas para: Windows x86-64, macOS x86-64, macOS arm64 e Linux x86-64. As rodas Linux são construídas para manylinux_2_28, o que as torna amplamente compatíveis (Debian 10, Ubuntu 18.10, Fedora 29).
Para uso C++ do pacote pip: No Linux e macOS, o comando find_package do CMake deve encontrar Halide desde que você esteja no mesmo ambiente virtual em que o instalou. No Windows, você precisará adicionar o diretório raiz do ambiente virtual a CMAKE_PREFIX_PATH . Isso pode ser feito executando set CMAKE_PREFIX_PATH=%VIRTUAL_ENV% em cmd .
Outros sistemas de compilação podem encontrar o caminho raiz do Halide executando python -c "import halide; print(halide.install_dir())" .
Alternativamente, se você usa macOS, você pode instalar o Halide via Homebrew assim:
$ brew install halide
A versão mais recente do Halide sempre pode ser encontrada no GitHub em https://github.com/halide/Halide/releases
Fornecemos versões binárias para muitas plataformas e arquiteturas populares, incluindo Windows x86 de 32/64 bits, macOS x86/ARM de 64 bits e Ubuntu Linux x86/ARM de 32/64 bits.
As versões do macOS são criadas usando ferramentas de linha de comando do XCode com Apple Clang 500.2.76. Isso significa que vinculamos ao libc++ em vez do libstdc++. Pode ser necessário ajustar as opções do compilador de acordo se estiver usando um XCode mais antigo cujo padrão não é libc++.
Usamos um Ubuntu LTS recente para construir as versões do Linux; se sua distribuição for muito antiga, talvez ela não tenha o glibc necessário.
As compilações noturnas do Halide e as versões LLVM que usamos no CI também estão disponíveis em https://buildbot.halide-lang.org/
Se você usa vcpkg para gerenciar dependências, você pode instalar o Halide via:
$ vcpkg install halide:x64-windows # or x64-linux/x64-osx
Uma ressalva: o vcpkg instala apenas os backends Halide mínimos necessários para compilar o código para a plataforma ativa. Se quiser incluir todos os back-ends, você deve instalar halide[target-all]:x64-windows . Observe que, como isso criará o LLVM, será necessário muito espaço em disco (até 100 GB).
Estamos interessados em trazer o Halide para outros gerenciadores de pacotes populares e repositórios de distribuição Linux! Acompanhamos o status de várias distribuições do Halide nesta edição do GitHub. Se você tem experiência na publicação de pacotes, ficaremos felizes em trabalhar com você!
Existem dois conjuntos de requisitos de plataforma relevantes para o Halide: aqueles necessários para executar a biblioteca do compilador no modo JIT ou AOT e aqueles necessários para executar as saídas binárias do compilador AOT.
Estas são as combinações de conjunto de ferramentas e plataformas de host testadas para construir e executar a biblioteca do compilador Halide.
| Compilador | Versão | SO | Arquiteturas |
|---|---|---|---|
| CCG | 9,5 | UbuntuLinux 20.04 LTS | x86, x64 |
| CCG | 11.4 | UbuntuLinux 22.04LTS | ARM32, ARM64 |
| MSVC | 2022 (19.37) | Janelas 11 (22631) | x86, x64 |
| AppleClang | 15.0.0 | macOS 14.4.1 | x64 |
| AppleClang | 14.0.0 | macOS 14.6 | ARM64 |
Alguns usuários construíram com sucesso o Halide para Linux usando Clang 9.0.0+, para Windows usando ClangCL 11.0.0+ e para Windows ARM64 por meio de compilação cruzada com MSVC. No entanto, não testamos ativamente esses cenários, portanto sua milhagem pode variar.
Além disso, estamos dispostos a apoiar (aceitando PRs para) combinações de plataforma e conjunto de ferramentas que ainda recebem suporte público ativo e primário de seus fornecedores originais. Por exemplo, no momento em que este artigo foi escrito, isso exclui o Windows 7 e inclui o Ubuntu 18.04 LTS.
Espera-se que os pipelines AOT compilados tenham suporte de plataforma muito mais amplo. Os binários usam C ABI e esperamos que qualquer compilador C compatível seja capaz de usar os cabeçalhos gerados corretamente. As ligações C++ atualmente exigem C++17. Se você descobrir um problema de compatibilidade com um pipeline gerado, abra um problema.
A qualquer momento, a construção do Halide requer a versão estável mais recente do LLVM, a versão estável anterior do LLVM ou o tronco. No momento em que este artigo foi escrito, isso significa que as versões 19, 18 e 17 são suportadas, mas a 16 não.
É mais simples obter uma versão binária do LLVM no macOS usando o Homebrew. Basta executar brew install llvm . Nas versões Debian do Linux, o repositório LLVM APT é melhor; use o script de instalação fornecido. Não conhecemos nenhuma versão binária oficial adequada para Windows, no entanto, aquelas que usamos em CI geralmente podem ser encontradas em https://buildbot.halide-lang.org, junto com tarballs para nossas outras plataformas testadas. Consulte a seção sobre Windows abaixo para obter mais conselhos.
Se o seu sistema operacional não possui pacotes para LLVM ou se você deseja mais controle sobre a configuração, você mesmo pode construí-lo. Primeiro verifique no GitHub:
$ git clone --depth 1 --branch llvmorg-18.1.8 https://github.com/llvm/llvm-project.git (LLVM 18.1.8 é o LLVM lançado mais recentemente no momento em que este artigo foi escrito. Para o tronco atual, use main em vez disso)
Então construa assim:
$ 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 Isso produzirá uma instalação funcional do LLVM em $PWD/llvm-install . Referimo-nos a esse caminho como LLVM_ROOT posteriormente. Não confunda esta árvore de instalação com a árvore de construção!
O LLVM leva muito tempo para ser construído, então o comando acima usa Ninja para maximizar o paralelismo. Se você optar por omitir -G Ninja , Makefiles serão gerados. Neste caso, habilite o paralelismo com cmake --build build -j NNN onde NNN é o número de trabalhos paralelos, ou seja, o número de CPUs que você possui.
Observe que você deve adicionar clang e lld a LLVM_ENABLE_PROJECTS e WebAssembly e X86 devem ser incluídos em LLVM_TARGETS_TO_BUILD . LLVM_ENABLE_RUNTIMES=compiler-rt é necessário apenas para construir os testes fuzz, e clang-tools-extra só é necessário se você planeja contribuir com código para Halide (para que você possa executar clang-tidy em suas solicitações pull). Você pode desabilitar o tratamento de exceções (EH) e o RTTI se não quiser as ligações do Python. Recomendamos ativar o conjunto completo para simplificar as compilações durante o desenvolvimento.
Isso é discutido com mais detalhes em BuildingHalideWithCMake.md. O CMake versão 3.28+ é necessário para construir o Halide.
Siga as instruções acima para construir o LLVM ou adquirir uma versão binária adequada. Em seguida, mude o diretório para o repositório Halide e execute:
$ cmake -G Ninja -S . -B build -DCMAKE_BUILD_TYPE=Release -DHalide_LLVM_ROOT= $LLVM_ROOT
$ cmake --build build A configuração -DHalide_LLVM_ROOT não é necessária se você tiver uma versão adequada para todo o sistema instalada. No entanto, se você tiver vários LLVMs instalados, poderá escolher entre eles.
Sugerimos construir com o Visual Studio 2022. Sua milhagem pode variar com versões anteriores. Certifique-se de instalar as "ferramentas C++ CMake para Windows" no instalador do Visual Studio. Para versões mais antigas do Visual Studio, não instale as ferramentas CMake, mas adquira o CMake e o Ninja nos respectivos sites do projeto.
Estas instruções começam na unidade D: :. Presumimos que este repositório git foi clonado para D:Halide . Também assumimos que seu ambiente shell está configurado corretamente. Para uma compilação de 64 bits, execute:
D:> "C:Program Files (x86)Microsoft Visual Studio2022CommunityVCAuxiliaryBuildvcvarsall.bat" x64
Para uma compilação de 32 bits, execute:
D:> "C:Program Files (x86)Microsoft Visual Studio2022CommunityVCAuxiliaryBuildvcvarsall.bat" x64_x86
A melhor maneira de obter dependências compatíveis no Windows é usar vcpkg. Instale assim:
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"
Ao usar o arquivo do conjunto de ferramentas, o vcpkg construirá automaticamente todas as dependências necessárias. No entanto, conforme mencionado acima, esteja ciente de que adquirir o LLVM dessa forma pode usar mais de 100 GB de espaço em disco para suas árvores de construção e levar muito tempo para ser construído. Você pode excluir manualmente as árvores de construção posteriormente, mas o vcpkg não fará isso automaticamente.
Consulte BuildingHalideWithCMake.md para obter instruções sobre como usar o Vcpkg para tudo, exceto LLVM.
Crie uma árvore de construção separada e chame o CMake com o conjunto de ferramentas do vcpkg. Isso será compilado em 32 ou 64 bits, dependendo do script de ambiente ( vcvars ) que foi executado anteriormente.
D:Halide> cmake -G Ninja -S . -B build ^
--toolchain D:/vcpkg/scripts/buildsystems/vcpkg.cmake ^
-DCMAKE_BUILD_TYPE=Release
Em seguida, execute a compilação com:
D:Halide> cmake --build build
Para executar todos os testes:
D:Halide> ctest --test-dir build --output-on-failure
Subconjuntos dos testes podem ser selecionados com -L e incluem correctness , generator , error e outros nomes de diretório em tests/ .
Siga estas etapas se quiser construir o LLVM sozinho. Primeiro, baixe os fontes do LLVM (estas instruções usam a versão 18.1.8).
D:> git clone --depth 1 --branch llvm-org-18.1.8 https://github.com/llvm/llvm-project.git
Como acima, execute vcvarsall.bat para escolher entre x86 e x64. Em seguida, configure o LLVM com o seguinte comando (para 32 bits, defina -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: se você deseja criar LLVM com MSBuild em vez de Ninja, use -G "Visual Studio 17 2022" -Thost=x64 -A x64 ou -G "Visual Studio 17 2022" -Thost=x64 -A Win32 no lugar de -G Ninja .
Por fim, execute a compilação e instale em um diretório local:
D:> cmake --build build --config Release
D:> cmake --install build --prefix llvm-install
Você pode substituir Debug por Release nos comandos cmake acima se desejar uma compilação de depuração.
Para usar isso com o Halide, mas ainda permitir que o vcpkg gerencie outras dependências, você deve adicionar dois sinalizadores à linha de comando de configuração do CMake do Halide. Primeiro, desative o LLVM com -DVCPKG_OVERLAY_PORTS=cmake/vcpkg . Em segundo lugar, aponte o CMake para nosso Halide recém-construído com -DHalide_LLVM_ROOT=D:/llvm-install .
Faça o que os buildbots fazem: https://buildbot.halide-lang.org/master/#/builders
Se a linha que melhor corresponde ao seu sistema estiver vermelha, talvez as coisas não estejam quebradas apenas para você. Se estiver verde, você pode clicar na versão mais recente e ver os comandos que os bots de compilação executam. Abra uma etapa ("Configurar Halide" é útil) e observe os logs "stdio" no visualizador. Esses logs contêm os comandos completos que foram executados, bem como as variáveis de ambiente com as quais foram executados.
Aviso
Não oferecemos suporte para Makefile. Sinta-se à vontade para usá-lo, mas se algo der errado, mude para a versão CMake. Observe também que o Makefile não pode construir as ligações do Python ou produzir pacotes de instalação.
DR : Instale o LLVM 17 (ou superior) e execute make no diretório raiz do repositório (onde está este README).
Por padrão, make usará a ferramenta llvm-config encontrada em PATH . Se você quiser usar um LLVM diferente, como um customizado seguindo as instruções acima, defina a seguinte variável de ambiente:
$ export LLVM_CONFIG= " $LLVM_ROOT /bin/llvm-config " Agora você deve ser capaz de executar make no diretório raiz da árvore de origem do Halide. make run_tests executará o conjunto de testes JIT e make test_apps garantirá que todos os aplicativos sejam compilados e executados (mas não verificará sua saída).
Ao construir os testes, você pode definir o destino de compilação AOT com a variável de ambiente HL_TARGET .
Se você deseja construir o Halide em um diretório separado, você pode fazer assim:
$ cd ..
$ mkdir halide_build
$ cd halide_build
$ make -f ../Halide/Makefile HL_JIT_TARGET=... definirá o destino de compilação JIT do Halide.
HL_DEBUG_CODEGEN=1 imprimirá pseudocódigo para o que o Halide está compilando. Números mais altos imprimirão mais detalhes.
HL_NUM_THREADS=... especifica o número de encadeamentos a serem criados para o conjunto de encadeamentos. Quando a diretiva de agendamento assíncrono é usada, mais threads do que esse número podem ser necessários e, portanto, alocados. É permitido um máximo de 256 threads. (Por padrão, é usado o número de núcleos no host.)
HL_TRACE_FILE=... especifica um arquivo de destino binário para despejar dados de rastreamento (ignorado, a menos que pelo menos um recurso trace_ esteja ativado no destino). A saída pode ser analisada programaticamente começando pelo código em utils/HalideTraceViz.cpp .
Temos mais documentação em doc/ , os seguintes links podem ser úteis:
| Documento | Descrição |
|---|---|
| Compilação CMake | Como configurar e construir Halide usando CMake. |
| Pacote CMake | Como usar o pacote Halide CMake para construir seu código. |
| Hexágono | Como usar o back-end Hexagon. |
| Pitão | Documentação para as ligações do Python. |
| RunGen | Como usar a interface RunGen para executar e comparar pipelines arbitrários. |
| Vulcano | Como usar o backend Halide Vulkan (BETA) |
| WebAssembly | Como usar o backend WebAssembly e como usar o V8 no lugar do wabt. |
| WebGPU | Como executar pipelines WebGPU (BETA) |
Os links a seguir são de maior interesse para desenvolvedores que desejam contribuir com código para o Halide:
| Documento | Descrição |
|---|---|
| Desenvolvedor CMake | Diretrizes para a criação de novo código CMake. |
| Teste Fuzz | Informações sobre testes fuzz do compilador Halide (em vez de pipelines). Destinado a desenvolvedores internos. |
