Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

19.6 KB
Raw Blame
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0

"""A new sd.cpp bundle must start before replacing the installed one; Windows ROCm without the HIP SDK uses Vulkan."""

from __future__ import annotations

import io
import os
import re
import sys
import types
import zipfile
from pathlib import Path
from typing import Optional

import pytest

_STUDIO = Path(__file__).resolve().parents[2]
if str(_STUDIO) not in sys.path:
    sys.path.insert(0, str(_STUDIO))

import install_sd_cpp_prebuilt as sdmod  # noqa: E402

_CLI, _SERVER = sdmod._binary_names()
_WIN = sys.platform == "win32"


def _starting_binary() -> bytes:
    if _WIN:
        return (
            Path(os.environ.get("SystemRoot", r"C:\Windows")) / "System32" / "where.exe"
        ).read_bytes()
    return b"#!/bin/sh\necho 'usage: sd-cli [options]'\n"


def _refused_binary() -> bytes:
    """An executable the loader refuses (Windows: python.exe with its pythonXY.dll import renamed)."""
    if _WIN:
        data = (Path(sys.base_prefix) / "python.exe").read_bytes()
        dll = f"python{sys.version_info[0]}{sys.version_info[1]}".encode()
        patched = re.sub(re.escape(dll) + rb"(?=\.dll)", b"z" * len(dll), data, flags = re.I)
        assert patched != data
        return patched
    return (
        b"#!/bin/sh\necho 'sd-cli: error while loading shared libraries: libhipblas.so.3: "
        b"cannot open shared object file: No such file or directory' >&2\nexit 127\n"
    )


def _bundle(payload: bytes, subdir: str = "") -> bytes:
    buf = io.BytesIO()
    with zipfile.ZipFile(buf, "w") as zf:
        for name in (_CLI, _SERVER):
            zf.writestr(f"{subdir}{name}", payload)
        zf.writestr(f"{subdir}stable-diffusion.dll", b"payload")
    return buf.getvalue()


def _names():
    if _WIN:
        return {
            "rocm": "sd-master-0518b34-bin-win-rocm-10.1.0-x64.zip",
            "vulkan": "sd-master-0518b34-bin-win-vulkan-x64.zip",
        }
    return {
        "rocm": "sd-master-0518b34-bin-Linux-Ubuntu-24.04-x86_64-rocm-7.2.1.zip",
        "vulkan": "sd-master-0518b34-bin-Linux-Ubuntu-24.04-x86_64-vulkan.zip",
    }


def _stub_release(monkeypatch, zips: dict):
    names = _names()
    release = {
        "tag_name": "master-982-0518b34",
        "assets": [
            {"name": names[k], "browser_download_url": f"https://example.invalid/{names[k]}"}
            for k in zips
        ],
    }
    by_name = {names[k]: v for k, v in zips.items()}
    monkeypatch.setenv("UNSLOTH_SD_CPP_TAG", "")
    monkeypatch.setattr(sdmod, "_fetch_release", lambda *a, **k: release)
    monkeypatch.setattr(
        sdmod, "_download", lambda url, dest, **k: dest.write_bytes(by_name[url.rsplit("/", 1)[1]])
    )
    monkeypatch.setattr(sdmod.platform, "system", lambda: "Windows" if _WIN else "Linux")
    monkeypatch.setattr(sdmod.platform, "machine", lambda: "AMD64" if _WIN else "x86_64")


def _managed_root(tmp_path, monkeypatch) -> Path:
    root = tmp_path / "sd-home" / "stable-diffusion.cpp"
    root.mkdir(parents = True)
    (root / sdmod.OWNERSHIP_MARKER).touch()
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path / "sd-home" / "studio"))
    sdmod._INSTALLED_ACCELERATOR_MEMO.clear()
    return root


def _working_vulkan_install(root: Path) -> Path:
    """What the affected host had: the mirror's Vulkan build in its versioned subdirectory."""
    sub = root / "sd-master-982-0518b34-uaba3a1c-bin-win-vulkan-x64"
    sub.mkdir()
    for name in (_CLI, _SERVER):
        (sub / name).write_bytes(_starting_binary())
        if not _WIN:
            (sub / name).chmod(0o755)
    sdmod._write_install_record(root, accelerator = "vulkan", repo = sdmod.DEFAULT_REPO, tag = "t")
    return sub / _SERVER


