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.
15 If you want to do a quick test of perltidy without doing any
16 installation, get a .tar.gz or a .zip source file and see the section
17 below "Method 2: Installation as a single binary script".
19 Uninstall older versions
20 In certain circumstances, it is best to remove an older version of
21 perltidy before installing the latest version. These are:
23 Uninstall a Version older than 20020225
24 You can use perltidy -v to determine the version number. The first
25 version of perltidy to use Makefile.PL for installation was
26 20020225, so if your previous installation is older than this, it is
27 best to remove it, because the installation path may now be
28 different. There were up to 3 files these older installations: the
29 script perltidy and possibly two man pages, perltidy.1 and
30 perl2web.1. If you saved your Makefile, you can probably use "make
31 uninstall". Otherwise, you can use a locate or find command to find
32 and remove these files.
34 Uninstall older versions when changing installation method
35 If you switch from one installation method to another, the paths to
36 the components of perltidy may change, so it is probably best to
37 remove the older version before installing the new version. If your
38 older installation method had an uninstall option (such as with
39 RPM's and debian packages), use it. Otherwise, you can locate and
40 remove the older files by hand. There are two key files: Tidy.pm and
41 perltidy. In addition, there may be one or two man pages, something
42 like Perl::Tidy.3pm and perltidy.1p. You can use a "locate" and/or
43 "find" command to find and remove these files. After installation,
44 you can verify that the new version of perltidy is working with the
45 "perltidy -v" command.
47 Two Installation Methods - Overview
48 These are generic instructions. Some system-specific notes and hints are
49 given in later sections.
51 Two separate installation methods are possible.
53 Method 1: Standard Installation Method
54 The standard method based on MakeMaker should work in a normal perl
55 environment. This is the recommended installation procedure for
56 systems which support it.
63 The "make" command is probably "nmake" under a Windows system. You
64 may need to become root (or administrator) before doing the "make
67 Method 2: Installation as a single binary script
68 If you just want to take perltidy for a quick test drive without
69 installing it, or are having trouble installing modules, you can
70 bundle it all in one independent executable script. This might also
71 be helpful on a system for which the Makefile.PL method does not
72 work, or if you are temporarily a guest on some system, or if you
73 want to try hacking a special version of perltidy without messing up
76 You just need to uncompress the source distribution, cd down into
77 it, and enter the command:
81 which will combine the pieces of perltidy into a single script named
82 perltidy in the current directory. This script should be fully
83 functional. Try it out on a handy perl script, for example
85 perl perltidy Makefile.PL
87 This should create Makefile.PL.tdy.
90 After installation by either method, verify that the installation
91 worked and that the correct new version is being by entering:
95 If the version number disagrees with the version number embedded in
96 the distribution file name, search for and remove the old version.
97 For example, under a Unix system, the command "which perltidy" might
98 show where it is. Also, see the above notes on uninstalling older
101 On a Unix system running the "bash" shell, if you had a previous
102 installation of perltidy, you may have to use
106 to get the shell to find the new one.
108 After perltidy is installed, you can find where it will look for
109 configuration files and environment variables on your system with
115 Unfortunately, the standard Perl installation method does not seem
116 able to do an uninstall.
122 On some systems, it will give you a list of files to remove by hand.
123 If not, you need to find the script perltidy and its module file
124 Tidy.pm, which will be in a subdirectory named Perl in the site
127 If you installed perltidy with the alternative method, you should
128 just reverse the steps that you used.
130 Unix Installation Notes
131 Alternative method - Unix
132 If the alternative method is used, test the script produced by the
135 perl ./perltidy somefile.pl
137 where somefile.pl is any convenient test file, such as Makefile.PL
140 1. If the script is not executable, use
144 2. Verify that the initial line in perltidy works for your system by
149 which should produce the usage text and then exit. This should
150 usually work, but if it does not, you will need to change the first
151 line in perltidy to reflect the location of perl on your system. On
152 a Unix system, you might find the path to perl with the command
155 3. A sample Makefile for this installation method is Makefile.npm.
156 Edit it to have the correct paths.
158 You will need to become root unless you change the paths to point to
159 somewhere in your home directory. Then issue the command
161 make -f Makefile.npm install
163 This installs perltidy and the man page perltidy.1.
165 5. Test the installation using
169 You should see the usage screen. Then, if you installed the man
174 which should bring up the manual page.
176 If you ever want to remove perltidy, you can remove perltidy and its
177 man pages by hand or use
181 Windows Installation Notes
182 On a Windows 9x/Me system you should CLOSE ANY OPEN APPLICATIONS to
183 avoid losing unsaved data in case of trouble.
185 Standard Method - Windows
186 After you unzip the distribution file, the procedure is probably
194 You may need to download a copy of unzip to unzip the .zip
195 distribution file; you can get this at
196 http://www.info-zip.org/pub/infozip/UnZip.html
198 If you have ActiveState Perl, the installation method is outlined at
199 http://aspn.activestate.com//ASPN/Reference/Products/ActivePerl/faq/
200 Windows/ActivePerl-Winfaq9.html#How_can_I_use_modules_from_CPAN_
202 You may need to download a copy of Microsoft's nmake program from
203 ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe
205 If you are not familiar with installing modules, or have trouble
206 doing so, and want to start testing perltidy quickly, you may want
207 to use the alternative method instead (next section).
209 Alternative Method - Windows
210 From the main installation directory, just enter
214 Placing the resulting file perltidy and the example batch file
215 perltidy.bat, located in the examples directory, in your path should
216 work. (You can determine your path by issuing the msdos command
217 "PATH"). However, the batch file probably will not support file
218 redirection. So, for example, to pipe the long help message through
219 'more', you might have to invoke perltidy with perl directly, like
222 perl \somepath\perltidy -h | more
224 The batch file will not work properly with wildcard filenames, but
225 you may use wildcard filenames if you place them in quotes. For
230 VMS Installation Notes
231 Links to VMS Utilities and Documentation
232 To install perltidy you will need the following utilities Perl, of
233 course, source with VMS goodies available from
234 http://www.sidhe.org/vmsperl or binary available from the Compaq
235 OpenVMS freeware CD. To unpack the source either gunzip and vmstar
236 available from the Compaq OpenVMS freeware CD or zip available from
237 http://www.info-zip.org/
239 To build perltidy you can use either MMS, Compaq's VMS equivalent of
240 make, or MMK, an MMS clone available from http://www.madgoat.com.
242 Information on running perl under VMS can be found at:
243 http://w4.lns.cornell.edu/~pvhp/perl/VMS.html
246 $ unzip -a perl-tidy-yyyymmdd.zip ! or
248 $ unzip /text=auto perl-tidy-yyyymmdd.zip ! or
250 $ gunzip perl-tidy-yyyymmdd.tgz
251 $ vmstar perl-tidy-yyyymmdd.tar
253 Build and install perltidy under VMS:
254 $ set default [.perl-tidy-yyymmdd]
260 Using Perltidy under VMS
261 Create a symbol. This should be put in a logon script, eg
264 $ perltidy == "perl perl_root:[utils]perltidy."
266 Default parameters can be placed in a perltidyrc file. Perltidy
267 looks for one in the following places and uses the first found if
268 the logical "PERLTIDY" is a file and the file exists then that is
269 used if the logical "PERLTIDY" is a directory then look for a
270 .perltidyrc file in the directory look for a .perltidyrc file in the
271 user's home directory
273 To see where the search is done and which .perltidyrc is used type
277 A system "PERLTIDY" logical can be defined pointing to a file with a
278 minimal configuration, and users can defined their own logical to
279 use a personal .perltidyrc file.
281 $ define /system perltidy perl_root:[utils]perltidy.rc
284 If you have one of the magic incantations at the start of perl
285 scripts, so that they can be invoked as a .com file, then you will
286 need to use the -x parameter which causes perltidy to skip all lines
287 until it finds a hash bang line eg "#!perl -w". Since it is such a
288 common option this is probably a good thing to put in a .perltidyrc
292 VMS file extensions will use an underscore character instead of a
293 dot, when necessary, to create a valid filename. So
297 will generate the output file myfile.pl_tdy instead of
298 myfile.pl.tdy, and so on.
301 Troubleshooting / Other Operating Systems
302 Is your system missing from the notes above, or are you having trouble?
303 Perltidy is quite portable.
305 If there seems to be a problem locating a configuration file, you can see
306 what is going on in the config file search with:
310 If you want to customize where perltidy looks for configuration files,
311 look at the routine 'find_config_file' in module 'Tidy.pm'. You should
312 be able to at least use the '-pro=filename' method under most systems.
314 Remember to place quotes (either single or double) around input
315 parameters which contain spaces, such as file names. For example:
317 perltidy "file name with spaces"
319 Without the quotes, perltidy would look for four files: file, name,
322 If you develop a system-dependent patch that might be of general
323 interest, please let us know.
326 You do not need a configuration file, but you may eventually want to
327 create one to save typing; the tutorial and man page discuss this.
329 SYSTEM TEMPORARY FILES
330 Perltidy needs to create a system temporary file when it invokes
331 Pod::Html to format pod text under the -html option. For Unix systems,
332 this will normally be a file in /tmp, and for other systems, it will be
333 a file in the current working directory named perltidy.TMP. This file
334 will be removed when the run finishes.
337 Documentation is contained in .pod format, either in the docs directory
338 or appended to the scripts.
340 These documents can also be found at http://perltidy.sourceforge.net
342 Reading the brief tutorial should help you use perltidy effectively. The
343 tutorial can be read interactively with perldoc, for example
348 or else an html version can be made with pod2html:
350 pod2html tutorial.pod >tutorial.html
352 If you use the Makefile.PL installation method on a Unix system, the
353 perltidy and Perl::Tidy man pages should automatically be installed.
354 Otherwise, you can extract the man pages with the pod2xxxx utilities, as
358 pod2text perltidy >perltidy.txt
359 pod2html perltidy >perltidy.html
362 pod2text Tidy.pm >Tidy.txt
363 pod2html Tidy.pm >Tidy.html
365 After installation, the installation directory of files may be deleted.
367 Perltidy is still being developed, so please check sourceforge
368 occasionally for updates if you find that it is useful. New releases are
369 announced on freshmeat.net.
372 Thanks to Michael Cartmell for supplying notes on VMS.
374 Thanks to Axel Rose for supplying notes on MacPerl.
376 FEEDBACK / BUG REPORTS
377 If you see ways to improve these notes, please let us know.
379 Bug reports, comments and suggestions are welcome. Attach the smallest
380 piece of code which demonstrates the bug or issue. If appropriate,
381 attach a .LOG file. Your efforts are greatly appreciated!
386 perltidy at users.sourceforge.net
387 http://perltidy.sourceforge.net