Hi Chris,
On Sat, Mar 29, 2025 at 02:00:06PM +0100, Chris Hofstaedtler wrote:
> I'm an interested party, but certainly no expert on this topic. I have
> however a few editorial remarks, inline below.
thanks for reviewing it. I made a pass across reviews received thus far
(1) and send and update now.
> > +Note that due to limitations in the archive management software, this
> > +value cannot currently be specified explicitly in binary package control
> > +files.
>
> The last paragraph here is a bit confusing. I think the text should
> reiterate that "no" is the implicit default.
Agreed Adding:
Instead, the field needs to be absent to imply its default value and
`debhelper` discards it when transforming a source package control
template.
> > +
> > +``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
>
> This could also say:
> +A binary package may be marked ``Multi-Arch: foreign`` if the provided
> ...
> with no loss of meaning.
Agreed.
> > +- 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
>
> s/there is/this/
This was rephrased several times. Thanks for spotting.
> > +- 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.
>
> How about:
> Usually, an executable does
> not expose linked shared libraries as its interface, and thus they
> should not be considered contributing to the package interface.
I see how this sounds nicer, but I also think it subtly changes meaning
an no longer fully conveys what I meant to say here.
A shared library typically has two levels of interfacing. One is the ABI
and this is the one not being exposed when linking it from an
executable. The other is library functions behaving in
architecture-dependent ways and this level may still be exposed. In
attempting to reword this, I arrive at a somewhat different paragraph:
- The dependencies of a package: A package may expose functionality of
other packages by depending on them. The ABI of a shared library
linked into an executable does not contribute to the interface, but
the behavior of library functions used may do so. Development packages
for shared libraries necessarily expose their own dependencies as
their interface since they enable others to link such libraries. An
extreme example is transitional packages, whose main purpose is to
expose the functionality of their dependency.
I hope you can all agree with this and we'll iterate otherwise.
>
> > + 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.
>
> + their own dependencies as the package interface.
Point taken and hopefully adressed in rewording.
> > +In such cases, where the package satisfies the criterion for
> > +``Multi-Arch: foreign`` but might expose architecture dependency,
>
>
> +``Multi-Arch: foreign`` but might expose an architecture-specific
> dependency,
> ?
Yes, thanks.
> > +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``.
>
> I assume this implies: "in the source package"
Kinda yes. Your remark raises the question of whether it should be
installed into a binary package and I have no answer to that. We have a
total of one packae that contains a README.multiarch, so our sample is
not huge.
I have deviated myself from this and used the Description field instead
in a number of occasions. For instance, gcc-for-host says:
When using gcc via this metapackage, all tools must be used with an
architecture prefix.
It's a slippery slope and I'm not sure how to best address this. Ideas
welcome. Left unchanged for now.
> > +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.
>
> +support the following properties:
Ok.
> > +
> > +- 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``.
>
> Two thoughts:
>
> 1) is DPKG_MAINTSCRIPT_PACKAGE_REFCOUNT documented in policy? Immediate
> question: is it 0- or 1-based, and is it in-/decremented before or after the
> maintscripts run?
It's explained in man 1 dpkg. As far as I understand it, the package
being maintained is always accounted for, so you never observe it as 0.
I don't think this belongs into policy.
> 2) should something be said about arch-specific changelog files?
I argue that this is not worth mentioning, because it tends to just
work. It's not something we need to draw attention to. The policy doesn'
tell much about binNMUs beyond the versioning scheme.
> > +A package annotated this way behaves as if it were annotated with the
>
> s/annotated/marked/ for consistency?
Yes, thanks.
> > +``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``
> an (?)
>
Yes, thanks.
Updated patch attached.
Helmut
diff --git a/policy/ch-controlfields.rst b/policy/ch-controlfields.rst
index 3151816..0e7d489 100644
--- a/policy/ch-controlfields.rst
+++ b/policy/ch-controlfields.rst
@@ -1307,6 +1307,154 @@ 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. Instead, the field needs to be absent to imply its default value
+and `debhelper` discards it when transforming a source package control
+template.
+
+``Multi-Arch: foreign``
+^^^^^^^^^^^^^^^^^^^^^^^
+
+A binary package may be marked ``Multi-Arch: foreign`` 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, this 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. The ABI of a shared library
+ linked into an executable does not contribute to the interface, but
+ the behavior of library functions used may do so. Development packages
+ for shared libraries necessarily expose their own dependencies as
+ their interface since they enable others to link such libraries. An
+ extreme example is transitional packages, whose main purpose is to
+ expose the functionality of their dependency.
+
+- 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-specific 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 the following 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 marked 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 an ``: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 +1591,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.
