Halida
Halide
Halide adalah bahasa pemrograman yang dirancang untuk memudahkan penulisan kode pemrosesan gambar dan array berkinerja tinggi pada mesin modern. Halide saat ini menargetkan:
Daripada menjadi bahasa pemrograman yang berdiri sendiri, Halide tertanam dalam C++. Ini berarti Anda menulis kode C++ yang membangun representasi pipa Halide dalam memori menggunakan API C++ Halide. Anda kemudian dapat mengkompilasi representasi ini ke file objek, atau mengkompilasi JIT dan menjalankannya dalam proses yang sama. Halide juga menyediakan pengikatan Python yang memberikan dukungan penuh untuk penulisan Halide yang tertanam dalam Python tanpa C++.
Halide membutuhkan C++17 (atau lebih baru) untuk digunakan.
Untuk detail lebih lanjut tentang apa itu Halide, lihat https://halide-lang.org.
Untuk dokumentasi API lihat https://halide-lang.org/docs.
Untuk beberapa contoh kode, baca tutorial online di https://halide-lang.org/tutorials. Kode yang sesuai ada di direktori tutorials/ . Contoh yang lebih besar ada di direktori apps/ .
Jika Anda telah memperoleh distribusi sumber lengkap dan ingin membuat Halide, lihat catatan di bawah.
Mulai Halide 19.0.0, kami menyediakan roda biner di PyPI. Halide menyediakan binding untuk C++ dan Python. Meskipun Anda hanya ingin menggunakan Halide dari C++, pip mungkin merupakan cara termudah untuk mendapatkan build biner Halide.
Rilis lengkap dapat diinstal dengan pip seperti:
$ pip install halide Setiap komit ke main dipublikasikan ke Test PyPI sebagai versi pengembangan dan ini dapat diinstal dengan beberapa tanda tambahan:
$ pip install halide --pre --extra-index-url https://test.pypi.org/simpleSaat ini, kami menyediakan roda untuk: Windows x86-64, macOS x86-64, macOS arm64, dan Linux x86-64. Roda Linux dibuat untuk manylinux_2_28, yang membuatnya kompatibel secara luas (Debian 10, Ubuntu 18.10, Fedora 29).
Untuk penggunaan paket pip di C++: Di Linux dan macOS, perintah find_package CMake akan menemukan Halide selama Anda berada di lingkungan virtual yang sama dengan tempat Anda menginstalnya. Di Windows, Anda perlu menambahkan direktori akar lingkungan virtual ke CMAKE_PREFIX_PATH . Ini dapat dilakukan dengan menjalankan set CMAKE_PREFIX_PATH=%VIRTUAL_ENV% di cmd .
Sistem build lain dapat menemukan jalur root Halide dengan menjalankan python -c "import halide; print(halide.install_dir())" .
Alternatifnya, jika Anda menggunakan macOS, Anda dapat menginstal Halide melalui Homebrew seperti:
$ brew install halide
Versi terbaru Halide selalu dapat ditemukan di GitHub di https://github.com/halide/Halide/releases
Kami menyediakan rilis biner untuk banyak platform dan arsitektur populer, termasuk Windows x86 32/64-bit, macOS x86/ARM 64-bit, dan Linux Ubuntu 32/64-bit x86/ARM.
Rilis macOS dibuat menggunakan alat baris perintah XCode dengan Apple Clang 500.2.76. Ini berarti kita menautkan dengan libc++, bukan libstdc++. Anda mungkin perlu menyesuaikan opsi kompiler jika Anda menggunakan XCode lama yang tidak default ke libc++.
Kami menggunakan Ubuntu LTS terbaru untuk membangun rilis Linux; jika distribusi Anda terlalu lama, mungkin distribusi tersebut tidak memiliki glibc yang diperlukan.
Versi Halide dan LLVM yang kami gunakan di CI juga tersedia di https://buildbot.halide-lang.org/
Jika Anda menggunakan vcpkg untuk mengelola dependensi, Anda dapat menginstal Halide melalui:
$ vcpkg install halide:x64-windows # or x64-linux/x64-osx
Satu peringatan: vcpkg hanya menginstal backend Halide minimum yang diperlukan untuk mengkompilasi kode untuk platform aktif. Jika Anda ingin menyertakan semua backend, Anda harus menginstal halide[target-all]:x64-windows sebagai gantinya. Perhatikan bahwa karena ini akan membangun LLVM, ini akan memakan banyak ruang disk (hingga 100GB).
Kami tertarik untuk menghadirkan Halide ke pengelola paket populer lainnya dan repositori distribusi Linux! Kami melacak status berbagai distribusi Halide dalam edisi GitHub ini. Jika Anda memiliki pengalaman menerbitkan paket, kami akan dengan senang hati bekerja sama dengan Anda!
Ada dua set persyaratan platform yang relevan dengan Halide: yang diperlukan untuk menjalankan pustaka kompiler dalam mode JIT atau AOT, dan yang diperlukan untuk menjalankan keluaran biner dari kompiler AOT.
Ini adalah kombinasi platform dan toolchain host yang diuji untuk membangun dan menjalankan perpustakaan kompiler Halide.
| Penyusun | Versi | sistem operasi | Arsitektur |
|---|---|---|---|
| GCC | 9.5 | Ubuntu Linux 20.04 LTS | x86, x64 |
| GCC | 11.4 | Ubuntu Linux 22.04 LTS | ARM32, ARM64 |
| MSVC | 2022 (19.37) | jendela 11 (22631) | x86, x64 |
| AppleDentang | 15.0.0 | macOS 14.4.1 | x64 |
| AppleDentang | 14.0.0 | macOS 14.6 | ARM64 |
Beberapa pengguna telah berhasil membangun Halide untuk Linux menggunakan Clang 9.0.0+, untuk Windows menggunakan ClangCL 11.0.0+, dan untuk Windows ARM64 dengan kompilasi silang dengan MSVC. Namun, kami tidak menguji skenario ini secara aktif, sehingga jarak tempuh Anda mungkin berbeda.
Selain itu, kami bersedia mendukung (dengan menerima PR untuk) kombinasi platform dan rantai alat yang masih menerima dukungan publik pihak pertama yang aktif dari vendor aslinya. Misalnya, pada saat penulisan, ini tidak termasuk Windows 7 dan mencakup Ubuntu 18.04 LTS.
Pipeline AOT yang dikompilasi diharapkan memiliki dukungan platform yang lebih luas. Biner menggunakan C ABI, dan kami mengharapkan kompiler C yang sesuai dapat menggunakan header yang dihasilkan dengan benar. Pengikatan C++ saat ini memerlukan C++17. Jika Anda menemukan masalah kompatibilitas dengan alur yang dihasilkan, silakan buka masalahnya.
Kapan saja, membangun Halide memerlukan LLVM versi stabil terbaru, LLVM versi stabil sebelumnya, atau trunk. Pada saat penulisan, ini berarti versi 19, 18, dan 17 didukung, namun versi 16 tidak.
Cara termudah untuk mendapatkan rilis biner LLVM di macOS adalah dengan menggunakan Homebrew. Jalankan saja brew install llvm . Pada Linux versi Debian, repo LLVM APT adalah yang terbaik; gunakan skrip instalasi yang disediakan. Kami mengetahui tidak ada rilis biner resmi yang cocok untuk Windows, namun rilis yang kami gunakan di CI biasanya dapat ditemukan di https://buildbot.halide-lang.org, bersama dengan tarball untuk platform kami yang lain yang telah diuji. Lihat bagian Windows di bawah untuk saran lebih lanjut.
Jika OS Anda tidak memiliki paket untuk LLVM, atau Anda ingin kontrol lebih besar atas konfigurasi, Anda dapat membuatnya sendiri. Pertama periksa dari GitHub:
$ git clone --depth 1 --branch llvmorg-18.1.8 https://github.com/llvm/llvm-project.git (LLVM 18.1.8 adalah LLVM terbaru yang dirilis pada saat penulisan. Untuk trunk saat ini, gunakan main sebagai gantinya)
Kemudian buat seperti ini:
$ 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 Ini akan menghasilkan instalasi LLVM yang berfungsi di $PWD/llvm-install . Kami menyebut jalur ini sebagai LLVM_ROOT nanti. Jangan bingung antara pohon instalasi ini dengan pohon build!
LLVM membutuhkan waktu lama untuk dibangun, jadi perintah di atas menggunakan Ninja untuk memaksimalkan paralelisme. Jika Anda memilih untuk menghilangkan -G Ninja , Makefiles akan dibuat. Dalam hal ini, aktifkan paralelisme dengan cmake --build build -j NNN dimana NNN adalah jumlah pekerjaan paralel, yaitu jumlah CPU yang Anda miliki.
Perhatikan bahwa Anda harus menambahkan clang dan lld ke LLVM_ENABLE_PROJECTS dan WebAssembly dan X86 harus disertakan dalam LLVM_TARGETS_TO_BUILD . LLVM_ENABLE_RUNTIMES=compiler-rt hanya diperlukan untuk membuat pengujian fuzz, dan clang-tools-extra hanya diperlukan jika Anda berencana menyumbangkan kode ke Halide (sehingga Anda dapat menjalankan clang-tidy pada permintaan penarikan Anda). Anda dapat menonaktifkan penanganan pengecualian (EH) dan RTTI jika Anda tidak menginginkan pengikatan Python. Kami merekomendasikan untuk mengaktifkan set lengkap untuk menyederhanakan pembangunan selama pengembangan.
Hal ini dibahas secara lebih rinci di BuildingHalideWithCMake.md. CMake versi 3.28+ diperlukan untuk membuat Halide.
Ikuti petunjuk di atas untuk membangun LLVM atau mendapatkan rilis biner yang sesuai. Kemudian ubah direktori ke repositori Halide dan jalankan:
$ cmake -G Ninja -S . -B build -DCMAKE_BUILD_TYPE=Release -DHalide_LLVM_ROOT= $LLVM_ROOT
$ cmake --build build Pengaturan -DHalide_LLVM_ROOT tidak diperlukan jika Anda menginstal versi seluruh sistem yang sesuai. Namun, jika Anda menginstal beberapa LLVM, LLVM dapat memilih di antara LLVM tersebut.
Kami menyarankan membangun dengan Visual Studio 2022. Jarak tempuh Anda mungkin berbeda dengan versi sebelumnya. Pastikan untuk menginstal "Alat C++ CMake untuk Windows" di penginstal Visual Studio. Untuk Visual Studio versi lama, jangan instal alat CMake, melainkan dapatkan CMake dan Ninja dari situs web proyek masing-masing.
Instruksi ini dimulai dari drive D: :. Kami berasumsi repo git ini dikloning ke D:Halide . Kami juga berasumsi bahwa lingkungan shell Anda telah diatur dengan benar. Untuk versi 64-bit, jalankan:
D:> "C:Program Files (x86)Microsoft Visual Studio2022CommunityVCAuxiliaryBuildvcvarsall.bat" x64
Untuk versi 32-bit, jalankan:
D:> "C:Program Files (x86)Microsoft Visual Studio2022CommunityVCAuxiliaryBuildvcvarsall.bat" x64_x86
Cara terbaik untuk mendapatkan dependensi yang kompatibel di Windows adalah dengan menggunakan vcpkg. Instal seperti ini:
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"
Saat menggunakan file toolchain, vcpkg akan secara otomatis membangun semua dependensi yang diperlukan. Namun, seperti disebutkan di atas, ketahuilah bahwa memperoleh LLVM dengan cara ini mungkin menggunakan lebih dari 100 GB ruang disk untuk pohon pembuatannya dan memerlukan waktu yang sangat lama untuk pembuatannya. Anda dapat menghapus pohon build secara manual setelahnya, tetapi vcpkg tidak akan melakukannya secara otomatis.
Lihat BuildingHalideWithCMake.md untuk petunjuk penggunaan Vcpkg untuk semuanya kecuali LLVM.
Buat pohon build terpisah dan panggil CMake dengan rantai alat vcpkg. Ini akan dibangun dalam versi 32-bit atau 64-bit tergantung pada skrip lingkungan ( vcvars ) yang dijalankan sebelumnya.
D:Halide> cmake -G Ninja -S . -B build ^
--toolchain D:/vcpkg/scripts/buildsystems/vcpkg.cmake ^
-DCMAKE_BUILD_TYPE=Release
Kemudian jalankan build dengan:
D:Halide> cmake --build build
Untuk menjalankan semua tes:
D:Halide> ctest --test-dir build --output-on-failure
Subkumpulan tes dapat dipilih dengan -L dan menyertakan correctness , generator , error , dan nama direktori lain di bawah tests/ .
Ikuti langkah-langkah berikut jika Anda ingin membuat LLVM sendiri. Pertama, unduh sumber LLVM (instruksi ini menggunakan rilis 18.1.8).
D:> git clone --depth 1 --branch llvm-org-18.1.8 https://github.com/llvm/llvm-project.git
Seperti di atas, jalankan vcvarsall.bat untuk memilih antara x86 dan x64. Kemudian konfigurasikan LLVM dengan perintah berikut (untuk 32-bit, setel -DLLVM_BUILD_32_BITS=ON sebagai gantinya):
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: Jika Anda ingin membuat LLVM dengan MSBuild alih-alih Ninja, gunakan -G "Visual Studio 17 2022" -Thost=x64 -A x64 atau -G "Visual Studio 17 2022" -Thost=x64 -A Win32 sebagai pengganti -G Ninja .
Terakhir, jalankan build dan instal ke direktori lokal:
D:> cmake --build build --config Release
D:> cmake --install build --prefix llvm-install
Anda dapat mengganti Debug dengan Release pada perintah cmake di atas jika Anda menginginkan build debug.
Untuk menggunakan ini dengan Halide, namun tetap mengizinkan vcpkg mengelola dependensi lain, Anda harus menambahkan dua tanda ke baris perintah konfigurasi CMake Halide. Pertama, nonaktifkan LLVM dengan -DVCPKG_OVERLAY_PORTS=cmake/vcpkg . Kedua, arahkan CMake ke Halide yang baru kita buat dengan -DHalide_LLVM_ROOT=D:/llvm-install .
Lakukan apa yang dilakukan buildbots: https://buildbot.halide-lang.org/master/#/builders
Jika baris yang paling cocok dengan sistem Anda berwarna merah, mungkin bukan hanya Anda yang rusak. Jika warnanya hijau, Anda dapat mengklik build terbaru dan melihat perintah yang dijalankan bot build. Buka satu langkah ("Konfigurasi Halide" berguna) dan lihat log "stdio" di penampil. Log ini berisi perintah lengkap yang dijalankan, serta variabel lingkungan yang menjalankannya.
Peringatan
Kami tidak menyediakan dukungan untuk Makefile. Jangan ragu untuk menggunakannya, tetapi jika terjadi kesalahan, beralihlah ke versi CMake. Perhatikan juga bahwa Makefile tidak dapat membuat pengikatan Python atau menghasilkan paket instalasi.
TL;DR : Instal LLVM 17 (atau lebih tinggi) dan jalankan make di direktori root repositori (di mana README ini berada).
Secara default, make akan menggunakan alat llvm-config yang ditemukan di PATH . Jika Anda ingin menggunakan LLVM yang berbeda, seperti LLVM yang dibuat khusus dengan mengikuti petunjuk di atas, atur variabel lingkungan berikut:
$ export LLVM_CONFIG= " $LLVM_ROOT /bin/llvm-config " Sekarang Anda seharusnya bisa menjalankan make di direktori root pohon sumber Halide. make run_tests akan menjalankan rangkaian pengujian JIT, dan make test_apps akan memastikan semua aplikasi dikompilasi dan dijalankan (tetapi tidak akan memeriksa hasilnya).
Saat membuat pengujian, Anda dapat menetapkan target kompilasi AOT dengan variabel lingkungan HL_TARGET .
Jika Anda ingin membangun Halide di direktori terpisah, Anda dapat melakukannya seperti:
$ cd ..
$ mkdir halide_build
$ cd halide_build
$ make -f ../Halide/Makefile HL_JIT_TARGET=... akan menetapkan target kompilasi JIT Halide.
HL_DEBUG_CODEGEN=1 akan mencetak kodesemu untuk apa yang dikompilasi Halide. Angka yang lebih tinggi akan mencetak lebih banyak detail.
HL_NUM_THREADS=... menentukan jumlah thread yang akan dibuat untuk kumpulan thread. Ketika arahan penjadwalan async digunakan, lebih banyak thread dari jumlah ini mungkin diperlukan dan karenanya dialokasikan. Maksimum 256 thread diperbolehkan. (Secara default, jumlah inti pada host digunakan.)
HL_TRACE_FILE=... menentukan file target biner untuk membuang data penelusuran (diabaikan kecuali setidaknya satu fitur trace_ diaktifkan di target). Outputnya dapat diuraikan secara terprogram dengan memulai dari kode di utils/HalideTraceViz.cpp .
Kami memiliki lebih banyak dokumentasi di doc/ , tautan berikut mungkin berguna:
| Dokumen | Keterangan |
|---|---|
| CMembuat build | Cara mengkonfigurasi dan membangun Halide menggunakan CMake. |
| paket CMake | Cara menggunakan paket Halide CMake untuk membuat kode Anda. |
| Segi enam | Cara menggunakan backend Hexagon. |
| ular piton | Dokumentasi untuk binding Python. |
| JalankanGen | Cara menggunakan antarmuka RunGen untuk menjalankan dan melakukan benchmark pada pipeline arbitrer. |
| Vulkan | Cara menggunakan backend Halide Vulkan (BETA) |
| Majelis Web | Cara menggunakan backend WebAssembly dan cara menggunakan V8 sebagai pengganti wabt. |
| WebGPU | Cara menjalankan pipeline WebGPU (BETA) |
Tautan berikut ini lebih menarik bagi pengembang yang ingin menyumbangkan kode ke Halide:
| Dokumen | Keterangan |
|---|---|
| Pengembang CMake | Pedoman untuk menulis kode CMake baru. |
| Pengujian Fuzz | Informasi tentang pengujian fuzz pada kompiler Halide (bukan pipeline). Ditujukan untuk pengembang internal. |
