Skip to content

Fix running Spice86 with the UI (in non-headless mode) on Linux - #2281

Merged
maximilien-noal merged 1 commit into
OpenRakis:masterfrom
xorangekiller:fix/skiasharp_linux
Jul 30, 2026
Merged

Fix running Spice86 with the UI (in non-headless mode) on Linux#2281
maximilien-noal merged 1 commit into
OpenRakis:masterfrom
xorangekiller:fix/skiasharp_linux

Conversation

@xorangekiller

Copy link
Copy Markdown
Contributor

At some point the Spice86 UI stopped working on Linux. Games would still ran in headless mode (with --HeadlessMode Minimal in the command line arguments), but not by default with the main interface (or with --HeadlessMode Avalonia, which is the default). Instead the SkiaSharp library threw an exception that indicated that a different version of the native Skia library was present on the system than the one supported by the version of SkiaSharp that Spice86 was compiled with.

Using Spice86 Debug build: /home/dev/Spice86/src/Spice86/bin/Debug/net10.0
Unhandled exception. System.TypeInitializationException: The type initializer for 'SkiaSharp.SKImageInfo' threw an exception.
 ---> System.TypeInitializationException: The type initializer for 'SkiaSharp.SkiaApi' threw an exception.
 ---> System.InvalidOperationException: The version of the native libSkiaSharp library (119.0) is incompatible with this version of SkiaSharp. Supported versions of the native libSkiaSharp library are in the range [150.0, 151.0).
   at SkiaSharp.SkiaSharpVersion.CheckNativeLibraryCompatible(Version minSupported, Version current, Boolean throwIfIncompatible)
   at SkiaSharp.SkiaSharpVersion.CheckNativeLibraryCompatible(Boolean throwIfIncompatible)
   at SkiaSharp.SkiaApi..cctor()
   --- End of inner exception stack trace ---
   at SkiaSharp.SkiaApi.sk_colortype_get_default_8888()
   at SkiaSharp.SkiaApi.sk_colortype_get_default_8888()
   at SkiaSharp.SKImageInfo..cctor()
   --- End of inner exception stack trace ---
   at Avalonia.Skia.PlatformRenderInterface..ctor(Nullable`1 maxResourceBytes, Nullable`1 useStencilBuffers)
   at Avalonia.Skia.SkiaPlatform.Initialize(SkiaOptions options)
   at Avalonia.SkiaApplicationExtensions.<>c.<UseSkia>b__0_0()
   at Avalonia.AppBuilder.SetupUnsafe()
   at Avalonia.AppBuilder.Setup()
   at Avalonia.AppBuilder.SetupWithLifetime(IApplicationLifetime lifetime)
   at Avalonia.ClassicDesktopStyleApplicationLifetimeExtensions.StartWithClassicDesktopLifetime(AppBuilder builder, String[] args, ShutdownMode shutdownMode)
   at Spice86.Program.Main(String[] args) in /home/dev/Spice86/src/Spice86/Program.cs:line 47
Aborted                    (core dumped)

After digging into it, I discovered that SkiaSharp depends on SkiaSharp.NativeAssets.Win32 and SkiaSharp.NativeAssets.macOS to ensure that they are always the correct versions for Windows and macOS, but it does no such thing for Linux. I added SkiaSharp.NativeAssets.Linux explicitly to the Spice86 dependencies (since it isn't implicitly pulled in as a transitive dependency of SkiaSharp like the Windows and macOS versions are), rebuilt, and that fixed the issue. I can now run Spice86 again with the full UI on Linux.

The unit tests didn't catch this bug because Spice86 still compiled on Linux. It just didn't run with the UI. The unit tests don't try to run it with the UI either. They run it in minimal mode with no UI - which makes sense. This was just a gap in the test coverage that happened to regress. I thought about how to introduce tests for it, but I think that would require integration tests, not just unit tests, and that it's not worth it for this fix. It's easier to just add the new dependency. It's unlikely that it will regress again in this way in the future now that it's there.

I'm sure that there's a specific commit that introduced this regression since I used to be able to run Spice86 on Linux, but I don't know what it was. Ideally I should have tracked it down and referenced it in this commit, but it was easier to just fix it than to bisect, so I didn't.

At some point the Spice86 UI stopped working on Linux. Games would still
ran in headless mode (with `--HeadlessMode Minimal` in the command line
arguments), but not by default with the main interface (or with
`--HeadlessMode Avalonia`, which is the default). Instead the SkiaSharp
library threw an exception that indicated that a different version of
the native Skia library was present on the system than the one supported
by the version of SkiaSharp that Spice86 was compiled with.

After digging into it, I discovered that SkiaSharp depends on
SkiaSharp.NativeAssets.Win32 and SkiaSharp.NativeAssets.macOS to ensure
that they are always the correct versions for Windows and macOS, but it
does no such thing for Linux. I added SkiaSharp.NativeAssets.Linux
explicitly to the Spice86 dependencies (since it isn't implicitly pulled
in as a transitive dependency of SkiaSharp like the Windows and macOS
versions are), rebuilt, and that fixed the issue. I can now run Spice86
again with the full UI on Linux.

The unit tests didn't catch this bug because Spice86 still compiled on
Linux. It just didn't run with the UI. The unit tests don't try to run
it with the UI either. They run it in minimal mode with no UI - which
makes sense. This was just a gap in the test coverage that happened to
regress. I thought about how to introduce tests for it, but I think that
would require integration tests, not just unit tests, and that it's not
worth it for this fix. It's easier to just add the new dependency. It's
unlikely that it will regress again in this way in the future now that
it's there.

I'm sure that there's a specific commit that introduced this regression
since I used to be able to run Spice86 on Linux, but I don't know what
it was. Ideally I should have tracked it down and referenced it in this
commit, but it was easier to just fix it than to bisect, so I didn't.
@xorangekiller xorangekiller self-assigned this Jul 30, 2026
@xorangekiller xorangekiller added the bugfix fixes a bug label Jul 30, 2026
@maximilien-noal

Copy link
Copy Markdown
Member

@xorangekiller sorry about that ! I'm glad you found a fix.

It's probably the skiasharp v4 update commit that broke it.

@maximilien-noal
maximilien-noal merged commit 9717868 into OpenRakis:master Jul 30, 2026
5 checks passed
@xorangekiller
xorangekiller deleted the fix/skiasharp_linux branch July 30, 2026 16:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bugfix fixes a bug

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants