This is an automated email from the git hooks/post-receive script. guillem pushed a commit to branch main in repository dpkg.
View the commit online: https://git.dpkg.org/cgit/dpkg/dpkg.git/commit/?id=3f87ca4be7cc874cc9c123549bb262c3f0f26416 commit 3f87ca4be7cc874cc9c123549bb262c3f0f26416 Author: Guillem Jover <[email protected]> AuthorDate: Sun Dec 14 20:10:23 2025 +0100 man: Improve architecture documentation Try to unify the terminology used to refer to the various concepts. Add some notes about specific values not applying in some contexts. Describe first what is a Debian architecture, then specify the allowed values and their use. Update some example architectures with names that might be easier to come across as being currently in use. Prompted-by: Helmut Grohne <[email protected]> --- man/deb-buildinfo.pod | 12 +++++++----- man/deb-changes.pod | 8 +++++--- man/deb-control.pod | 18 +++++++++--------- man/deb-src-control.pod | 35 ++++++++++++++++++++--------------- man/dpkg-architecture.pod | 34 ++++++++++++++++++++++++---------- man/dsc.pod | 7 ++++--- 6 files changed, 69 insertions(+), 45 deletions(-) diff --git a/man/deb-buildinfo.pod b/man/deb-buildinfo.pod index fe6e682db..4b26f992c 100644 --- a/man/deb-buildinfo.pod +++ b/man/deb-buildinfo.pod @@ -99,14 +99,16 @@ If the build is source-only, then the field is omitted (since dpkg 1.20.0). =item B<Architecture:> I<arch-list> (required) -This space-separated field lists the architectures of the files currently -being built. +The architecture list specifies on which type of machine this package runs. +The value should be a list of architecture names separated by spaces. + Common architectures are B<amd64>, B<armel>, B<i386>, etc. -Note that the B<all> value is meant for packages that are architecture -independent. +Note that the special B<all> value is meant for packages that are +architecture independent (such as shell and Perl scripts or documentation). If the source for the package is also being built, the special entry B<source> is also present. -Architecture wildcards must never be present in the list. + +B<Note:> Architecture wildcards are not allowed in this context. =item B<Version:> I<version-string> (required) diff --git a/man/deb-changes.pod b/man/deb-changes.pod index 335a8ffe9..ab552ad48 100644 --- a/man/deb-changes.pod +++ b/man/deb-changes.pod @@ -88,12 +88,14 @@ If the upload is source-only, then the field is omitted (since dpkg 1.19.3). =item B<Architecture:> I<arch-list> Lists the architectures of the files currently being uploaded. + Common architectures are B<amd64>, B<armel>, B<i386>, etc. -Note that the B<all> value is meant for packages that are architecture -independent. +Note that the special B<all> value is meant for packages that are +architecture independent (such as shell and Perl scripts or documentation). If the source for the package is also being uploaded, the special entry B<source> is also present. -Architecture wildcards must never be present in the list. + +B<Note:> Architecture wildcards are not allowed in this context. =item B<Version:> I<version-string> (required) diff --git a/man/deb-control.pod b/man/deb-control.pod index 8e48d2094..8416f04f2 100644 --- a/man/deb-control.pod +++ b/man/deb-control.pod @@ -147,19 +147,19 @@ This field is usually only needed when the answer is B<yes>, and is commonly injected by the archive software. It denotes a package that is required when building other packages. -=item B<Architecture:> I<arch>|B<all> (required) +=item B<Architecture:> B<all>|I<arch> (required) -The architecture specifies which type of hardware this package was compiled -for. -An architecture name must start with an alphanumeric character (“0-9a-zA-Z”), -and then gets followed by alphanumeric and dash (‘-’) characters. +The architecture specifies on which type of machine this package runs. Common architectures are B<amd64>, B<armel>, B<i386>, B<powerpc>, etc. -Note that the -B<all> -value is meant for packages that are architecture independent. -Some examples of this are shell and Perl scripts, and documentation. +Note that the special B<all> value is meant for packages that are +architecture independent (such as shell and Perl scripts or documentation). + +B<Note:> Architecture wildcards are not allowed in this context. + +An architecture name must start with an alphanumeric character (“0-9a-zA-Z”), +and then gets followed by alphanumeric and dash (‘-’) characters. =item B<Origin:> I<name> diff --git a/man/deb-src-control.pod b/man/deb-src-control.pod index a6ff52ca5..431659c0b 100644 --- a/man/deb-src-control.pod +++ b/man/deb-src-control.pod @@ -381,23 +381,28 @@ B<udeb> is for size-constrained packages used by the debian installer. B<deb> is the default value, it is assumed if the field is absent. More types might be added in the future. -=item B<Architecture:> I<arch>|B<all>|B<any> (required) +=item B<Architecture:> I<arch-list> (required) -The architecture specifies on which type of hardware this package runs. -For -packages that run on all architectures, use the -B<any> -value. -For packages that are architecture independent, such as shell and Perl -scripts or documentation, use the -B<all> -value. -To restrict the packages to a certain set of architectures, specify the -architecture names, separated by a space. -An architecture name must start with an alphanumeric character (“0-9a-zA-Z”), +The architecture list specifies on which type of machine this package runs. +The value should be a list of architecture names and/or wildcards +separated by spaces. + +The special B<all> value, by itself, is meant for packages that are +architecture independent (such as shell and Perl scripts or documentation), +the special B<any> wildcard value, by itself, is meant for packages that are +architecture dependent but run on all architectures +(which matches on all specific architecture names, excluding B<all>). +Most packages will use either B<all> or B<any>. +To restrict the packages to a certain set of architectures, +specify one or more architecture names and/or architecture wildcards, +separated by spaces. + +An architecture name or wildcard must start with +an alphanumeric character (“0-9a-zA-Z”), and then gets followed by alphanumeric and dash (”-”) characters. -It's also possible to put architecture wildcards in that list -(see L<dpkg-architecture(1)> for more information about them). + +For more information about architecture names and wildcards, +see L<dpkg-architecture(1)>. =item B<Build-Profiles:> I<restriction-formula> diff --git a/man/dpkg-architecture.pod b/man/dpkg-architecture.pod index 9d37b92ce..7303a1a3d 100644 --- a/man/dpkg-architecture.pod +++ b/man/dpkg-architecture.pod @@ -192,15 +192,27 @@ and that itself will build (or run emulated) code for the target architecture. =item Debian architecture -The Debian architecture string, -used in package relationships, -and in binary package names -(which specifies the binary tree in a package repository). +A Debian architecture describes a “machine” (considering it as an +abstraction not necessarily tied to an actual physical device) +representing a specific execution environment, +including its CPU and attributes (such as endianness and bits), +an operating system (usually a kernel, but other paradigms using userland +services are possible) and its interfaces towards userland including the +executable format and their ABI, +and a libc library and its ABI. + +The special architecture B<all> denotes an architecture independent +execution environment, +used for things such as shell and Perl scripts or documentation. + +A Debian architecture is used in binary package metadata and filenames +(which specifies the binary tree in a package repository), +and can appear in package relationships. An architecture must start with an alphanumeric character (“0-9a-zA-Z”), -and then gets followed by alphanumeric and dash (“-”) characters. +and then gets followed by alphanumeric or dash (“-”) characters. -Examples: i386, sparc, hurd-i386. +Examples: amd64, i386, sparc64, hurd-amd64, musl-linux-riscv64. =item Debian architecture tuple @@ -214,8 +226,10 @@ Examples: base-gnu-linux-amd64, eabihf-musl-linux-arm. =item Debian architecture wildcard -A Debian architecture wildcard is a special architecture string that will -match any real architecture being part of it. +A Debian architecture wildcard is a special architecture that acts as a +pattern and will match any ”machine” architecture being part of it +(except for B<all>). + The general form is a Debian architecture tuple with four or less elements, and with at least one of them being B<any>. Missing elements of the tuple are prefixed implicitly as B<any>, and thus @@ -236,7 +250,7 @@ musl-any-any. =item GNU system type -An architecture specification string consisting of two parts separated by +A GNU architecture specification string consisting of two parts separated by a hyphen: CPU and system. The CPU part never contains a hyphen, @@ -245,7 +259,7 @@ from its general ABI, where the general ABI might contain both runtime (such as libc) and executable ABI specifiers joined without a hyphen. -Examples: i586-linux-gnu, sparc-linux-gnu, i686-gnu, x86_64-netbsd. +Examples: i586-linux-gnu, sparc64-linux-gnu, i686-gnu, x86_64-netbsd. =item multiarch triplet diff --git a/man/dsc.pod b/man/dsc.pod index 535f591ea..1bef02f13 100644 --- a/man/dsc.pod +++ b/man/dsc.pod @@ -85,11 +85,12 @@ architecture, build-profile and other involved restrictions. =item B<Architecture:> I<arch-list> (recommended) -A list of architectures and architecture wildcards separated by spaces -which specify the type of hardware this package can be compiled for. +The architecture list specifies on which type of machine this package runs. +The value should be a list of architecture names and/or wildcards +separated by spaces. + Common architecture names and architecture wildcards are B<amd64>, B<armel>, B<i386>, B<linux-any>, B<any-amd64>, etc. - Note that the B<all> value is meant for packages that are architecture independent, and B<any> for packages that are architecture dependent. The list may include (or consist solely of) the special value B<all>. -- Dpkg.Org's dpkg
