When an install goes wrong

Symptoms first, since that is what you have when you arrive here.

“Can’t locate Foo/Bar.pm” after a successful install

The install said it worked, and the module is not there. Two causes.

You have not set PPERL5LIB. An install does not put itself on the search path. Check that the tree is where you think it is:

ls ~/.pperl/lib/perl5
export PPERL5LIB="$HOME/.pperl/lib/perl5"

The module went into an architecture directory. This is the subtle one. ExtUtils::MakeMaker sends everything from a distribution that declares XS into lib/perl5/<archname>/, even when what it actually installs is pure Perl. pperl searches no architecture directory, so the module lands somewhere pperl will never look.

WWW::Form::UrlEncoded installed “successfully” this way, and then Plack::Request->parameters died with Can't locate WWW/Form/UrlEncoded.pm.

pperl --cpan prevents this: it pins INSTALLARCHLIB, INSTALLSITEARCH and INSTALLVENDORARCH to the plain lib tree for both toolchains, so nothing can be installed into an architecture directory. If you are driving an installer yourself, you need to do the same, or check afterwards:

find ~/.pperl/lib/perl5 -maxdepth 1 -type d

Anything other than package directories is a sign the pinning did not happen.

The installer wants to build a module pperl already has

Confirm what pperl thinks it provides, and at which version:

pperl -MConfig -MExtUtils::MakeMaker -e \
  'my $f = Config::lib_file("Storable.pm"); print "$f ", MM->parse_version($f), "\n"'
# ./pperl-native/Storable.pm 3.41

If the path starts with ./pperl-native/ the module is built in. If the installer still wants it, compare the versions: the dependency may genuinely be newer than the version pperl carries, in which case no arrangement will satisfy it.

An installer that is not pperl’s own, run under pperl, looks for modules with file tests and does not see the built-in ones. Use pperl --cpan.

“dynamic loading not available in this perl”

XS. Read the no-XS rule to work out which shape the distribution is, because shapes 2 and 3 there have a way forward and shapes 4 and 5 do not.

The message appearing at runtime rather than install time is usually good news: it means the module caught it and is choosing its Perl implementation.

The install hangs waiting for input

It should not - under --cpan, PERL_MM_USE_DEFAULT and NONINTERACTIVE_TESTING are both set, so distributions take their own defaults. If you are driving an installer yourself, set both.

Tests fail but the module is fine

-T goes straight through to the CPAN client and skips the tests:

pperl --cpan -T Some::Module

Worth doing once to find out whether the module or its test suite is the problem. A test suite that itself depends on XS will fail against a perfectly good pure-Perl module.

Starting over

The tree is disposable. Nothing else refers to it:

rm -rf ~/.pperl
pperl --cpan Your::Module

Reporting

If a pure-Perl distribution fails to install, or installs and then cannot be loaded, that is a pperl bug and worth filing:

petamem/pperl-bugtracker#issues

Include the distribution name and version, the full --cpan output, and pperl -e 'print "$_\n" for @INC'.