DocKnot 3.01

The last release of DocKnot failed a whole bunch of CPAN tests that didn't fail locally or on Travis-CI, so this release cleans that up and adds a few minor things to the dist command (following my conventions to run cppcheck and Valgrind tests). The test failures are moderately interesting corners of Perl module development that I hadn't thought about, so seem worth blogging about.

First, the more prosaic one: as part of the tests of docknot dist, the test suite creates a new Git repository because the release process involves git archive and needs a repository to work from. I forgot to use git config to set user.email and user.name, so that broke on systems without Git global configuration. (This would have been caught by the Debian package testing, but sadly I forgot to add git to the build dependencies, so that test was being skipped.) I always get bitten by this each time I write a test suite that uses Git; someday I'll remember the first time.

Second, the build system runs perl Build.PL to build a tiny test package using Module::Build, and it was using system Perl. Slaven Rezic pointed out that this fails if Module::Build isn't installed system-wide or if system Perl doesn't work for whatever reason. Using system Perl is correct for normal operation of docknot dist, but the test suite should use the same Perl version used to run the test suite. I added a new module constructor argument for this, and the test suite now passes in $^X for that argument.

Finally, there was a more obscure problem on Windows: the contents of generated and expected test files didn't match because the generated file content was supposedly just the file name. I think I fixed this, although I don't have Windows on which to test. The root of the problem is another mistake I've made before with Perl: File::Temp->new() does not return a file name, but it returns an object that magically stringifies to the file name, so you can use it that way in many situations and it appears to magically work. However, on Windows, it was not working the way that it was on my Debian system. The solution was to explicitly call the filename method to get the actual file name and use it consistently everywhere; hopefully tests will now pass on Windows.

You can get the latest version from CPAN or from the DocKnot distribution page. A Debian package is also available from my personal archive. I'll probably upload DocKnot to Debian proper during this release cycle, since it's gotten somewhat more mature, although I'd like to make some backward-incompatible changes and improve the documentation first.