Meson build flags¶

Complete reference for every build-time option libvmaf exposes via core/meson_options.txt, plus the standard Meson options that materially change what ships in the binary.

Per ADR-0100, build flags are a user-discoverable surface and ship documentation in the same PR as the code.

Pass any option via -D<name>=<value> on meson setup:

meson setup build -Denable_cuda=true -Denable_avx512=false -Dbuildtype=release

Reconfigure an existing build tree without wiping it:

meson configure build -Denable_sycl=true
ninja -C build

Project options (meson_options.txt)¶

Flag interactions¶

• enable_asm=false disables every SIMD path. This is an escape hatch for toolchains that can't compile the *.asm kernels — it gives a pure-scalar binary much slower than even the AVX2 path.
• enable_avx512 is auto-downgraded. Even with -Denable_avx512=true, the build will disable the AVX-512 source files if nasm --version is < 2.14 or if the host headers don't expose the required intrinsics. Scripted builds should not assume this flag survives configure-time.
• enable_cuda + enable_sycl can coexist. Both backends compile into the same binary; the runtime picks one per extractor based on which backend has a kernel available. Use --no_cuda / --no_sycl at run time to pin a backend for A/B comparisons.
• enable_nvcc=false is experimental. Clang CUDA support lags nvcc on newer CUDA toolchains; this flag is intended for maintainers investigating codegen regressions, not for day-to-day builds.
• enable_float does not turn off the integer path. The fixed-point extractors always compile; this flag only adds the float twins on top. It defaults to true so that --feature float_adm and related CLI flags work out of the box; set -Denable_float=false only on size-constrained embedded targets that cannot afford the extra object files.
• enable_dnn=auto vs enabled. Always set enabled in CI if you want tiny-AI coverage — auto will silently skip the DNN tests if ORT fails to link and will not flag the gap as a failure.

Options referenced in docs but not present¶

All build flags referenced elsewhere in the docs are defined in core/meson_options.txt. The table above is exhaustive — every option listed there matches a core/meson_options.txt entry as of 2026-05-30 (ADR-0100 per-surface doc-substance audit). The enable_vulkan option referenced in older revisions was removed per ADR-0726; the corresponding core/src/vulkan/ tree and libvmaf_vulkan.h header are gone, though subprojects/packagefiles/volk/ and vk-mem-alloc/ remain in tree pending follow-up cleanup.

enable_hip was added by ADR-0212 (T7-10) — the option exists and the backend it enables is partially live; see the table above and backends/hip/overview.md for the per-kernel coverage matrix.

Standard Meson options that matter¶

These come from Meson itself, not meson_options.txt — but they change the emitted artifact, so they belong in the build-time surface.

Recommended configurations¶

# Fast iteration (CPU only, debug assertions on, AVX2/AVX-512 kept)
meson setup build \
  -Dbuildtype=debugoptimized \
  -Denable_cuda=false -Denable_sycl=false

# Release with CUDA + NVTX for profiling
meson setup build \
  -Dbuildtype=release \
  -Denable_cuda=true -Denable_nvtx=true \
  -Denable_sycl=false

# CI golden-gate config (matches the Netflix CPU golden job)
meson setup build \
  -Dbuildtype=release \
  -Denable_cuda=false -Denable_sycl=false \
  -Denable_float=true -Dbuilt_in_models=true

# Tiny-AI tests (CI)
meson setup build \
  -Dbuildtype=release \
  -Denable_dnn=enabled

# Sanitizer run (for `make test`)
meson setup build \
  -Dbuildtype=debug \
  -Db_sanitize=address,undefined

How feature flags land in the binary¶

core/src/meson.build reads each option once and stores it in a configuration_data() block that drives:

• the #define HAVE_AVX512 … macro baked into the library headers,
• whether .cu / .cpp / .asm source files are added to the target,
• whether the libvmaf_cuda.h / libvmaf_sycl.h headers are installed (these headers are omitted from the installed tree when their backend is disabled at build — see core/include/core/meson.build).

To inspect the resolved configuration of an existing build tree:

meson configure build | head -40

Related¶

Symbol visibility¶

All translation units in libvmaf are compiled with -fvisibility=hidden (see core/src/meson.build). Only symbols explicitly annotated with VMAF_EXPORT (defined in core/include/libvmaf/macros.h) appear in the dynamic symbol table of libvmaf.so. This eliminates silent symbol interposition from embedded third-party code (libsvm, pdjson) and internal helper symbols.

For downstream consumers building their own code with -fvisibility=hidden: the VMAF_EXPORT attribute on every declaration in the installed public headers means you do not need to add manual visibility overrides for libvmaf entry points.

Verification gate:

nm -D --defined-only build/src/libvmaf.so.* | grep ' [TW] ' | grep -v ' vmaf_' | wc -l
# Must print 0

See ADR-0379 and Research-0092 for the original 207-symbol audit and fix rationale.

See also¶

• ADR-0100 — project-wide doc-substance rule (this page satisfies the Build-flag bar).
• backends/index.md — how build flags turn into runtime backend availability.
• ADR-0022 — enable_dnn + ORT choice.
• getting-started/building-on-windows.md — platform-specific toolchain setup.
• development/release.md — release build + signing flow.