xbintsc 0.3.68 → 0.3.79

package/scripts/build-gui.ts

@@ -13,6 +13,8 @@
  *   1. fetch the pinned SDL3 source into `vendor/SDL` (gitignored),
  *   2. build `libSDL3.a` with CMake,
  *   2b. fetch + build static FreeType and HarfBuzz for text,
+ *   2c. fetch + build a minimal static FFmpeg for `<video>`/`<audio>`
+ *       (skipped on Windows, where media support is compiled out),
  *   3. compile the engine translation units,
  *   4. merge everything into `gui.a` (libtool on macOS, `ar -M` elsewhere;
  *      `gui.lib` on Windows, built from MSVC-compatible COFF objects).
@@ -31,6 +33,7 @@
  */
 
 import { existsSync, mkdirSync, readdirSync, renameSync, rmSync } from "node:fs";
+import { availableParallelism } from "node:os";
 import { spawnSync, type SpawnSyncReturns } from "node:child_process";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -41,11 +44,23 @@ const runtimeDir = join(root, "runtime");
 const engineDir = join(runtimeDir, "ext_gui");
 const vendorDir = join(root, "vendor");
 const sdlSrc = join(vendorDir, "SDL");
-const sdlBuild = join(sdlSrc, "build");
+/* SDL's build tree is a *sibling* of its source, like FreeType's and HarfBuzz's,
+ * never inside it: the CI cache keyed on a vendored library ships the whole
+ * `vendor/SDL` tree, and a CMake build tree is not relocatable across machines
+ * or platforms. `CMakeCache.txt` records the host's compiler and probes, and
+ * SDL's video options are `option()`s — the first configure to run wins, so a
+ * cached `SDL_X11=OFF` (e.g. from a Windows configure, where the option's
+ * default is OFF) survives into a Linux configure and SDL then aborts with
+ * "SDL could not find X11 or Wayland development libraries". Keeping the build
+ * tree out of the cached source path makes each machine configure its own. */
+const sdlBuild = join(vendorDir, "sdl-build");
 const freetypeSrc = join(vendorDir, "freetype");
 const freetypeBuild = join(vendorDir, "freetype-build");
 const harfbuzzSrc = join(vendorDir, "harfbuzz");
 const harfbuzzBuild = join(vendorDir, "harfbuzz-build");
+const ffmpegSrc = join(vendorDir, "ffmpeg");
+const ffmpegBuild = join(vendorDir, "ffmpeg-build");
+const ffmpegInstall = join(ffmpegBuild, "dist");
 const objDir = join(root, "build", "gui-obj");
 const outDir = join(runtimeDir, "lib", platformSlug());
 
@@ -82,8 +97,24 @@ const cmakeGeneratorArgs: readonly string[] = isWindows
 const SDL_TAG = process.env.SDL3_TAG || "release-3.2.10";
 const FREETYPE_VERSION = process.env.FREETYPE_VERSION || "2.13.3";
 const HARFBUZZ_VERSION = process.env.HARFBUZZ_VERSION || "10.1.0";
+const FFMPEG_VERSION = process.env.FFMPEG_VERSION || "7.1";
 const FREETYPE_URL = `https://download.savannah.gnu.org/releases/freetype/freetype-${FREETYPE_VERSION}.tar.xz`;
 const HARFBUZZ_URL = `https://github.com/harfbuzz/harfbuzz/releases/download/${HARFBUZZ_VERSION}/harfbuzz-${HARFBUZZ_VERSION}.tar.xz`;
