Skip to content

Display and control your Android device

Separate build instructions from README

Romain Vimont963890e9c2fe
diff --git a/BUILD.md b/BUILD.md
new file mode 100644
index 00000000..745ac50c
--- /dev/null
+++ b/BUILD.md
@@ -0,0 +1,236 @@
+# Build scrcpy
+
+Here are the instructions to build _scrcpy_ (client and server).
+
+You may want to build only the client: the server binary, which will be pushed
+to the Android device, does not depend on your system and architecture. In that
+case, use the [prebuilt server] (so you will not need Java or the Android SDK).
+
+[prebuilt server]: #prebuilt-server
+
+
+## Requirements
+
+You need [adb]. It is available in the [Android SDK platform
+tools][platform-tools], or packaged in your distribution (`android-adb-tools`).
+
+On Windows, download the [platform-tools][platform-tools-windows] and extract
+the following files to a directory accessible from your `PATH`:
+ - `adb.exe`
+ - `AdbWinApi.dll`
+ - `AdbWinUsbApi.dll`
+
+The client requires [FFmpeg] and [LibSDL2]. Just follow the instructions.
+
+[adb]: https://developer.android.com/studio/command-line/adb.html
+[platform-tools]: https://developer.android.com/studio/releases/platform-tools.html
+[platform-tools-windows]: https://dl.google.com/android/repository/platform-tools-latest-windows.zip
+[ffmpeg]: https://en.wikipedia.org/wiki/FFmpeg
+[LibSDL2]: https://en.wikipedia.org/wiki/Simple_DirectMedia_Layer
+
+
+
+## System-specific steps
+
+### Linux
+
+Install the required packages from your package manager.
+
+#### Debian/Ubuntu
+
+```bash
+# runtime dependencies
+sudo apt install ffmpeg libsdl2-2.0.0
+
+# client build dependencies
+sudo apt install make gcc pkg-config meson \
+ libavcodec-dev libavformat-dev libavutil-dev \
+ libsdl2-dev
+
+# server build dependencies
+sudo apt install openjdk-8-jdk
+```
+
+#### Fedora
+
+```bash
+# enable RPM fusion free
+sudo dnf install https://download1.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm
+
+# client build dependencies
+sudo dnf install SDL2-devel ffms2-devel meson gcc make
+
+# server build dependencies
+sudo dnf install java
+```
+
+
+
+### Windows
+
+#### Cross-compile from Linux
+
+This is the preferred method (and the way the release is built).
+
+From _Debian_, install _mingw_:
+
+```bash
+sudo apt install mingw-w64 mingw-w64-tools
+```
+
+You also need the JDK to build the server:
+
+```bash
+sudo apt install openjdk-8-jdk
+```
+
+Then generate the releases:
+
+```bash
+make -f Makefile.CrossWindows
+```
+
+It will generate win32 and win64 releases into `dist/`.
+
+
+#### In MSYS2
+
+From Windows, you need [MSYS2] to build the project. From an MSYS2 terminal,
+install the required packages:
+
+[MSYS2]: http://www.msys2.org/
+
+```bash
+# runtime dependencies
+pacman -S mingw-w64-x86_64-SDL2 \
+ mingw-w64-x86_64-ffmpeg
+
+# client build dependencies
+pacman -S mingw-w64-x86_64-make \
+ mingw-w64-x86_64-gcc \
+ mingw-w64-x86_64-pkg-config \
+ mingw-w64-x86_64-meson
+```
+
+For a 32 bits version, replace `x86_64` by `i686`:
+
+```bash
+# runtime dependencies
+pacman -S mingw-w64-i686-SDL2 \
+ mingw-w64-i686-ffmpeg
+
+# client build dependencies
+pacman -S mingw-w64-i686-make \
+ mingw-w64-i686-gcc \
+ mingw-w64-i686-pkg-config \
+ mingw-w64-i686-meson
+```
+
+Java (>= 7) is not available in MSYS2, so if you plan to build the server,
+install it manually and make it available from the `PATH`:
+
+```bash
+export PATH="$JAVA_HOME/bin:$PATH"
+```
+
+### Mac OS
+
+Install the packages with [Homebrew]:
+
+[Homebrew]: https://brew.sh/
+
+```bash
+# runtime dependencies
+brew install sdl2 ffmpeg
+
+# client build dependencies
+brew install pkg-config meson
+```
+
+Additionally, if you want to build the server, install Java 8 from Caskroom, and
+make it avaliable from the `PATH`:
+
+```bash
+brew tap caskroom/versions
+brew cask install java8
+export JAVA_HOME="$(/usr/libexec/java_home --version 1.8)"
+export PATH="$JAVA_HOME/bin:$PATH"
+```
+
+### Docker
+
+See [pierlon/scrcpy-docker](https://github.com/pierlon/scrcpy-docker).
+
+
+## Common steps
+
+If you want to build the server, install the [Android SDK] (_Android Studio_),
+and set `ANDROID_HOME` to its directory. For example:
+
+[Android SDK]: https://developer.android.com/studio/index.html
+
+```bash
+export ANDROID_HOME=~/android/sdk
+```
+
+If you don't want to build the server, use the [prebuilt server].
+
+Clone the project:
+
+```bash
+git clone https://github.com/Genymobile/scrcpy
+cd scrcpy
+```
+
+Then, build:
+
+```bash
+meson x --buildtype release --strip -Db_lto=true
+cd x
+ninja
+```
+
+### Run
+
+To run without installing:
+
+```bash
+./run x [options]
+```
+
+
+### Install
+
+After a successful build, you can install _scrcpy_ on the system:
+
+```bash
+sudo ninja install # without sudo on Windows
+```
+
+This installs two files:
+
+ - `/usr/local/bin/scrcpy`
+ - `/usr/local/share/scrcpy/scrcpy-server.jar`
+
+Just remove them to "uninstall" the application.
+
+You can then [run](README.md#run) _scrcpy_.
+
+
+## Prebuilt server
+
+ - [`scrcpy-server-v1.3.jar`][direct-scrcpy-server].
+ _(SHA-256: 0f9a5a217f33f0ed7a1498ceb3c0cccf31c53533893aa952e674c1571d2740c1)_
+
+[direct-scrcpy-server]: https://github.com/Genymobile/scrcpy/releases/download/v1.3/scrcpy-server-v1.3.jar
+
+Download the prebuilt server somewhere, and specify its path during the Meson
+configuration:
+
+```bash
+meson x --buildtype release --strip -Db_lto=true \
+ -Dprebuilt_server=/path/to/scrcpy-server.jar
+cd x
+ninja
+sudo ninja install
+```
diff --git a/README.md b/README.md
index 6eb0e974..e8ada144 100644
--- a/README.md
+++ b/README.md
@@ -11,62 +11,20 @@ It works on _GNU/Linux_, _Windows_ and _MacOS_.
The Android part requires at least API 21 (Android 5.0).
-You need [adb]. It is available in the [Android SDK platform
-tools][platform-tools], or packaged in your distribution (`android-adb-tools`).
-
-On Windows, just [download scrcpy for Windows](#windows), `adb` is included.
-
Make sure you [enabled adb debugging][enable-adb] on your device(s).
-The client requires [FFmpeg] and [LibSDL2]. On Windows, they are included in the
-[prebuilt application](#windows).
-
-[adb]: https://developer.android.com/studio/command-line/adb.html
[enable-adb]: https://developer.android.com/studio/command-line/adb.html#Enabling
-[platform-tools]: https://developer.android.com/studio/releases/platform-tools.html
-[platform-tools-windows]: https://dl.google.com/android/repository/platform-tools-latest-windows.zip
-[ffmpeg]: https://en.wikipedia.org/wiki/FFmpeg
-[LibSDL2]: https://en.wikipedia.org/wiki/Simple_DirectMedia_Layer
-
-## Build and install
-
-### System-specific steps
-
-#### Linux
-
-Install the required packages from your package manager.
-
-##### Debian/Ubuntu
-
-```bash
-# runtime dependencies
-sudo apt install ffmpeg libsdl2-2.0.0
-
-# client build dependencies
-sudo apt install make gcc pkg-config meson \
- libavcodec-dev libavformat-dev libavutil-dev \
- libsdl2-dev
-
-# server build dependencies
-sudo apt install openjdk-8-jdk
-```
-##### Fedora
-```bash
-# enable RPM fusion free
-sudo dnf install https://download1.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm
+## Get the app
-# client build dependencies
-sudo dnf install SDL2-devel ffms2-devel meson gcc make
-# server build dependencies
-sudo dnf install java
-```
+### Linux
-##### Arch Linux
+On Linux, you typically need to [build the app manually][BUILD]. Don't worry,
+it's not that hard.
-Two [AUR] packages have been created by users:
+For Arch Linux, two [AUR] packages have been created by users:
- [`scrcpy`](https://aur.archlinux.org/packages/scrcpy/)
- [`scrcpy-prebuiltserver`](https://aur.archlinux.org/packages/scrcpy-prebuiltserver/)
@@ -74,7 +32,7 @@ Two [AUR] packages have been created by users:
[AUR]: https://wiki.archlinux.org/index.php/Arch_User_Repository
-#### Windows
+### Windows
For Windows, for simplicity, prebuilt archives with all the dependencies
(including `adb`) are available:
@@ -87,80 +45,10 @@ For Windows, for simplicity, prebuilt archives with all the dependencies
[direct-win32]: https://github.com/Genymobile/scrcpy/releases/download/v1.3/scrcpy-win32-v1.3.zip
[direct-win64]: https://github.com/Genymobile/scrcpy/releases/download/v1.3/scrcpy-win64-v1.3.zip
-Instead, you may want to build it manually.
-
-In that case, download the [platform-tools][platform-tools-windows] and extract
-the following files to a directory accessible from your `PATH`:
- - `adb.exe`
- - `AdbWinApi.dll`
- - `AdbWinUsbApi.dll`
-
-##### Cross-compile from Linux
+You can also [build the app manually][BUILD].
-This is the preferred method (and the way the release is built).
-From _Debian_, install _mingw_:
-
-```bash
-sudo apt install mingw-w64 mingw-w64-tools
-```
-
-You also need the JDK to build the server:
-
-```bash
-sudo apt install openjdk-8-jdk
-```
-
-Then generate the releases:
-
-```bash
-make -f Makefile.CrossWindows
-```
-
-It will generate win32 and win64 releases into `dist/`.
-
-
-##### In MSYS2
-
-From Windows, you need [MSYS2] to build the project. From an MSYS2 terminal,
-install the required packages:
-
-[MSYS2]: http://www.msys2.org/
-
-```bash
-# runtime dependencies
-pacman -S mingw-w64-x86_64-SDL2 \
- mingw-w64-x86_64-ffmpeg
-
-# client build dependencies
-pacman -S mingw-w64-x86_64-make \
- mingw-w64-x86_64-gcc \
- mingw-w64-x86_64-pkg-config \
- mingw-w64-x86_64-meson
-```
-
-For a 32 bits version, replace `x86_64` by `i686`:
-
-```bash
-# runtime dependencies
-pacman -S mingw-w64-i686-SDL2 \
- mingw-w64-i686-ffmpeg
-
-# client build dependencies
-pacman -S mingw-w64-i686-make \
- mingw-w64-i686-gcc \
- mingw-w64-i686-pkg-config \
- mingw-w64-i686-meson
-```
-
-Java (>= 7) is not available in MSYS2, so if you plan to build the server,
-install it manually and make it available from the `PATH`:
-
-```bash
-export PATH="$JAVA_HOME/bin:$PATH"
-```
-
-#### Mac OS
+### Mac OS
The application is available in [Homebrew]. Just install it:
@@ -170,106 +58,12 @@ The application is available in [Homebrew]. Just install it:
brew install scrcpy
```
-Instead, you may want to build it manually. Install the packages:
+You can also [build the app manually][BUILD].
-```bash
-# runtime dependencies
-brew install sdl2 ffmpeg
-
-# client build dependencies
-brew install pkg-config meson
-```
-
-Additionally, if you want to build the server, install Java 8 from Caskroom, and
-make it avaliable from the `PATH`:
-
-```bash
-brew tap caskroom/versions
-brew cask install java8
-export JAVA_HOME="$(/usr/libexec/java_home --version 1.8)"
-export PATH="$JAVA_HOME/bin:$PATH"
-```
-
-#### Docker
-
-See [pierlon/scrcpy-docker](https://github.com/pierlon/scrcpy-docker).
-
-### Common steps
-
-Install the [Android SDK] (_Android Studio_), and set `ANDROID_HOME` to
-its directory. For example:
-
-[Android SDK]: https://developer.android.com/studio/index.html
-
-```bash
-export ANDROID_HOME=~/android/sdk
-```
-
-Clone the project:
-
-```bash
-git clone https://github.com/Genymobile/scrcpy
-cd scrcpy
-```
-
-Then, build:
-
-```bash
-meson x --buildtype release --strip -Db_lto=true
-cd x
-ninja
-```
-
-You can test it from here:
-
-```bash
-ninja run
-```
-
-Or you can install it on the system:
-
-```bash
-sudo ninja install # without sudo on Windows
-```
-
-This installs two files:
-
- - `/usr/local/bin/scrcpy`
- - `/usr/local/share/scrcpy/scrcpy-server.jar`
-
-Just remove them to "uninstall" the application.
-
-
-#### Prebuilt server
-
-Since the server binary, that will be pushed to the Android device, does not
-depend on your system and architecture, you may want to use the prebuilt binary
-instead:
-
- - [`scrcpy-server-v1.3.jar`][direct-scrcpy-server].
- _(SHA-256: 0f9a5a217f33f0ed7a1498ceb3c0cccf31c53533893aa952e674c1571d2740c1)_
-
-[direct-scrcpy-server]: https://github.com/Genymobile/scrcpy/releases/download/v1.3/scrcpy-server-v1.3.jar
-
-In that case, the build does not require Java or the Android SDK.
-
-Download the prebuilt server somewhere, and specify its path during the Meson
-configuration:
-
-```bash
-meson x --buildtype release --strip -Db_lto=true \
- -Dprebuilt_server=/path/to/scrcpy-server.jar
-cd x
-ninja
-sudo ninja install
-```
-
## Run
-_At runtime, `adb` must be accessible from your `PATH`._
-
-If everything is ok, just plug an Android device, and execute:
+Plug an Android device, and execute:
```bash
scrcpy
@@ -312,15 +106,6 @@ To show physical touches while scrcpy is running:
scrcpy -t
```
-To run without installing:
-
-```bash
-./run x [options]
-```
-
-(where `x` is your build directory).
-
-
## Shortcuts
| Action | Shortcut |
@@ -354,6 +139,13 @@ A colleague challenged me to find a name as unpronounceable as [gnirehtet].
[`strcpy`]: http://man7.org/linux/man-pages/man3/strcpy.3.html
+## How to build?
+
+See [BUILD].
+
+[BUILD]: BUILD.md
+
+
## Common issues
See the [FAQ](FAQ.md).