This is the place to find hints on how to make your Debian package ready for cross-compilation
Contents
Nomenclature
It needs to be noted that tools listed here use a naming of architecture roles inherited from the GNU autotools, which some people used to nomenclature from other tools might perhaps find confusing. The difference is in perspective, either system-centric (this nomenclature) or object-centric (the other variant):
build means the architecture of the chroot/dpkg/compiler's executable, i.e. the architecture of the build system (called host by cmake/kernel/etc)
host means the architecture of produced executable objects, i.e. the architecture of the host system where these guest objects will run on (called target or sometimes build elsewhere)
target is what the produced executable objects will generate when producing executable objects, i.e. the architecture of the systems the built programs target their results to run on (relevant only for compilers and similar)
Salsa CI
The default Salsa-CI pipeline now includes a test-crossbuild job, that will attempt to cross-compile your package on the default amd64 build architecture for the arm64 host architecture.
So use this default pipeline to get automatic feedback whether your package is cross-compilable (or not).
To setup a cross-compilation environment locally, see the end of this document.
Dependencies
Many build-dependencies must use the architecture of the host architecture (e.g. C-libraries you want to link against).
Other build-dependencies must be executed on the build machine. These are obviously compilers, but also interpreters, documentation generators,...
To help the cross-building environment, you can annotate Build-Dependencies, so that the correct architecture is picked.
declare "Indep" Build-dependencies
Typically, cross-compilation is mostly interesting to produce arch:any packages, as the host architecture can use arch:all packages produced on any (non-crossbuilding) build machine.
To allow the resolver to not worry about any Build-Depends that it won't need anyhow, make sure to declare all build-dependencies that are only needed for building arch:all packages using the Build-Depends-Indep stanza:
use ':any' specifier for dependencies
For some packages a given dependency must have the host architecture, and sometimes the build architecture.
If you require your Build-Dependency to be executable on the host machine, annotate this by adding the :any architecture specifier;
d/rules
dh automatically takes care of most cross-building issues.
Sometimes you need to run some programs directly within d/rules (that is: 'outside' of dh), in which case you should make sure to pick the cross-building variants. You can get cross-building variants of common build tools by including the /usr/share/dpkg/buildtools.mk snippet.
To make everything more optional, the following example does a weak include and defines a fallback: