Perl distributions from the Comprehensive Perl Archive Network (CPAN) may fail to build for a variety of reasons. Inspect the output, and run the tests in verbose mode. The CPAN module configuration or network problems may prevent modules from being downloaded. See Life with CPAN for more information.
Compiling Perl modules requires make and other development utilities. Ensure these are installed on the build system. Installation of these tools will vary by operating system, either requiring ports or packages to be installed (apt-get install build-essential on Debian Linux), or a development kit from the vendor.
Knowledge of how to build and debug software on Unix is required. Consult the vendor supplied developer documentation, if any, along with the README file provided with the module.
If the install has previously failed, CPAN may cache this result. In the cpan shell, run clean Module::Name, or otherwise cleanup the ~/.cpan/build directory to start over, especially if the build logs need to be saved with script(1) or tee(1) for easier inspection:
$ rm -rf ~/.cpan/build
$ cpan XML::LibXSLT 2>&1 | tee build.log
…
If a bug is found, contact the module author with a patch or bug report. Include as much relevant detail as possible, such as the output from perl -V, the operating system, and so forth.
Getting Help
If the error message is beyond your abilities, request help only with the appropriate build logs. The complete build logs from a clean build are required for others to help with the build problem. Use script(1) to record the build session (or copy and paste the complete logs) and be sure to edit out any passwords or other site-specific details from the build log. However, include as much data as possible.
To restart from scratch, remove the CPAN build directory. This will either be set in the user-specific ~/.cpan/CPAN/MyConfig.pm file, or the CPAN/Config.pm file somewhere under @INC for root:
$ grep build_dir ~/.cpan/CPAN/MyConfig.pm
'build_dir' => q[/home/user/.cpan/build],
$ perl -MCPAN::Config -le 'print $INC{"CPAN/Config.pm"}' \
| xargs grep build_dir
'build_dir' => q[/var/root/.cpan/build],
Then rebuild the module, saving the complete build logs.
Missing Libraries
Perl modules that rely on C libraries may issue misleading errors if the required library and header files are not installed, or if an incompatible version of the library is installed. “Probably harmless” missing library warnings are usually not harmless at all, for example when installing XML::LibXML::Common. For the missing -lxml2 warning to be satisfied, a file such as libxml2.* must first be installed on the system. Library files may use *.a, *.so, or *.dylib extensions, depending on the platform. Either build the source manually for Libxml2, or install it from a vendor supplied port or package system.
Note (probably harmless): No library found for -lxml2
Another common error will be for missing header files (e.g. expat.h) which again points to missing development libraries (e.g. libexpat). Libraries installed to custom locations, such as under a special software ports tree, may require setting LD_LIBRARY_PATH and other environment variables to properly locate the library and header files.
Verbose Testing
Verbose testing may provide more detail on why a make test run fails. This can be done with the look command under the CPAN shell plus the subsequent Unix shell commands shown below. Be sure to inspect the test scripts under the t directory to compare the error message with the code that generated the message.
cpan> install HTML::Mason
Running install for module HTML::Mason
Running make for D/DR/DROLSKY/HTML-Mason-1.23.tar.gz
…
t/02a-filter..........ok
t/04-misc.............FAILED tests 9-10
Failed 2/11 tests, 81.82% okay
t/05-request..........ok
…
Failed Test Stat Wstat Total Fail Failed List of Failed
---------------------------------------------------------------------------
t/04-misc.t 11 2 18.18% 9-10
2 tests skipped.
Failed 1/23 test scripts, 95.65% okay. 2/376 subtests failed, 99.47% okay.
*** Error code 35
Stop in /var/spool/cpan/build/HTML-Mason-1.23.
/usr/bin/make test -- NOT OK
Running make install
make test had returned bad status, won't install without force
cpan>
cpan> look HTML::Mason
Running look for module HTML::Mason
Trying to open a subshell in the build directory...
Working directory is /var/spool/cpan/build/HTML-Mason-1.23
# make test TEST_VERBOSE=1 TEST_FILE=t/04-misc.t | tee test.log
…
Consider also installing Test::Harness, as this includes the prove command:
$ make
…
$ prove -b -v t/04-misc.t | tee test.log
Interactive Modules
Poorly written modules may attempt to prompt the user for input during the build or testing process. This introduces a fragile captive user interface that may be difficult or impossible to automate. The ExtUtils::MakeMaker supplied prompt subroutine may be disabled by closing standard input, or setting the PERL_MM_USE_DEFAULT=1 environment variable. Then inspect the test scripts to see what environment variables they expect. For example, WWW::Curl 3.02 will hang while building on Mac OS X (as of version 10.4.9) unless the following environment variables are set:
$ env PERL_MM_USE_DEFAULT=1 \
CURL_TEST_URL=http://example.org/ \
make test
Process Tracing Method
The cause of the hang can be determined using a process tracing utility, such as ktrace(1). Unix Debugging Tips contains more information on debugging systems with ktrace or strace.
$ perl Makefile.PL
Found curl.h in /usr/include/curl/curl.h
Building curlopt-constants.c for your libcurl version
Building Easy.pm constants for your libcurl version
Checking if your kit is complete...
Looks good
Writing Makefile for WWW::Curl
$ make
…
$ ktrace -di make test
PERL_DL_NONLAZY=1 /usr/bin/perl "-MExtUtils::Command::MM" "-e" ↵
"test_harness(0, 'blib/lib', 'blib/arch')" t/*.t
t/00constants.............ok
t/01basic.................
On Mac OS X, use the kdump(1) utility to inspect the ktrace.out file for the hung process shown above:
$ kdump -f ktrace.out | tail
1804 perl RET write 34/0x22
1800 perl GIO fd 15 read 34 bytes
"# Please enter an URL to fetch [] "
1800 perl RET read 34/0x22
1800 perl CALL read(0xf,0x185ce00,0x1000)
1804 perl CALL fstat(0,0xbfffc1a8)
1804 perl RET fstat 0
1804 perl CALL ioctl(0,0x4004667a ,0xbfffc128)
1804 perl RET ioctl 0
1804 perl CALL read(0,0x37000,0x20000)
This indicates the script wants a URL, but for some reason the fragile prompt is broken. Inspecting the t/01basic.t script reveals the CURL_TEST_URL environment variable should be set.
Bypass tests with force install
Errors during the make test phase can be skipped using force install under the CPAN shell. This should only be done if the module is being installed for testing, or if the tests are known to not work, and the module is therefore safe for production use. Note that force install only forces the module, not any of the module dependencies. If the dependencies have any problems, investigate and fix those before attempting to install the module.
cpan> force install HTML::Mason
If you force install broken code to a production system, shame on you! Development systems can suffer the dangers of random module installs. Test and production systems should instead use a local package or software depot that contains the tested, working version of the module. This localized software can then be reproduced as needed onto new production systems. Code from CPAN may not be reproducible, as the author could upload a new, incompatible module version, or delete the entire module without warning (though old versions of the module may be available on backpan).
To avoid installing modules into system areas, consult using CPAN with a non-root account.
Fixing Bugs
If possible, fix the bug. Test scripts could need tweaks, or support for an environment variable that toggles tests that could easily fail. Consider git-cpan-init, which offers a quick means to download CPAN modules into git repositories, and equally easy means to submit tickets to CPAN RT.
