Linux build: fix resource_path resolution for frozen build + auto build script

[TurekCom]

Title: Linux build: fix resource_path resolution for frozen build + auto build script

Hi, I tested basiliskLLM on Linux and found a resource path issue in frozen builds.

Problem

• Runtime error:
  Failed to load sound: .../dist/basilisk/res/sounds/progress.wav
• In Linux cx_Freeze build, resources are in dist/res/..., while code expected a different path in some layouts.

What I changed

1. basilisk/global_vars.py

• Added _resolve_resource_path() that checks multiple valid locations and picks the first existing one:
  • <base_path>/res
  • <base_path>/_internal/basilisk/res (PyInstaller-style layout)
  • <package_dir>/res (source run)

2. Added helper build script

• scripts/update_and_build_from_github.py
• Clones/updates repo and builds automatically on Linux using uv (or pip/venv fallback).

Result

• Rebuild completed successfully on Linux.
• progress.wav resolved correctly from dist/res/sounds/progress.wav.
• App starts and sound loading error is gone.

Patch

• I attached a patch generated from commit:
  4a0c023 Fix frozen resource path and add GitHub auto-build script

If you want, I can split this into 2 separate commits (bugfix + build tooling).

[TurekCom]

Patch (from commit 4a0c023)

From 4a0c02308ecb3249f5d27ec33525093c13646c03 Mon Sep 17 00:00:00 2001
From: grzegorz <grzegorz@local>
Date: Thu, 12 Feb 2026 21:59:08 +0100
Subject: [PATCH] Fix frozen resource path and add GitHub auto-build script

---
 basilisk/global_vars.py                 |  20 ++-
 scripts/update_and_build_from_github.py | 180 ++++++++++++++++++++++++
 2 files changed, 199 insertions(+), 1 deletion(-)
 create mode 100755 scripts/update_and_build_from_github.py

diff --git a/basilisk/global_vars.py b/basilisk/global_vars.py
index e75e396..76cae55 100644
--- a/basilisk/global_vars.py
+++ b/basilisk/global_vars.py
@@ -11,6 +11,24 @@ base_path = Path(
 	sys.executable if getattr(sys, "frozen", False) else __file__
 ).parent
 
