Groups | Search | Server Info | Login | Register

Groups > linux.debian.bugs.dist > #1288174

Bug#879049: debian-policy: Clarify how nodoc is to be used with DEB_BUILD_OPTIONS & DEB_BUILD_PROFILES

Cross-posted to 2 groups.

Show all headers | View raw

On Wed, 01 Apr 2026 at 23:58:18 +0200, Santiago Vila wrote:
>Several months ago I made the experiment of building the archive with
>the nodoc build profile, with the intention of reporting bugs (with
>whatever severity would be appropriate).
>
>The problem: I found more than 950 packages which FTBFS with
>nodoc profile. For the curious:
>
>https://people.debian.org/~sanvila/build-logs/nodoc-20251010/

That's more than I would have expected, but doesn't entirely surprise 
me either.

One common failure mode is annotating a B-D with <!nodoc> but actually 
it's necessary for all builds, because even though it's only used when 
building documentation, the upstream build system checks for it 
unconditionally (<!nocheck> often has the same problem).

Another is annotating a B-D with <!nodoc>, but enabling the option that 
requires it (--enable-doc or -Ddoc=enabled or similar) whenever building 
Architecture: all - especially if the source package's only 
Architecture: all binaries *are* documentation (a fairly common pattern, 
especially for libraries, seen in src:libsdl3 for example).

 From an arbitrary sample of those logs, it seems like another recurring 
problem is that the build does something programmatically to 
documentation or examples (chmod or sed), but installation of those 
files has been suppressed (either by debhelper or by the upstream build 
system), and so it fails - usually easily fixed with some conditionals 
in debian/rules, but that won't happen and continue to work unless 
something is routinely testing that code path.

Salsa-CI pipelines have an option to exercise build-profile builds, and 
maintainers who are interested in making sure a package does support 
nodoc correctly should probably enable that option, but that quickly 
results in a *lot* of builds if you also want to exercise nocheck, 
noinsttest, etc., so it doesn't necessarily scale to the whole archive.

>Now I wonder if this nodoc profile is something that every package is
>supposed to support, or maybe it would make sense to have some opt-out
>or opt-in mechanism

One of the failing logs is for docbook-xsl-doc, and I think it certainly 
doesn't make sense to expect packages containing only documentation to 
support this build-profile, except possibly in a trivial sense where 
every binary package has Build-Profiles: <!nodoc> and therefore the 
build stops early with "nothing to do".

I think the most important targets for all build profiles (and 
cross-compiling, and many other nice things) are the packages that are
in the critical path for architecture bootstrapping, or for 
bootstrapping a particular desktop, language or other stack ecosystem: 
it's those that are most likely to need compiling with minimal 
dependencies. For arbitrary leaf packages it's a lot less interesting.

     smcv

Back to linux.debian.bugs.dist | Previous | Next — Previous in thread | Next in thread | Find similar

Thread

Bug#879049: debian-policy: Clarify how nodoc is to be used with DEB_BUILD_OPTIONS & DEB_BUILD_PROFILES Jeremy Bícha <jbicha@debian.org> - 2026-04-01 23:00 +0200
  Bug#879049: debian-policy: Clarify how nodoc is to be used with DEB_BUILD_OPTIONS & DEB_BUILD_PROFILES Santiago Vila <sanvila@debian.org> - 2026-04-02 00:10 +0200
    Bug#879049: debian-policy: Clarify how nodoc is to be used with DEB_BUILD_OPTIONS & DEB_BUILD_PROFILES Simon McVittie <smcv@debian.org> - 2026-04-02 10:50 +0200
    Bug#879049: debian-policy: Clarify how nodoc is to be used with DEB_BUILD_OPTIONS & DEB_BUILD_PROFILES Bill Allombert <ballombe@debian.org> - 2026-04-02 11:00 +0200

csiph-web