[[multiarch]]
=== Multiarch

The multiarch support for cross-architecture installation of binary packages (particularly +++i386<->amd64+++, but also other combinations) in the *dpkg* and *apt* packages introduced to Debian *wheezy* (7.0, May 2013) demands us to pay extra attention for the packaging.

You should read the following references in detail.

* Ubuntu wiki https://wiki.ubuntu.com/MultiarchSpec[MultiarchSpec] (upstream)
* Debian wiki https://wiki.debian.org/Multiarch/Implementation[Multiarch/Implementation] (Debian situation)

It uses the triplet such as *i386-linux-gnu* and *x86_64-linux-gnu* for the install path of shared libraries. The actual triplet path is dynamically set into *$(DEB_HOST_MULTIARCH)* value by *dpkg-architecture* for each build. This can be done by including */usr/share/dpkg/default.mk* in the *debian/rules* file as described in <<buildflags>>.

For example, the path to install multiarch libraries are changed as follows. (Old special purpose library paths such as */lib32/* and */lib64/* are not used any more.)

[options="header", cols="2,3,3"]
|====
|Classic path	|i386 multiarch path		|amd64 multiarch path
|/lib/	  	|/lib/i386-linux-gnu/		|/lib/x86_64-linux-gnu/
|/usr/lib/	|/usr/lib/i386-linux-gnu/	|/usr/lib/x86_64-linux-gnu/
|====

For  Autotools based packages under the *debhelper* package (compat>=9), this path setting is automatically taken care by the *dh_auto_configure* command.

For other packages with non-supported build systems, you need to manually adjust the install path as follows.

* If *./configure* is used in the part of *override_dh_auto_configure* target in *debian/rules*, make sure to replace it with "*dh_auto_configure --*" while retargeting the install path from */usr/lib/* to */usr/lib/$(DEB_HOST_MULTIARCH)/*.
* Replace all occurrences of **/usr/lib/** with **/usr/lib/*/** in **debian/**'foo'**.install** files.

All files installed simultaneously as the multiarch package to the same file path should have exactly the same file content. You must be careful on differences generated by the data byte order and by the compression algorithm.

Please note that *--libexecdir* specifies the default path to install executable programs run by other programs rather than by users. Its Autotools default is */usr/libexec/* but its Debian default is */usr/lib/*.  If such executable is "Multi-arch: foreign" package, path such as */usr/lib/* or */usr/lib/*'packagename' may be more desirable than */usr/lib/i386-linux-gnu/* which *dh_auto_configure* uses.

References:

* https://www.debian.org/doc/packaging-manuals/fhs/fhs-2.3.html#USRLIBLIBRARIESFORPROGRAMMINGANDPA[Filesystem Hierarchy Standard: /usr/lib : Libraries for programming and packages] states "*/usr/lib* includes object files, libraries, and internal binaries that are not intended to be executed directly by users or shell scripts." (Debian policy)

* http://www.gnu.org/prep/standards/html_node/Directory-Variables.html[GNU Coding Standards: 7.2.5 Variables for Installation Directories] has description for *libexecdir* as "The definition of *libexecdir* is the same for all packages, so you should install your data in a subdirectory thereof. Most packages install their data under *$(libexecdir)/package-name/* ...". (It is always good idea to follow GNU unless it conflicts with the Debian policy)

* https://wiki.debian.org/Multiarch[Debian multiarch support]
