Hi Sean,
On Wed, Feb 25, 2026 at 09:20:09PM +0000, Sean Whitton wrote:
> Thanks for the updated patch. I have just three remaining changes I'd
> like to ask you to make:
Thank you for your continued effor on this and sorry for my delay.
> Helmut Grohne [09/Jul 7:14pm +02] wrote:
> >> > +- 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
> >>
> >> s/multiple/different/
> >
> > Yes, thanks.
>
> Here you did s/different/multiple/ instead. Can you change both
> 'multiple's to 'different'?
Right. That gets a lot of "differen*". I tried a bit to avoid that e.g.
using "vary", but ultimately feared that I would change meaning too
much.
> >> > In particular, ``postrm`` must consider
> >> > + that another instance may still be present.
> >>
> >> How about:
> >>
> >> In particular, any ``postrm`` script must not assume that all
> >> instances of the package (i.e., instances for other architectures)
> >> are all gone.
> >
> > I don't see what aspect you are improving here and prefer the existing
> > wording, because it is more focused on the key aspect. That said, "may"
> > is not the right term there.
>
> I think that "another instance may still be present" is strange.
> Up to this point in the text we haven't been using "instance" to mean:
> packages of the same name but for different architectures.
> Therefore it feels like the reader has to guess that this is what
> "instance" means here. My suggested wording avoids that problem.
The term is also used in the Multi-Arch: no paragraph, but I agree that
it is not formally defined.
Your explanation makes me agree, but I think "all" should not be
duplicated and I therefore dropped the latter.
> >> > +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.
> >>
> >> Can you avoid "should" here? I don't think you intend to be normative.
> >
> > Unless I misunderstand "should", that particular normative is intended
> > here. I was even considering that usage of allowed must be discussed
> > with d-devel beforehand just like the use of epochs.
>
> There seem to be two possible normative requirements:
> - if the package can be used in an architecture-dependent way or an
> architecture-independent way and it's up to the depender, then you
> should use multi-arch:allowed
This reading is not intended. Technically speaking, any situation that
can be addressed with M-A:allowed can also be addressed without by
introducing more binary packages using other M-A values.
> - you should not use multi-arch:allowed commonly (where common == !rare)
>
> Are you really trying to say both? I think you really want to say:
> - if the package can be used in an arch-dep or arch-indep way and it's
> up to the depender then you *can* use multi-arch:allowed
> - you should not use multi-arch:allowed commonly
>
> i.e. just one should.
You did capture the intention here.
> If you really do mean both shoulds, then I suggest two sentences/clauses
> with "should" appearing twice. But that seems strange because for the
> other field values we don't explicitly say that you *should* use this
> value if it applies to your package. E.g. we don't say "if the
> interfaces the package provides are independent of its architecture you
> *should* use multi-arch:foreign".
I concur and split the sentence leaving should only in the former.
Beyond these, I also found two spelling mistake that made it past these
review rounds.
Helmut
diff --git a/policy/ch-controlfields.rst b/policy/ch-controlfields.rst
--- a/policy/ch-controlfields.rst
+++ b/policy/ch-controlfields.rst
@@ -1307,6 +1307,166 @@ 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 can combine packages from multiple architectures.
+The ``Multi-Arch`` header enables individual packages to declare their
+support for this feature, and influences the way dependencies are
+handled. It can be declared in binary package sections of a source
+package template control file and in binary package control files. The
+permitted header values are ``no`` (default), ``foreign``, ``same`` and
+``allowed``. Their semantics are described in the following sections.
+
+.. _s-f-Multi-Arch-no:
+
+``Multi-Arch: no``
+^^^^^^^^^^^^^^^^^^
+
+This means that a ``Depends``, ``Pre-Depends``, ``Provides``,
+``Recommends`` or ``Suggests`` relation between packages is satisfied
+only by packages of the same architecture. There is no effect on
+``Breaks``, ``Conflicts`` and ``Replaces``. Furthermore, multiple
+instances of a package with the same name but different architectures
+cannot be installed at the same time. Architecture-independent packages
+are treated as though they had the architecture value of the installed
+``dpkg`` package.
+
+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 in order to imply its
+default value and ``debhelper`` discards it when transforming a source
+package control template.
+
+``Multi-Arch: foreign``
+^^^^^^^^^^^^^^^^^^^^^^^
+
+This means that the interfaces the package provides are independent of
+its architecture, and that it therefore satisfies dependencies on a
+package of this name regardless of the architecture of the package
+declaring the dependency. Any virtual packages provided (see
+:ref:`s-virtual`) inherit this property.
+
+There are five main areas that can contribute to the interface of a
+package. If any of them provides an architecture-dependent interface, a
+package must not be marked with ``Multi-Arch: foreign``. Note that
+architecture-independent packages can reasonably provide
+architecture-dependent interfaces and therefore
+architecture-independent packages are not implicitly treated as
+``Multi-Arch: foreign``.
+
+- The installed files of a package: Architecture-dependent packages may
+ install different sets of files or files with different content for
+ different architectures. These differences may contribute to the
+ interface (e.g. an endianness-dependent database file). For
+ architecture-independent binary packages, this aspect does not apply.
+
+- The behavior of package's installed files: packages usually have
+ an expected way of having their files used. They may be executed or
+ interpreted. If the architecture of the package that installed them is
+ exposed in the process of their intended use, their interface is
+ considered architecture-dependent.
+
+ For instance, shared and static libraries are inherently
+ architecture-dependent. They therefore prohibit the use of
+ ``Multi-Arch: foreign`` unless they are not intended to be used by
+ other packages. Whilst binary executables generally differ across
+ architectures, the exposed interface can be independent of the
+ architecture used to execute. Architecture exposure can happen via the
+ command line arguments, the data exchanged or the way they process
+ files. Last but not least, data files can have architecture-dependent
+ structure.
+
+- Maintainer scripts and triggers: A package can behave in an
+ architecture dependent way, when the behavior of maintainer scripts or
+ invoked triggers depends on the architecture. 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 and thereby provide an
+ architecture-dependent interface itself. The ABI of a shared library
+ linked into an executable does not usually 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. Therefore,
+ transitional packages should copy the ``Architecture`` and
+ ``Multi-Arch`` field from their target.
+
+- Implicit and foreign dependencies of a package: Essential packages are
+ implicitly depended upon and need not be included 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, packages must not use other packages in ways declined by
+their ``debian/README.multiarch``.
+
+``Multi-Arch: same``
+^^^^^^^^^^^^^^^^^^^^
+
+This means that other packages with the exact same name and version, but
+different architectures, can be installed concurrently. All those
+packages must be declared ``Multi-Arch: same``.
+
+For a given file name, if the package for one architecture installs a
+file there, then the packages for every other architecture must either
+install no file there, or a bit-identical file. Given this restriction,
+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 not assume that all
+instances of the package (e.g., instances for other architectures) are
+gone. It may check the ``DPKG_MAINTSCRIPT_PACKAGE_REFCOUNT`` environment
+variable set by ``dpkg``.
+
+``Multi-Arch: allowed``
+^^^^^^^^^^^^^^^^^^^^^^^
+
+This means the same as ``Multi-Arch: no`` except that a package
+depending on this package may choose to treat it as though it were
+marked ``Multi-Arch: foreign``. This is done by appending ``:any`` to
+the name of the package in the dependency relation field. For example,
+where foo is ``Multi-Arch: allowed``, bar might have ``Depends: foo:any
+(>= 1.0)``. Then bar's dependency on foo is satisfied even when bar and
+foo have different architectures.
+
+Only a ``Multi-Arch: allowed`` package satisfies a dependency with the
+``:any`` suffix.
+
+This value should be used rarely. It exists 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
+*[email protected]* first.
+
.. _s5.7:
User-defined fields
@@ -1443,3 +1601,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 unique across architectures and
+ cannot be changed without breakig ABI.
