Helmut Grohne <[email protected]> [24/Mar 2:12pm +01] wrote: > 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.
Seconded. Thanks Helmut. (You changed my "i.e." to an "e.g." which isn't right but that's an editorial change I can make when committing.) -- Sean Whitton
signature.asc
Description: PGP signature
