A Practical Perl Toolkit from perlfaq3

You will finish with a repeatable way to move from a Perl programming problem to the right local tool: an interactive debugger, installed-module check, warning-driven diagnosis, profiler or cross-reference report. The examples are based on perlfaq3(1) from Debian's perl-doc package, version 5.38.2-3.2ubuntu0.6, with Perl v5.38.2.

Allow 15 minutes for the first pass. You need a shell and a working Perl installation. Most examples are unprivileged and read or execute only the code you provide. Do not run an unfamiliar script merely because you are investigating it.

1. Start with the local index

perlfaq3 is a map, not a single utility. It points you towards the manpage that owns the detail. Read it locally so its examples match the Perl installation you are using:

$ man perlfaq3
$ perl -v
This is perl 5, version 38, subversion 2 (v5.38.2)

The FAQ groups the next move by task. Use perldebug for the debugger, perlrun for interpreter switches, perlfunc for built-ins, and perlmod or perlmodlib for modules. This prevents a common distraction: trying to solve a language or module problem by searching for a debugger command.

2. Try a disposable interactive session

For a quick experiment, start the debugger with an empty program:

$ perl -de 42
Loading DB routines from perl5db.pl version 1.77
Editor support available.
main::(-e:1):   42
  DB<1>

At the DB<1> prompt, enter legal Perl such as print 2 + 2, "\n";. The debugger evaluates it immediately. Enter q to leave. This session is useful for checking syntax, expressions and data-handling ideas without creating a file.

Do not paste commands containing untrusted shell substitutions into a session you do not understand. The debugger evaluates Perl in the current process context, so treat it as code execution, not as a harmless calculator.

3. Check a module before changing the environment

First ask whether Perl can load a module. This is a read-only check and does not install anything:

$ perl -MExtUtils::Installed -e1
$ perl -MData::Dumper -e1

No output and a zero status mean the load succeeded. To inspect installed distributions, the FAQ suggests cpan -l:

$ cpan -l
DBI   1.643
Clone 0.46

The list can be long, and local CPAN configuration warnings may appear. Do not confuse listing with installation. The cpan -a option creates an autobundle for later reinstallation; it writes a bundle file, so do not use it merely to answer whether one module exists. Installing or upgrading packages is a separate, state-changing operation and may require elevated privileges or a deliberate local-library setup.

4. Make a script fail earlier and explain itself

Before deeper debugging, add strictness and warnings to your own program:

#!/usr/bin/perl
use strict;
use warnings;

my $total = 2 + 2;
print "total=$total\n";

These pragmas make many naming and suspicious-operation mistakes visible near their cause. For a temporary value trace, write to standard error so normal output remains usable:

print STDERR "value=[$value]\n";

For nested structures, the FAQ recommends Data::Dumper:

use Data::Dumper qw(Dumper);
print STDERR Dumper(\%data);

5. Profile only after you can reproduce the work

When the question is where time goes, use a profiler rather than guessing. The FAQ documents Devel::NYTProf:

$ perl -d:NYTProf path/to/example.pl
$ nytprofhtml

NYTProf records statement and subroutine activity, then nytprofhtml turns its database into an HTML report. Run it against a bounded test input first: profiling adds overhead and creates report data in the working directory. Review the generated files before sharing them, because paths, arguments or application data may appear in the report.

For a small comparison between code fragments, the FAQ points to Benchmark. Measure representative input and repeat enough times to reduce noise; a faster micro-test is not automatically a faster complete program.

6. Generate a cross-reference when names are unclear

For a report of symbols and where they are used, run the B::Xref backend:

$ perl -MO=Xref path/to/example.pl

The exact report depends on the program. Use it to investigate a large or unfamiliar script, not as a substitute for tests. If a backend or module is missing, return to the module check in step 3 and confirm the installed Perl documentation for the backend you intend to use.

7. Keep formatting separate from diagnosis

The FAQ names perltidy from Perl::Tidy as a formatter. Formatting can make a review easier, but it does not fix behaviour, prove correctness or replace warnings and tests. Run it on a copy or in version control so you can review every change. If you do not already have the command, do not install it during an incident without recording the package and version used.