Environment:Lance format Lance SIMD And Platform Requirements
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Performance |
| Last Updated | 2026-02-08 19:00 GMT |
Overview
Platform-specific SIMD compilation requirements for Lance's fp16 kernels, requiring GCC 12+ or Clang 6+ on x86_64/aarch64, controlled by the `fp16kernels` feature flag.
Description
Lance includes hand-optimized C SIMD kernels (`f16.c`, `dist_table.c`) in the `lance-linalg` crate for high-performance float16 distance computations used in vector search. These kernels are compiled at build time with architecture-specific flags. The build system auto-detects the target architecture and selects appropriate SIMD instruction sets: AVX-512/AVX2 on x86_64, NEON on aarch64, and LSX/LASX on loongarch64.
Usage
This environment is required when the `fp16kernels` feature flag is enabled for vector search operations that use float16 data. Without this feature, Lance falls back to pure Rust implementations. The feature is enabled in CI for Linux x86_64 and macOS ARM64 builds, and is recommended for production deployments doing heavy vector search workloads.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| OS | Linux or macOS | Windows not supported for fp16 kernels |
| Hardware (x86_64) | CPU with AVX2 (Haswell+) | AVX-512 optional for Sapphire Rapids+ |
| Hardware (aarch64) | CPU with ARMv8.2-a fp16 | Apple M1+ or ARM Neoverse |
| Compiler (x86_64 AVX2) | GCC >= 12 or Clang >= 6 | For `_Float16` / `__fp16` support |
| Compiler (x86_64 AVX-512) | GCC >= 11 or Clang >= 12 | For sapphirerapids architecture |
| Compiler (aarch64 macOS) | Apple Clang (Xcode) | NEON with apple-m1 tuning |
| Compiler (aarch64 Linux) | GCC or Clang | ARMv8.2-a fp16 extension |
Dependencies
System Packages
- `clang` >= 6 (recommended) or `gcc` >= 12 — C compiler with float16 support
- `cc` Rust crate — Used by build.rs to invoke the C compiler
Rust Feature Flags
- `fp16kernels` — Enables compilation of SIMD f16 kernels in lance-linalg
- Available in both the `lance` and `pylance` (Python) packages
Credentials
No credentials required. Build-time environment variables detected automatically:
- `CARGO_CFG_TARGET_ARCH` — Target architecture (set by Cargo)
- `CARGO_CFG_TARGET_OS` — Target operating system (set by Cargo)
- `CARGO_FEATURE_FP16KERNELS` — Feature flag detection (set by Cargo)
- `RUSTUP_TOOLCHAIN` — Rust toolchain detection
Quick Install
# Install Clang (recommended compiler)
sudo apt-get install -y clang
# Build with fp16 kernels enabled
CC=clang CXX=clang++ cargo build --features fp16kernels
# For Python bindings with fp16 kernels
CC=clang CXX=clang++ maturin develop --features fp16kernels
Code Evidence
Windows exclusion from `rust/lance-linalg/build.rs:30-35`:
if target_os == "windows" {
println!(
"cargo:warning=fp16 kernels are not supported on Windows. Skipping compilation of kernels."
);
return Ok(());
}
Architecture detection and SIMD flag selection from `rust/lance-linalg/build.rs:37-77`:
if target_arch == "aarch64" && target_os == "macos" {
build_f16_with_flags("neon", &["-mtune=apple-m1"]).unwrap();
} else if target_arch == "aarch64" && target_os == "linux" {
build_f16_with_flags("neon", &["-march=armv8.2-a+fp16"]).unwrap();
} else if target_arch == "x86_64" {
// Build a version with AVX512
if let Err(err) = build_f16_with_flags("avx512", &["-march=sapphirerapids", "-mavx512fp16"])
// ...
// Build a version with AVX
// While GCC doesn't have support for _Float16 until GCC 12, clang
// has support for __fp16 going back to at least clang 6.
// We use haswell since it's the oldest CPUs on AWS.
if let Err(err) = build_f16_with_flags("avx2", &["-march=haswell"]) {
return Err(format!("Unable to build AVX2 f16 kernels. Please use Clang >= 6 or GCC >= 12..."));
};
}
Compiler flags from `rust/lance-linalg/build.rs:99-115`:
builder
.std("c17")
.file("src/simd/f16.c")
.flag("-ffast-math")
.flag("-funroll-loops")
.flag("-O3")
.flag("-Wall")
.flag("-Wextra")
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `Unable to build AVX2 f16 kernels. Please use Clang >= 6 or GCC >= 12` | C compiler too old for _Float16 | Install clang >= 6 and set `CC=clang` |
| `Skipping build of AVX-512 fp16 kernels` | Compiler lacks sapphirerapids support | This is a warning only; AVX2 fallback is used. Upgrade to Clang >= 12 for AVX-512 |
| `fp16 kernels are not supported on Windows` | Windows not supported | Use WSL2 or disable the `fp16kernels` feature |
| `Unable to build f16 kernels on given target_arch` | Unsupported architecture with fp16kernels enabled | Remove the `fp16kernels` feature flag |
Compatibility Notes
- Windows: fp16 kernels are completely unsupported. Build emits a warning and skips.
- x86_64: AVX-512 is optional; if the compiler lacks sapphirerapids support, only AVX2 kernels are built. Both are runtime-selected.
- loongarch64: Supported with LSX and LASX instruction sets.
- iOS/Android: Build succeeds without fp16kernels feature; errors only if feature is explicitly enabled on unsupported platforms.
- Compiler choice: Clang is preferred over GCC because it has broader `__fp16` support going back to Clang 6, while GCC requires version 12+ for `_Float16`.