Perl script documentation with Pod::Usage

One of the most important parts of maintainable and usable system administration scripts is documentation. Code comments are a key component to this, but so is usage documentation. In this post, I’ll address an easy way to add complete and useful usage documentation to your scripts using the module Pod::Usage.

Pod::Usage is a module that lets you easily convert Pod documentation to a help message or man page. To use it, you just need to include several Pod sections in your documentation. These include the NAME, SYNOPSIS, OPTIONS, and DESCRIPTION sections. Pod::Usage will use some of these sections to generate usage information and man pages. Once you’ve written all of your documentation, you can use Getopt::Long to capture options passed to the script like –help and –man. For these options, you can run the function ‘pod2usage’, with varying levels of verbosity.

For example, ‘pod2usage(-verbose => 1)’ will print out a short usage message (generated from the SYNOPSIS Pod section). To open a full man page in your default man viewer, you can use a verbosity of 2. Additionally, you can print out a string before your generated usage message, by providing the ‘-msg’ option inside the function call. For example, ‘pod2usage(-msg => “Not enough arguments”, -verbose => 1)’ will print “Not enough arguments”, followed by the usage message for your script.

You can find documentation on the Pod::Usage module as well as example code on perldoc.perl.org.

Working with missing Makefile.PL scripts in CPAN modules

Some versions of CPAN (notably, the one that ships with Red Hat / CentOS 4.6, v1.7601) will automatically attempt to create a ‘Makefile.PL’ script if a module you’re trying to install through CPAN is missing one. However, sometimes this may lead to an error during the module installation, usually something like: “Too early to specify a build action ‘Build’.  Do ‘Build Build’ instead.”. This appears to be caused by a missing argument to ExtUtils::MakeMaker’s WriteMakefile subroutine. If the ‘PL_FILES’ argument doesn’t exist, MakeMaker will incorrectly attempt to use the Build.PL file included with the module. Continue reading “Working with missing Makefile.PL scripts in CPAN modules”

Easily installing Perl modules with Yum

Although many Perl modules are available through Red Hat and CentOS’s repositories, the name the modules have in the repository differ from the name of the module itself.

To use yum to install a Perl module using the module name, just place ‘”perl()”‘ around the name of the module (double quotes included) when giving it as an argument to yum. For example, to install the ‘Net::Telnet’ module, you would run ‘yum install “perl(Net::Telnet)”‘.

Alternatively, to construct the correct package name, you would prepend the module’s name with ‘perl-’, and change all of the instances of ‘::’ to ‘-’. For example, the package for the ‘Net::Telnet’ module would be ‘perl-Net-Telnet’.