Skip to main content

Cross-Compile with the Yocto SDK

A Yocto SDK lets you compile an application on a Linux development host for a different target architecture. In this tutorial, you will generate an SDK, install it on the host, compile a small C program, and run the resulting binary on a board.

The commands below use Grinn Genio BSP as an example. For another platform, use the machine name and kas configuration from its image build guide.

important

Generate the SDK from the same BSP revision, machine, image configuration, and kas extensions as the image running on the board. A mismatched SDK can produce an application that requires libraries or versions that are not available on the target.

Before You Start​

You need:

  • a completed Yocto image build;
  • a Linux development host with enough space for the SDK;
  • the matching image running on the target board;
  • ADB access to the board.

The SDK is generated and installed on the development host. The compiled application is then copied to and executed on the target board.

1. Generate the SDK​

Run the build from the root of the BSP workspace. The following command uses Grinn Genio BSP as an example:

Development host
export KAS_CONFIG="meta-grinn-genio/kas/default.yml"
export KAS_MACHINE=grinn-genio-700-sbc
export KAS_CONTAINER_IMAGE_DISTRO=debian-bookworm

kas-container build --task populate_sdk "$KAS_CONFIG"

The populate_sdk task generates an installer containing the cross-compiler, target headers and libraries, and a target sysroot matching the selected image.

If the image was built with kas extensions, include the same extensions when generating its SDK. For example:

Development host
export KAS_CONFIG="meta-grinn-genio/kas/default.yml:meta-grinn-genio/kas/custom-packages.yml"
kas-container build --task populate_sdk "$KAS_CONFIG"

Wait for the build to finish and return to the shell prompt before continuing.

2. Install the SDK​

With the default build directory, Yocto places the SDK installer under build/tmp/deploy/sdk in the BSP workspace. List the installer from the same workspace root:

Development host
ls -1 build/tmp/deploy/sdk/*.sh

Example output:

Example output
build/tmp/deploy/sdk/rity-demo-glibc-x86_64-rity-demo-image-armv8a-grinn-genio-700-sbc-toolchain-25.1-release.sh

The installer filename contains image, architecture, machine, and version information, so it can change between BSP releases. If more than one installer is listed, select the one for the current machine and image. Copy its filename into SDK_INSTALLER:

Development host
export SDK_INSTALLER="$PWD/build/tmp/deploy/sdk/<selected-installer>.sh"
mkdir -p "$HOME/yocto-sdk"
chmod +x "$SDK_INSTALLER"
"$SDK_INSTALLER" -d "$HOME/yocto-sdk"

Replace <selected-installer> with the filename displayed by ls.

The installer copies the SDK to the development host. It does not install anything on the target board.

3. Activate the SDK Environment​

The environment setup script is stored at the top level of the SDK installation directory. List it with:

Development host
ls -1 "$HOME/yocto-sdk"/environment-setup-*

Example output:

Example output
/home/<user>/yocto-sdk/environment-setup-armv8a-poky-linux

For the Grinn Genio BSP example, source this script in the current shell:

Development host
export SDK_ENV="$HOME/yocto-sdk/environment-setup-armv8a-poky-linux"
source "$SDK_ENV"
printf '%s\n' "$CC"

For another platform, use the setup script displayed by ls. Sourcing the script configures CC, compiler flags, the target sysroot, and other cross-development variables. Source it again in every new shell before using the SDK.

In this example, $CC begins with aarch64-poky-linux-gcc and includes the matching target sysroot.

4. Create the Test Application​

Create a separate application directory on the development host:

Development host
mkdir -p "$HOME/yocto-hello-world"
cd "$HOME/yocto-hello-world"

Save the following source as hello_world.c:

hello_world.c
#include <stdio.h>

int main(void)
{
    puts("Hello from the Yocto SDK!");
    return 0;
}

5. Compile and Check the Binary​

Compile the application with the compiler command provided by the SDK:

Development host
${CC} hello_world.c -o hello_world
file hello_world

Example output:

Example output
hello_world: ELF 64-bit LSB pie executable, ARM aarch64, ...

Check the target architecture through ADB:

Development host
adb shell uname -m

For this example, the target reports aarch64, matching the architecture shown by file.

An AArch64 binary cannot normally run directly on an x86-64 development host. The host created the binary, but the matching target architecture must execute it. If file reports the host architecture instead, the SDK environment was not active or the host compiler was used instead of ${CC}.

6. Copy and Run the Application​

Confirm that ADB lists the expected board with status device:

Development host
adb devices -l

Copy the binary to the board and run it from /tmp:

Development host
adb push hello_world /tmp/hello_world
adb shell 'chmod +x /tmp/hello_world && /tmp/hello_world'

Expected output:

Hello from the Yocto SDK!

Troubleshooting​

No SDK installer is found​

Confirm that populate_sdk completed successfully and that the selected machine and configuration match the image build.

$CC is empty or file reports the host architecture​

Source the selected environment-setup-* script again in the current shell, confirm that $CC contains a cross-compiler, and compile with ${CC} instead of calling gcc directly.

The application reports a missing library on the target​

Generate and install an SDK matching the exact image on the board. Rebuild the SDK with the same BSP revision, machine, image configuration, and kas extensions used for that image.

ADB does not list the board​

Follow the selected board's ADB access instructions. Continue only after the expected device appears with status device.

For more detail, see the Yocto Project manual's SDK application workflow.