REW

How To Cross-compile GStreamer?

Published Aug 29, 2025 5 min read
On this page

Cross-compiling GStreamer is a powerful technique for developing applications for embedded systems and other non-native architectures.

The process requires careful setup of a toolchain and build environment but offers significant time savings over compiling directly on slow target hardware. Modern GStreamer development relies on the Meson build system, which has robust support for cross-compilation.

Cross-compilation methods for GStreamer

1. gst-build (for Meson-native projects)

gst-build is the recommended method for cross-compiling GStreamer and its core plugins. It uses the Meson build system and has been integrated into the main GStreamer source repository since September 2021.

Pros:

  • Monorepo simplicity: Builds the entire GStreamer platform from a single source tree, making it easy to manage.
  • Robust Meson support: Meson is built for cross-compilation and handles complex dependencies seamlessly with a cross-file.
  • Ideal for development: Allows for rapid iteration and testing of GStreamer features.

Cons:

  • Limited external dependencies: Only builds dependencies that have been ported to Meson. For non-Meson libraries, you will need to pre-build or provide them via a sysroot.

2. Cerbero (for projects with external dependencies)

Cerbero is a more comprehensive build system used by GStreamer for building a wide array of dependencies, including those not using Meson.

Pros:

  • Automated dependency handling: Simplifies the process of building a large number of external libraries alongside GStreamer.
  • Comprehensive builds: Can create a complete, self-contained GStreamer environment with all necessary dependencies.

Cons:

  • Potentially complex: Requires learning the Cerbero build system and may not be necessary if your project has few external dependencies.
  • May disable features: Certain features like GObject introspection may be disabled during cross-compilation unless you use tools like QEMU with binfmt_misc.

3. Buildroot/Yocto (for embedded Linux images)

For building entire embedded Linux systems, platforms like Buildroot and Yocto are often the best choice. These systems automatically handle the cross-compilation of GStreamer and all its dependencies as part of the overall system image build.

Pros:

  • System-level integration: Provides a complete, consistent cross-compilation environment for the entire target OS.
  • Reproducible builds: Ensures a predictable and repeatable build process.
  • Comprehensive package management: Handles all dependencies, not just GStreamer-related ones.

Cons:

  • High complexity: Involves a significant learning curve and more overhead than simple cross-compilation.
  • Slower for simple cases: Unnecessary if you only need GStreamer and a few dependencies.

Step-by-step guide for cross-compiling with gst-build and Meson

This guide will focus on the modern gst-build and Meson approach, as it is the most common for GStreamer development.

Step 1: Set up the environment

  • Install build tools: Ensure you have git, Python 3.5+, Meson 0.54+, and Ninja installed on your host machine.sh

    sudo apt-get install git python3 python3-pip ninja-build
pip3 install --user meson

    Use code with caution.

  • Install the cross-compiler: Install the toolchain for your target architecture. For example, to target 64-bit ARM for a Raspberry Pi or similar board, install the aarch64-linux-gnu toolchain:sh

    sudo apt install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu libc6-dev-arm64-cross

    Use code with caution.

  • Obtain the GStreamer source: Clone the GStreamer monorepo from Git:sh

    git clone https://gitlab.freedesktop.org/gstreamer/gstreamer.git
cd gstreamer

    Use code with caution.

Step 2: Create a Meson cross-file

The cross-file is the heart of the Meson cross-compilation process. It tells Meson where to find the cross-compiler, what the target architecture is, and where the target's libraries and headers are located (the sysroot).

Example cross-file for aarch64 (e.g., cross_file_aarch64.txt):

[binaries]
c = 'aarch64-linux-gnu-gcc'
cpp = 'aarch64-linux-gnu-g++'
ar = 'aarch64-linux-gnu-ar'
strip = 'aarch64-linux-gnu-strip'
pkg-config = '/usr/bin/aarch64-linux-gnu-pkg-config'
[properties]
sys_root = '/usr/aarch64-linux-gnu' # The root directory of the target's libraries and headers
pkg_config_libdir = '/usr/aarch64-linux-gnu/lib/pkgconfig'
[host_machine]
system = 'linux'
cpu_family = 'aarch64'
cpu = 'arm64'
endian = 'little'

Use code with caution.

  • [binaries]: Specifies the cross-compilers and build tools.
  • [properties]: Defines properties for the build, such as the location of the sysroot and the path for pkg-config to find target-specific .pc files.
  • [host_machine]: Describes the target architecture. This is slightly counter-intuitive; "host" in cross-compilation refers to the target machine (the one that hosts the compiled binaries), while the build machine is where the compilation happens.

Step 3: Configure and build GStreamer

Now, use Meson to configure the build with your cross-file and then use Ninja to perform the compilation.

  1. **Configure the build:**sh

    # 'build_aarch64' is the name of your build directory
meson setup --cross-file cross_file_aarch64.txt build_aarch64

    Use code with caution.

    This command will configure the project for cross-compilation. You can also pass additional options to enable or disable specific features, such as plugins or libraries. For example:sh

    meson setup --cross-file cross_file_aarch64.txt -Dlibav=disabled build_aarch64

    Use code with caution.

  2. **Compile the source:**sh

    ninja -C build_aarch64

    Use code with caution.

  3. **Install the artifacts:**After a successful build, you can install the compiled libraries and plugins into a destination directory using DESTDIR. This is crucial for collecting the build artifacts without installing them on the host system.sh

    ninja -C build_aarch64 install DESTDIR=/opt/gstreamer-aarch64

    Use code with caution.

Step 4: Run the binaries on the target

Finally, transfer the contents of your DESTDIR to your target system. You will need to set up several environment variables on the target machine so the system can find the GStreamer libraries and plugins.

# On the target machine:
export PATH=/opt/gstreamer-aarch64/usr/local/bin:$PATH
export LD_LIBRARY_PATH=/opt/gstreamer-aarch64/usr/local/lib:$LD_LIBRARY_PATH
export GST_PLUGIN_PATH=/opt/gstreamer-aarch64/usr/local/lib/gstreamer-1.0

Use code with caution.

You can then run gst-inspect-1.0 to verify your plugins are present and working.

Enjoyed this article? Share it with a friend.