1 PERLTIDY INSTALLATION NOTES
2 Get a distribution file
3 Source Files in .tar.gz and .zip format
4 This document tells how to install perltidy from the basic source
5 distribution files in .tar.gz or .zip format. These files are
6 identical except for the line endings. The .tar.gz has Unix style
7 line endings, and the .zip file has Windows style line endings. The
8 standard perl MakeMaker method should work for these in most cases.
10 Source files in RPM and .deb format
11 The web site also has links to RPM and Debian .deb Linux packages,
12 which may be convenient for some users.
14 Uninstall older versions
15 In certain circumstances, it is best to remove an older version of
16 perltidy before installing the latest version. These are:
18 Uninstall a Version older than 20020225
19 You can use perltidy -v to determine the version number. The first
20 version of perltidy to use Makefile.PL for installation was
21 20020225, so if your previous installation is older than this, it is
22 best to remove it, because the installation path may now be
23 different. There were up to 3 files these older installations: the
24 script perltidy and possibly two man pages, perltidy.1 and
25 perl2web.1. If you saved your Makefile, you can probably use "make
26 uninstall". Otherwise, you can use a locate or find command to find
27 and remove these files.
29 Uninstall older versions when changing installation method
30 If you switch from one installation method to another, the paths to
31 the components of perltidy may change, so it is probably best to
32 remove the older version before installing the new version. If your
33 older installation method had an uninstall option (such as with
34 RPM's and debian packages), use it. Otherwise, you can locate and
35 remove the older files by hand. There are two key files: Tidy.pm and
36 perltidy. In addition, there may be one or two man pages, something
37 like Perl::Tidy.3pm and perltidy.1p. You can use a "locate" and/or
38 "find" command to find and remove these files. After installation,
39 you can verify that the new version of perltidy is working with the
40 "perltidy -v" command.
42 Two Installation Methods - Overview
43 These are generic instructions. Some system-specific notes and hints are
44 given in later sections.
46 Two separate installation methods are possible.
48 Method 1: Standard Installation Method
49 The standard method based on MakeMaker should work in a normal perl
50 environment. This is the recommended installation procedure for
51 systems which support it.
58 The "make" command is probably "nmake" under a Windows system. You
59 may need to become root (or administrator) before doing the "make
62 Method 2: Installation as a single binary script
63 An alternative method is possible which avoids installing modules.
64 This method can be used to quickly test perltidy to see if it will
65 be useful, without doing a full installation. Also, this might be
66 helpful on a system for which the Makefile.PL method does not work,
67 or if you are temporarily a guest on some system.
69 The command to do this is
73 which will combine the pieces of perltidy into a single script named
74 perltidy in the current directory. This script should be functional.
77 After installation by either method, verify that the installation
78 worked and that the correct new version is being by entering:
82 If the version number disagrees with the version number embedded in
83 the distribution file name, search for and remove the old version.
84 For example, under a Unix system, the command "which perltidy" might
85 show where it is. Also, see the above notes on uninstalling older
88 On a Unix system running the "bash" shell, if you had a previous
89 installation of perltidy, you may have to use
93 to get the shell to find the new one.
95 After perltidy is installed, you can find where it will look for
96 configuration files and environment variables on your system with
102 Unfortunately, the standard Perl installation method does not seem
103 able to do an uninstall.
109 On some systems, it will give you a list of files to remove by hand.
110 If not, you need to find the script perltidy and its module file
111 Tidy.pm, which will be in a subdirectory named Perl in the site
114 If you installed perltidy with the alternative method, you should
115 just reverse the steps that you used.
117 Unix Installation Notes
118 Alternative method - Unix
119 If the alternative method is used, test the script produced by the
122 perl ./perltidy somefile.pl
124 where somefile.pl is any convenient test file, such as Makefile.PL
127 1. If the script is not executable, use
131 2. Verify that the initial line in perltidy works for your system by
136 which should produce the usage text and then exit. This should
137 usually work, but if it does not, you will need to change the first
138 line in perltidy to reflect the location of perl on your system. On
139 a Unix system, you might find the path to perl with the command
142 3. A sample Makefile for this installation method is Makefile.npm.
143 Edit it to have the correct paths.
145 You will need to become root unless you change the paths to point to
146 somewhere in your home directory. Then issue the command
148 make -f Makefile.npm install
150 This installs perltidy and the man page perltidy.1.
152 5. Test the installation using
156 You should see the usage screen. Then, if you installed the man
161 which should bring up the manual page.
163 If you ever want to remove perltidy, you can remove perltidy and its
164 man pages by hand or use
168 Windows Installation Notes
169 On a Windows 9x/Me system you should CLOSE ANY OPEN APPLICATIONS to
170 avoid losing unsaved data in case of trouble.
172 Standard Method - Windows
173 After you unzip the distribution file, the procedure is probably
181 You may need to download a copy of unzip to unzip the .zip
182 distribution file; you can get this at
183 http://www.info-zip.org/pub/infozip/UnZip.html
185 If you have ActiveState Perl, the installation method is outlined at
186 http://aspn.activestate.com//ASPN/Reference/Products/ActivePerl/faq/
187 Windows/ActivePerl-Winfaq9.html#How_can_I_use_modules_from_CPAN_
189 You may need to download a copy of Microsoft's nmake program from
190 ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe
192 If you are not familiar with installing modules, or have trouble
193 doing so, and want to start testing perltidy quickly, you may want
194 to use the alternative method instead (next section).
196 Alternative Method - Windows
197 From the main installation directory, just enter
201 Placing the resulting file perltidy and the example batch file
202 perltidy.bat, located in the examples directory, in your path should
203 work. (You can determine your path by issuing the msdos command
204 "PATH"). However, the batch file probably will not support file
205 redirection. So, for example, to pipe the long help message through
206 'more', you might have to invoke perltidy with perl directly, like
209 perl \somepath\perltidy -h | more
211 The batch file will not work properly with wildcard filenames, but
212 you may use wildcard filenames if you place them in quotes. For
217 VMS Installation Notes
218 Links to VMS Utilities and Documentation
219 To install perltidy you will need the following utilities Perl, of
220 course, source with VMS goodies available from
221 http://www.sidhe.org/vmsperl or binary available from the Compaq
222 OpenVMS freeware CD. To unpack the source either gunzip and vmstar
223 available from the Compaq OpenVMS freeware CD or zip available from
224 http://www.info-zip.org/
226 To build perltidy you can use either MMS, Compaq's VMS equivalent of
227 make, or MMK, an MMS clone available from http://www.madgoat.com.
229 Information on running perl under VMS can be found at:
230 http://w4.lns.cornell.edu/~pvhp/perl/VMS.html
233 $ unzip -a perl-tidy-yyyymmdd.zip ! or
235 $ unzip /text=auto perl-tidy-yyyymmdd.zip ! or
237 $ gunzip perl-tidy-yyyymmdd.tgz
238 $ vmstar perl-tidy-yyyymmdd.tar
240 Build and install perltidy under VMS:
241 $ set default [.perl-tidy-yyymmdd]
247 Using Perltidy under VMS
248 Create a symbol. This should be put in a logon script, eg
251 $ perltidy == "perl perl_root:[utils]perltidy."
253 Default parameters can be placed in a perltidyrc file. Perltidy
254 looks for one in the following places and uses the first found if
255 the logical "PERLTIDY" is a file and the file exists then that is
256 used if the logical "PERLTIDY" is a directory then look for a
257 .perltidyrc file in the directory look for a .perltidyrc file in the
258 user's home directory
260 To see where the search is done and which .perltidyrc is used type
264 A system "PERLTIDY" logical can be defined pointing to a file with a
265 minimal configuration, and users can defined their own logical to
266 use a personal .perltidyrc file.
268 $ define /system perltidy perl_root:[utils]perltidy.rc
271 If you have one of the magic incantations at the start of perl
272 scripts, so that they can be invoked as a .com file, then you will
273 need to use the -x parameter which causes perltidy to skip all lines
274 until it finds a hash bang line eg "#!perl -w". Since it is such a
275 common option this is probably a good thing to put in a .perltidyrc
279 VMS file extensions will use an underscore character instead of a
280 dot, when necessary, to create a valid filename. So
284 will generate the output file myfile.pl_tdy instead of
285 myfile.pl.tdy, and so on.
287 Mac Installation Notes
288 This release contains a patch by Axel Rose to make perltidy work under
289 MacPerl. The patch is in the 'perltidy' script and prompts the user to
290 interactively enter command line arguments.
292 The normal installation process (just dropping the .tgz file on a
293 distribution-provided "installme" script) should work.
295 MacPerl users may want to open the "perltidy" script and save it as
296 droplet. Then just use the drag&drop mechanism to provide the file
299 Please be sure enclose in quotes any filenames which contain spaces.
300 This is true for all systems, but worth emphasizing for Mac's, where
303 Troubleshooting / Other Operating Systems
304 Is your system missing from the notes above, or are you having trouble?
305 Perltidy is quite portable. The main source of system-dependent
306 programming, and system problems, has been the external system call to
307 perl to perform a syntax check. This can be skipped with the -nsyn
310 perltidy -nsyn filename
312 This is the first thing to try if perltidy seems to cause a system to
313 hang in some way. In fact, this has been such a problem with Windows
314 95/98/Me that the syntax check is deactivated for these systems.
316 However, perltidy is also fairly slow, and it may be just taking a long
317 time on a large file, so give it a little time to finish. To illustrate,
318 on a 1.4 GHz PC the following command takes about 0.4 seconds to
321 $ time perltidy Makefile.PL
324 for the small file Makefile.PL supplied with the distribution. On the
325 very large file Tidy.pm (20500 lines, 721k bytes), however, the time
326 increases to 45 seconds:
328 $ time perltidy Tidy.pm
331 Another source of system-dependent programming has to do with locating
332 configuration files. You can see what is going on in the config file
337 If you want to customize where perltidy looks for configuration files,
338 look at the routine 'find_config_file' in module 'Tidy.pm'. You should
339 be able to at least use the '-pro=filename' method under most systems.
341 Remember to place quotes (either single or double) around input
342 parameters which contain spaces, such as file names. For example:
344 perltidy "file name with spaces"
346 Without the quotes, perltidy would look for four files: file, name,
349 If you develop a system-dependent patch that might be of general
350 interest, please let us know.
353 You do not need a configuration file, but you may eventually want to
354 create one to save typing; the tutorial and man page discuss this.
356 SYSTEM TEMPORARY FILES
357 Perltidy needs to create a system temporary file when it invokes
358 Pod::Html to format pod text under the -html option. For Unix systems,
359 this will normally be a file in /tmp, and for other systems, it will be
360 a file in the current working directory named perltidy.TMP. This file
361 will be removed when the run finishes.
364 Documentation is contained in .pod format, either in the docs directory
365 or appended to the scripts.
367 These documents can also be found at http://perltidy.sourceforge.net
369 Reading the brief tutorial should help you use perltidy effectively. The
370 tutorial can be read interactively with perldoc, for example
375 or else an html version can be made with pod2html:
377 pod2html tutorial.pod >tutorial.html
379 If you use the Makefile.PL installation method on a Unix system, the
380 perltidy and Perl::Tidy man pages should automatically be installed.
381 Otherwise, you can extract the man pages with the pod2xxxx utilities, as
385 pod2text perltidy >perltidy.txt
386 pod2html perltidy >perltidy.html
389 pod2text Tidy.pm >Tidy.txt
390 pod2html Tidy.pm >Tidy.html
392 After installation, the installation directory of files may be deleted.
394 Perltidy is still being developed, so please check sourceforge
395 occasionally for updates if you find that it is useful. New releases are
396 announced on freshmeat.net.
399 Thanks to Michael Cartmell for supplying notes on VMS.
401 Thanks to Axel Rose for supplying notes on MacPerl.
403 FEEDBACK / BUG REPORTS
404 If you see ways to improve these notes, please let us know.
406 Bug reports, comments and suggestions are welcome. Attach the smallest
407 piece of code which demonstrates the bug or issue. If appropriate,
408 attach a .LOG file. Your efforts are greatly appreciated!
413 perltidy at users.sourceforge.net
414 http://perltidy.sourceforge.net