A Practical Perl Utility Bench: Documentation, Tests and Checksums

You will use the Perl utilities already installed on Linux to answer four everyday questions: where is the documentation, was a module shipped with this Perl, did a test suite pass, and has a file changed? The examples use Perl 5.38.2 from Ubuntu's perl-doc package. Allow 15 minutes for the first pass, plus time to inspect any project-specific test output.

The perlutil manual is a catalogue rather than a single command. It lists tools for documentation, conversion, administration, development, testing and general file work. Start with the commands you actually need, then use each tool's own manual for its complete option set.

1. Confirm the installation

Check the interpreter and the documentation package before troubleshooting a missing command. These commands only read local package metadata and do not need elevated privileges.

$ perl -v
$ dpkg-query -W -f='${Package} ${Version}\n' perl perl-doc
$ command -v perldoc corelist prove shasum json_pp podchecker

On the system used for this guide, the relevant versions are perl 5.38.2-3.2ubuntu0.6 and perl-doc 5.38.2-3.2ubuntu0.6. Paths can differ on another distribution. If perldoc or a listed utility is absent, install the distribution's documentation or Perl utility package through its normal package manager. Do not copy Ubuntu package names to another distribution.

2. Find and read Perl documentation

perldoc is the main interface to Perl's documentation. Give it a page or module name. The terminal formatter normally opens the result in a pager, so press q when you have finished reading.

$ perldoc perlutil
$ perldoc File::Temp
$ perldoc -l perlutil
/usr/share/perl/5.38/pod/perlutil.pod

The -l form prints the source path instead of formatting the page. That is useful when you need to confirm which installed documentation is being read. It does not mean the path is a stable interface for scripts; use the documented command or module interface instead.

To capture plain text for a search or a ticket, use the terminal formatter explicitly:

$ perldoc -T perlutil > /tmp/perlutil.txt
$ rg -n 'corelist|prove|shasum' /tmp/perlutil.txt

The temporary file is disposable. Avoid redirecting documentation into a project file by accident, and remember that a pager can hide the command prompt until you quit it.

3. Check whether a module belongs to core

corelist queries Module::CoreList. It tells you what was shipped with particular Perl releases; it does not tell you whether a module is currently loadable in your shell's selected Perl.

$ corelist JSON::PP
Data for 2023-11-29
-------------------
JSON::PP was first released with perl v5.13.9
$ corelist -v 5.38.2 JSON::PP
JSON::PP 4.16

Output formatting varies with the installed corelist release, so treat the module and release information as the useful part. Verify the interpreter you will actually run as well:

$ perl -MJSON::PP -e 'print JSON::PP->VERSION, "\n"'
4.16

A module can be part of a Perl distribution and still be unavailable because your program uses another Perl, a restricted library path, or a broken installation. Check command -v perl and perl -V before changing PERL5LIB or installing anything.

4. Run a project's tests with prove

prove is the command-line test runner supplied with Test::Harness. Run it from the project directory, where the test files and any local build directories are visible.

$ cd /path/to/project
$ prove -l t
t/basic.t .. ok
All tests successful.
Files=1, Tests=3,  0 wallclock secs
Result: PASS

The exact summary depends on the project. The reliable signal for a script is the exit status:

$ prove -l t
$ test "$?" -eq 0 && echo 'tests passed'
tests passed

-l adds the project's lib directory to the module search path. Use it when the tests exercise code in a checkout rather than an installed module. Do not add sudo: tests should normally run as your user, and root-owned test artefacts can create the next failure.

Failure checkpoint: a non-zero status is a test or setup result, not a request to rerun as root. Read the first failing test, confirm the Perl version, and inspect the project's README for dependencies. If a test created temporary state, remove only the paths documented by that project.

5. Verify a file with shasum

shasum, shipped with Digest::SHA, can print a digest or verify a checksum file. Verification is read-only and is safer than comparing a long hash by eye.

$ shasum -a 256 download.tar.gz
3f5c...  download.tar.gz
$ shasum -a 256 download.tar.gz > download.tar.gz.sha256
$ shasum -a 256 --check download.tar.gz.sha256
download.tar.gz: OK

The first digest above is illustrative, not an expected value. When a vendor publishes a trusted SHA-256 value, compare your output with that value or save the vendor's exact checksum line. A checksum proves that two inputs produce the same digest; it does not prove that the download came from a trustworthy source. Obtain the reference over an authenticated channel.

6. Format small JSON and inspect POD

Two other utilities from the same catalogue are useful for quick checks. json_pp formats JSON without requiring a separate JSON implementation, while podchecker reports errors in Perl's documentation markup.

$ printf '%s\n' '{"name":"Ada","active":true}' | json_pp
{
   "active" : true,
   "name" : "Ada"
}
$ podchecker lib/My/Module.pm
lib/My/Module.pm pod syntax OK.

These commands inspect or transform their input; they do not edit the source file in place. Redirect output to a new temporary or review file if you need to keep it. Be careful with a redirection target: > truncates an existing file before the command starts.