1 <h1>PERLTIDY INSTALLATION NOTES</h1>
3 <h1>Get a distribution file</h1>
6 <li><p>Source Files in .tar.gz and .zip format</p>
8 <p>This document tells how to install perltidy from the basic source
9 distribution files in <code>.tar.gz</code> or <code>.zip</code> format. These files are
10 identical except for the line endings. The <code>.tar.gz</code> has Unix style
11 line endings, and the <code>.zip</code> file has Windows style line endings. The
12 standard perl MakeMaker method should work for these in most cases. </p></li>
13 <li><p>Source files in RPM and .deb format</p>
15 <p>The web site also has links to RPM and Debian .deb Linux packages, which may be
16 convenient for some users.</p></li>
19 <h1>Quick Test Drive</h1>
21 <p>If you want to do a quick test of perltidy without doing any installation, get
22 a <code>.tar.gz</code> or a <code>.zip</code> source file and see the section below "Method 2: Installation
23 as a single binary script".</p>
25 <h1>Uninstall older versions</h1>
27 <p>In certain circumstances, it is best to remove an older version
28 of perltidy before installing the latest version. These are:</p>
31 <li><p>Uninstall a Version older than 20020225</p>
33 <p>You can use perltidy -v to determine the version number. The first
34 version of perltidy to use Makefile.PL for installation was 20020225, so
35 if your previous installation is older than this, it is best to remove
36 it, because the installation path may now be different. There were up
37 to 3 files these older installations: the script <code>perltidy</code> and
38 possibly two man pages, <code>perltidy.1</code> and <code>perl2web.1</code>. If you saved
39 your Makefile, you can probably use <code>make uninstall</code>. Otherwise, you
40 can use a <code>locate</code> or <code>find</code> command to find and remove these files.</p></li>
41 <li><p>Uninstall older versions when changing installation method</p>
43 <p>If you switch from one installation method to another, the paths to the
44 components of perltidy may change, so it is probably best to remove the older
45 version before installing the new version. If your older installation method
46 had an uninstall option (such as with RPM's and debian packages), use it.
47 Otherwise, you can locate and remove the older files by hand. There are two
48 key files: <code>Tidy.pm</code> and <code>perltidy</code>. In addition, there may be one or two
49 man pages, something like <code>Perl::Tidy.3pm</code> and <code>perltidy.1p</code>. You can use a
50 <code>locate</code> and/or <code>find</code> command to find and remove these files. After
51 installation, you can verify that the new version of perltidy is working with
52 the <code>perltidy -v</code> command.</p></li>
55 <h1>Two Installation Methods - Overview</h1>
57 <p>These are generic instructions. Some system-specific notes and hints
58 are given in later sections. </p>
60 <p>Two separate installation methods are possible. </p>
63 <li><p>Method 1: Standard Installation Method</p>
65 <p>The standard method based on MakeMaker should work in a normal perl
66 environment. This is the recommended installation procedure for
67 systems which support it.</p>
69 <pre><code> perl Makefile.PL
75 <p>The <code>make</code> command is probably <code>nmake</code> under a Windows system. You
76 may need to become root (or administrator) before doing the <code>make
77 install</code> step. </p></li>
78 <li><p>Method 2: Installation as a single binary script</p>
80 <p>If you just want to take perltidy for a quick test drive without installing it,
81 or are having trouble installing modules, you can bundle it all in one
82 independent executable script. This might also be helpful on a system for
83 which the Makefile.PL method does not work, or if you are temporarily a guest
84 on some system, or if you want to try hacking a special version of perltidy
85 without messing up your regular version. </p>
87 <p>You just need to uncompress the source distribution, cd down into it, and enter
90 <pre><code> perl pm2pl
93 <p>which will combine the pieces of perltidy into a single script named
94 <code>perltidy</code> in the current directory. This script should be
95 fully functional. Try it out on a handy perl script, for example</p>
97 <pre><code>perl perltidy Makefile.PL
100 <p>This should create <code>Makefile.PL.tdy</code>.</p></li>
101 <li><p>After Installation</p>
103 <p>After installation by either method, verify that the installation worked
104 and that the correct new version is being by entering:</p>
106 <pre><code>perltidy -v
109 <p>If the version number disagrees with the version number embedded in the
110 distribution file name, search for and remove the old version.
111 For example, under a Unix system, the command <code>which perltidy</code> might
112 show where it is. Also, see the above notes on uninstalling older
115 <p>On a Unix system running the <code>bash</code> shell, if you had a previous
116 installation of perltidy, you may have to use </p>
121 <p>to get the shell to find the new one.</p>
123 <p>After <code>perltidy</code> is installed, you can find where it will look for
124 configuration files and environment variables on your system with
127 <pre><code>perltidy -dpro
129 <li><p>How to Uninstall</p>
131 <p>Unfortunately, the standard Perl installation method does not seem able
132 to do an uninstall.</p>
136 <pre><code>make uninstall
139 <p>On some systems, it will give you a list of files to remove by hand. If
140 not, you need to find the script <code>perltidy</code> and its module file
141 <code>Tidy.pm</code>, which will be in a subdirectory named <code>Perl</code> in the site
144 <p>If you installed perltidy with the alternative method, you should just
145 reverse the steps that you used.</p></li>
148 <h2>Unix Installation Notes</h2>
151 <li><p>Alternative method - Unix</p>
153 <p>If the alternative method is used, test the script produced by the
154 <code>pm2pl</code> perl script:</p>
156 <pre><code>perl ./perltidy somefile.pl
159 <p>where <code>somefile.pl</code> is any convenient test file, such as <code>Makefile.PL</code>
162 <p>1. If the script is not executable, use </p>
164 <pre><code>chmod +x perltidy
167 <p>2. Verify that the initial line in perltidy works for your system by
170 <pre><code>./perltidy -h
173 <p>which should produce the usage text and then exit. This should usually
174 work, but if it does not, you will need to change the first line in
175 <code>perltidy</code> to reflect the location of perl on your system. On a Unix
176 system, you might find the path to perl with the command 'which perl'.</p>
178 <p>3. A sample <code>Makefile</code> for this installation method is <code>Makefile.npm</code>.
179 Edit it to have the correct paths.</p>
181 <p>You will need to become root unless you change the paths to point to
182 somewhere in your home directory. Then issue the command</p>
184 <pre><code>make -f Makefile.npm install
187 <p>This installs perltidy and the man page perltidy.1. </p>
189 <p>5. Test the installation using</p>
191 <pre><code>perltidy -h
194 <p>You should see the usage screen. Then, if you installed the man pages,
197 <pre><code>man perltidy
200 <p>which should bring up the manual page. </p>
202 <p>If you ever want to remove perltidy, you can remove perltidy and its man
203 pages by hand or use</p>
205 <pre><code>make uninstall
209 <h2>Windows Installation Notes</h2>
211 <p>On a Windows 9x/Me system you should CLOSE ANY OPEN APPLICATIONS to
212 avoid losing unsaved data in case of trouble.</p>
215 <li><p>Standard Method - Windows</p>
217 <p>After you unzip the distribution file, the procedure is probably this:</p>
219 <pre><code> perl Makefile.PL
225 <p>You may need to download a copy of <code>unzip</code> to unzip the <code>.zip</code> distribution
226 file; you can get this at
227 http://www.info-zip.org/pub/infozip/UnZip.html</p>
229 <p>If you have ActiveState
230 Perl, the installation method is outlined at
231 http://aspn.activestate.com//ASPN/Reference/Products/ActivePerl/faq/Windows/ActivePerl-Winfaq9.html#How_can_I_use_modules_from_CPAN_</p>
233 <p>You may need to download a copy of Microsoft's <code>nmake</code> program from
234 ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe</p>
236 <p>If you are not familiar with installing modules, or have trouble doing
237 so, and want to start testing perltidy quickly, you may want to use the
238 alternative method instead (next section).</p></li>
239 <li><p>Alternative Method - Windows</p>
241 <p>From the main installation directory, just enter</p>
243 <pre><code>perl pm2pl
246 <p>Placing the resulting file <code>perltidy</code> and the example batch file
247 <code>perltidy.bat</code>, located in the <code>examples</code> directory, in your path should
248 work. (You can determine your path by issuing the msdos command
249 <code>PATH</code>). However, the batch file probably will not support file
250 redirection. So, for example, to pipe the long help message through
251 'more', you might have to invoke perltidy with perl directly, like this:</p>
253 <pre><code>perl \somepath\perltidy -h | more
256 <p>The batch file will not work properly with wildcard filenames, but you may
257 use wildcard filenames if you place them in quotes. For example</p>
259 <pre><code>perltidy '*.pl'
263 <h2>VMS Installation Notes</h2>
266 <li><p>Links to VMS Utilities and Documentation</p>
268 <p>To install perltidy you will need the following utilities Perl, of
269 course, source with VMS goodies available from
270 http://www.sidhe.org/vmsperl or binary available from the Compaq OpenVMS
271 freeware CD. To unpack the source either gunzip and vmstar available
272 from the Compaq OpenVMS freeware CD or zip available from
273 http://www.info-zip.org/</p>
275 <p>To build perltidy you can use either <strong>MMS</strong>, Compaq's VMS equivalent of
276 make, or <strong>MMK</strong>, an <strong>MMS</strong> clone available from
277 http://www.madgoat.com.</p>
279 <p>Information on running perl under VMS can be found at:
280 http://w4.lns.cornell.edu/~pvhp/perl/VMS.html</p></li>
281 <li><p>Unpack the source:</p>
283 <pre><code>$ unzip -a perl-tidy-yyyymmdd.zip ! or
286 $ unzip /text=auto perl-tidy-yyyymmdd.zip ! or
289 $ gunzip perl-tidy-yyyymmdd.tgz
290 $ vmstar perl-tidy-yyyymmdd.tar
292 <li><p>Build and install perltidy under VMS:</p>
294 <pre><code>$ set default [.perl-tidy-yyymmdd]
300 <li><p>Using Perltidy under VMS</p>
302 <p>Create a symbol. This should be put in a logon script, eg sylogin.com</p>
304 <pre><code>$ perltidy == "perl perl_root:[utils]perltidy."
307 <p>Default parameters can be placed in a <code>perltidyrc</code> file. Perltidy
308 looks for one in the following places and uses the first found if the
309 logical <code>PERLTIDY</code> is a file and the file exists then that is used if the
310 logical <code>PERLTIDY</code> is a directory then look for a <code>.perltidyrc</code> file in the
311 directory look for a <code>.perltidyrc</code> file in the user's home directory</p>
313 <p>To see where the search is done and which <code>.perltidyrc</code> is used type</p>
315 <pre><code>$ perltidy -dpro
318 <p>A system <code>PERLTIDY</code> logical can be defined pointing to a file with a
319 minimal configuration, and users can defined their own logical to use a
320 personal <code>.perltidyrc</code> file.</p>
322 <pre><code>$ define /system perltidy perl_root:[utils]perltidy.rc
324 <li><p>The -x Parameter</p>
326 <p>If you have one of the magic incantations at the start of perl scripts,
327 so that they can be invoked as a .com file, then you will need to use
328 the <strong>-x</strong> parameter which causes perltidy to skip all lines until it
329 finds a hash bang line eg <code>#!perl -w</code>. Since it is such a common
330 option this is probably a good thing to put in a <code>.perltidyrc</code> file.</p></li>
331 <li><p>VMS File Extensions</p>
333 <p>VMS file extensions will use an underscore character instead of a dot,
334 when necessary, to create a valid filename. So </p>
336 <pre><code> perltidy myfile.pl
339 <p>will generate the output file <code>myfile.pl_tdy</code> instead of
340 <code>myfile.pl.tdy</code>, and so on. </p></li>
343 <h1>Troubleshooting / Other Operating Systems</h1>
345 <p>If there seems to be a problem locating a configuration file, you can see
346 what is going on in the config file search with:</p>
348 <pre><code>perltidy -dpro
351 <p>If you want to customize where perltidy looks for configuration files,
352 look at the routine 'find_config_file' in module 'Tidy.pm'. You should
353 be able to at least use the '-pro=filename' method under most systems. </p>
355 <p>Remember to place quotes (either single or double) around input
356 parameters which contain spaces, such as file names. For example:</p>
358 <pre><code>perltidy "file name with spaces"
361 <p>Without the quotes, perltidy would look for four files: <code>file</code>,
362 <code>name</code>, <code>with</code>, and <code>spaces</code>.</p>
364 <p>If you develop a system-dependent patch that might be of general
365 interest, please let us know.</p>
367 <h1>CONFIGURATION FILE</h1>
369 <p>You do not need a configuration file, but you may eventually want to
370 create one to save typing; the tutorial and man page discuss this.</p>
372 <h1>SYSTEM TEMPORARY FILES</h1>
374 <p>Perltidy needs to create a system temporary file when it invokes
375 Pod::Html to format pod text under the -html option. For Unix systems,
376 this will normally be a file in /tmp, and for other systems, it will be
377 a file in the current working directory named <code>perltidy.TMP</code>. This file
378 will be removed when the run finishes.</p>
380 <h1>DOCUMENTATION</h1>
382 <p>Documentation is contained in <strong>.pod</strong> format, either in the <code>docs</code> directory
383 or appended to the scripts. </p>
385 <p>These documents can also be found at http://perltidy.sourceforge.net</p>
387 <p>Reading the brief tutorial should help you use perltidy effectively. <br />
388 The tutorial can be read interactively with <strong>perldoc</strong>, for
395 <p>or else an <code>html</code> version can be made with <strong>pod2html</strong>:</p>
397 <pre><code>pod2html tutorial.pod >tutorial.html
400 <p>If you use the Makefile.PL installation method on a Unix system, the
401 <strong>perltidy</strong> and <strong>Perl::Tidy</strong> man pages should automatically be installed.
402 Otherwise, you can extract the man pages with the <strong>pod2xxxx</strong> utilities, as
406 pod2text perltidy >perltidy.txt
407 pod2html perltidy >perltidy.html
410 pod2text Tidy.pm >Tidy.txt
411 pod2html Tidy.pm >Tidy.html
414 <p>After installation, the installation directory of files may be deleted. </p>
416 <p>Perltidy is still being developed, so please check sourceforge occasionally
417 for updates if you find that it is useful. New releases are announced
418 on freshmeat.net.</p>
422 <p>Thanks to the many programmers who have documented problems, made suggestions and sent patches. </p>
424 <h1>FEEDBACK / BUG REPORTS</h1>
426 <p>If you see ways to improve these notes, please let us know.</p>
428 <p>A list of current bugs and issues can be found at the CPAN site <a href="https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy">https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy</a></p>
430 <p>To report a new bug or problem, use the link on this page . </p>