Platform & Backend Matrix

This page combines platform support and backend-module configuration for llamadart.

The native-assets hook currently pins llamadart-native tag b9016 (hook/build.dart). Module availability below is for that pinned tag.

Platform/architecture coverage#

All iOS targets above require the consuming Flutter/Xcode project to use a minimum deployment target of 16.4 or newer (for example platform :ios, '16.4').

Runtime capability notes#

• State persistence (LlamaEngine.stateSaveFile(...) / stateLoadFile(...)) is available on native backends and on WebGPU bridge assets v0.1.15+ that expose stateSaveFile / stateLoadFile bridge APIs. On web, state paths refer to the bridge WASMFS virtual filesystem and are not durable across page reloads. Durable browser storage currently requires app-level export/import outside the Dart stateSaveFile / stateLoadFile helpers.

Current module availability by bundle (b9016)#

Selector names and aliases#

llamadart_native_backends values are matched against modules discovered in the selected bundle. Current configurable-bundle module names are:

• cpu
• vulkan
• opencl
• cuda
• blas
• hip

Aliases:

• vk -> vulkan
• ocl -> opencl
• open-cl -> opencl

GpuBackend.metal remains valid as a runtime backend preference on Apple targets, but Apple targets are non-configurable in llamadart_native_backends.

Configuring native backend modules#

Use hooks.user_defines.llamadart.llamadart_native_backends:

hooks:
  user_defines:
    llamadart:
      llamadart_native_backends:
        platforms:
          android-arm64:
            backends: [vulkan]
            cpu_profile: full # default; use compact for baseline-only
          linux-x64: [vulkan, cuda]
          windows-x64:
            backends: [vulkan, cuda, blas]

Android arm64 CPU policy keys (platforms.android-arm64):

• cpu_profile: full (default): include all Android ARM CPU variant modules.
• cpu_profile: compact: include baseline CPU variant module only.
• cpu_variants: [...] (advanced): explicit CPU variant list, overrides cpu_profile.

Supported canonical cpu_variants values:

• android_armv8.0_1 (baseline)
• android_armv8.2_1
• android_armv8.2_2
• android_armv8.6_1
• android_armv9.0_1
• android_armv9.2_1
• android_armv9.2_2

Variant feature differences:

Accepted cpu_variants input forms are normalized, for example:

• baseline
• armv8_6_1
• v9_0_1
• android-armv9.2_2
• libggml-cpu-android_armv8.2_2.so

If cpu_variants contains unknown entries, they are ignored with warnings. If no valid entries remain, selection falls back to cpu_profile (or default full).

Selection and fallback behavior#

• Configurable targets start from defaults (cpu, vulkan) if available.
• cpu is auto-added as fallback when present in the bundle.
• Android arm64 defaults to cpu_profile: full.
• cpu_variants (if provided) takes precedence over cpu_profile for Android arm64.
• If requested modules are unavailable for a bundle, the hook warns and falls back to defaults.
• If defaults are also unavailable, all available modules in that bundle are used as fallback.
• Backend-owned runtime dependencies follow the selected backend module. CUDA runtime DLLs (cudart64_*, cublas64_*, cublaslt64_*) are bundled only when cuda is selected, and OpenBLAS runtime libraries are bundled only when blas is selected. Unknown runtime libraries are kept for compatibility with future native bundle layouts.
• Apple targets (ios-*, macos-*) support cpu + metal, but ignore per-backend module config in this hook path because runtime libraries are consolidated.
• windows-x64 performs extra runtime dependency validation:
  • cuda requires cudart and cublas DLLs.
  • blas requires OpenBLAS DLL.
• If you change llamadart_native_backends, run flutter clean once to clear stale native-asset outputs.

Vulkan cooperative matrix driver crashes#

Some Vulkan drivers advertise cooperative matrix support but crash inside the Vulkan property query calls used by upstream ggml-vulkan. This is a driver failure, not a llamadart loader failure. Use upstream ggml-vulkan's opt-out environment variables before starting the Dart/Flutter process:

GGML_VK_DISABLE_COOPMAT=1
GGML_VK_DISABLE_COOPMAT2=1

On Windows PowerShell:

$env:GGML_VK_DISABLE_COOPMAT = "1"
$env:GGML_VK_DISABLE_COOPMAT2 = "1"
flutter run -d windows

These variables disable the cooperative matrix optimized Vulkan paths for that process. They can reduce Vulkan performance, so use them only when the Vulkan driver crashes or reports device loss in the cooperative matrix path.

Related docs#

• Native Build Hooks
• Linux Prerequisites
• WebGPU Bridge