1PERLTIDY INSTALLATION NOTES 2Get 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. 9 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. 13 14Quick Test Drive 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". 18 19Uninstall older versions 20 In certain circumstances, it is best to remove an older version of 21 perltidy before installing the latest version. These are: 22 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. 33 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. 46 47Two Installation Methods - Overview 48 These are generic instructions. Some system-specific notes and hints are 49 given in later sections. 50 51 Two separate installation methods are possible. 52 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. 57 58 perl Makefile.PL 59 make 60 make test 61 make install 62 63 The "make" command is probably "nmake" under a Windows system. You 64 may need to become root (or administrator) before doing the "make 65 install" step. 66 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 74 your regular version. 75 76 You just need to uncompress the source distribution, cd down into 77 it, and enter the command: 78 79 perl pm2pl 80 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 84 85 perl perltidy Makefile.PL 86 87 This should create Makefile.PL.tdy. 88 89 After Installation 90 After installation by either method, verify that the installation 91 worked and that the correct new version is being by entering: 92 93 perltidy -v 94 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 99 versions. 100 101 On a Unix system running the "bash" shell, if you had a previous 102 installation of perltidy, you may have to use 103 104 hash -r 105 106 to get the shell to find the new one. 107 108 After perltidy is installed, you can find where it will look for 109 configuration files and environment variables on your system with 110 the command: 111 112 perltidy -dpro 113 114 How to Uninstall 115 Unfortunately, the standard Perl installation method does not seem 116 able to do an uninstall. 117 118 But try this: 119 120 make uninstall 121 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 125 library. 126 127 If you installed perltidy with the alternative method, you should 128 just reverse the steps that you used. 129 130 Unix Installation Notes 131 Alternative method - Unix 132 If the alternative method is used, test the script produced by the 133 "pm2pl" perl script: 134 135 perl ./perltidy somefile.pl 136 137 where somefile.pl is any convenient test file, such as Makefile.PL 138 itself. Then, 139 140 1. If the script is not executable, use 141 142 chmod +x perltidy 143 144 2. Verify that the initial line in perltidy works for your system by 145 entering: 146 147 ./perltidy -h 148 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 153 'which perl'. 154 155 3. A sample Makefile for this installation method is Makefile.npm. 156 Edit it to have the correct paths. 157 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 160 161 make -f Makefile.npm install 162 163 This installs perltidy and the man page perltidy.1. 164 165 5. Test the installation using 166 167 perltidy -h 168 169 You should see the usage screen. Then, if you installed the man 170 pages, try 171 172 man perltidy 173 174 which should bring up the manual page. 175 176 If you ever want to remove perltidy, you can remove perltidy and its 177 man pages by hand or use 178 179 make uninstall 180 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. 184 185 Standard Method - Windows 186 After you unzip the distribution file, the procedure is probably 187 this: 188 189 perl Makefile.PL 190 nmake 191 nmake test 192 nmake install 193 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 197 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_ 201 202 You may need to download a copy of Microsoft's nmake program from 203 ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe 204 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). 208 209 Alternative Method - Windows 210 From the main installation directory, just enter 211 212 perl pm2pl 213 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 220 this: 221 222 perl \somepath\perltidy -h | more 223 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 226 example 227 228 perltidy '*.pl' 229 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/ 238 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. 241 242 Information on running perl under VMS can be found at: 243 http://w4.lns.cornell.edu/~pvhp/perl/VMS.html 244 245 Unpack the source: 246 $ unzip -a perl-tidy-yyyymmdd.zip ! or 247 248 $ unzip /text=auto perl-tidy-yyyymmdd.zip ! or 249 250 $ gunzip perl-tidy-yyyymmdd.tgz 251 $ vmstar perl-tidy-yyyymmdd.tar 252 253 Build and install perltidy under VMS: 254 $ set default [.perl-tidy-yyymmdd] 255 $ perl perltidy.pl 256 $ mmk 257 $ mmk test 258 $ mmk install 259 260 Using Perltidy under VMS 261 Create a symbol. This should be put in a logon script, eg 262 sylogin.com 263 264 $ perltidy == "perl perl_root:[utils]perltidy." 265 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 272 273 To see where the search is done and which .perltidyrc is used type 274 275 $ perltidy -dpro 276 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. 280 281 $ define /system perltidy perl_root:[utils]perltidy.rc 282 283 The -x Parameter 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 289 file. 290 291 VMS File Extensions 292 VMS file extensions will use an underscore character instead of a 293 dot, when necessary, to create a valid filename. So 294 295 perltidy myfile.pl 296 297 will generate the output file myfile.pl_tdy instead of 298 myfile.pl.tdy, and so on. 299 300 Mac Installation Notes 301 This release contains a patch by Axel Rose to make perltidy work under 302 MacPerl. The patch is in the 'perltidy' script and prompts the user to 303 interactively enter command line arguments. 304 305 The normal installation process (just dropping the .tgz file on a 306 distribution-provided "installme" script) should work. 307 308 MacPerl users may want to open the "perltidy" script and save it as 309 droplet. Then just use the drag&drop mechanism to provide the file 310 parameter. 311 312 Please be sure enclose in quotes any filenames which contain spaces. 313 This is true for all systems, but worth emphasizing for Mac's, where 314 this is common. 315 316Troubleshooting / Other Operating Systems 317 Is your system missing from the notes above, or are you having trouble? 318 Perltidy is quite portable. The main source of system-dependent 319 programming, and system problems, has been the external system call to 320 perl to perform a syntax check. This can be skipped with the -nsyn 321 parameter: 322 323 perltidy -nsyn filename 324 325 This is the first thing to try if perltidy seems to cause a system to 326 hang in some way. In fact, this has been such a problem with Windows 327 95/98/Me that the syntax check is deactivated for these systems. 328 329 However, perltidy is also fairly slow, and it may be just taking a long 330 time on a large file, so give it a little time to finish. To illustrate, 331 on a 1.4 GHz PC the following command takes about 0.4 seconds to 332 complete: 333 334 $ time perltidy Makefile.PL 335 real 0m0.398s 336 337 for the small file Makefile.PL supplied with the distribution. On the 338 very large file Tidy.pm (20500 lines, 721k bytes), however, the time 339 increases to 45 seconds: 340 341 $ time perltidy Tidy.pm 342 real 0m45.202s 343 344 Another source of system-dependent programming has to do with locating 345 configuration files. You can see what is going on in the config file 346 search with: 347 348 perltidy -dpro 349 350 If you want to customize where perltidy looks for configuration files, 351 look at the routine 'find_config_file' in module 'Tidy.pm'. You should 352 be able to at least use the '-pro=filename' method under most systems. 353 354 Remember to place quotes (either single or double) around input 355 parameters which contain spaces, such as file names. For example: 356 357 perltidy "file name with spaces" 358 359 Without the quotes, perltidy would look for four files: file, name, 360 with, and spaces. 361 362 If you develop a system-dependent patch that might be of general 363 interest, please let us know. 364 365CONFIGURATION FILE 366 You do not need a configuration file, but you may eventually want to 367 create one to save typing; the tutorial and man page discuss this. 368 369SYSTEM TEMPORARY FILES 370 Perltidy needs to create a system temporary file when it invokes 371 Pod::Html to format pod text under the -html option. For Unix systems, 372 this will normally be a file in /tmp, and for other systems, it will be 373 a file in the current working directory named perltidy.TMP. This file 374 will be removed when the run finishes. 375 376DOCUMENTATION 377 Documentation is contained in .pod format, either in the docs directory 378 or appended to the scripts. 379 380 These documents can also be found at http://perltidy.sourceforge.net 381 382 Reading the brief tutorial should help you use perltidy effectively. The 383 tutorial can be read interactively with perldoc, for example 384 385 cd docs 386 perldoc tutorial.pod 387 388 or else an html version can be made with pod2html: 389 390 pod2html tutorial.pod >tutorial.html 391 392 If you use the Makefile.PL installation method on a Unix system, the 393 perltidy and Perl::Tidy man pages should automatically be installed. 394 Otherwise, you can extract the man pages with the pod2xxxx utilities, as 395 follows: 396 397 cd bin 398 pod2text perltidy >perltidy.txt 399 pod2html perltidy >perltidy.html 400 401 cd lib/Perl 402 pod2text Tidy.pm >Tidy.txt 403 pod2html Tidy.pm >Tidy.html 404 405 After installation, the installation directory of files may be deleted. 406 407 Perltidy is still being developed, so please check sourceforge 408 occasionally for updates if you find that it is useful. New releases are 409 announced on freshmeat.net. 410 411CREDITS 412 Thanks to Michael Cartmell for supplying notes on VMS. 413 414 Thanks to Axel Rose for supplying notes on MacPerl. 415 416FEEDBACK / BUG REPORTS 417 If you see ways to improve these notes, please let us know. 418 419 Bug reports, comments and suggestions are welcome. Attach the smallest 420 piece of code which demonstrates the bug or issue. If appropriate, 421 attach a .LOG file. Your efforts are greatly appreciated! 422 423 Thank You 424 425 Steve Hancock 426 perltidy at users.sourceforge.net 427 http://perltidy.sourceforge.net 428