Bug#759405: perl: make pod2man timestamps reproducible

[Dominic Hargreaves]

On Tue, Aug 26, 2014 at 06:07:00PM -0700, Niko Tyni wrote:
> Manual pages generated with Pod::Man have a date header based on the
> timestamp of the source file, or the current time when reading STDIN.
> For the benefit of reproducible builds [1], it would be nice if this
> date did not vary across rebuilds.
> 
> I doubt any normal build system feeds STDIN to Pod::Man, but another
> case where the current time is used is when there are Debian patches to
> the source file. Quoting the dpkg-source(1) manual page:
> 
>   The timestamp of all patched files is reset to the extraction time of
>   the source package (this avoids timestamp skews  leading  to  problems
>   when  autogenerated  files  are patched)
> 
> I've filed #759404 against dpkg-dev about changing this, but in the
> meantime it would be nice to fix/work around this somehow. The best thing
> I've come up with is an environment variable (maybe POD2MAN_DATE?) that
> would override the date; changing build systems to pass the '--date'
> option to pod2man or its equivalents would be much more intrusive.

I'm not sure that is sufficient in all cases, since mtimes are typically
updated by VCSs like git. Or are you thinking of that as a separate
problem for reproducible builds?

> AFAICS this could be done by changing Pod::Man::devise_date() to fall
> back to this variable if it is set. Changing /usr/bin/pod2man isn't
> enough: at least ExtUtils::MakeMaker build systems use their own pod2man
> implementation in ExtUtils::Command::MM, and so does the perl build
> itself in the 'installman' script.
> 
> I'm not sure who should export this environment variable, but debhelper
> springs to mind. It should probably be done for all build systems rather
> than just for the perl ones, as there may well be non-perl packages in
> the archive that use POD for documentation.

The plan seems reasonable.

Cheers,
Dominic.