+const FFMPEG_URL = `https://ffmpeg.org/releases/ffmpeg-${FFMPEG_VERSION}.tar.xz`;
+
+/* A deliberately minimal FFmpeg: containers and decoders for the common web
+ * media formats, file access only, no network, no encoder, no filter graph.
+ * Disabling everything first keeps the static libraries small and the build
+ * short. `--disable-x86asm` drops the nasm/yasm build dependency (the C
+ * fallbacks are plenty for playback). This configuration is LGPL-only, so the
+ * resulting `gui.a` stays redistributable under the engine's terms. */
+const FFMPEG_COMPONENTS: readonly string[] = [
+  "--enable-protocol=file",
+  "--enable-demuxer=mov,matroska,avi,flv,mpegts,mp3,ogg,wav,flac,aac,m4v,asf,mpeg,mpegvideo,h264,hevc,vc1",
+  "--enable-decoder=h264,hevc,vp8,vp9,av1,aac,aac_latm,mp3,mp3float,opus,vorbis,flac,alac,pcm_s16le,pcm_s24le,pcm_s32le,pcm_u8,pcm_f32le,pcm_alaw,pcm_mulaw,ac3,eac3,wmav2,mjpeg",
+  "--enable-parser=h264,hevc,vp8,vp9,av1,aac,aac_latm,mpegaudio,opus,vorbis,mpeg4video,mjpeg,flac",
+  "--enable-bsf=h264_mp4toannexb,hevc_mp4toannexb,aac_adtstoasc,vp9_superframe,vp9_superframe_split,extract_extradata",
+];
 
 function fail(message: string): never {
   console.error(`xbintsc: ${message}`);
@@ -93,13 +124,14 @@ function fail(message: string): never {
 function run(
   command: string,
   args: readonly string[],
-  options: { input?: string; quietStderr?: boolean } = {},
+  options: { input?: string; quietStderr?: boolean; cwd?: string } = {},
 ): SpawnSyncReturns<string> {
   const quiet = options.quietStderr === true;
   const result = spawnSync(command, args, {
     stdio: options.input !== undefined ? ["pipe", "inherit", "inherit"] : quiet ? ["ignore", "inherit", "pipe"] : "inherit",
     encoding: "utf8",
     input: options.input,
+    cwd: options.cwd,
   });
   if (result.status !== 0) {
     if (quiet && result.stderr) process.stderr.write(result.stderr);
@@ -142,12 +174,49 @@ function findCxx(): string {
   return cxx;
 }
 
+function findCc(): string {
+  const cc = firstAvailable([process.env.xbintsc_CC, process.env.CC, "clang", "cc", "gcc"]);
+  if (!cc) fail("no C compiler found; install clang or set xbintsc_CC");
+  return cc;
+}
+
 function findArchiver(): string {
   const ar = firstAvailable([process.env.xbintsc_AR, "llvm-ar", "ar"]);
   if (!ar) fail("no archiver found; set xbintsc_AR to llvm-ar or ar");
   return ar;
 }
 
+/** Directories a CMake `find_path` would search, relative to the filesystem
+ * root, used to check that a development package is installed. */
+const HEADER_PREFIXES = ["/usr/include", "/usr/local/include", "/opt/homebrew/include"];
+
+/** True on Debian and its derivatives, where the message below can name the
+ * packages to install. Anywhere else the headers may well live under a prefix
+ * this check does not know (`/usr/pkg`, `/nix/store`, …), so it stays quiet
+ * instead of failing a build that would have worked. */
+function isDebianLike(): boolean {
+  return existsSync("/etc/debian_version");
+}
+
+/** Fail with the package names to install when a header SDL needs is missing,
+ * rather than letting SDL configure itself without a window backend and then
+ * abort with a summary that does not say which package is missing. */
+function requireHeaders(feature: string, headers: readonly string[], packages: string): void {
+  if (isWindows || !isDebianLike()) return;
+  const missing = headers.filter(
+    (header) => !HEADER_PREFIXES.some((prefix) => existsSync(join(prefix, header))),
+  );
+  if (missing.length === 0) return;
+  const hint =
+    process.env.xbintsc_SKIP_HEADER_CHECK === "1"
+      ? ""
+      : " (set xbintsc_SKIP_HEADER_CHECK=1 if they are installed under a prefix this check does not know)";
+  fail(
+    `${feature} needs ${missing.join(", ")}, which is not installed; ` +
+      `install its development package first (Debian/Ubuntu: ${packages})${hint}`,
+  );
+}
+
 /** First of `candidates` that exists on disk (CMake generators place static
  * libraries either at the build root or under `Release/`). */
 function firstExisting(candidates: readonly string[]): string | undefined {
@@ -187,6 +256,16 @@ function harfbuzzArchive(): string | undefined {
   return builtLibrary(harfbuzzBuild, ["libharfbuzz.a", "harfbuzz.lib"], /^harfbuzz[-\d.]*\.lib$/);
 }
 
+/* FFmpeg's release tarball has no CMake build, so it uses its own configure +
+ * make. It also installs its headers under a prefix (rather than in the source
+ * tree) because the *source* root contains a file literally named `version`
+ * that would shadow the C++ standard header for any `.cpp` that includes it. */
+const FFMPEG_LIBRARY_NAMES = ["libavformat.a", "libavcodec.a", "libswscale.a", "libswresample.a", "libavutil.a"];
+function ffmpegStaticLibraries(): string[] | undefined {
+  const libraries = FFMPEG_LIBRARY_NAMES.map((name) => join(ffmpegInstall, "lib", name));
+  return libraries.every((library) => existsSync(library)) ? libraries : undefined;
+}
+
 /* -- 1. SDL3 source ------------------------------------------------------- */
 
 if (!existsSync(join(sdlSrc, "CMakeLists.txt"))) {
@@ -199,6 +278,28 @@ if (!existsSync(join(sdlSrc, "CMakeLists.txt"))) {
 
 const existingSdlArchive = sdlArchive();
 if (!existingSdlArchive) {
+  /* Older trees configured SDL inside its source (`vendor/SDL/build`) and a
+   * cache from one of those would be reused by the next configure — the exact
+   * failure `sdlBuild` above exists to prevent. */
+  const legacyBuild = join(sdlSrc, "build");
+  if (existsSync(join(legacyBuild, "CMakeCache.txt"))) {
+    console.log("xbintsc: discarding the legacy in-source SDL build tree");
+    rmSync(legacyBuild, { recursive: true, force: true });
+  }
+
+  /* SDL enables a window backend from the headers it finds, and aborts when it
+   * finds neither X11 nor Wayland, so say which package is missing instead of
+   * relaying its summary. */
+  requireHeaders(
+    "SDL3's X11 video driver",
+    /* `Xlib.h` comes from libx11-dev; `Xext.h` is the header SDL gates HAVE_X11
+     * on as well, and it comes from libxext-dev. */
+    ["X11/Xlib.h", "X11/extensions/Xext.h"],
+    "libx11-dev libxext-dev libxrandr-dev libxcursor-dev libxi-dev libxinerama-dev libxfixes-dev",
+  );
+  requireHeaders("SDL3's Wayland video driver", ["wayland-client-core.h"],
+    "libwayland-dev libxkbcommon-dev libdecor-0-dev");
+
   const cmake = findCmake();
   console.log(`xbintsc: building static SDL3 with ${cmake}`);
   const configureArgs = [
@@ -221,10 +322,12 @@ if (!existingSdlArchive) {
 
 /** Download a release tarball into `vendor/` and extract it under `name`.
  * Release tarballs are used (not git clones) because they ship generated
- * sources, so no ragel/autotools step is needed. */
-function ensureTarballSource(name: string, url: string, extractedName: string): string {
+ * sources, so no ragel/autotools step is needed. `marker` is a file that only
+ * exists once the tarball has been extracted (CMake projects ship
+ * `CMakeLists.txt`; FFmpeg ships `configure`). */
+function ensureTarballSource(name: string, url: string, extractedName: string, marker = "CMakeLists.txt"): string {
   const destination = join(vendorDir, name);
-  if (existsSync(join(destination, "CMakeLists.txt"))) return destination;
+  if (existsSync(join(destination, marker))) return destination;
   const tarball = join(vendorDir, `${name}.tar.xz`);
   console.log(`xbintsc: fetching ${name} from ${url}`);
   mkdirSync(vendorDir, { recursive: true });
@@ -284,6 +387,43 @@ if (!existsSync(harfbuzzArchive() ?? "")) {
   console.log(`xbintsc: reusing existing ${harfbuzzArchive()}`);
 }
 
+/* -- 2c. FFmpeg (media decoding) ------------------------------------------ */
+
+/* Windows builds have no `configure`/`make`, so media support is compiled out
+ * there; the element still works and reports an `error` event. */
+let ffmpegLibraries: string[] | undefined;
+if (isWindows) {
+  console.log("xbintsc: skipping FFmpeg on Windows; <video>/<audio> will report an error");
+} else {
+  ensureTarballSource("ffmpeg", FFMPEG_URL, `ffmpeg-${FFMPEG_VERSION}`, "configure");
+  ffmpegLibraries = ffmpegStaticLibraries();
+  if (!ffmpegLibraries) {
+    const cc = findCc();
+    const ccxx = findCxx();
+    console.log(`xbintsc: building minimal static FFmpeg ${FFMPEG_VERSION} with ${cc}`);
+    mkdirSync(ffmpegBuild, { recursive: true });
+    run(join(ffmpegSrc, "configure"), [
+      `--prefix=${ffmpegInstall}`,
+      "--enable-static", "--disable-shared",
+      "--disable-programs", "--disable-doc",
+      "--disable-htmlpages", "--disable-manpages", "--disable-podpages", "--disable-txtpages",
+      "--disable-avdevice", "--disable-avfilter", "--disable-postproc",
+      "--disable-everything",
+      "--enable-avformat", "--enable-avcodec", "--enable-avutil", "--enable-swscale", "--enable-swresample",
+      "--disable-network", "--disable-autodetect", "--disable-x86asm", "--disable-debug", "--enable-pic",
+      `--cc=${cc}`,
+      `--cxx=${ccxx}`,
+      ...FFMPEG_COMPONENTS,
+    ], { cwd: ffmpegBuild });
+    run("make", ["-j", String(availableParallelism())], { cwd: ffmpegBuild });
+    run("make", ["install"], { cwd: ffmpegBuild });
+    ffmpegLibraries = ffmpegStaticLibraries();
+  } else {
+    console.log(`xbintsc: reusing existing ${ffmpegInstall}/lib`);
+  }
+  if (!ffmpegLibraries) fail("FFmpeg build did not produce the expected static libraries");
+}
+
 /* -- 3. engine objects ---------------------------------------------------- */
 
 const cxx = findCxx();
@@ -295,12 +435,14 @@ const includeFlags = [
   "-I", join(freetypeBuild, "include"),
   "-I", join(harfbuzzSrc, "src"),
 ];
+if (ffmpegLibraries) includeFlags.push("-I", join(ffmpegInstall, "include"));
 const sources = readdirSync(engineDir)
   .filter((entry) => entry.endsWith(".cpp"))
   .sort();
 
 const objects: string[] = [];
 const cxxFlags = ["-std=c++17", "-O2", "-Wall", "-Wextra", ...includeFlags];
+if (ffmpegLibraries) cxxFlags.push("-DXT_GUI_WITH_FFMPEG=1");
 /* The engine is C++ and the MSVC C++ runtime must match the static C CRT that
  * clang links by default, so let every engine object record `libcpmt` as a
  * default library. The extension itself only contributes the DLL import library
@@ -324,7 +466,7 @@ const harfbuzz = harfbuzzArchive();
 if (!sdl || !freetype || !harfbuzz) {
   fail("one of the SDL3/FreeType/HarfBuzz archives was not found after building");
 }
-const libraries = [sdl, freetype, harfbuzz];
+const libraries = [sdl, freetype, harfbuzz, ...(ffmpegLibraries ?? [])];
 
 mkdirSync(outDir, { recursive: true });
 rmSync(output, { force: true });

package/scripts/check-file-length.ts

@@ -36,7 +36,11 @@ const IGNORED_DIRECTORIES = new Set([
 ]);
 
 /** Vendored third-party sources that ship verbatim and are not ours to split. */
-const VENDORED_FILES = new Set([join("runtime", "ext_gui", "stb_image.h")]);
+const VENDORED_FILES = new Set([
+  join("runtime", "ext_gui", "stb_image.h"),
+  join("runtime", "ext_gui", "nanosvg.h"),
+  join("runtime", "ext_gui", "nanosvgrast.h"),
+]);
 
 /** Machine-generated files: they are reproduced from their sources by a script,
  * so their size is not a sign of a module that needs splitting. */

package/scripts/install-gui-deps.sh

@@ -0,0 +1,28 @@
+#!/bin/sh
+#
+# Install everything Linux needs to build and exercise the GUI archive.
+#
+# `npm run gui` compiles SDL3 from source, so SDL3 needs to *find* the window
+# system it will use: without the X11/Wayland development headers it either
+# configures itself without a window backend and then aborts ("SDL could not
+# find X11 or Wayland development libraries"), or -- now -- `scripts/build-gui.ts`
+# says which package is missing. `cmake` configures the vendored libraries,
+# `clang` compiles the runtime and the emitted LLVM IR, `libvulkan-dev` plus a
+# driver gives SDL_GPU the Vulkan backend it selects on Linux, and `xvfb` lets
+# the example and the e2e suites run headlessly.
+#
+# One list, one place: every Linux job that runs `npm run gui` (or a GUI
+# example) sources this, so a job cannot quietly miss a package the others
+# install. Requires sudo and a Debian/Ubuntu host.
+#
+# Usage:  sudo sh scripts/install-gui-deps.sh
+set -eu
+
+apt-get update
+apt-get install -y \
+  clang cmake \
+  libx11-dev libxext-dev libxrandr-dev libxcursor-dev libxi-dev \
+  libxinerama-dev libxfixes-dev libxkbcommon-dev libwayland-dev \
+  wayland-protocols libdecor-0-dev libasound2-dev libpulse-dev \
+  libdbus-1-dev libudev-dev libdrm-dev libgbm-dev libgl1-mesa-dev \
+  libegl1-mesa-dev libvulkan-dev mesa-vulkan-drivers xvfb