Bug#727610: debian-policy: clearer discussion of why build-indep implies building the whole package

[Ximin Luo <infinity0@gmx.com>]

Package: debian-policy
Severity: normal

I was recently told to split part of my Build-Depends field into a separate Build-Depends-Indep field. Not one to follow orders without question, I went and did some research, and found this snippet in the policy[1]:

"There is no Build-Depends-Arch; this role is essentially met with Build-Depends. Anyone building the build-indep and binary-indep targets is assumed to be building the whole package, and therefore installation of all build dependencies is required.

The assumption confused me at first. For example, one natural distributed build process might be (A):

1. build-indep on a single machine
2. copy the half-built tree to all machines
3. build-arch on all machines

In this case, then clearly it is advantageous to have a separate Build-Depends-Arch. For example, if I am only building docs in (1), I would not want to install all of the -dev dependencies at that stage.

However, thinking about it a bit more, leads me to deduce that the actual build process is something like (B):

1. build (-indep and -arch) on a single machine (perhaps the developer's?)
2. build-arch on all other machines of a different arch

The assumption then makes sense in this context, but for a person not familiar with Debian's build infrastructure, it takes quite some effort to work out.

So, the reason why I originally thought (A) is because I was confused and thought that "build-arch" was simply "do build tasks that are arch-dependent" and the counterpart for "build-indep". Of course, I now realise that this interpretation doesn't make sense because arch-indep vs arch-dep tasks might overlap in the order they need to be run in. So (A) is actually not coherent, but again it takes some effort to work this out.

The more precise definition of "build-arch" from [2] says "The build-arch target must perform all the configuration and compilation required for producing all architecture-dependant binary packages".

If other people are making the similar mistake, it would be useful to add a discussion/debunking of that more "intuitive" interpretation to try to prevent this.

[1] http://www.debian.org/doc/debian-policy/footnotes.html#f55
[2] http://www.debian.org/doc/debian-policy/ch-source.html

-- System Information:
Debian Release: jessie/sid
  APT prefers testing
  APT policy: (990, 'testing'), (500, 'unstable'), (500, 'stable'), (1, 'experimental')
Architecture: amd64 (x86_64)
Foreign Architectures: i386

Kernel: Linux 3.9-1-amd64 (SMP w/4 CPU cores)
Locale: LANG=en_GB.UTF-8, LC_CTYPE=en_GB.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash