Hi! On Thu, 2025-01-16 at 13:26:39 -0500, Chris Knadle wrote: > Looking at the manpage for dpkg-architecture, the variable I may want to > conditionally build upon might be DEB_TARGET_ARCH rather than DEB_HOST_ARCH.
Others have already given pointers about this confusion. I'm more interested in trying to see whether we can improve the man page to avoid it. I think if you search for stuff and end up in the VARIABLES section, from there it's hard to notice the TERMS one, but in the past it seemed excessive to me to either repeat the same or back-reference the TERMS section on each variable definition. Perhaps a middle ground would be adding a reference in the DEB_BUILD_ARCH and DEB_TARGET_ARCH, like in the attached patch? Do you think that would have helped? (I've gone over those two sections to try to further clarify and update things I noticed, although I think the «Debian architecture» one could do with some major update.) Thanks, Guillem
diff --git i/man/dpkg-architecture.pod w/man/dpkg-architecture.pod index ae26b6d5c..a74716fd7 100644 --- i/man/dpkg-architecture.pod +++ w/man/dpkg-architecture.pod @@ -185,27 +185,30 @@ The machine the package is built for. =item target machine The machine the compiler is building for, or the emulator will run code for. This is only needed when building a cross-toolchain (or emulator), one that will be built on the build architecture, to be run on the host architecture, -and to build (or run emulated) code for the target architecture. +and that itself will build (or run emulated) code for the target architecture. =item Debian architecture -The Debian architecture string, which specifies the binary tree in the -FTP archive. +The Debian architecture string, +used in binary packages, +which specifies the binary tree in a package repository. + Examples: i386, sparc, hurd-i386. =item Debian architecture tuple A Debian architecture tuple is the fully qualified architecture with all its components spelled out. This differs with Debian architectures in that at least the I<cpu> component does not embed the I<abi>. The current tuple has the form I<abi>-I<libc>-I<os>-I<cpu>. + 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. @@ -227,22 +230,30 @@ the following pairs are equivalent: Examples: linux-any, any-i386, hurd-any, eabi-any-any-arm, musl-any-any. =item GNU system type An architecture specification string consisting of two parts separated by -a hyphen: cpu and system. +a hyphen: CPU and system. + +The CPU part never contains a hyphen, +while the system part might itself contain a hyphen to separate a kernel +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. =item multiarch triplet The clarified GNU system type, used for filesystem paths. This triplet does not change even when the baseline ISA gets bumped, so that the resulting paths are stable over time. The only current difference with the GNU system type is that the CPU part for i386 based systems is always i386. + Examples: i386-linux-gnu, x86_64-linux-gnu. Example paths: /lib/powerpc64le-linux-gnu/, /usr/lib/i386-kfreebsd-gnu/. =back =head1 VARIABLES @@ -254,12 +265,16 @@ section for a description of the naming scheme): =over =item B<DEB_BUILD_ARCH> The Debian architecture of the build machine. +B<Note>: If you are not building tools that need to run during the build, +these are probably not the variables you are looking for. +Please see L</TERMS> section for the meanings of these terms. + =item B<DEB_BUILD_ARCH_ABI> The Debian ABI name of the build machine (since dpkg 1.18.11). =item B<DEB_BUILD_ARCH_LIBC> @@ -344,12 +359,16 @@ The clarified GNU system type of the host machine, used for filesystem paths (since dpkg 1.16.0). =item B<DEB_TARGET_ARCH> The Debian architecture of the target machine (since dpkg 1.17.14). +B<Note>: If you are not building cross-toolchains (or emulators), +these are probably not the variables you are looking for. +Please see L</TERMS> section for the meanings of these terms. + =item B<DEB_TARGET_ARCH_ABI> The Debian ABI name of the target machine (since dpkg 1.18.11). =item B<DEB_TARGET_ARCH_LIBC>
