Differences

This shows you the differences between two versions of the page.

--- raspberry:cross-platform-compile:cross-compile-overview [2026/09/02 20:09] – [The problem with using host-version ARM libraries] oscar
+++ raspberry:cross-platform-compile:cross-compile-overview [2026/09/04 12:41] (current) – [Cross Platform Development for Raspberry] oscar
@@ Line 6: / Line 6: @@
   - Exact **identical Linux/Debian versions** on X86 build host and Raspberry runtime target
   - **Different Linux/Debian versions** on X86 build host and Raspberry runtime target
-==== The problem with using host-version ARM libraries ====
+  - [[raspberry:cross-platform-compile:check-architecture|Check the architecture of Host and Target]]
+  - [[raspberry:cross-platform-compile:setup-for-identical-Debian-versions|For identical Debian distro/version]]
+  - [[raspberry:cross-platform-compile:setup-for-different-Debian-versions|For different Debian distro/version]]
+  - [[raspberry:cross-platform-compile:cross-platform-debugging|Cross Platform Debugging]]
+===== Compatibility rule =====
+Build against the oldest operating-system release and CPU that the resulting
+binary must support. Do not link a Bookworm target against Trixie ARM libraries. Doing so can create
+dependencies on newer glibc or library symbols that are unavailable on the
+Bookworm target. For example:
+<code>
+Incorrect:
+Trixie compiler + Trixie armhf libraries -> Bookworm target
+Correct:
+Trixie compiler + Bookworm armhf sysroot -> Bookworm target
+</code>
+===== The problem with different host and target ARM libraries =====
 The important guideline is that **the target system's ABI, headers, libraries and library versions vs. what you build against.** For example:
 <code>
@@ Line 43: / Line 65: @@
              ✗
        program won't run, with errors like:
-            ./program: /lib/arm-linux-gnueabihf/libc.so.6: version `GLIBC_2.41' not found
+       ".../lib/arm-linux-gnueabihf/libc.so.6: version `GLIBC_2.41' not found..."
 </code>
-This is one of the most common reasons why **building on a newer distribution for an older target** causes trouble.
+This is one of the most common reasons why **building on a newer distribution for an older target** causes trouble. It isn't only the **libraries** that matter. The headers matter too. Suppose you compile against Trixie's headers (///usr/include//), but run on Bookworm. You can potentially get differences in:
-===== But the reverse is usually fine =====
+  * API definitions
-Suppose:
+  * feature macros
-<code>
+  * structure definitions
-Host:   Debian Trixie
+  * constants
-Target: Raspbian Bookworm
+  * kernel interfaces
-</code>
+  * glibc interfaces
-and you use the **Raspbian Bookworm sysroot**.
+  * library-specific APIs
-Then:
-<code>
-Trixie GCC
-     │
-     ▼
-Raspbian Bookworm headers
-     +
-Raspbian Bookworm libraries
-     │
-     ▼
-Raspbian Bookworm executable
-</code>
-The host's distribution version becomes much less important. You are essentially saying:
-> "Use this compiler, but pretend the target filesystem is this Raspbian Bookworm system."
-That's exactly what `--sysroot` is for.
----
-==== There's another subtle reason ====
-It isn't only the **libraries** that matter. The headers matter too. Suppose you compile against Trixie's headers:
-<code>
-/usr/include
-</code>
-but run on Bookworm.
-You can potentially get differences in:
-* API definitions
-* feature macros
-* structure definitions
-* constants
-* kernel interfaces
-* glibc interfaces
-* library-specific APIs
 So the ideal relationship is:
-<code>
-                   Raspbian Bookworm
-                  ┌─────────────────┐
-                  │ headers         │
-                  │ libraries       │
-                  │ linker files    │
-                  │ ABI             │
-                  └────────┬────────┘
-                           │
-                           ▼
-                     cross compiler
-                           │
-                           ▼
-                    your executable
-</code>
 That's why a **target-specific sysroot** is the clean solution.
----
+===== But the reverse is usually fine =====
+If you deliberately want to require a newer target system, that's perfectly legitimate. For example:
-## One important exception
-If you deliberately want to require a newer target system, that's perfectly legitimate.
-For example:
 <code>
 Build against Trixie armhf
           ↓
 Deploy only to Trixie armhf
+          ↓
+      No problem.
 </code>
+The rule is simple: **Don't build against a newer userspace than the oldest target you intend to support.** This is particularly important for `glibc`.
-No problem.
-The rule is simply:
-> **Don't build against a newer userspace than the oldest target you intend to support.**
-This is particularly important for `glibc`.
----
-This distinction matters:
-### Target = Debian armhf
-<code>
-Debian Bookworm x86-64
-        ↓
-Debian Bookworm armhf
-</code>
-Excellent fit for: crossbuild-essential-armhf
-### Target = Raspberry Pi OS 32-bit
-<code>
-Debian Bookworm x86-64
-        ↓
-Raspberry Pi OS armhf
-</code>
-You should ideally use the **actual Raspberry Pi OS sysroot/libraries**.
-This becomes particularly important if you're linking against anything beyond libc.
-you want the headers and libraries corresponding to the **actual target system**. Otherwise you can end up with:
-<code>
-compile successfully
-       ↓
-link successfully
-       ↓
-copy to Pi
-       ↓
-runtime/library incompatibility
-</code>
-[[raspberry:cross-platform-compile:setup-for-identical-Debian-versions|Setup for Identical Debian versions]]
-[[raspberry:cross-platform-compile:crossbuild-essential-armhf|crossbuild-essential-armhf]]
 ====== Raspberry Pi OS vs Debian armhf ======
-One important distinction: Raspberry Pi OS vs Debian armhf
+One important distinction: Raspberry Pi OS vs Debian armhf. Raspberry Pi OS is Debian-derived, but its 32-bit repository contains packages built for Raspberry Pi hardware and may contain versions or patches marked with `+rpt`. Use the Raspberry Pi OS repositories when Raspberry Pi OS is the
+target. Use Debian repositories only when the target is Debian armhf.
-There is, however, a **very important caveat** for Raspberry Pi.
-If your target is **Raspberry Pi OS 32-bit**, don't blindly assume that Debian Bookworm's armhf libraries are an exact match.
-Debian itself points this out:
+If your target is **Raspberry Pi OS 32-bit**, don't blindly assume that Debian Bookworm's armhf libraries are an exact match. Debian itself points this out:
 > Raspberry Pi OS armhf can be subtly incompatible with Debian armhf.