Re: Bug#759186: debian-policy: please consider adding "nodoc" as a possible value for DEB_BUILD_OPTIONS to policy
Hi!
I quite like the proposal for a "nodoc" option and support in build-profiles
for it... it would also be useful for maintainers to be able to more quickly
build and test their packages without waiting for the several hundred MB of
texlive to be installed yet again. I can imagine it would be appealing for
admins making their own backports or their own package recompiles too.
>> In my view, DEB_BUILD_OPTIONS should just enable or disable certain code
>> paths of the upstream build itself but not influence anything else. So
>> if "nodoc" is set, the build should just not run the steps that create
>> documentation. If there are any *-doc binary packages, then they will
>> probably come out empty but that should be expected. If documentation
>> was part of a main binary package, then that package will now ship less
>> files.
>
> Ah, yes, that's a good point. It's going to be tricky to suppress the
> actual package construction without modifying debian/control, which we
> don't want to do.
At the same time, I would imagine a lot of source packages will fail to
build with a naive implementation of 'nodoc'. For many packages, just
dropping the build-dependencies and then skipping the invocation of the doc-
preparation-system (texlive/doxygen etc) is then going to cascade into a
failure at a later step of the build when (say) dh_installdoc tries to move
the documentation files from either the unpacked source or from debian/tmp/
into debian/$foo-doc/.
Successfully building these packages will require one of:
* the maintainer wrapping successive dh_* calls in a wrapper to check if
nodoc is set -- this is what packages are currently doing, it seems
* the maintainer to use crude hacks like executable package.install files to
cause debhelper to not install files if nodoc is set (ick?)
* support from the build system to skip the problematic parts for the
package. The dh sequencer could, perhaps, not call some parts of the normal
debhelper sequence (dh_install{,docs,examples,man,…}) for -doc packages if
nodoc is used. However, this wouldn't help packages that weren't building
separate foo-doc packages.
* require support from the build system to swallow errors about missing
files in /usr/share/doc if nodoc is set -- for example missing
dh_install{,docs,examples,man,…} could emit warnings and not errors for
missing files.
Getting maintainers to reinvent this wheel in debian/rules for each package
isn't a pleasant prospect. I don't know whether such code as suggested above
would be welcome inside debhelper as I imagine it won't be pretty.
I know policy is not about mandating implementation details, but maintainers
do find the specific examples in §4.9.1 to be useful -- it would be good if
a practical pointer on how nodoc could be implemented by the maintainer were
included as part of this change. At the very least, a warning about what
might need to be done to pull this off would be worthwhile.
At the risk of scope creep on this proposal, is it worth a quick chat with
the debhelper maintainers? Whatever debhelper does or doesn't implement is
going to significantly influence current practice and, in the spirit of
policy documenting practice, it would be good to include the likely
implementers in this discussion. It would seem important to have a feasible
implementation that doesn't require us reverting to a debian/rules listing
out every dh_* command in the sequence and then decorating that with lots of
conditionals.
cheers
Stuart
--
Stuart Prescott http://www.nanonanonano.net/ stuart@nanonanonano.net
Debian Developer http://www.debian.org/ stuart@debian.org
GPG fingerprint 90E2 D2C1 AD14 6A1B 7EBB 891D BBC1 7EBB 1396 F2F7
Reply to: