M Makefile → Makefile

@@ -14,6 +14,13 @@ else ifeq ($(UNAME_S),Darwin)
     LDFLAGS += -framework AudioToolbox -framework CoreFoundation
 else ifeq ($(UNAME_S),Linux)
     LDFLAGS += -lasound
+    # Only link -lasound if the ALSA headers are actually installed
+    # (libasound2-dev). Mirrors the __has_include check in beeper.c, which
+    # falls back to the OSS backend when they're missing.
+    HAVE_ALSA := $(shell echo '\#include <alsa/asoundlib.h>' | $(CC) -E - >/dev/null 2>&1 && echo 1)
+    ifeq ($(HAVE_ALSA),1)
+        LDFLAGS += -lasound
+    endif
 endif
 
 .PHONY: clean test

M devices/beeper.c → devices/beeper.c

@@ -34,11 +34,23 @@ * Build requirements (see Makefile):
  *   Windows      -> nothing extra (winmm is linked via #pragma comment;
  *                   MinGW users should add -lwinmm)
  *   macOS        -> -framework AudioToolbox -framework CoreFoundation
- *   Linux        -> -lasound
+ *   Linux        -> -lasound, if the ALSA headers are available at compile
+ *                   time (see XYW_HAVE_ALSA below); otherwise falls back
+ *                   to the OSS backend, same as *BSD
  *   *BSD/other   -> nothing extra (uses /dev/dsp)
  */
 static void beep_play_tone(double frequency_hz, unsigned long duration_ms, double volume, xyw_byte *error);
 
+// Detect whether ALSA's development headers are actually installed.
+// libasound2-dev isn't always present (e.g. on minimal/headless VPS
+// images), so rather than hard-failing the build we fall back to the
+// generic OSS backend below when it's missing.
+#if defined(__linux__) && defined(__has_include)
+#if __has_include(<alsa/asoundlib.h>)
+#define XYW_HAVE_ALSA 1
+#endif
+#endif
+
 // Synthesizes a mono 16-bit square wave. 
 // Caller owns the returned buffer.
 // Shared by every backend below - this is the only part of tone
@@ -208,7 +220,7 @@ play_buffer(buf, frames, BEEP_SAMPLE_RATE, error);
     free(buf);
 }
 
-#elif defined(__linux__)
+#elif defined(XYW_HAVE_ALSA)
 
 #include <alsa/asoundlib.h>
 #include <unistd.h>
@@ -267,7 +279,8 @@ play_buffer(buf, frames, BEEP_SAMPLE_RATE, error);
     free(buf);
 }
 
-#else // generic backend (e.g. BSD)
+#else // generic OSS backend: FreeBSD, NetBSD, OpenBSD, DragonFly, and
+      // Linux systems where the ALSA headers aren't installed
 
 #include <fcntl.h>
 #include <unistd.h>
@@ -361,4 +374,4 @@ 
 void beeper_teardown(xyw_byte *data)
 {
     (void)data;
-}
+}