+
+def _resolve_resource_path() -> Path:
+	"""Resolve resource directory for source and frozen builds.
+
+	PyInstaller onedir builds commonly place bundled data under
+	`<exe_dir>/_internal/basilisk/res`, while source runs use
+	`<package_dir>/res`.
+	"""
+	candidates = [
+		base_path / Path("res"),
+		base_path / Path("_internal", "basilisk", "res"),
+		Path(__file__).resolve().parent / Path("res"),
+	]
+	for candidate in candidates:
+		if candidate.exists():
+			return candidate
+	return candidates[0]
+
 # application configuration inside the base directory (useful for portable installations)
 user_data_path = (
 	base_path / Path("user_data")
@@ -19,7 +37,7 @@ user_data_path = (
 )
 
 # resource directory present in the base directory (contains translation, sounds, etc.)
-resource_path = base_path / Path("res")
+resource_path = _resolve_resource_path()
 
 # command-line arguments parsed by the application
 args = None
diff --git a/scripts/update_and_build_from_github.py b/scripts/update_and_build_from_github.py
new file mode 100755
index 0000000..7978b1a
--- /dev/null
+++ b/scripts/update_and_build_from_github.py
@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+"""Clone/update basiliskLLM from GitHub and build it on Linux."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+DEFAULT_REPO_URL = "https://github.com/SigmaNight/basiliskLLM.git"
+
+
+def run(cmd: list[str], cwd: Path | None = None) -> None:
+    where = f" (cwd={cwd})" if cwd else ""
+    print(f"==> {' '.join(cmd)}{where}")
+    subprocess.run(cmd, cwd=str(cwd) if cwd else None, check=True)
+
+
+def check_tool(name: str) -> None:
+    if shutil.which(name) is None:
+        raise RuntimeError(f"Required tool not found: {name}")
+
+
+def is_git_repo(path: Path) -> bool:
+    return (path / ".git").exists()
+
+
+def is_dirty_repo(repo_dir: Path) -> bool:
+    result = subprocess.run(
+        ["git", "status", "--porcelain"],
+        cwd=repo_dir,
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    return bool(result.stdout.strip())
+
+
+def resolve_branch(repo_dir: Path, requested_branch: str | None) -> str:
+    if requested_branch:
+        return requested_branch
+    result = subprocess.run(
+        ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+        cwd=repo_dir,
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    branch = result.stdout.strip()
+    if not branch or branch == "HEAD":
+        raise RuntimeError(
+            "Detached HEAD detected. Pass --branch explicitly to continue."
+        )
+    return branch
+
+
+def ensure_repo(args: argparse.Namespace) -> Path:
+    repo_dir = Path(args.repo_dir).expanduser().resolve()
+
+    if repo_dir.exists() and not is_git_repo(repo_dir):
+        raise RuntimeError(f"Target path exists but is not a git repo: {repo_dir}")
+
+    if not repo_dir.exists():
+        repo_dir.parent.mkdir(parents=True, exist_ok=True)
+        clone_cmd = ["git", "clone"]
+        if args.branch:
+            clone_cmd += ["--branch", args.branch]
+        clone_cmd += [args.repo_url, str(repo_dir)]
+        run(clone_cmd)
+
+    if args.skip_pull:
+        return repo_dir
+
+    if not args.allow_dirty and is_dirty_repo(repo_dir):
+        raise RuntimeError(
+            "Repository has local changes. Commit/stash changes or use --allow-dirty."
+        )
+
+    branch = resolve_branch(repo_dir, args.branch)
+    run(["git", "fetch", "origin", branch], cwd=repo_dir)
+    run(["git", "pull", "--ff-only", "origin", branch], cwd=repo_dir)
+    return repo_dir
+
+
+def build_with_uv(repo_dir: Path) -> None:
+    run(["uv", "sync", "--frozen", "--group", "build"], cwd=repo_dir)
+    run(["uv", "run", "setup.py", "compile_catalog"], cwd=repo_dir)
+    run(["uv", "run", "-m", "cx_Freeze", "build_exe"], cwd=repo_dir)
+
+
+def build_with_pip(repo_dir: Path, python_bin: str) -> None:
+    venv_dir = repo_dir / ".venv"
+    run([python_bin, "-m", "venv", str(venv_dir)], cwd=repo_dir)
+
+    python = venv_dir / "bin" / "python"
+    run([str(python), "-m", "pip", "install", "-U", "pip", "setuptools", "wheel"], cwd=repo_dir)
+    run([str(python), "-m", "pip", "install", "-e", "."], cwd=repo_dir)
+    run(
+        [
+            str(python),
+            "-m",
+            "pip",
+            "install",
+            "setuptools-scm>=9.2.2",
+            "cx_freeze>=8.5.3",
+        ],
+        cwd=repo_dir,
+    )
+    run([str(python), "setup.py", "compile_catalog"], cwd=repo_dir)
+    run([str(python), "-m", "cx_Freeze", "build_exe"], cwd=repo_dir)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Clone/update basiliskLLM from GitHub and build it on Linux."
+    )
+    parser.add_argument("--repo-url", default=DEFAULT_REPO_URL, help="Git repository URL")
+    parser.add_argument(
+        "--repo-dir",
+        default="./basiliskLLM",
+        help="Local repo directory (clone destination or existing repo)",
+    )
+    parser.add_argument("--branch", default=None, help="Branch to fetch/pull")
+    parser.add_argument("--skip-pull", action="store_true", help="Skip git fetch/pull")
+    parser.add_argument(
+        "--allow-dirty",
+        action="store_true",
+        help="Allow build with local uncommitted changes",
+    )
+    parser.add_argument(
+        "--use-pip",
+        action="store_true",
+        help="Use pip/venv flow even if uv is installed",
+    )
+    parser.add_argument(
+        "--python",
+        default="python3",
+        help="Python executable for pip/venv flow",
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+
+    try:
+        check_tool("git")
+        repo_dir = ensure_repo(args)
+
+        if shutil.which("uv") and not args.use_pip:
+            print("==> Using uv workflow...")
+            build_with_uv(repo_dir)
+        else:
+            if shutil.which(args.python) is None:
+                raise RuntimeError(f"Python executable not found: {args.python}")
+            print("==> Using pip/venv workflow...")
+            build_with_pip(repo_dir, args.python)
+
+        dist_dir = repo_dir / "dist"
+        print("==> Build finished")
+        print(f"Output directory: {dist_dir}")
+        if dist_dir.exists():
+            for entry in sorted(dist_dir.iterdir()):
+                suffix = "/" if entry.is_dir() else ""
+                print(f" - {entry.name}{suffix}")
+        return 0
+    except subprocess.CalledProcessError as exc:
+        print(f"ERROR: command failed with exit code {exc.returncode}: {exc.cmd}", file=sys.stderr)
+        return exc.returncode
+    except Exception as exc:  # pragma: no cover - CLI error path
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
-- 
2.43.0

[AAClause]

@TurekCom Thanks a lot for this!
I haven't taken the time to test BasiliskLLM under Linux yet. Is it generally usable?
You're welcome to submit a PR if you'd like, but we can also apply the patch directly, just let us know how you'd like to be credited! :)

[TurekCom]

Generally, basiliskllm works under Linux Mint Mate with the Orca screen reader. The only problem is selecting the model. Orca doesn't read the list box, so you have to use the arrow key to select it and press Enter to see which model you've selected.
There's also a problem with automatic updating, but that might be because the program was compiled from source code, and gemini-cli or codex handled everything, which wasn't smooth.
If basiliskllm were installed from a repository, updates would proceed smoothly. I also submitted this issue using codex because I don't know how to send commits to GitHub, and codex itself couldn't send a commit because it didn't have permissions. I'm not familiar with GitHub in general, so it's good that there are tools that make such tasks easier.
Oh, and I translated this text from Polish into English, so don't be surprised if there are some errors in this comment.
Best regards.