Build Linux Binary

You are an expert Linux build automation specialist for .NET/Avalonia projects.

Follow these instructions exactly and in order to build Linux binaries for XerahS.

Shared Build Guardrails

Before Linux packaging work, follow build-common for shared timeout, lock recovery, no-concurrent-build, -m:1, TFM, and SkiaSharp rules. This Linux skill owns package-linux usage, log monitoring, Linux artifact validation, and Linux-specific XAML precompilation diagnostics.

Build Process

Preparation

Build the pinned submodule revision. Update ImageEditor only when requested, using the operator's Git wrapper. For confirmed stalls or output locks, use build-common; do not terminate unrelated builds.

Phase 2: Run the Build Script

Use the packaging script below. If the host buffers output, capture a log and inspect it while the build runs. Redirection alone does not background a shell command.

bash build/linux/package-linux.sh > build_output.log 2>&1

Verify the exit code and resulting artifacts. Judge stalls from output and process activity, not a fixed timeout.

Phase 3: Handle Common Failures

🔴 Failure: No precompiled XAML found for XerahS.UI.App

Symptom (at runtime, not build time):

Avalonia.Markup.Xaml.XamlLoadException: No precompiled XAML found for XerahS.UI.App, 
make sure to specify x:Class and include your XAML file as AvaloniaResource

Root Cause: A C# converter class referenced in an .axaml file uses the wrong namespace.
Avalonia's XAML compiler silently fails to compile the referencing AXAML, which cascades to break the entire app's precompiled XAML.

How to diagnose:

• Check any recently added/modified converters under ShareX.ImageEditor/src/ShareX.ImageEditor/UI/Adapters/Converters/

• Verify their C# namespace matches the AXAML xmlns:converters import:

  In EditorView.axaml:

  xmlns:converters="using:ShareX.ImageEditor.Converters"
  

  So all converter classes must declare:

  namespace ShareX.ImageEditor.Converters;
  

Fix:

// WRONG — will silently break Avalonia XAML precompilation:
namespace ShareX.ImageEditor.UI.Adapters.Converters;

// CORRECT — matches the xmlns:converters import in EditorView.axaml:
namespace ShareX.ImageEditor.Converters;

After fixing, rebuild from scratch.

🔴 Failure: AVLN9999: The process cannot access the file '...XerahS.Imgur.Plugin.pdb' because it is being used by another process

Root Cause: A previous dotnet publish is still running in the background (e.g. from a backgrounded & command).

Fix: identify the lock holder and use build-common to cancel only the affected task-owned build, then rerun the packaging script.

🔴 Failure: MSB3026: Could not copy '...XerahS.Uploaders.dll' ... being used by another process

Root Cause: Parallel plugin publishing is racing to write shared DLLs.

Fix: This is usually a transient retry (MSBuild will retry automatically). If it becomes fatal:

rm -rf src/desktop/core/XerahS.Uploaders/obj/Release
bash build/linux/package-linux.sh

🔴 Failure: Error: No plugins were published for linux-x64

Root Cause: The plugin csproj discovery glob found no files, or a plugin build failed early.

Check:

find src/desktop/plugins -mindepth 2 -maxdepth 2 -name "*.csproj"

Each plugin project under src/desktop/plugins/ needs a plugin.json in the same directory.

Phase 4: Validation

After the build completes, verify the artifacts:

ls -lh dist/

Expected output:

XerahS-0.16.1-linux-x64.deb    ~90-120MB
XerahS-0.16.1-linux-arm64.deb  ~90-120MB
XerahS-0.16.1-linux-x64.rpm    ~90-120MB  (if rpmbuild installed)
XerahS-0.16.1-linux-arm64.rpm  ~90-120MB  (if rpmbuild installed)

Timestamps should match the current build session.

Important Notes

Why Avalonia XAML Precompilation Fails Silently

• Avalonia compiles .axaml files to IL at build time
• If a referenced type (e.g. a converter) cannot be resolved, the AXAML file is silently skipped
• This doesn't fail the build, but crashes the application at startup
• The fix is always: ensure C# namespace matches the xmlns import in the AXAML

Key Build Parameters (from package-linux.sh)

• -p:PublishSingleFile=true --self-contained true: Main app ships as one binary
• -p:OS=Linux -p:DefineConstants=LINUX: Enables Linux-specific code paths
• -p:EnableWindowsTargeting=true: Required when cross-compiling on Linux due to shared project references
• Plugins publish with --no-self-contained to share the runtime with the main app

Sequential Builds Are Mandatory

NEVER run two builds at the same time. ShareX.ImageEditor targets multiple TFMs and MSBuild parallelism causes them to race on the same ShareX.ImageEditor.dll output path.

• Architectures: package-linux.sh iterates linux-x64 then linux-arm64 sequentially — never invoke it twice concurrently.
• Internal parallelism: If CS2012 / file lock errors appear on ShareX.ImageEditor, pre-build it separately with /m:1 to force single-threaded compilation:

  dotnet build ShareX.ImageEditor/src/ShareX.ImageEditor/ShareX.ImageEditor.csproj \
    -c Release -p:UseSharedCompilation=false /m:1
  

• Between builds: Ensure this checkout's previous build has exited before starting another build sharing its outputs.

Background Build Caution

• Do not background the build script with & unless you redirect output to a log file
• Multiple concurrent builds share obj/ folders and will conflict
• Cancel a confirmed stalled task-owned build before retrying; leave other checkouts' processes alone.

stdout Buffering Issue

• If the host buffers output, redirect to a log and inspect progress through the host's file or terminal tools.

Success Criteria

• ✅ Both linux-x64 and linux-arm64 .deb packages created in dist/
• ✅ Files are ~90-120 MB in size
• ✅ Timestamps are recent (within build session)
• ✅ No lingering dotnet or package-linux.sh processes
• ✅ App launches without XamlLoadException at startup

Troubleshooting

Related Files

• Shared guardrails: build-common
• Build script: build/linux/package-linux.sh
• Packaging tool: build/linux/XerahS.Packaging/
• Version config: Directory.Build.props
• Main app project: src/desktop/app/XerahS.App/XerahS.App.csproj
• Converters namespace reference: ShareX.ImageEditor.Converters (match all new converter classes to this)