macOS: -Dmacos_openal_provider=system fails to build ('AL/al.h' file not found)

[rebelancap]

Summary

-Dmacos_openal_provider=system cannot build on macOS when OpenAL Soft is not on the default pkg-config search path. The provider selection silently falls back to Apple's OpenAL.framework, but the include-mode define is applied unconditionally, so the two halves disagree and compilation fails.

Environment

• macOS 27.0, Apple M4 Pro
• Xcode 26.6 / Apple clang 21.0.0
• Meson 1.11.1, Ninja 1.13.2
• openQ4 227ee810 (main), openQ4-game 61a3c10d
• Homebrew openal-soft 1.25.2 installed

Reproduce

bash tools/build/meson_setup.sh setup builddir . \
  --backend ninja --buildtype=release --wrap-mode=forcefallback \
  -Dmacos_openal_provider=system
bash tools/build/meson_setup.sh compile -C builddir

Configure reports OpenAL : YES and the build then fails:

FAILED: openQ4-client_arm64.p/src_framework_Session_menu.cpp.o
../src/framework/../sound/snd_local.h:116:11: fatal error: 'AL/al.h' file not found

Cause

Homebrew's openal-soft is keg-only, so its openal.pc is not on the default PKG_CONFIG_PATH. Meson's dependency('openal') therefore misses via pkg-config and falls back to the Apple framework — visible in meson-log.txt:

Called: `pkg-config --modversion openal` -> 1
Package 'openal' not found
Looking for framework openal in .../MacOSX.sdk/System/Library/Frameworks
Run-time dependency openal found: YES (.../OpenAL.framework)

But -DUSE_OPENAL_SOFT_INCLUDES=1 is still added for the system provider, and src/sound/snd_local.h:111-119 then selects the OpenAL Soft header layout:

#if defined(__APPLE__) && !defined(USE_OPENAL_SOFT_INCLUDES)
    #include <OpenAL/al.h>   // Apple framework layout
#else
    #include <AL/al.h>       // OpenAL Soft layout — not provided by the framework
#endif

So the provider resolved to the framework while the includes were told to expect OpenAL Soft.

Suggested fix

Either would do:

1. Make the system provider strict — dependency('openal', required: true, method: 'pkg-config') — so a missing OpenAL Soft is a clear configure error instead of a confusing compile error; or
2. Only define USE_OPENAL_SOFT_INCLUDES when the dependency actually resolved via pkg-config, letting a framework fallback use the framework header layout.

(1) seems truer to the option's intent, since the point of system is specifically to not use the Apple framework.

Workaround

export PKG_CONFIG_PATH=/opt/homebrew/opt/openal-soft/lib/pkgconfig

Why this matters beyond the build error

The Apple OpenAL framework has no EFX, so s_useEAXReverb compiles out entirely (OPENQ4_OPENAL_EFX_SUPPORTED gate in AL_SoundVoice.cpp / AL_SoundHardware.cpp). With the workaround applied, the same build reports:

OpenAL version: 1.1 ALSOFT 1.25.2
OpenAL EFX filters available.
OpenAL EFX reverb send enabled.

So system is currently the only way to get reverb on macOS, and it is the path that does not build out of the box.