crossdesk/docs/BUILD_EN.md

Build from source

Back to README · 中文

After cloning, run build and packaging commands from the repository root. The Xmake options and CI workflow define the build configuration. 1.4.3 is an example version for local builds; change both the configuration value and packaging argument together so the app and package versions match.

Build requirements

• Git, Xmake (3.1.1 or newer for both desktop and mobile), and the platform toolchain listed below.
• The build scripts use Xmake to manage CMake 3.x (≥ 3.21, < 4.0), Rust 1.92.0, and other dependencies. The first build downloads tools and source archives. See the Slint package configuration for the constraints.

Windows

Install Visual Studio 2022 with the Desktop development with C++ workload, Windows SDK, and C++ Clang Compiler for Windows component, plus Xmake. Windows x64 builds use clang-cl for libyuv to enable SIMD conversion and scaling; the application still uses MSVC. In a developer PowerShell, run:

git clone --recurse-submodules https://github.com/kunkundi/crossdesk.git
cd crossdesk
xmake f -c -p windows -a x64 -m release --CROSSDESK_VERSION=1.4.3 --USE_CUDA=false -y
xmake b -vy crossdesk
xmake r crossdesk

Use release for performance measurements; debug keeps symbols and disables application compiler optimizations.

Installer packaging also uses NSIS. Copy the repository's nsProcess.dll into NSIS's Plugins/x86-unicode directory and ensure makensis is on PATH. After building Release, run:

.\apps\desktop\scripts\windows\pkg_x64.ps1 1.4.3

See the Windows packaging script and CI workflow for the full process. Manual deployment must retain the runtime libraries, both service helpers and the usbmmidd_v2 driver folder (copied into the output directory by xmake after the build); see Windows Service.

macOS

Install Xcode and its command-line tools, plus Xmake, then run:

git clone --recurse-submodules https://github.com/kunkundi/crossdesk.git
cd crossdesk
xmake f -c -m release --target_minver=14.0 --CROSSDESK_VERSION=1.4.3 --USE_CUDA=false -y
xmake b -vy crossdesk
xmake r crossdesk

The current CI sets macOS 14.0 as the minimum target for both Intel and Apple Silicon. Check the workflow for its Xcode/SDK versions. Package with the script matching your architecture:

# Apple Silicon
./apps/desktop/scripts/macos/pkg_arm64.sh 1.4.3
# Intel
./apps/desktop/scripts/macos/pkg_x64.sh 1.4.3

The scripts create an .app and .pkg containing the Slint runtime. Screen Recording and Accessibility grants depend on the app path and signature; use a consistent application bundle when testing host functionality.

Linux

Linux builds support Ubuntu 20.04 or later on amd64 and arm64. Release packages use Ubuntu 20.04/glibc 2.31 as their compatibility baseline. The dependency commands below target Ubuntu 20.04; adapt package names and toolchains for other distributions or newer versions, or use the build image below to reproduce CI. Install the base build dependencies first:

sudo apt-get update
sudo apt-get install -y \
  git curl unzip build-essential gcc-10 g++-10 python3-pip \
  pkg-config binutils dpkg-dev \
  libx11-dev libxext-dev libxrender-dev libxft-dev libxrandr-dev \
  libxinerama-dev libxcursor-dev libxi-dev libxfixes-dev libxv-dev \
  libxtst-dev libxcb-randr0-dev libxcb-xtest0-dev libxcb-xinerama0-dev \
  libxcb-shape0-dev libxcb-xkb-dev libxcb-xfixes0-dev libxcb-shm0-dev \
  libasound2-dev libsndio-dev libpulse-dev \
  libgl1-mesa-dev

Ubuntu 20.04's bundled CMake 3.16 is too old. Xmake downloads a CMake 3.x version within the range above; replacing the system CMake manually is not required.

Ubuntu 20.04's default GCC 9 lacks parts of the C++20 standard library needed by Slint's C++ API, so the commands above install GCC 10 and the configuration below selects it explicitly.

Clone the submodules and build a release binary:

git clone --recurse-submodules https://github.com/kunkundi/crossdesk.git
cd crossdesk

# Run this when the repository has already been cloned
git submodule update --init --recursive

xmake f -c -m release --CROSSDESK_VERSION=1.4.3 --USE_CUDA=false --toolchain=gcc-10 -y
xmake b -vy crossdesk

Use --toolchain=gcc-10 so that both CrossDesk and third-party packages such as libyuv, which xmake builds during configuration, use GCC 10. Specifying only --cc/--cxx may still let dependency builds fall back to the system /bin/cc and /bin/c++. Keep -c when switching compilers to clear the old configuration.

The amd64 binary is written to build/linux/x86_64/release/crossdesk; the arm64 binary is written to build/linux/arm64/release/crossdesk.

For Wayland and DRM, install the D-Bus, DRM, and PipeWire development dependencies. Ubuntu 20.04 uses the repository's PipeWire header SDK; Ubuntu 22.04 and later can use the distribution's libpipewire-0.3-dev and libspa-0.2-dev packages instead:

