A collection of (personal, opinionated) short notes on tools and techniques for developing software. First prepared for the Tk Tutorial project (see http://tktut.sourceforge.net).
Intended for novice or occasional Perl programmers. Others might find useful ideas.
The first release is based on work done on Linux.
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 -d tktut1_window
O tkRunning
O inhibit_exit
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
If the debugger appears to hang, the program might be waiting for user input via the GUI: click a button to cause an event that can get control back to the debugger.
If the program appears to hang, the debugger might have paused it at a breakpoint: check the console for messages or prompts (press the Enter key to see if a prompt appears).
Step through the program with the next command and see how the display changes when data is modified.
Skip through the breakpoint with the continue command, or delete the breakpoint when not needed.
Note: Installing Active State's debugger might prevent access to Perl's basic command-line debugger.
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: http://perltidy.sourceforge.net
Unpack the package, and read through the brief tutorial for a good overview and quick start notes (in the docs/tutorial.pod file).
Usage:
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
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.
@echo command:
@echo Message text
-mkdir tktut
See also the flags -i, --ignore-errors
and -k, --keep-going.
TKTUT_DOC = $(TKTUT_TEXT_DOC)
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.
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
View the output with a program such as gv, ghostview.
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.ps test --highlight-level=none
Note: perltidy might delete these characters, unless they appear in a comment.
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:
http://www.cvsgui.org
http://www.mozilla.org/bonsai.html
cvs update -C devnotesDo this to restart with a clean copy of the file after making changes that are not worth saving.
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.
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 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.
For open source projects, see FreeMWare (linux.tucows.com, experimental, doesn't look like an active project); www.plex86.org.
Commercial vendors include VMware, Connectix (Virtual PC on Windows), NeTraverse (Win4Lin).
=begin html
<p><a href="devnotes.html">View dev tips
</a>
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
</a>
Other html lines....
Other non-html lines....
On some systems, I have found that =for works when =begin/=end fail.
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....
Newline
Newline
Space
Newline
Newline
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.
Notes:
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.
Example:
use Tk::widgets qw( Button Label Frame Text Menubutton );
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- users.sourceforge.net>
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
http://tktut.sourceforge.net
$Id: devnotes.pod,v 1.8 2002/05/07 17:10:21 clpoda Exp $