def test_the_loader_refusal_is_read_from_the_exit_status_and_output():
    assert "not found" in sdmod.loader_refusal(0xC0000135)
    # Python reports the NTSTATUS signed on some builds.
    assert sdmod.loader_refusal(0xC0000135 - (1 << 32))
    assert sdmod.loader_refusal(0xC0000139)
    assert sdmod.loader_refusal(
        127, "sd-cli: error while loading shared libraries: libhipblas.so.3"
    )
    # A process that reached main is not refused, whatever it exits with.
    assert sdmod.loader_refusal(0) is None
    assert sdmod.loader_refusal(1, "unknown option --help") is None
    assert sdmod.loader_refusal(127) is None
    assert sdmod.loader_refusal(None) is None


def test_a_glibc_symbol_version_failure_is_a_loader_refusal():
    assert sdmod.loader_refusal(
        1,
        "./sd-cli: /opt/sd/libstable-diffusion.so: version `LIBDEMO_2' not found "
        "(required by ./sd-cli)",
    )
    assert sdmod.loader_refusal(
        1,
        "./sd-cli: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.38' not found (required by ./sd-cli)",
    )
    assert sdmod.loader_refusal(1, "error: model file not found") is None


def _build_version_mismatch(tmp: Path) -> Optional[Path]:
    import shutil
    import subprocess

    cc = shutil.which("cc") or shutil.which("gcc")
    if _WIN or sys.platform == "darwin" or not cc:
        return None
    (tmp / "v1.map").write_text("LIBDEMO_1 { global: demo; local: *; };\n")
    (tmp / "v2.map").write_text("LIBDEMO_2 { global: demo; local: *; };\n")
    (tmp / "lib.c").write_text("int demo(void) { return 0; }\n")
    (tmp / "main.c").write_text("int demo(void);\nint main(void) { return demo(); }\n")
    build = tmp / "build"
    build.mkdir()
    try:
        for ver, out in (("v2.map", build / "libdemo.so"), ("v1.map", tmp / "libdemo.so")):
            subprocess.run(
                [
                    cc,
                    "-shared",
                    "-fPIC",
                    f"-Wl,--version-script={tmp / ver}",
                    "-o",
                    str(out),
                    str(tmp / "lib.c"),
                ],
                check = True,
                capture_output = True,
            )
        exe = tmp / _CLI
        subprocess.run(
            [cc, "-o", str(exe), str(tmp / "main.c"), f"-L{build}", "-ldemo"],
            check = True,
            capture_output = True,
        )
    except (OSError, subprocess.CalledProcessError):
        return None
    return exe


def test_probe_refuses_a_real_elf_whose_library_lacks_the_needed_version(tmp_path):
    exe = _build_version_mismatch(tmp_path)
    if exe is None:
        pytest.skip("needs a Linux C toolchain")
    assert sdmod.probe_binary_starts(exe)


def test_probe_reports_a_refused_binary_and_passes_a_starting_one(tmp_path):
    bad = tmp_path / "bad" / _CLI
    good = tmp_path / "good" / _CLI
    for path, data in ((bad, _refused_binary()), (good, _starting_binary())):
        path.parent.mkdir()
        path.write_bytes(data)
        if not _WIN:
            path.chmod(0o755)
    assert sdmod.probe_binary_starts(bad)
    assert sdmod.probe_binary_starts(good) is None


def test_a_bundle_that_cannot_start_never_replaces_the_working_one(tmp_path, monkeypatch):
    """Regression: a refused ROCm zip must not sweep the working Vulkan build."""
    root = _managed_root(tmp_path, monkeypatch)
    old_server = _working_vulkan_install(root)
    before = old_server.read_bytes()
    _stub_release(monkeypatch, {"rocm": _bundle(_refused_binary())})

    with pytest.raises(RuntimeError, match = "cannot start"):
        sdmod.install(install_dir = root, accelerator = "rocm")

    assert old_server.is_file() and old_server.read_bytes() == before
    assert (old_server.parent / _CLI).is_file()
    # Nothing of the refused bundle reached the tree, and its record still names the working build.
    assert not (root / _CLI).exists() and not (root / _SERVER).exists()
    assert sdmod.read_install_record(root).get("accelerator") == "vulkan"
    assert not list(root.parent.glob(".sd-cpp-verify-*"))


@pytest.mark.skipif(_WIN, reason = "glibc loader message")
def test_a_symbol_version_refusal_never_replaces_the_working_one(tmp_path, monkeypatch):
    root = _managed_root(tmp_path, monkeypatch)
    old_server = _working_vulkan_install(root)
    before = old_server.read_bytes()
    refused = (
        b"#!/bin/sh\necho \"$0: /opt/libstable-diffusion.so: version \\`LIBDEMO_2' not found "
        b'(required by $0)" >&2\nexit 1\n'
    )
    _stub_release(monkeypatch, {"rocm": _bundle(refused)})

    with pytest.raises(sdmod.UnrunnableBuildError):
        sdmod.install(install_dir = root, accelerator = "rocm")

    assert old_server.is_file() and old_server.read_bytes() == before
    assert sdmod.read_install_record(root).get("accelerator") == "vulkan"


