Hi Sean and other policy editors,
it may appear strange to resume a thread that was last discussed seven
years ago. Yet, we picked up this matter at the Würzburg sprint and
iterated a lot on the proposal refining and extending it to cover all
Multi-Arch values.
On Sat, Oct 14, 2017 at 02:53:50PM -0700, Sean Whitton wrote:
> If we are finished with our definitions for `no` and `foreign`, I think
> it would be worth releasing them in Policy, of course with a caveat
> saying "there are other possible values". I say this as a package
> maintainer would has benefitted from reading your descriptions of
> `foreign` and `no`. These are useful and should be out there.
I am really sorry I failed to follow up back then as I really do agree
that having something in policy would help a lot.
You'll fine the result of two days of discussion and iteration among
Jochen, josch, Holger and myself attached.
Kind regards
Jochen, josch and Helmut
diff --git a/policy/ch-controlfields.rst b/policy/ch-controlfields.rst
index 3151816..d43acac 100644
--- a/policy/ch-controlfields.rst
+++ b/policy/ch-controlfields.rst
@@ -1307,6 +1307,150 @@ This list is intentionally incomplete. You should consult the
documentation of the tool or package in question for which keywords it
defines and when they are needed.
+.. _s-f-Multi-Arch:
+
+``Multi-Arch``
+~~~~~~~~~~~~~~
+
+A Debian installation may combine packages from multiple architectures.
+The ``Multi-Arch`` header enables individual packages to declare their
+support for this feature. It may occur only in the control file of a
+binary package or in the per-package fields paragraph of a source
+package control file. The semantics of permitted values are ``no``
+(default), ``foreign``, ``same`` and ``allowed`` as described
+individually.
+
+.. _s-f-Multi-Arch-no:
+
+``Multi-Arch: no``
+^^^^^^^^^^^^^^^^^^
+
+When satisfying a dependency (using ``Depends``, ``Pre-Depends``,
+``Provides``, ``Recommends``, or ``Suggests``), the architecture of the
+depender and the architecture of the dependee being thus marked are
+required to be equal. For negative dependency relations (``Breaks``,
+``Conflicts``, and ``Replaces``) the architecture does not have to match
+for the relation to take effect. Architecture-independent packages are
+treated as if they had the architecture value of the installed `dpkg`
+package. Furthermore, multiple instances of a package with the same
+name and different architectures are not considered coinstallable.
+
+Note that due to limitations in the archive management software, this
+value cannot currently be specified explicitly in binary package control
+files.
+
+``Multi-Arch: foreign``
+^^^^^^^^^^^^^^^^^^^^^^^
+
+A binary package may be marked with a ``Multi-Arch: foreign`` control
+header if the provided interfaces are independent of the architecture of
+the package. Any provided virtual packages (see :ref:`s-virtual`)
+inherit this property. Given this header value, dependencies on this
+package are considered satisfied even when the depender's architecture
+differs from the marked package.
+
+There are five main areas that can contribute to the interface of a
+package and if any of them provides an architecture-dependent interface,
+a package must not be marked with ``Multi-Arch: foreign``.
+
+- The installed files of a package: Architecture-dependent packages may
+ install different sets of files or files with different content for
+ multiple architectures and these differences may contribute to the
+ interface (e.g. an endianess-dependent database file). For
+ architecture-independent binary packages, there is aspect does not
+ apply.
+
+- The behavior of installed files of a package: When interfacing with
+ installed files by executing them, their behavior may contribute to
+ the provided interface. For instance, interfacing with shared and
+ static libraries necessarily is architecture-dependent. Whilst binary
+ executables generally differ with architectures, the exposed interface
+ (for example the command line interface, the content on standard
+ input/output, the way they process files) may be independent of the
+ architecture used to execute. In that case, their interface may be
+ considered architecture-independent.
+
+- Maintainer scripts and triggers: A package may behave in an
+ architecture dependent way, when the maintainer scripts or invoked
+ triggers behave differently on different architectures. For instance,
+ byte-compiling source files into architecture-dependent bytecode
+ during ``postinst`` may turn the interface of a package
+ architecture-dependent.
+
+- The dependencies of a package: A package may expose functionality of
+ other packages by depending on them. In general, an executable does
+ not expose its linked shared libraries and therefore they do not
+ usually contribute to the interface. On the other hand, the whole
+ point of transitional packages is to expose such functionality.
+ Likewise, development packages for shared libraries necessarily expose
+ their own dependencies.
+
+- Implicit and foreign dependencies of a package: Essential packages are
+ implicitly depended upon and need not show up in ``Depends``. Yet
+ their behaviour can be architecture-dependent. For instance, using
+ ``dpkg --print-architecture`` can be used to emit the native
+ architecture even though ``dpkg`` is marked ``Multi-Arch: foreign``.
+ Similarly, calling ``pkgconf`` (without a prefix) will behave
+ differently on different architectures as its search path is
+ architecture-dependent even though ``pkgconf-bin`` is considered
+ ``Multi-Arch: foreign``.
+
+The interfaces of a package are determined by its maintainer. However,
+some packages might expose architecture dependencies when other packages
+use them in a manner not intended by the maintainer. This can happen
+when it is not clear which parts of the package are its interfaces.
+
+In such cases, where the package satisfies the criterion for
+``Multi-Arch: foreign`` but might expose architecture dependency,
+because it is not clear which parts of the package are its interfaces,
+the interfaces of the package should be described in the file
+``debian/README.multiarch``.
+
+Conversely, justifying the use of functionality that is not covered by
+its offered interface with a dependency on such a package is not
+allowed.
+
+``Multi-Arch: same``
+^^^^^^^^^^^^^^^^^^^^
+
+Multiple binary packages with the same name and version may be installed
+concurrently if all of them carry this header valued ``same``. Any set
+of packages with matching name and version being thus marked must
+support two properties.
+
+- All filenames that are present in multiple of these packages must
+ contain bit-identical content across architectures. [#]_
+
+ For files whose name is unique within this set, no such requirement
+ exists. Therefore, such packages usually install most of their files
+ below ``/usr/lib/${DEB_HOST_MULTIARCH}``.
+
+- The maintainer scripts must be prepared to be configured or
+ deconfigured multiple times. In particular, ``postrm`` must consider
+ that another instance may still be present. It may check the
+ ``DPKG_MAINTSCRIPT_PACKAGE_REFCOUNT`` environment variable set by
+ ``dpkg``.
+
+``Multi-Arch: allowed``
+^^^^^^^^^^^^^^^^^^^^^^^
+
+A package annotated this way behaves as if it were annotated with the
+``no`` value except that a depender may now append ``:any`` to the
+package name in a dependency relation field. In that case, the
+dependency is considered satisfied even when the architecture of the
+depender differs from the dependee's. Dependencies carrying a ``:any``
+suffix can only be satisfied by packages marked ``Multi-Arch: allowed``.
+
+This value should be used rarely for cases where the package can be used
+in an architecture-dependent way or in an architecture-independent way
+and the decision of which applies is deferred to the depender. The most
+common use is with programming language interpreters that enable loading
+architecture-dependent plugins.
+
+Since removing this value tends to break reverse dependencies that
+employ ``:any``, uses of it should be discussed with
+*debian-de...@lists.debian.org* first.
+
.. _s5.7:
User-defined fields
@@ -1443,3 +1587,9 @@ details.
.. [#]
That is, the parts which are not the ``.dsc``.
+
+.. [#]
+ As an exception, the ``libc6`` package is marked ``Multi-Arch: same``
+ despite not fully complying with this requirement, because the
+ location of the dynamic loader is not universally unique and cannot
+ be changed without breakig ABI.