sudo apt-get install -y libdbus-1-dev libdrm-dev
# Skip this line if the system PipeWire 0.3 development packages are installed
sudo ./docker/linux-build/install-pipewire-sdk.sh

xmake f -c -m release --USE_WAYLAND=true --USE_DRM=true --USE_CUDA=false \
  --CROSSDESK_VERSION=1.4.3 --toolchain=gcc-10 -y
xmake b -vy crossdesk

Build a Debian package after compiling a release binary on the matching architecture:

# amd64
./apps/desktop/scripts/linux/pkg_amd64.sh 1.4.3

# arm64
./apps/desktop/scripts/linux/pkg_arm64.sh 1.4.3

Each packaging run uses the same compiled application to create the standard crossdesk-linux-<arch>-<version>.deb and crossdesk-virtual-desktop-xfce-linux-<arch>-<version>.deb. Both contain the complete application; only the latter requires Xvfb, Xfce and D-Bus session tools. Building and packaging need none of these optional runtime components. To run a complete virtual desktop from source, install them as described in headless operation. The build image and CI can retain them for testing.

The package scripts install the shared Slint runtime in the private /usr/lib/crossdesk directory, so users do not need to install libslint_cpp.so separately. The package-managed package-name file beside it identifies the update download variant without changing user settings. PipeWire is not a mandatory runtime dependency. CrossDesk detects the host's PipeWire 0.3 runtime dynamically and can still use X11 capture (and DRM when enabled at build time) when it is unavailable.

Common build options

--USE_CUDA=true/false: Enable CUDA hardware codec acceleration, disabled by default
--USE_WAYLAND=true/false: Enable Wayland/PipeWire capture on Linux, disabled by default
--USE_DRM=true/false: Enable DRM capture on Linux, disabled by default
--CROSSDESK_PORTABLE=true/false: Build the portable variant, disabled by default
--CROSSDESK_VERSION=xxx: Set the CrossDesk version

# Example
xmake f --CROSSDESK_VERSION=1.4.3 --USE_CUDA=true

Run:

xmake r crossdesk

Development Without CUDA Environment

For Linux developers who do not have a CUDA environment installed and want to enable hardware codec feature, a preconfigured Ubuntu 20.04 compatibility build image is provided. This image contains the required build dependencies and produces both Linux package variants with the glibc 2.31 baseline.

See the build image notes for image tags and architecture differences. The CUDA example below targets the amd64 image. Inside the container, download the project and run:

export CUDA_PATH=/usr/local/cuda
export XMAKE_GLOBALDIR=/data

xmake f --root -c -m release --CROSSDESK_VERSION=1.4.3 --USE_CUDA=true --toolchain=gcc-10 -y
xmake b --root -vy crossdesk

For Windows developers without a CUDA environment installed, run the following command to install the CUDA build environment:

xmake require -vy "cuda 12.6.3"

After the installation is complete, execute:

xmake require --info "cuda 12.6.3"

Find the installdir field in the output.

From the output above, locate the CUDA installation directory — this is the path pointed to by installdir. Add this path to your system environment variable CUDA_PATH, or set it in the terminal using:

$env:CUDA_PATH = "C:\path\to\cuda_installdir"

Then re-run:

xmake f --USE_CUDA=true
xmake b -vy crossdesk

Connection issues at runtime

A disconnected status can result from network, server configuration, or certificate trust problems. See the FAQ and self-hosted TLS guide before changing the installation.

About Xmake

Installing Xmake

You can install Xmake using one of the following methods:

Using curl:

curl -fsSL https://xmake.io/shget.text | bash

Using wget:

wget https://xmake.io/shget.text -O - | bash

Using powershell:

irm https://xmake.io/psget.text | iex

Build Options

# Select Debug; replace debug with release for a Release build
xmake f -m debug

# Optional build parameters
-r : Rebuild the target
-v : Show detailed build logs
-y : Automatically confirm prompts

# Example
xmake b -vy crossdesk

Run Options

# Launch the current build in a debugger; this does not select Debug build mode
xmake r -d crossdesk

For more information, please refer to the official Xmake documentation.

iOS / iPadOS

The native client has a separate Xcode project and requires an arm64 physical device running iOS 16+. See the iOS development guide for build and media/file-transfer checks. CI exports an unsigned app; device installation requires your own signing.

iOS CI can run manually on its own, is called by the main build workflow, and runs for relevant pull requests. It retains the existing toolchain, license/privacy checks, app verification and ZIP packaging. Tag releases continue to collect the unsigned app archive under the same artifact name.

Refreshing screenshots

Desktop README images are rendered directly from the current Slint UI. See the screenshot notes for reproduction commands.

Android

The native controller is a separate Gradle project in apps/android, targeting Android 8.0+ arm64 with SDK 36, NDK r28c, and Xmake 3.1.1 or newer. See the Android development guide for APK builds, installation, and emulator tests.

Android CI can run manually on its own and is also called by the main build workflow. It uploads Debug/device-test APKs, an unsigned Release APK and Lint reports, runs native protocol tests, and checks 16 KB alignment and license contents. Tag releases include the unsigned Release APK, which requires your own signing before installation. Device tests must be run separately on an arm64 phone or emulator.