On Sat, Mar 29, 2025 at 12:35:45PM +0100, Helmut Grohne wrote: > 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.
quite obviously I happily second this myself. (and am ready to second further
improved versions as well. :)
thanks to everyone involved! I've been waiting for having this documented in
-policy for years, so I'm delighted to see huge progress here!
--
cheers,
Holger
⢀⣴⠾⠻⢶⣦⠀
⣾⠁⢠⠒⠀⣿⡁ holger@(debian|reproducible-builds|layer-acht).org
⢿⡄⠘⠷⠚⠋⠀ OpenPGP: B8BF54137B09D35CF026FE9D 091AB856069AAA1C
⠈⠳⣄
Society: Be Yourself!
Society: No, not like that.
signature.asc
Description: PGP signature