def test_the_refusal_names_what_was_asked_for(tmp_path, monkeypatch):
    root = _managed_root(tmp_path, monkeypatch)
    _stub_release(monkeypatch, {"rocm": _bundle(_refused_binary())})
    with pytest.raises(sdmod.UnrunnableBuildError) as info:
        sdmod.install(install_dir = root, accelerator = "rocm")
    assert info.value.accelerator == "rocm"
    assert info.value.asset == _names()["rocm"]


def test_a_bundle_that_starts_still_replaces_the_previous_one(tmp_path, monkeypatch):
    root = _managed_root(tmp_path, monkeypatch)
    old_server = _working_vulkan_install(root)
    _stub_release(monkeypatch, {"rocm": _bundle(_starting_binary())})

    cli = sdmod.install(install_dir = root, accelerator = "rocm")

    assert cli == root / _CLI
    assert not old_server.exists()
    assert sdmod.read_install_record(root).get("accelerator") == "rocm"
    assert not list(root.parent.glob(".sd-cpp-verify-*"))


def test_the_kill_switch_restores_the_unverified_install(tmp_path, monkeypatch):
    monkeypatch.setenv("UNSLOTH_SD_CPP_VERIFY_INSTALL", "0")
    root = _managed_root(tmp_path, monkeypatch)
    old_server = _working_vulkan_install(root)
    _stub_release(monkeypatch, {"rocm": _bundle(_refused_binary())})

    sdmod.install(install_dir = root, accelerator = "rocm")

    assert not old_server.exists()
    assert (root / _SERVER).is_file()


def test_cuda_bundles_are_not_probed(tmp_path):
    # They load the host / llama.cpp CUDA runtime the backend adds at spawn; a bare probe would refuse them.
    assert sdmod._should_verify("sd-master-x-bin-win-cuda12-x64.zip") is False
    assert sdmod._should_verify("sd-master-x-bin-win-rocm-10.1.0-x64.zip") is True


# --- backend: the Windows ROCm request and the install ladder ---------------------------------


@pytest.fixture
def fake_settings(monkeypatch):
    from storage import studio_db

    store: dict = {}
    monkeypatch.setattr(
        studio_db, "get_app_setting", lambda key, fallback = None: store.get(key, fallback)
    )
    monkeypatch.setattr(
        studio_db,
        "upsert_app_settings",
        lambda settings, **_k: store.update(settings) or dict(store),
    )
    return store


@pytest.fixture
def backend(monkeypatch, fake_settings):
    from core.inference import sd_cpp_backend as bk

    monkeypatch.setattr(bk, "_accelerator_runtime_failures", {}, raising = False)
    monkeypatch.setattr(
        bk,
        "_HOST_FINGERPRINT_MEMO",
        {"runtime": "7.1", "gpus": ["AMD Radeon 8060S"]},
        raising = False,
    )
    monkeypatch.setattr(bk, "_failed_accelerator_upgrades", set(), raising = False)
    monkeypatch.setattr(bk, "_failed_pin_upgrades", set(), raising = False)
    monkeypatch.delenv("UNSLOTH_DIFFUSION_SD_CPP_VULKAN_FALLBACK", raising = False)
    return bk


@pytest.fixture
def windows_host(monkeypatch, backend, tmp_path):
    """A Windows host whose loader search path is ``dirs``; add hipblas.dll to one to install the HIP SDK."""
    sdk = tmp_path / "hip-sdk-bin"
    system32 = tmp_path / "System32"
    sdk.mkdir()
    system32.mkdir()
    # The Adrenalin driver puts amdhip64 in System32; hipblas only comes with the HIP SDK.
    (system32 / "amdhip64_7.dll").write_bytes(b"")
    monkeypatch.delenv("UNSLOTH_SD_CPP_WINDOWS_ROCM", raising = False)
    monkeypatch.setattr(backend, "_on_windows", lambda: True, raising = False)
    monkeypatch.setattr(
        backend, "_windows_dll_search_dirs", lambda: [str(system32), str(sdk)], raising = False
    )
    return types.SimpleNamespace(sdk = sdk, system32 = system32)


def test_windows_rocm_without_the_hip_sdk_starts_at_vulkan(windows_host, backend):
    assert backend.preferred_accelerator("rocm") == "vulkan"


