If you want to do a quick test of perltidy without doing any installation, get a .tar.gz or a .zip source file and see the section below ``Method 2: Installation as a single binary script''.
In certain circumstances, it is best to remove an older version of perltidy before installing the latest version. These are:
make uninstall. Otherwise, you
can use a locate or find command to find and remove these files.
locate and/or find command to find and remove these files. After
installation, you can verify that the new version of perltidy is working with
the perltidy -v command.
These are generic instructions. Some system-specific notes and hints are given in later sections.
Two separate installation methods are possible.
perl Makefile.PL
make
make test
make install
The make command is probably nmake under a Windows system. You
may need to become root (or administrator) before doing the make
install step.
You just need to uncompress the source distribution, cd down into it, and enter the command:
perl pm2pl
which will combine the pieces of perltidy into a single script named perltidy in the current directory. This script should be fully functional. Try it out on a handy perl script, for example
perl perltidy Makefile.PL
This should create Makefile.PL.tdy.
perltidy -v
If the version number disagrees with the version number embedded in the
distribution file name, search for and remove the old version.
For example, under a Unix system, the command which perltidy might
show where it is. Also, see the above notes on uninstalling older
versions.
On a Unix system running the bash shell, if you had a previous
installation of perltidy, you may have to use
hash -r
to get the shell to find the new one.
After perltidy is installed, you can find where it will look for configuration files and environment variables on your system with the command:
perltidy -dpro
But try this:
make uninstall
On some systems, it will give you a list of files to remove by hand. If not, you need to find the script perltidy and its module file Tidy.pm, which will be in a subdirectory named Perl in the site library.
If you installed perltidy with the alternative method, you should just reverse the steps that you used.
pm2pl perl script:
perl ./perltidy somefile.pl
where somefile.pl is any convenient test file, such as Makefile.PL itself. Then,
1. If the script is not executable, use
chmod +x perltidy
2. Verify that the initial line in perltidy works for your system by entering:
./perltidy -h
which should produce the usage text and then exit. This should usually work, but if it does not, you will need to change the first line in perltidy to reflect the location of perl on your system. On a Unix system, you might find the path to perl with the command 'which perl'.
3. A sample Makefile for this installation method is Makefile.npm. Edit it to have the correct paths.
You will need to become root unless you change the paths to point to somewhere in your home directory. Then issue the command
make -f Makefile.npm install
This installs perltidy and the man page perltidy.1.
5. Test the installation using
perltidy -h
You should see the usage screen. Then, if you installed the man pages, try
man perltidy
which should bring up the manual page.
If you ever want to remove perltidy, you can remove perltidy and its man pages by hand or use
make uninstall
On a Windows 9x/Me system you should CLOSE ANY OPEN APPLICATIONS to avoid losing unsaved data in case of trouble.
perl Makefile.PL
nmake
nmake test
nmake install
You may need to download a copy of unzip to unzip the .zip distribution file; you can get this at http://www.info-zip.org/pub/infozip/UnZip.html
If you have ActiveState Perl, the installation method is outlined at http://aspn.activestate.com//ASPN/Reference/Products/ActivePerl/faq/Windows/ActivePerl-Winfaq9.html#How_can_I_use_modules_from_CPAN_
You may need to download a copy of Microsoft's nmake program from ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe
If you are not familiar with installing modules, or have trouble doing so, and want to start testing perltidy quickly, you may want to use the alternative method instead (next section).
perl pm2pl
Placing the resulting file perltidy and the example batch file
perltidy.bat, located in the examples directory, in your path should
work. (You can determine your path by issuing the msdos command
PATH). However, the batch file probably will not support file
redirection. So, for example, to pipe the long help message through
'more', you might have to invoke perltidy with perl directly, like this:
perl \somepath\perltidy -h | more
The batch file will not work properly with wildcard filenames, but you may use wildcard filenames if you place them in quotes. For example
perltidy '*.pl'
To build perltidy you can use either MMS, Compaq's VMS equivalent of make, or MMK, an MMS clone available from http://www.madgoat.com.
Information on running perl under VMS can be found at: http://w4.lns.cornell.edu/~pvhp/perl/VMS.html
$ unzip -a perl-tidy-yyyymmdd.zip ! or
$ unzip /text=auto perl-tidy-yyyymmdd.zip ! or
$ gunzip perl-tidy-yyyymmdd.tgz $ vmstar perl-tidy-yyyymmdd.tar
$ set default [.perl-tidy-yyymmdd] $ perl perltidy.pl $ mmk $ mmk test $ mmk install
$ perltidy == "perl perl_root:[utils]perltidy."
Default parameters can be placed in a perltidyrc file. Perltidy
looks for one in the following places and uses the first found if the
logical PERLTIDY is a file and the file exists then that is used if the
logical PERLTIDY is a directory then look for a .perltidyrc file in the
directory look for a .perltidyrc file in the user's home directory
To see where the search is done and which .perltidyrc is used type
$ perltidy -dpro
A system PERLTIDY logical can be defined pointing to a file with a
minimal configuration, and users can defined their own logical to use a
personal .perltidyrc file.
$ define /system perltidy perl_root:[utils]perltidy.rc
#!perl -w. Since it is such a common
option this is probably a good thing to put in a .perltidyrc file.
perltidy myfile.pl
will generate the output file myfile.pl_tdy instead of myfile.pl.tdy, and so on.
This release contains a patch by Axel Rose to make perltidy work under MacPerl. The patch is in the 'perltidy' script and prompts the user to interactively enter command line arguments.
The normal installation process (just dropping the .tgz file on a distribution-provided ``installme'' script) should work.
MacPerl users may want to open the ``perltidy'' script and save it as droplet. Then just use the drag&drop mechanism to provide the file parameter.
Please be sure enclose in quotes any filenames which contain spaces. This is true for all systems, but worth emphasizing for Mac's, where this is common.
Is your system missing from the notes above, or are you having trouble? Perltidy is quite portable. The main source of system-dependent programming, and system problems, has been the external system call to perl to perform a syntax check. This can be skipped with the -nsyn parameter:
perltidy -nsyn filename
This is the first thing to try if perltidy seems to cause a system to hang in some way. In fact, this has been such a problem with Windows 95/98/Me that the syntax check is deactivated for these systems.
However, perltidy is also fairly slow, and it may be just taking a long time on a large file, so give it a little time to finish. To illustrate, on a 1.4 GHz PC the following command takes about 0.4 seconds to complete:
$ time perltidy Makefile.PL
real 0m0.398s
for the small file Makefile.PL supplied with the distribution. On the very large file Tidy.pm (20500 lines, 721k bytes), however, the time increases to 45 seconds:
$ time perltidy Tidy.pm
real 0m45.202s
Another source of system-dependent programming has to do with locating configuration files. You can see what is going on in the config file search with:
perltidy -dpro
If you want to customize where perltidy looks for configuration files, look at the routine 'find_config_file' in module 'Tidy.pm'. You should be able to at least use the '-pro=filename' method under most systems.
Remember to place quotes (either single or double) around input parameters which contain spaces, such as file names. For example:
perltidy "file name with spaces"
Without the quotes, perltidy would look for four files: file, name, with, and spaces.
If you develop a system-dependent patch that might be of general interest, please let us know.
You do not need a configuration file, but you may eventually want to create one to save typing; the tutorial and man page discuss this.
Perltidy needs to create a system temporary file when it invokes Pod::Html to format pod text under the -html option. For Unix systems, this will normally be a file in /tmp, and for other systems, it will be a file in the current working directory named perltidy.TMP. This file will be removed when the run finishes.
Documentation is contained in .pod format, either in the docs directory or appended to the scripts.
These documents can also be found at http://perltidy.sourceforge.net
Reading the brief tutorial should help you use perltidy effectively. The tutorial can be read interactively with perldoc, for example
cd docs perldoc tutorial.pod
or else an html version can be made with pod2html:
pod2html tutorial.pod >tutorial.html
If you use the Makefile.PL installation method on a Unix system, the perltidy and Perl::Tidy man pages should automatically be installed. Otherwise, you can extract the man pages with the pod2xxxx utilities, as follows:
cd bin pod2text perltidy >perltidy.txt pod2html perltidy >perltidy.html cd lib/Perl pod2text Tidy.pm >Tidy.txt pod2html Tidy.pm >Tidy.html
After installation, the installation directory of files may be deleted.
Perltidy is still being developed, so please check sourceforge occasionally for updates if you find that it is useful. New releases are announced on freshmeat.net.
Thanks to Michael Cartmell for supplying notes on VMS.
Thanks to Axel Rose for supplying notes on MacPerl.
If you see ways to improve these notes, please let us know.
Bug reports, comments and suggestions are welcome. Attach the smallest piece of code which demonstrates the bug or issue. If appropriate, attach a .LOG file. Your efforts are greatly appreciated!
Thank You
Steve Hancock perltidy at users.sourceforge.net http://perltidy.sourceforge.net