This is the place to find hints on how to make your Debian package ready for cross-compilation

<<TableOfContents>>

== 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 [[https://salsa.debian.org/salsa-ci-team/pipeline|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 [[#See_also|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:

{{{#!highlight debcontrol
Build-Depends-Indep:
 doxygen,
}}}

=== 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;

{{{#!highlight debcontrol
Depends:
 python3:any,
}}}


== 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:

{{{#!highlight make
-include /usr/share/dpkg/buildtools.mk
PKG_CONFIG?=pkg-config

export DEB_CFLAGS_MAINT_APPEND = $(shell $(PKG_CONFIG) --cflags foobar)
}}}

= See also =

 * [[CrossCompiling|Setting up  a Cross Compilation environment]]
 * CrossBuildPackagingGuidelines