def test_windows_rocm_with_the_hip_sdk_on_path_keeps_rocm(windows_host, backend):
    (windows_host.sdk / "hipblas.dll").write_bytes(b"")
    assert backend.preferred_accelerator("rocm") == "rocm"


@pytest.mark.parametrize(
    "env,value,want",
    [
        ("UNSLOTH_SD_CPP_WINDOWS_ROCM", "1", "rocm"),
        ("UNSLOTH_SD_CPP_WINDOWS_ROCM", "0", "vulkan"),
        ("UNSLOTH_DIFFUSION_SD_CPP_VULKAN_FALLBACK", "0", "rocm"),
    ],
)
def test_windows_rocm_kill_switches(windows_host, backend, monkeypatch, env, value, want):
    monkeypatch.setenv(env, value)
    assert backend.preferred_accelerator("rocm") == want


def test_other_hosts_and_accelerators_are_untouched(backend, monkeypatch):
    monkeypatch.delenv("UNSLOTH_SD_CPP_WINDOWS_ROCM", raising = False)
    monkeypatch.setattr(backend, "_on_windows", lambda: False, raising = False)
    assert backend.preferred_accelerator("rocm") == "rocm"
    monkeypatch.setattr(backend, "_on_windows", lambda: True, raising = False)
    monkeypatch.setattr(backend, "_windows_dll_search_dirs", lambda: [], raising = False)
    assert backend.preferred_accelerator("cuda") == "cuda"
    assert backend.preferred_accelerator("vulkan") == "vulkan"


def test_an_unstartable_rocm_bundle_falls_to_the_vulkan_build(tmp_path, monkeypatch, backend):
    """A fresh install with a refused ROCm bundle ends on Vulkan and records the host."""
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path / "sd-home" / "studio"))
    sdmod._INSTALLED_ACCELERATOR_MEMO.clear()
    root = sdmod.default_install_dir()
    _stub_release(
        monkeypatch,
        {"rocm": _bundle(_refused_binary()), "vulkan": _bundle(_starting_binary(), "vk/")},
    )
    monkeypatch.setattr(backend, "_managed_tree_in_use", lambda: False)
    monkeypatch.setattr(backend, "is_managed_binary", lambda _b: True)

    server = backend.ensure_sd_server_binary(accelerator = "rocm")

    assert server is not None and Path(server) == root / "vk" / _SERVER
    assert sdmod.read_install_record(root).get("accelerator") == "vulkan"
    assert backend.accelerator_runtime_failed("rocm") is True
    assert backend.preferred_accelerator("rocm") == "vulkan"
    cli = backend.ensure_sd_cpp_binary(accelerator = backend.preferred_accelerator("rocm"))
    assert cli is not None and Path(cli) == root / "vk" / _CLI


def test_the_refusal_record_survives_a_fallback_from_another_release(
    tmp_path, monkeypatch, backend
):
    """The record applies even when the Vulkan fallback comes from a non-pinned release."""
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path / "sd-home" / "studio"))
    sdmod._INSTALLED_ACCELERATOR_MEMO.clear()
    root = sdmod.default_install_dir()
    _stub_release(
        monkeypatch,
        {"rocm": _bundle(_refused_binary()), "vulkan": _bundle(_starting_binary(), "vk/")},
    )
    monkeypatch.setattr(sdmod, "_pinned_tag", lambda: "master-982-0518b34-uaba3a1c")
    monkeypatch.setattr(backend, "_managed_tree_in_use", lambda: False)
    monkeypatch.setattr(backend, "is_managed_binary", lambda _b: True)

    server = backend.ensure_sd_server_binary(accelerator = "rocm")

    assert server is not None
    assert sdmod.read_install_record(root).get("tag") != "master-982-0518b34-uaba3a1c"
    assert backend.accelerator_runtime_failed("rocm") is True
    assert backend.preferred_accelerator("rocm") == "vulkan"


def _dll_dir(path: Path, *dlls: str) -> Path:
    path.mkdir(parents = True, exist_ok = True)
    for dll in dlls:
        (path / dll).write_bytes(b"")
    return path


@pytest.fixture
def hip_sdk(tmp_path, monkeypatch):
    """HIP SDK 7.2 as its MSI leaves it: HIP_PATH (with its trailing separator) set, bin dir not on PATH."""
    program_files = tmp_path / "Program Files"
    root = program_files / "AMD" / "ROCm" / "7.2"
    bindir = _dll_dir(root / "bin", "hipblas.dll", "rocblas.dll", "amdhip64_7.dll")
    monkeypatch.setenv("ProgramFiles", str(program_files))
    monkeypatch.setenv("HIP_PATH", str(root) + os.sep)
    monkeypatch.delenv("ROCM_PATH", raising = False)
    return types.SimpleNamespace(bin = bindir, program_files = program_files)


