Introducing a new way to review your PRs.

Read the announcement

genymobile / scrcpy

Display and control your Android device

View on GitHub

13 documents · Updated Nov 16, 2026

docs / build-test-release-and-packaging

Build, Test, Release, and Packaging

Overview

The top-level native build is Meson. meson.build declares the scrcpy project version, adds C warning defaults, and conditionally enters app/ and server/ based on meson_options.txt options compile_app and compile_server. The native client is assembled by app/meson.build: it builds the scrcpy executable from the C source list, probes libc functions into config.h, records SCRCPY_VERSION, PREFIX, PORTABLE, feature flags, default ports, and debugger behavior, then installs the binary plus man page, icons, shell completions, and Linux desktop files. Client feature options in meson_options.txt gate platform-specific source files and dependencies: V4L2 and VA-API only on Linux, D3D11VA only on Windows, VideoToolbox only on macOS, and USB/libusb when enabled.

The Android server can be built through Meson or directly through Gradle. server/meson.build creates the installed scrcpy-server target under share/scrcpy; by default it invokes server/…/build-wrapper.sh, which runs gradlew -p server assembleDebug for Meson debug builds or assembleRelease otherwise, then copies the produced APK to Meson's scrcpy-server output. If -Dprebuilt_server=<path> is passed, server/meson.build skips Gradle and copies that prebuilt file instead. install_release.sh uses this path for source installs: it downloads a versioned server from GitHub, verifies its SHA-256, runs Meson with -Dprebuilt_server=scrcpy-server, builds, and installs via ninja install.

Gradle is only configured for the :server project. settings.gradle includes :server; top-level build.gradle pins the Android Gradle Plugin and repositories; gradle/wrapper/gradle-wrapper.properties pins the Gradle distribution and checksum. server/build.gradle defines the Android application namespace, SDK versions, versionCode, versionName, JUnit dependency, and applies config/android-checkstyle.gradle. That checkstyle file adds a checkstyle task to Gradle check, scans Android Java source sets, uses config/…/checkstyle.xml, and sets ignoreFailures = true, so style findings are reported but do not fail check.

There is also a manual Android server build path in server/build_without_gradle.sh. It uses $ANDROID_HOME, ANDROID_PLATFORM/ANDROID_BUILD_TOOLS defaults, generates a minimal BuildConfig.java, runs aidl, compiles Java with javac, dexes with dx for platforms below 31 or d8 otherwise, and writes a scrcpy-server archive in BUILD_DIR. This script must be kept version-aligned with Gradle because it hard-codes SCRCPY_VERSION_NAME.

