Skip to content

Cross-Building IGT

Overview

Producing an IGT build for another architecture requires setting up a cross-compilation environment with the appropriate toolchain, system root directory, and Meson configuration. This guide covers the essential steps for cross-building IGT GPU Tools for different target architectures.

Cross-Build Toolchain

Required Components

Cross-building requires installing a toolchain with support for the target architecture, or a toolchain built specifically for the target, plus an emulator (like QEMU). For IGT, the minimal toolchain consists of GCC and binutils.

Example: ARM64 on Fedora

For cross-building with ARM64 as the target architecture, install these packages:

# Fedora packages for ARM64 cross-compilation
binutils-aarch64-linux-gnu
gcc-aarch64-linux-gnu

Alternative Toolchain Sources

Pre-built cross-compiler toolchain tarballs are also available:

  • Bootlin Toolchains: https://toolchains.bootlin.com/
  • Various distribution-specific cross-compilation packages
  • Custom-built toolchains for specific targets

System Root Directory (sysroot)

Purpose

Besides a toolchain, a system root directory containing the libraries used by IGT pre-compiled to the target architecture is required.

Obtaining a Sysroot

The sysroot can be obtained through several methods:

  1. Cross-building a distribution using Yocto, buildroot, or similar tools
  2. Copying the system root from an existing installation for the desired architecture
  3. Building dependencies manually for the target architecture

The sysroot must contain all IGT build-time and runtime library dependencies compiled for the target architecture.

Important Considerations

Toolchain Dependencies

Cross-build toolchains may require some dependent object files and libraries to also be copied to the system root directory. For instance, with Fedora, files located under /usr/aarch64-linux-gnu/sys-root/ (for aarch64 architecture) should also be stored in the sysroot directory used by Meson, otherwise the preparation step will fail.

Meson Configuration

Cross-File Requirement

Meson requires an extra configuration file for non-native builds, passed via the --cross-file parameter. This file contains details about:

  • Target OS/architecture specifications
  • Host (native) OS/architecture information
  • Sysroot location and compiler configurations
  • Binary locations and execution wrappers

Configuration Sections

[host_machine] Section

Defines the system and architecture of the native OS.

Example: Native OS is Linux x86_64 architecture 

[host_machine]
system = 'linux'
cpu_family = 'x86_64'
cpu = 'x86_64'
endian = 'little'

[target_machine] Section

Contains details about the target OS/architecture.

Example: Target is aarch64 (ARM 64-bit architecture) 

[target_machine]
system = 'linux'
cpu_family = 'aarch64'
cpu = 'aarch64'
endian = 'little'

[constants] Section (Optional)

Helps define reusable paths and arguments for use in other sections.

[constants]
sysroot = '/aarch64-sysroot'
common_args = ['--sysroot=' + sysroot]

[properties] Section

Contains arguments to be used by the build binaries.

[properties]
sys_root = sysroot
c_args = common_args
c_link_args = common_args
pkg_config_libdir = [
    sysroot + '/usr/lib64/pkgconfig',
    sysroot + '/usr/share/pkgconfig',
    sysroot + '/usr/local/lib/pkgconfig'
]

[binaries] Section

Contains the binaries to be used during the build.

  • Can use either native or target toolchain
  • If using target toolchain, requires exe_wrapper pointing to an architecture emulator like qemu-arm
[binaries]
c = '/usr/bin/aarch64-linux-gnu-gcc'
ar = '/usr/bin/aarch64-linux-gnu-gcc-ar'
ld = '/usr/bin/aarch64-linux-gnu-ld'
strip = '/usr/bin/aarch64-linux-gnu-strip'
pkgconfig = 'pkg-config'

Build Process

Preparation

Prepare for cross-compilation by calling Meson with the cross-compilation config file and build directory:

meson --cross-file arm64_cross.txt build

Compilation

Execute the actual compilation using Ninja:

ninja -C build

Build Limitations

Cross-Compilation Limitations

Some parts of the IGT build are disabled during cross-compilation, including:

  • Testlist file creation
  • Documentation generation
  • Other steps that depend on running generated code on the native machine

Pre-configured Examples

The IGT root directory contains pre-configured cross-compilation examples using QEMU to run target-OS machine toolchains:

  • meson-cross-arm64.txt - ARM64 architecture
  • meson-cross-armhf.txt - ARM hard-float architecture
  • meson-cross-mips.txt - MIPS architecture

Complete Example Configuration

Native Cross-Builder Toolchain: arm64_cross.txt

[constants]
sysroot = '/aarch64-sysroot'
common_args = ['--sysroot=' + sysroot]

[properties]
sys_root = sysroot
c_args = common_args
c_link_args = common_args
pkg_config_libdir = [
    sysroot + '/usr/lib64/pkgconfig',
    sysroot + '/usr/share/pkgconfig',
    sysroot + '/usr/local/lib/pkgconfig'
]

[binaries]
c = '/usr/bin/aarch64-linux-gnu-gcc'
ar = '/usr/bin/aarch64-linux-gnu-gcc-ar'
ld = '/usr/bin/aarch64-linux-gnu-ld'
strip = '/usr/bin/aarch64-linux-gnu-strip'
pkgconfig = 'pkg-config'

[host_machine]
system = 'linux'
cpu_family = 'x86_64'
cpu = 'x86_64'
endian = 'little'

[target_machine]
system = 'linux'
cpu_family = 'aarch64'
cpu = 'aarch64'
endian = 'little'

Best Practices

Sysroot Management

  • Ensure all required dependencies are present in the sysroot
  • Verify library paths match the target architecture
  • Include both runtime and development packages

Toolchain Verification

  • Test the cross-compilation toolchain independently before building IGT
  • Verify that the toolchain can produce working binaries for the target
  • Check that all required tools (gcc, binutils, etc.) are available

Build Validation

  • Use emulation (QEMU) to test cross-compiled binaries when possible
  • Validate that the cross-compiled IGT works on actual target hardware
  • Compare functionality with native builds to ensure completeness

References