def _rocm_bundle(tmp_path: Path) -> Path:
    """The upstream win-rocm layout: amdhip64_7.dll beside sd-cli, hipblas.dll left to the SDK."""
    return _dll_dir(tmp_path / "bundle", _CLI, "stable-diffusion.dll", "amdhip64_7.dll") / _CLI


def test_the_hip_sdk_is_found_through_hip_path(hip_sdk):
    assert sdmod.windows_hip_sdk_bin_dirs() == [str(hip_sdk.bin)]


def test_without_hip_path_the_default_location_is_searched_newest_7x_first(hip_sdk, monkeypatch):
    monkeypatch.delenv("HIP_PATH")
    rocm = hip_sdk.program_files / "AMD" / "ROCm"
    older = _dll_dir(rocm / "7.1" / "bin", "hipblas.dll", "amdhip64_7.dll")
    # A 6.x hipblas.dll binds amdhip64_6.dll, not the bundle's HIP 7 runtime.
    _dll_dir(rocm / "6.4" / "bin", "hipblas.dll", "amdhip64_6.dll")
    assert sdmod.windows_hip_sdk_bin_dirs() == [str(hip_sdk.bin), str(older)]


def test_no_hip_sdk_finds_nothing(tmp_path, monkeypatch):
    monkeypatch.setenv("ProgramFiles", str(tmp_path / "Program Files"))
    monkeypatch.delenv("HIP_PATH", raising = False)
    monkeypatch.delenv("ROCM_PATH", raising = False)
    assert sdmod.windows_hip_sdk_bin_dirs() == []


def _search_path(env: dict, var: str) -> list[str]:
    return env[var].split(os.pathsep)


def test_the_rocm_bundle_child_gets_the_hip_sdk_after_the_callers_path(tmp_path, hip_sdk):
    from core.inference import sd_cpp_engine

    binary = _rocm_bundle(tmp_path)
    var = sd_cpp_engine._lib_path_var()
    env = sd_cpp_engine.runtime_env(str(binary), {var: "caller-dir"})
    assert _search_path(env, var) == [str(binary.parent.resolve()), "caller-dir", str(hip_sdk.bin)]
    probe = sdmod._probe_env(binary)
    assert _search_path(probe, var)[0] == str(binary.parent)
    assert _search_path(probe, var)[-1] == str(hip_sdk.bin)


def test_other_bundles_and_a_bundled_hipblas_get_no_hip_sdk(tmp_path, hip_sdk):
    from core.inference import sd_cpp_engine

    vulkan = _dll_dir(tmp_path / "vk", _CLI, "stable-diffusion.dll") / _CLI
    rocm_with_hipblas = _dll_dir(tmp_path / "full", _CLI, "amdhip64_7.dll", "hipblas.dll") / _CLI
    var = sd_cpp_engine._lib_path_var()
    for binary in (vulkan, rocm_with_hipblas):
        assert sdmod.hip_sdk_dirs_for_bundle(binary.parent) == []
        env = sd_cpp_engine.runtime_env(str(binary), {var: "caller-dir"})
        assert str(hip_sdk.bin) not in _search_path(env, var)


@pytest.fixture
def windows_path_only(tmp_path, monkeypatch, backend):
    system_root = tmp_path / "Windows"
    (system_root / "System32").mkdir(parents = True)
    monkeypatch.setenv("SystemRoot", str(system_root))
    monkeypatch.setenv("PATH", str(_dll_dir(tmp_path / "on-path")))
    monkeypatch.delenv("UNSLOTH_SD_CPP_WINDOWS_ROCM", raising = False)
    monkeypatch.setattr(backend, "_on_windows", lambda: True, raising = False)
    return backend


def test_windows_rocm_with_the_hip_sdk_installed_off_path_keeps_rocm(windows_path_only, hip_sdk):
    assert windows_path_only.windows_hip_runtime_missing_dlls() == []
    assert windows_path_only.preferred_accelerator("rocm") == "rocm"


def test_windows_rocm_without_any_hip_sdk_still_starts_at_vulkan(
    windows_path_only, tmp_path, monkeypatch
):
    monkeypatch.setenv("ProgramFiles", str(tmp_path / "Program Files"))
    monkeypatch.delenv("HIP_PATH", raising = False)
    monkeypatch.delenv("ROCM_PATH", raising = False)
    assert windows_path_only.windows_hip_runtime_missing_dlls() == ["hipblas.dll"]
    assert windows_path_only.preferred_accelerator("rocm") == "vulkan"