1 # PERLTIDY INSTALLATION NOTES
3 # Get a distribution file
5 - Source Files in .tar.gz and .zip format
7 This document tells how to install perltidy from the basic source
8 distribution files in `.tar.gz` or `.zip` format. These files are
9 identical except for the line endings. The `.tar.gz` has Unix style
10 line endings, and the `.zip` file has Windows style line endings. The
11 standard perl MakeMaker method should work for these in most cases.
13 - Source files in RPM and .deb format
15 The web site also has links to RPM and Debian .deb Linux packages, which may be
16 convenient for some users.
20 If you want to do a quick test of perltidy without doing any installation, get
21 a `.tar.gz` or a `.zip` source file and see the section below "Method 2: Installation
22 as a single binary script".
24 # Uninstall older versions
26 In certain circumstances, it is best to remove an older version
27 of perltidy before installing the latest version. These are:
29 - Uninstall a Version older than 20020225
31 You can use perltidy -v to determine the version number. The first
32 version of perltidy to use Makefile.PL for installation was 20020225, so
33 if your previous installation is older than this, it is best to remove
34 it, because the installation path may now be different. There were up
35 to 3 files these older installations: the script `perltidy` and
36 possibly two man pages, `perltidy.1` and `perl2web.1`. If you saved
37 your Makefile, you can probably use `make uninstall`. Otherwise, you
38 can use a `locate` or `find` command to find and remove these files.
40 - Uninstall older versions when changing installation method
42 If you switch from one installation method to another, the paths to the
43 components of perltidy may change, so it is probably best to remove the older
44 version before installing the new version. If your older installation method
45 had an uninstall option (such as with RPM's and debian packages), use it.
46 Otherwise, you can locate and remove the older files by hand. There are two
47 key files: `Tidy.pm` and `perltidy`. In addition, there may be one or two
48 man pages, something like `Perl::Tidy.3pm` and `perltidy.1p`. You can use a
49 `locate` and/or `find` command to find and remove these files. After
50 installation, you can verify that the new version of perltidy is working with
51 the `perltidy -v` command.
53 # Two Installation Methods - Overview
55 These are generic instructions. Some system-specific notes and hints
56 are given in later sections.
58 Two separate installation methods are possible.
60 - Method 1: Standard Installation Method
62 The standard method based on MakeMaker should work in a normal perl
63 environment. This is the recommended installation procedure for
64 systems which support it.
71 The `make` command is probably `nmake` under a Windows system. You
72 may need to become root (or administrator) before doing the `make
75 - Method 2: Installation as a single binary script
77 If you just want to take perltidy for a quick test drive without installing it,
78 or are having trouble installing modules, you can bundle it all in one
79 independent executable script. This might also be helpful on a system for
80 which the Makefile.PL method does not work, or if you are temporarily a guest
81 on some system, or if you want to try hacking a special version of perltidy
82 without messing up your regular version.
84 You just need to uncompress the source distribution, cd down into it, and enter
89 which will combine the pieces of perltidy into a single script named
90 `perltidy` in the current directory. This script should be
91 fully functional. Try it out on a handy perl script, for example
93 perl perltidy Makefile.PL
95 This should create `Makefile.PL.tdy`.
99 After installation by either method, verify that the installation worked
100 and that the correct new version is being by entering:
104 If the version number disagrees with the version number embedded in the
105 distribution file name, search for and remove the old version.
106 For example, under a Unix system, the command `which perltidy` might
107 show where it is. Also, see the above notes on uninstalling older
110 On a Unix system running the `bash` shell, if you had a previous
111 installation of perltidy, you may have to use
115 to get the shell to find the new one.
117 After `perltidy` is installed, you can find where it will look for
118 configuration files and environment variables on your system with
125 Unfortunately, the standard Perl installation method does not seem able
132 On some systems, it will give you a list of files to remove by hand. If
133 not, you need to find the script `perltidy` and its module file
134 `Tidy.pm`, which will be in a subdirectory named `Perl` in the site
137 If you installed perltidy with the alternative method, you should just
138 reverse the steps that you used.
140 ## Unix Installation Notes
142 - Alternative method - Unix
144 If the alternative method is used, test the script produced by the
147 perl ./perltidy somefile.pl
149 where `somefile.pl` is any convenient test file, such as `Makefile.PL`
152 1\. If the script is not executable, use
156 2\. Verify that the initial line in perltidy works for your system by
161 which should produce the usage text and then exit. This should usually
162 work, but if it does not, you will need to change the first line in
163 `perltidy` to reflect the location of perl on your system. On a Unix
164 system, you might find the path to perl with the command 'which perl'.
166 3\. A sample `Makefile` for this installation method is `Makefile.npm`.
167 Edit it to have the correct paths.
169 You will need to become root unless you change the paths to point to
170 somewhere in your home directory. Then issue the command
172 make -f Makefile.npm install
174 This installs perltidy and the man page perltidy.1.
176 5\. Test the installation using
180 You should see the usage screen. Then, if you installed the man pages,
185 which should bring up the manual page.
187 If you ever want to remove perltidy, you can remove perltidy and its man
192 ## Windows Installation Notes
194 On a Windows 9x/Me system you should CLOSE ANY OPEN APPLICATIONS to
195 avoid losing unsaved data in case of trouble.
197 - Standard Method - Windows
199 After you unzip the distribution file, the procedure is probably this:
206 You may need to download a copy of `unzip` to unzip the `.zip` distribution
207 file; you can get this at
208 http://www.info-zip.org/pub/infozip/UnZip.html
210 If you have ActiveState
211 Perl, the installation method is outlined at
212 http://aspn.activestate.com//ASPN/Reference/Products/ActivePerl/faq/Windows/ActivePerl-Winfaq9.html#How\_can\_I\_use\_modules\_from\_CPAN\_
214 You may need to download a copy of Microsoft's `nmake` program from
215 ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe
217 If you are not familiar with installing modules, or have trouble doing
218 so, and want to start testing perltidy quickly, you may want to use the
219 alternative method instead (next section).
221 - Alternative Method - Windows
223 From the main installation directory, just enter
227 Placing the resulting file `perltidy` and the example batch file
228 `perltidy.bat`, located in the `examples` directory, in your path should
229 work. (You can determine your path by issuing the msdos command
230 `PATH`). However, the batch file probably will not support file
231 redirection. So, for example, to pipe the long help message through
232 'more', you might have to invoke perltidy with perl directly, like this:
234 perl \somepath\perltidy -h | more
236 The batch file will not work properly with wildcard filenames, but you may
237 use wildcard filenames if you place them in quotes. For example
241 ## VMS Installation Notes
243 - Links to VMS Utilities and Documentation
245 To install perltidy you will need the following utilities Perl, of
246 course, source with VMS goodies available from
247 http://www.sidhe.org/vmsperl or binary available from the Compaq OpenVMS
248 freeware CD. To unpack the source either gunzip and vmstar available
249 from the Compaq OpenVMS freeware CD or zip available from
250 http://www.info-zip.org/
252 To build perltidy you can use either **MMS**, Compaq's VMS equivalent of
253 make, or **MMK**, an **MMS** clone available from
254 http://www.madgoat.com.
256 Information on running perl under VMS can be found at:
257 http://w4.lns.cornell.edu/~pvhp/perl/VMS.html
261 $ unzip -a perl-tidy-yyyymmdd.zip ! or
263 $ unzip /text=auto perl-tidy-yyyymmdd.zip ! or
265 $ gunzip perl-tidy-yyyymmdd.tgz
266 $ vmstar perl-tidy-yyyymmdd.tar
268 - Build and install perltidy under VMS:
270 $ set default [.perl-tidy-yyymmdd]
276 - Using Perltidy under VMS
278 Create a symbol. This should be put in a logon script, eg sylogin.com
280 $ perltidy == "perl perl_root:[utils]perltidy."
282 Default parameters can be placed in a `perltidyrc` file. Perltidy
283 looks for one in the following places and uses the first found if the
284 logical `PERLTIDY` is a file and the file exists then that is used if the
285 logical `PERLTIDY` is a directory then look for a `.perltidyrc` file in the
286 directory look for a `.perltidyrc` file in the user's home directory
288 To see where the search is done and which `.perltidyrc` is used type
292 A system `PERLTIDY` logical can be defined pointing to a file with a
293 minimal configuration, and users can defined their own logical to use a
294 personal `.perltidyrc` file.
296 $ define /system perltidy perl_root:[utils]perltidy.rc
300 If you have one of the magic incantations at the start of perl scripts,
301 so that they can be invoked as a .com file, then you will need to use
302 the **-x** parameter which causes perltidy to skip all lines until it
303 finds a hash bang line eg `#!perl -w`. Since it is such a common
304 option this is probably a good thing to put in a `.perltidyrc` file.
306 - VMS File Extensions
308 VMS file extensions will use an underscore character instead of a dot,
309 when necessary, to create a valid filename. So
313 will generate the output file `myfile.pl_tdy` instead of
314 `myfile.pl.tdy`, and so on.
316 # Troubleshooting / Other Operating Systems
318 If there seems to be a problem locating a configuration file, you can see
319 what is going on in the config file search with:
323 If you want to customize where perltidy looks for configuration files,
324 look at the routine 'find\_config\_file' in module 'Tidy.pm'. You should
325 be able to at least use the '-pro=filename' method under most systems.
327 Remember to place quotes (either single or double) around input
328 parameters which contain spaces, such as file names. For example:
330 perltidy "file name with spaces"
332 Without the quotes, perltidy would look for four files: `file`,
333 `name`, `with`, and `spaces`.
335 If you develop a system-dependent patch that might be of general
336 interest, please let us know.
340 You do not need a configuration file, but you may eventually want to
341 create one to save typing; the tutorial and man page discuss this.
343 # SYSTEM TEMPORARY FILES
345 Perltidy needs to create a system temporary file when it invokes
346 Pod::Html to format pod text under the -html option. For Unix systems,
347 this will normally be a file in /tmp, and for other systems, it will be
348 a file in the current working directory named `perltidy.TMP`. This file
349 will be removed when the run finishes.
353 Documentation is contained in **.pod** format, either in the `docs` directory
354 or appended to the scripts.
356 These documents can also be found at http://perltidy.sourceforge.net
358 Reading the brief tutorial should help you use perltidy effectively.
359 The tutorial can be read interactively with **perldoc**, for
365 or else an `html` version can be made with **pod2html**:
367 pod2html tutorial.pod >tutorial.html
369 If you use the Makefile.PL installation method on a Unix system, the
370 **perltidy** and **Perl::Tidy** man pages should automatically be installed.
371 Otherwise, you can extract the man pages with the **pod2xxxx** utilities, as
375 pod2text perltidy >perltidy.txt
376 pod2html perltidy >perltidy.html
379 pod2text Tidy.pm >Tidy.txt
380 pod2html Tidy.pm >Tidy.html
382 After installation, the installation directory of files may be deleted.
384 Perltidy is still being developed, so please check sourceforge occasionally
385 for updates if you find that it is useful. New releases are announced
390 Thanks to the many programmers who have documented problems, made suggestions and sent patches.
392 # FEEDBACK / BUG REPORTS
394 If you see ways to improve these notes, please let us know.
396 A list of current bugs and issues can be found at the CPAN site [https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy](https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy)
398 To report a new bug or problem, use the link on this page .