Introduction to Notes on Developing Perl Code

A collection of (personal, opinionated) short notes on tools and techniques for developing software. First prepared for the Tk Tutorial project (see

Intended for novice or occasional Perl programmers. Others might find useful ideas.

The first release is based on work done on Linux.

Checking Perl Source Code: strict and -w

Include the use strict pragma at the start of the program to see and avoid possible problems.

Consider using it on all programs, long or short, to get in the habit of writing strict code.

Invoke Perl as perl -w to receive warnings about problem code.

Perl's Debugger with Tk


perl -d tktut1_window

O tkRunning

O inhibit_exit

Helpful Debugger Commands

h : Show list of commands

h h : Show brief summary of most commands

h cmd : Show help on specific cmd

x expr : Print expression nicely

q or ^D : Quit

Debug Tips

Other Debug Information Sources

Perltidy to Format Source Code

Use perltidy to format Perl programs to have a consistent appearance.

Well-formatted source code can help to show problems, eg, missing punctuation, mismatched parentheses, hashes with an odd number of elements.

Get it from SourceForge:

Unpack the package, and read through the brief tutorial for a good overview and quick start notes (in the docs/tutorial.pod file).


perltidy test

Formatted output is written to a separate file, test.tdy.

Run the test.tdy program and verify it works ok after any changes that were made.

If you're curious, run diff on the two files to see what changed:

diff test test.tdy

Make and Makefile to Build Files

A Makefile describes how to build various output files from input files: which commands to use, with what options, and in what order. Use it to build the files that you use during a project. Automate any series of steps that must be done repeatedly.

How a Makefile can help Perl projects: to build postscript printer files; to get a cross-reference listing from a profiler; to run utility programs like perltidy; to build html and man output files from pod source files.

The make program executes one or more commands defined in Makefile at user's request, eg:

make test: Build the target named test.

make all: Build the target named all, which usually includes everything for the project.

make clean: Build the target named clean, which usually removes all output files, prior to making everything.

The make program searches Makefile and executes the minimal set of steps needed to accomplish the requested task.

See the Makefile for the Tk Tutorial project for an example of what can be done with a little effort. Much time was saved while preparing the files for the project by using make.

A similar program called nmake is available from Microsoft on Windows.

Ant is a more recent build tool. This Java-based build tool uses XML, and is designed for cross-platform projects. It requires a Java environment on its host machine.

Makefile Tips

Writing Messages
Write a message to the screen with the @echo command:

@echo Message text

Ignore Errors in Command Line
Some errors reported by make can safely be ignored and processing can continue (eg, mkdir that fails because the dir already exists). Precede such commands with a hyphen before them, and make will continue even if that command fails:
    -mkdir tktut

See also the flags -i, --ignore-errors and -k, --keep-going.

Identify Variables Properly
Use proper syntax when including a variable on the right side of a rule, eg:

The construct $(...) identifies the variable.

Without this syntax, make would expect to find a target with the name TKTUT_TEXT_DOC in the Makefile. If you don't have such a target, make will fail with an error. If you do have such a target, make will use it to build this target; in some cases that might lead to undesired results, and problems that are hard to debug.

Formatting and Printing Files with a2ps

Much debugging work can be done on screen, without printing any files. When hard-copy is desired, try formatting the file before printing it to ensure that it looks good on paper. The a2ps program can prepare Perl programs and pod files for a PostScript printer.

a2ps -o test.out test

a2ps --highlight-level=none ...

a2ps -r --chars-per-line=80 --columns=2 --rows=1 ...

The full command looks like this (should be on a single line):

a2ps -r --chars-per-line=80 --columns=2 --rows=1 -o test --highlight-level=none

Formatting Tips

Source Control

Use CVS, RCS, or some other source code control tool to keep track of all changes made to source code and other critical project files.

For files that need not be under version control, use a solid backup program and process to avoid losing important data.

CVS is a good choice if you intend to work with others on a project.

SourceForge provides a CVS facility for its projects that can involve many people in many places via the Internet.

Start with the Overview section of info cvs to get the basics of configuration and usage.

For a GUI for CVS, search the web; I found these:

CVS Tips

cvs update -C devnotes
Get most recently saved copy of devnotes file from repository, and overwrite any version in the local dir with it.

Do this to restart with a clean copy of the file after making changes that are not worth saving.

Remove obsolete file from repository
If a file becomes obsolete and is no longer needed, either ignore it; or delete the file from the directory then remove it from CVS with these steps:
    rm oldfile
    cvs remove oldfile
    cvs commit oldfile

Add a note telling why the file is being removed from CVS.

The file's state is changed, and it might be moved to the Attic subdir in the CVS repository. It is available if needed, but won't appear in the list of files shown by commands like cvs status.

If you leave the file in the dir and in CVS, it can be annoying to see it listed whenever a status command is done.

Check status of CVS files regularly
Run the status command every night, before running a backup, or before doing a build, to ensure that CVS has current files.

cvs status

Show full status info on each file in CVS for the current dir.

cvs status | grep File

Show one line with file name and status: a quick way to see which files have been modified and need to be saved. Check any file that is not Up-to-date.

Virtual Machine Software

Virtual machine s/w allows one hardware platform to run independent guest operating systems on the host o/s simultaneously. These notes refer to VMware, a commercial product that allows the host and guest o/s to be either Windows or Linux.

A user can operate multiple virtual machines from a single console, which saves space (fewer computers, keyboards, screens in the lab) and saves time (keep your hands and eyes in one place, instead of moving among different consoles).

A PC with VMware can have multiple copies of Linux and Windows o/s's configured as virtual machines on the host system.

The host and guest o/s's share one network interface and other hardware resources. Each system has its own network identity (name, IP address), and disk space.

The user can switch among the various o/s's without rebooting; a combination of keystrokes triggers the change.

VM Tips

Suspend and resume
Suspend a VM, then Resume operation later with the exact desktop configuration of the previous session: much quicker than rebooting any o/s.

Portability testing
Develop programs on your preferred system, then copy to the other virtual machines to test portability.

For open source projects, see FreeMWare (, experimental, doesn't look like an active project);

Commercial vendors include VMware, Connectix (Virtual PC on Windows), NeTraverse (Win4Lin).

Perl Pod Tips

Formatting for HTML output
When preparing pod documents for a web page using HTML, try the following construct to identify HTML-specific formatting:

    =begin html

    <p><a href="devnotes.html">View dev tips 

    Other html lines....

    =end html

Build the HTML document with

    pod2html index.pod > index.html

View the result in a web browser to verify that it worked.

If the HTML was not properly interpreted, try the format instruction that operates on a single-paragraph:

    =for html
    <p><a href="devnotes.html">View dev tips
    Other html lines....

    Other non-html lines....

On some systems, I have found that =for works when =begin/=end fail.

Adding vertical spacing
Pod is a simple formatter, and does not provide any command to add vertical spacing between two lines. Follow these instructions to add vertical spacing in some types of output documents (see Notes).

To add vertical spacing between lines of output text insert three lines between the lines of text in the pod file in this manner:

    Normal paragraph 1....
    1. A blank line.
    2. Verbatim paragraph: line with one space.
    3. A blank line.
    Normal paragraph 2....

Stated simply:

    Normal paragraph 1....
    Normal paragraph 2....

The first blank line terminates paragraph 1.

The line with only a blank space (tab is a good choice also) is treated by pod formatters as a verbatim paragraph; it has no visible characters.

The second blank line terminates the verbatim paragraph.

To add multiple vertical spaces, each verbatim paragraph must be terminated by its own blank line; if you add several verbatim paragraphs without the blank line between each of them, they will be concatenated into a single verbatim paragraph.


Make sure the line with only the space character on it is not automatically erased by something like autoindent with the Vi editor (eg, check the line with Vi's :l command to see that it has a space character before end-of-line).

Using different formatters on the pod source document has these effects:

    pod2text: One blank line can be added.
    pod2man: One blank line can be added.
    pod2html: Multiple blank lines can be added.

Perl Tips

Preload for better performance.
Specify functions to be used in the program during initialization. The init phase will take longer, but avoiding Autoload might improve the overall performance of the program. See Tk::widgets(1).


use Tk::widgets qw( Button Label Frame Text Menubutton );

Use perldoc -i to ignore case.
Invoke perldoc with its -i option to ignore case. Many of the Tk documentation pages are named using mixed case, and the use of initial caps is inconsistent. Perldoc requires the exact name unless ignore case is specified.

Also, watch out for similarly-named items like tk and Tk; and Tk/option and Tk/options.


Many thanks to all the builders of open source software; and to SourceForge and VA Software for their services.

Prepared by C. L. Poda <clpoda -at->

Copyright (c) 2002 by C. Poda. Permission is hereby granted to distribute this document intact, and in accordance with the licenses of the Perl distribution; derived documents must include this copyright notice intact.

See details on the Tk Tutorial project at

$Id: devnotes.pod,v 1.8 2002/05/07 17:10:21 clpoda Exp $