diff --git a/docs/guide/build.md b/docs/guide/build.md index 6c75071a..d0cd3e6f 100644 --- a/docs/guide/build.md +++ b/docs/guide/build.md @@ -1,22 +1,97 @@ # Build Notes -To build the native code, be sure to install the prerequisite software (follow the links): +Building from source compiles three native libraries: Google's WebRTC, the JNI library around it, and FFmpeg with dav1d for the `webrtc-java-media` module. The tools below are what the build expects to find. The CI setup in `.github/actions/prepare-/action.yml` installs the same set and is the reference when in doubt. -**Note**: You don't have to install the Depot Tools, the build script will do that for you. +You don't have to install Chromium's `depot_tools`, Siso or GN: the build clones `depot_tools` into the WebRTC checkout and uses the tools it brings. -| OS | Build Instructions | -| --------- | ----------------------------------------------------------------- | -| Linux | [Ubuntu][build-linux-ubuntu], [other distros][build-linux-other] | -| macOS | Xcode 9 or higher | -| Windows | [Visual Studio][build-windows] | +## Prerequisites -Assuming you have all the prerequisites installed for your OS, run: +### All platforms + +| Tool | Notes | +| --------------------- | ----------------------------------------------------------------------------------------- | +| JDK 17 or newer | The libraries target Java 8, but the JavaFX module needs 11 and the examples need 17. | +| Maven 3.6.3 or newer | | +| Git | Clones `depot_tools`, the WebRTC sources and the submodules. | +| CMake 3.13 or newer | Must be on the `PATH`. The Maven build does not download it. | +| Python 3 | Runs `depot_tools` and the Linux sysroot script. On macOS it also needs `setuptools`. | +| Meson and Ninja | Build dav1d, the AV1 software decoder linked into FFmpeg (`pip install meson`). | +| Disk space | About 15 GB for the WebRTC checkout and its toolchains, kept in `~/webrtc` by default. | + +FFmpeg and dav1d come from Git submodules, which a plain clone leaves empty. Fetch them before the first build: + +```shell +git submodule update --init --depth 1 webrtc-java-media/third-party/ffmpeg webrtc-java-media/third-party/dav1d +``` + +### Linux + +Linux builds run on an x86-64 host and cross-compile for ARM. Install the build tools (Debian/Ubuntu package names): + +```shell +sudo apt-get install binutils cmake git make meson nasm ninja-build pkg-config python3 python3-setuptools rsync unzip wget xz-utils +``` + +The JNI library compiles against the libc++ headers of the WebRTC build. Those headers only support the Clang that the WebRTC branch pins, so the toolchain files expect that exact Clang in `/opt/clang`. Install it this way (the package name is in `.github/actions/prepare-linux/action.yml` and changes with the WebRTC branch): + +```shell +CLANG_PACKAGE=clang-llvmorg-24-init-7747-g62397f8b-27.tar.xz +wget https://commondatastorage.googleapis.com/chromium-browser-clang/Linux_x64/$CLANG_PACKAGE +sudo mkdir -p /opt/clang +sudo tar -xf $CLANG_PACKAGE -C /opt/clang +``` + +Headers and libraries (X11, D-Bus, GIO, GBM, libdrm) come from a Debian sysroot in `/opt/sysroot` rather than from the host, so no `-dev` packages are needed. Install the sysroot for each target architecture you build for (`amd64`, `arm64` or `armhf`): + +```shell +python3 webrtc-jni/src/main/cpp/dependencies/webrtc/linux/sysroot/install-sysroot.py --arch=amd64 +sudo mkdir -p /opt/sysroot +sudo mv webrtc-jni/src/main/cpp/dependencies/webrtc/linux/debian* /opt/sysroot/ +``` + +To cross-compile for ARM, CI also installs `gcc-aarch64-linux-gnu g++-aarch64-linux-gnu` (`-Plinux-aarch64`) or `gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf` (`-Plinux-aarch32`). + +Running the tests requires the runtime libraries the native library links against. A desktop system already has them. On a headless one, install them with: + +```shell +sudo apt-get install libx11-6 libxext6 libxfixes3 libxdamage1 libxtst6 libxrandr2 libxcomposite1 libglib2.0-0 libgbm1 libdrm2 +``` + +### macOS + +- Xcode 16 (CI uses 16.1), selected with `xcode-select`. The library targets macOS 11 and later. +- The remaining tools from [Homebrew](https://brew.sh): + +```shell +brew install cmake nasm meson ninja pkgconf python-setuptools +``` + +`nasm` is needed for the x86-64 build (`-Pmacos-cross-x86_64`), including when you cross-compile from Apple Silicon. + +### Windows + +- **Visual Studio 2022** with the *Desktop development with C++* workload. The build uses this local installation, not Google's internal toolchain. Add *MSVC ARM64 build tools* to build for `windows-aarch64`, and *C++ Clang tools for Windows* to build with `-Pwindows-clang`. +- **Windows SDK 10.0.28000.0**, this exact version. The WebRTC branch pins it, and `gn gen` fails without it. Install it with the *Debugging Tools for Windows* feature, because the toolchain setup needs `dbghelp.dll`. A different WebRTC branch may pin a different SDK (`SDK_VERSION` in `build/vs_toolchain.py`). +- **MSYS2**, installed in `C:\msys64` (set `MSYS2_ROOT` for another location). FFmpeg's configure scripts and makefiles need a POSIX shell with `make` and `nasm`. Git for Windows' bash has neither. + + ```shell + winget install MSYS2.MSYS2 + C:\msys64\usr\bin\bash -lc "pacman -S --needed make nasm diffutils pkgconf" + ``` + +- **Ninja and Meson** on the `PATH`, e.g. `choco install ninja` and `pip install meson`. + +Run Maven from an ordinary command prompt or PowerShell. The build sets up the MSYS2 shell and the Visual Studio environment itself. + +## Building + +With the prerequisites installed, run: ```shell mvn install ``` -On the first run, the WebRTC source tree will be loaded into the `//webrtc` directory. This will take a while and require about 20 GB of disk space. +On the first run, the WebRTC source tree is loaded into the `//webrtc` directory, and FFmpeg and dav1d are built into `//ffmpeg`. This takes a long time. Later builds reuse both as long as their configuration is unchanged. To build the native libraries without running the tests, use `mvn package -DskipTests`, as CI does. ## Build Parameters @@ -37,10 +112,6 @@ A compiled WebRTC build records its GN arguments, extra targets, and patch fingerprint. Changes to patch content invalidate both build-tree and installed caches, so a native rebuild also includes the updated patches. -[build-linux-ubuntu]: https://chromium.googlesource.com/chromium/src/+/master/docs/linux/build_instructions.md#system-requirements -[build-linux-other]: https://chromium.googlesource.com/chromium/src/+/master/docs/linux/build_instructions.md#Notes-for-other-distros -[build-windows]: https://chromium.googlesource.com/chromium/src/+/master/docs/windows_build_instructions.md#visual-studio - ## Release workflow Maintainers start **Prepare release** (`release.yml`) from `main`, providing the