Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,16 @@ fontconfig (xim:fontconfig) and the C runtime only; X11, Wayland and GL are load
when used. `mcpplibs::mwrap::slint::macros::SLINT_FEATURE_RENDERER_SKIA` and the
others say which features are present.

### A window on Linux needs a GL vendor

libglvnd is only a dispatcher: a window on the default OpenGL renderer also needs the
vendor library (Mesa, or NVIDIA's on an NVIDIA X server). `compat.slint` depends on
`compat.glx-runtime` (the same package `compat.glfw` uses) for it, so a project needs
nothing extra; an older descriptor needs `compat.glx-runtime = "2026.09.11"` in
`[dependencies]`. If a window still aborts with `argument does not name a valid config`,
[`tools/check_display/`](tools/check_display/README.md) shows which part is missing;
`SLINT_BACKEND=winit-software` runs without GL meanwhile.

## Build and testing

Linux, macOS and Windows CI build the modules with GCC and Clang and run the tests:
Expand Down
9 changes: 9 additions & 0 deletions README.zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,15 @@ int main() {
Linux 上该库只依赖 fontconfig(xim:fontconfig)和 C 运行时;X11、Wayland 与 GL 在用到时
动态加载。`mcpplibs::mwrap::slint::macros::SLINT_FEATURE_RENDERER_SKIA` 等常量说明哪些功能存在。

### Linux 上的窗口需要 GL 厂商库

libglvnd 只是分发器:默认的 OpenGL 渲染器开窗口还需要厂商库(Mesa;NVIDIA 的 X 服务器上是
NVIDIA 的)。`compat.slint` 依赖 `compat.glx-runtime`(`compat.glfw` 用的同一个包)来提供它,
项目不需要额外写什么;更早的描述符则需要在 `[dependencies]` 里加
`compat.glx-runtime = "2026.09.11"`。窗口仍以 `argument does not name a valid config` 中止时,
[`tools/check_display/`](tools/check_display/README.md) 能指出缺的是哪一环;
期间可用 `SLINT_BACKEND=winit-software` 不经 GL 运行。

## 构建与测试

Linux、macOS 与 Windows 的 CI 用 GCC 和 Clang 构建模块并运行测试:经模块使用运行时类型,
Expand Down
2 changes: 1 addition & 1 deletion docs/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,4 +32,4 @@ import mcpplibs.mwrap.slint;

## The SDK's features

Upstream CMake's desktop defaults: `interpreter`, `backend-winit`, `renderer-femtovg`, `renderer-software`, `accessibility`, `system-tray`, `testing`, and the compiler. `SLINT_FEATURE_RENDERER_SKIA`, `BACKEND_QT`, `EXPERIMENTAL`, `FREESTANDING`, `LIVE_PREVIEW` and the image pixel formats are `false`; `slint::testing` is declared only with `EXPERIMENTAL`, so it is not here. On Linux the library NEEDs `libfontconfig.so.1` (xim:fontconfig) and the C runtime; X11, Wayland and GL are loaded when a window needs them.
Upstream CMake's desktop defaults: `interpreter`, `backend-winit`, `renderer-femtovg`, `renderer-software`, `accessibility`, `system-tray`, `testing`, and the compiler. `SLINT_FEATURE_RENDERER_SKIA`, `BACKEND_QT`, `EXPERIMENTAL`, `FREESTANDING`, `LIVE_PREVIEW` and the image pixel formats are `false`; `slint::testing` is declared only with `EXPERIMENTAL`, so it is not here. On Linux the library NEEDs `libfontconfig.so.1` (xim:fontconfig) and the C runtime; X11, Wayland and GL are loaded when a window needs them. A window on the OpenGL renderer needs a GL vendor library (Mesa, or NVIDIA's on an NVIDIA X server) that libglvnd dispatches to: `compat.slint` brings it through `compat.glx-runtime`, as `compat.glfw` does; `tools/check_display/` diagnoses a machine where the window still aborts (`argument does not name a valid config`), and `SLINT_BACKEND=winit-software` runs without GL.
44 changes: 44 additions & 0 deletions tools/check_display/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# check_display: does a window's GPU path work on this machine?

A Slint window needs an X11 or Wayland session and, for the default OpenGL renderer, a GL vendor
library (Mesa, or NVIDIA's). The headless build and `mcpp test` never touch any of that, so a machine
where the window dies shows no sign of it until a person runs the program. This directory is how to
find out which part is missing. Run it from a **desktop terminal** (`DISPLAY` or `WAYLAND_DISPLAY` set).

```
cd tools/check_display
./check-homes.sh # read-only: which xlings homes hold nvidia-gl-host-link, and is it current
./run.sh # build and run the probe: as an mcpp program runs, with an NVIDIA overlay, through `mcpp run`
./slint-variants.sh <project> # run a Slint project's binary six ways, 8 s each
```

`slint-variants.sh` takes the project directory (default: the current one) and, if it differs from
the directory name, the binary name. Each variant opens a window for up to 8 seconds: exit **124** =
the window came up, **134** = it aborted.

## The probe (`src/main.cpp`)

It uses only `dlopen`/`dlsym`, so it sees exactly what a toolkit's own `dlopen()` sees under mcpp's
loader.

- `0.` the environment (glvnd and Mesa variables choose the vendor).
- `1.` which of the libraries a toolkit loads at run time resolve, including the NVIDIA vendor libraries.
- `2.` EGL devices (no X needed).
- `3.` EGL on X11 and how many configurations each template gets.
- `4.` GLX on X11: the server's GLX vendor and the configuration count. glutin tries GLX and then
EGL, and reports GLXBadFBConfig as `argument does not name a valid config`. On an NVIDIA X server
the GLX vendor is NVIDIA's, so `libGLX_nvidia.so.0` must load.
- `SUMMARY` and the exit code: 0 fine, 2 EGL on X11 gave nothing, 7 GLX gave nothing or an X error,
6 the host has NVIDIA but the program gets no NVIDIA EGL device, 3/4 could not get that far.

## Reading the result

| what you see | meaning | what to do |
|---|---|---|
| Slint default aborts with `glutin: argument does not name a valid config`; probe part 4 says `client vendor: (null)` or `libGLX_nvidia.so.0` is not found | libglvnd is only a dispatcher and nothing wired a vendor into it: the GL provider (`xim:graphics`, through `compat.glx-runtime`) is not in the project's dependency closure | `compat.slint` carries that dependency (index PR #871); with an older descriptor, add `compat.glx-runtime = "2026.09.11"` to `[dependencies]` |
| the same, with `compat.glx-runtime` present | the `nvidia-gl-host-link` copy is stale (a driver upgrade leaves its version-named links dangling), `check-homes.sh` shows it: "links named for the live driver: 0 of N", "dangling" > 0 | reinstall `nvidia-gl-host-link`, or run `xlings-gl-doctor` |
| `SLINT_BACKEND=winit-software` works and the default does not | the software renderer needs no GL; the failure is in the GL path above | use it as a stop-gap |
| no window and a different error | an X11 or Wayland library is missing (`libX11.so.6`, `libxkbcommon-x11.so.0` ...): probe part 1 | add the library's xim package |

Wayland is not covered: the index has no package that provides `opengl.egl.driver`, and the probe
only exercises X11.
31 changes: 31 additions & 0 deletions tools/check_display/check-homes.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
#!/bin/sh
# Which copy of nvidia-gl-host-link is stale? No build needed; read-only.
live=$(cat /sys/module/nvidia/version 2>/dev/null)
[ -n "$live" ] || live=$(grep -o '[0-9][0-9][0-9]\.[0-9]*\.[0-9]*' /proc/driver/nvidia/version 2>/dev/null | head -1)
echo "host driver now: ${live:-none loaded}"
for home in "$HOME/.xlings" "$HOME/.mcpp/registry"; do
echo
echo "== $home"
found=0
for p in "$home"/data/xpkgs/xim-x-nvidia-gl-host-link/*/; do
[ -d "$p" ] || continue
found=1
stamp=$(tr -d '\n' < "$p/.host-driver-version" 2>/dev/null)
total=$(ls "$p/lib" 2>/dev/null | grep -c '\.so\.[0-9][0-9][0-9]\.[0-9]*\.[0-9]*')
cur=$(ls "$p/lib" 2>/dev/null | grep -c "$live")
dang=$(find "$p/lib" -xtype l 2>/dev/null | wc -l)
echo " $(basename "$p") stamp=${stamp:-none} links named for the live driver: $cur of $total dangling: $dang"
done
[ "$found" = 0 ] && echo " (no nvidia-gl-host-link here)"
for g in "$home"/data/xpkgs/xim-x-libglvnd/*/lib/glx-vendor; do
[ -d "$g" ] || continue
echo " glvnd GLX vendors ($(basename "$(dirname "$(dirname "$g")")")): $(ls "$g" | grep -v '^\.' | tr '\n' ' ')"
done
for lib in "$home"/subos/*/lib; do
[ -d "$lib" ] || continue
echo " subos $(basename "$(dirname "$lib")"): nvidia links dangling: $(find "$lib" -maxdepth 1 -xtype l -name '*nvidia*' 2>/dev/null | wc -l)"
done
done
echo
echo "Reading: a copy whose 'links named for the live driver' is 0 and whose 'dangling' is > 0 is stale."
echo "mcpp uses ~/.mcpp/registry; the global ~/.xlings is a different copy."
13 changes: 13 additions & 0 deletions tools/check_display/make-overlay.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
#!/bin/sh
# Prints the path of a directory of symlinks to the host's NVIDIA user-space libraries, built by
# globbing the host for the driver that is loaded NOW. No list of file names; nothing is copied.
live=$(cat /sys/module/nvidia/version 2>/dev/null)
[ -n "$live" ] || live=$(grep -o '[0-9][0-9][0-9]\.[0-9]*\.[0-9]*' /proc/driver/nvidia/version 2>/dev/null | head -1)
[ -n "$live" ] || { echo "no NVIDIA driver is loaded" >&2; exit 1; }
libdir=${HOST_LIBDIR:-/usr/lib/x86_64-linux-gnu}
dir=${TMPDIR:-/tmp}/gl-overlay-$live
rm -rf "$dir"; mkdir -p "$dir"
for f in "$libdir"/libnvidia-*.so* "$libdir"/libEGL_nvidia.so* "$libdir"/libGLX_nvidia.so* "$libdir"/libGLESv*_nvidia.so*; do
[ -e "$f" ] && ln -s "$f" "$dir/"
done
echo "$dir"
17 changes: 17 additions & 0 deletions tools/check_display/mcpp.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
[package]
name = "glprobe"
version = "0.1.0"
description = "Minimal probe: can a program built by mcpp load the host's GL driver libraries, and does EGL on X11 give it a configuration?"
license = "Apache-2.0"

[language]
standard = "c++23"
modules = true
import_std = false

[build]
sources = ["src/*.cpp"]

[targets.glprobe]
kind = "bin"
main = "src/main.cpp"
18 changes: 18 additions & 0 deletions tools/check_display/run.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
#!/bin/sh
# Build the probe with mcpp, run it as mcpp programs run today (A), then again with an
# overlay generated from the live driver version on the search path (B).
# B runs the built binary directly: LD_LIBRARY_PATH holds only NVIDIA libraries, so it cannot
# pull in a second libc, and it does not depend on what `mcpp run` does with the environment.
cd "$(dirname "$0")" || exit 1
mcpp build || exit 1
bin=$(find target -type f -path '*/bin/glprobe' -printf '%T@ %p\n' | sort -nr | head -1 | cut -d' ' -f2-)
[ -x "$bin" ] || { echo "glprobe was not built" >&2; exit 1; }
echo; echo "################ A: as an mcpp-built program runs today"
"$bin"; a=$?
echo; echo "################ B: plus an overlay of the live driver's NVIDIA libraries"
ov=$(./make-overlay.sh) || { echo "(no NVIDIA driver: B skipped)"; echo; echo "A exit=$a"; exit "$a"; }
echo "overlay: $ov ($(ls "$ov" | wc -l) links)"
LD_LIBRARY_PATH="$ov" "$bin"; b=$?
echo; echo "################ C: through mcpp run (mcpp's own environment, not your shell's)"
mcpp run; c=$?
echo; echo "A exit=$a B exit=$b C exit=$c (0 fine; 2 EGL on X11 gave no configuration; 7 GLX gave none or an X error; 6 the host has NVIDIA but this program gets no NVIDIA EGL device; 3/4 could not get that far)"
29 changes: 29 additions & 0 deletions tools/check_display/slint-variants.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
#!/bin/sh
# Run a Slint project's own binary in several ways and say what each does.
# Each run opens a window for up to 8 seconds, then is stopped: exit 124 means it was still
# running when stopped, i.e. the window came up; 134 means it aborted (SIGABRT).
# usage: ./slint-variants.sh [project-dir] [binary-name] (default: the current directory; the binary is named after the project directory)
here=$(cd "$(dirname "$0")" && pwd)
proj=${1:-.}
cd "$proj" || { echo "no such project: $proj" >&2; exit 1; }
name=${2:-$(basename "$(pwd)")}
mcpp build >/dev/null 2>&1 || mcpp build || exit 1
bin=$(find target -type f -path "*/bin/$name" -printf '%T@ %p\n' | sort -nr | head -1 | cut -d' ' -f2-)
[ -x "$bin" ] || { echo "no $name binary under $proj/target (pass its name as the second argument)" >&2; exit 1; }
out=$(mktemp)
run() {
label=$1; shift
env "$@" timeout 8 "$bin" >"$out" 2>&1; rc=$?
case $rc in 124) verdict="window stayed up (stopped by the 8 s timeout)";; 134) verdict="ABORTED (SIGABRT)";; 0) verdict="exited normally";; *) verdict="exit $rc";; esac
echo; echo "=== $label"; echo " -> $verdict"
grep -vE '^\s*$|Fontconfig|RUST_BACKTRACE|note: run with' "$out" | head -4 | cut -c1-220 | sed 's/^/ /'
}
ov=$("$here/make-overlay.sh" 2>/dev/null)
mesa=/usr/share/glvnd/egl_vendor.d/50_mesa.json
run "default"
run "software renderer: SLINT_BACKEND=winit-software" SLINT_BACKEND=winit-software
run "OpenGL renderer, explicit: SLINT_BACKEND=winit-femtovg" SLINT_BACKEND=winit-femtovg
run "OpenGL, GLX vendor forced to mesa" SLINT_BACKEND=winit-femtovg __GLX_VENDOR_LIBRARY_NAME=mesa
[ -f "$mesa" ] && run "OpenGL, EGL and GLX both forced to mesa" SLINT_BACKEND=winit-femtovg __GLX_VENDOR_LIBRARY_NAME=mesa __EGL_VENDOR_LIBRARY_FILENAMES=$mesa
[ -n "$ov" ] && run "default + overlay of the live NVIDIA driver (LD_LIBRARY_PATH=$ov)" LD_LIBRARY_PATH="$ov"
rm -f "$out"
Loading
Loading