Native client unit tests live under app/tests/** but are registered in app/meson.build, not discovered automatically. They are only built when the Meson buildtype is debug; each test executable is compiled with -DSC_TEST, the relevant production C files, and src/compat.c, then registered with Meson's test(). release/test_client.sh creates release/work/build-test with -Dcompile_server=false and address/undefined sanitizers, then runs ninja -C ... test. Server tests live under server/src/test/** and are run by release/test_server.sh through gradlew -p server check, which also triggers the non-failing checkstyle task.

Dependency/bootstrap scripts for release builds are under app/deps/**. _init standardizes arguments as <host> <native|cross> <static|shared>, computes install/build/source directories under app/deps/work, selects MinGW host triplets for win32 and win64 cross builds, and provides checksum-verified download helpers. sdl.sh, dav1d.sh, ffmpeg.sh, and libusb.sh download pinned upstream versions, verify SHA-256 sums, build into host/build/link-specific directories, and install into app/deps/work/install/<host>-<build>-<link>. The adb_linux.sh, adb_macos.sh, and adb_windows.sh scripts fetch Android platform-tools adb artifacts into app/deps/work/install/adb-*; the Windows script also installs AdbWinApi.dll and AdbWinUsbApi.dll.

Release scripts in release/** orchestrate artifact production through release/build_common, which defines release/work, release/output, and VERSION from git describe --tags --always unless overridden. release/build_server.sh runs Gradle release assembly and copies server-release-unsigned.apk to release/work/build-server/server/scrcpy-server. release/build_linux.sh and release/build_macos.sh build static native dependencies, configure Meson with -Dcompile_server=false -Dportable=true -Dstatic=true, and stage scrcpy, icons, man page, LICENSE, and platform adb files in dist. Linux also exposes only selected system libdrm, libva, and libva-drm pkg-config files and checks that the resulting binary does not link directly to libva. release/build_windows.sh builds shared dependencies for win32, win64, or native winarm64, configures Meson with -Dcompile_server=false -Dportable=true, uses cross_win32.txt/cross_win64.txt for x86 cross builds, and stages scrcpy.exe, Windows helper assets, dependency DLLs, adb.exe, ADB DLLs, and LICENSE.txt.

Packaging combines separately built client and server artifacts. release/package_client.sh <target> <zip|tar.gz> copies release/work/build-<target>/dist plus release/work/build-server/server/scrcpy-server into a directory named scrcpy-<target>-$VERSION, then archives it into release/output. release/package_server.sh publishes the same server file alone as scrcpy-server-$VERSION. release/release.sh is the default release pipeline: it clears release/output, runs server and client tests, builds the server, builds Windows 32/64 and Linux x86_64 clients, packages those artifacts, and writes checksums through release/generate_checksums.sh. generate_checksums.sh expects the standalone server, Linux x86_64 tarball, Windows 32/64/ARM64 zips, and macOS aarch64/x86_64 tarballs to exist in release/output, so it covers more artifacts than release/release.sh currently builds.

Versioning is spread across build systems. bump_version updates meson.build, server/build.gradle, server/build_without_gradle.sh, and app/scrcpy-windows.rc, deriving Android versionCode as major * 10000 + minor * 100 + patch. install_release.sh also embeds the release server URL and SHA-256 for the current version and is not updated by bump_version.

For local runs from a Meson build directory, run sets SCRCPY_ICON_DIR=app/data and SCRCPY_SERVER_PATH=<builddir>/server/scrcpy-server, then executes <builddir>/app/scrcpy with any passed arguments. Meson's development environment in app/meson.build and server/meson.build exposes the same icon and server paths when supported by the Meson version.

Coupling

  • If the project version changes, update every version source together: meson.build, server/build.gradle, server/build_without_gradle.sh, app/scrcpy-windows.rc through bump_version, and the prebuilt URL/checksum in install_release.sh if source-install users should fetch the same release server.
  • If a client test is added, removed, or renamed under app/tests/**, also update the explicit tests array in app/meson.build; Meson does not discover these files automatically.
  • If server source layout or generated AIDL requirements change, verify both server/build.gradle and server/build_without_gradle.sh; the manual build script hard-codes source package globs, generated AIDL inputs, Java target level, and dexing steps independently of Gradle.
  • If release output names or supported target matrix change, keep release/release.sh, release/package_client.sh, and release/generate_checksums.sh synchronized; checksum generation names artifacts explicitly and will fail if an expected package was not produced.
  • If native dependency versions or feature flags change in app/…/*.sh, verify matching Meson dependencies and options in app/meson.build; release builds deliberately set PKG_CONFIG_LIBDIR to the staged dependency install trees so missing or renamed .pc files break configuration rather than falling back to system libraries.
  • If Windows cross-toolchain names change, update both cross_win32.txt/cross_win64.txt and the host-triplet logic in app/deps/_init; dependencies and Meson use separate cross configuration paths.
  • If Checkstyle is expected to gate CI, change config/android-checkstyle.gradle; ignoreFailures = true currently means gradlew -p server check reports style violations without failing the task.

Risks

  • release/generate_checksums.sh lists Windows ARM64 and macOS packages, but release/release.sh only builds Windows 32/64 and Linux x86_64 before invoking it. Running the default release script without separately producing scrcpy-winarm64-$VERSION.zip, scrcpy-macos-aarch64-$VERSION.tar.gz, and scrcpy-macos-x86_64-$VERSION.tar.gz causes checksum generation to fail.
  • server/…/build-wrapper.sh exits successfully without producing scrcpy-server when invoked as root. This avoids Gradle downloads during sudo ninja install, but if the server output was not already built by a non-root ninja, an install can silently reuse a stale server or miss the expected generated artifact.
  • install_release.sh pins both PREBUILT_SERVER_URL and PREBUILT_SERVER_SHA256. If only build-system versions are bumped, source installs can download and package an older server while the native client reports the new SCRCPY_VERSION from meson.build.