From a8aa640b793f86c099cb7ebe2b96d3df33bcfbeb Mon Sep 17 00:00:00 2001
From: Matthew Stanley <1379tech@gmail.com>
Date: Fri, 24 Jul 2026 13:02:44 -0700
Subject: [PATCH] runtime: name the exact CLI flag when no file picker is
 available

On macOS/Linux there is no native GUI file picker, and in headless mode a
picker would block, so pick_runtime_file() bails when it can't resolve the
BIOS/disc interactively. The old message ("<title> requires a command-line
path on this platform") never said WHICH flag to pass, so a first-time
from-source user on Linux hit "no BIOS selected; exiting." with no idea what
to do.

Thread the responsible flag (--bios / --disc) into pick_runtime_file and print
an actionable message with the flag and a full example command, on both the
headless and the no-GUI-picker paths. Points at the game README's "Building
From Source" for the full run line.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 runtime/src/main.cpp | 23 +++++++++++++++++------
 1 file changed, 17 insertions(+), 6 deletions(-)

diff --git a/runtime/src/main.cpp b/runtime/src/main.cpp
index fa02815f..f8f8ee66 100644
--- a/runtime/src/main.cpp
+++ b/runtime/src/main.cpp
@@ -863,12 +863,14 @@ static void launcher_info(const char* title, const std::string& msg) {
 static std::string s_picker_game_name = "PSXRecomp";
 
 static bool pick_runtime_file(const char* title, const char* filter,
-                              std::filesystem::path& out) {
+                              std::filesystem::path& out, const char* cli_flag) {
     // Headless: never open an interactive file dialog (it blocks). Fail the
     // resolve so boot aborts cleanly with the stderr message the caller printed.
     if (g_headless) {
-        std::fprintf(stderr, "psxrecomp: headless — cannot prompt for '%s'; "
-                             "supply it via game.toml / --disc / --bios.\n", title);
+        std::fprintf(stderr,
+            "psxrecomp: headless — cannot prompt for '%s'.\n"
+            "  Supply it on the command line:  %s <path>   (or set it in game.toml).\n",
+            title, cli_flag);
         return false;
     }
 #ifdef _WIN32
@@ -891,7 +893,16 @@ static bool pick_runtime_file(const char* title, const char* filter,
 #else
     (void)filter;
     (void)out;
-    std::fprintf(stderr, "psxrecomp: %s requires a command-line path on this platform.\n", title);
+    // No native GUI file picker on this platform (macOS/Linux): the file must be
+    // named on the command line. Tell the user the exact flag + a full example
+    // instead of a dead-end "requires a command-line path".
+    std::fprintf(stderr,
+        "psxrecomp: no graphical file picker on this platform — '%s'\n"
+        "  must be supplied on the command line:  %s <path>\n"
+        "  Example:  ./<game-exe> --game game.toml "
+        "--bios /path/to/SCPH1001.BIN --disc /path/to/game.cue\n"
+        "  (or set the path in game.toml). See the game's README, \"Building From Source\".\n",
+        title, cli_flag);
     return false;
 #endif
 }
@@ -1059,7 +1070,7 @@ static std::filesystem::path resolve_bios_for_runtime(const char* requested,
         if (!pick_runtime_file(
                 bios_title.c_str(),
                 "PlayStation BIOS (*.bin)\0*.bin\0All Files (*.*)\0*.*\0",
-                picked)) {
+                picked, "--bios")) {
             return {};
         }
         if (validate_bios_for_launch(picked)) {
@@ -1118,7 +1129,7 @@ static std::filesystem::path resolve_disc_for_runtime(const std::filesystem::pat
         if (!pick_runtime_file(
                 disc_title.c_str(),
                 "PS1 Disc Images (*.cue;*.bin;*.iso)\0*.cue;*.bin;*.iso\0All Files (*.*)\0*.*\0",
-                picked)) {
+                picked, "--disc")) {
             return {};
         }
         picked = normalize_disc_path_for_launch(picked);