--- /dev/null
+PERLTIDY INSTALLATION NOTES
+Get a distribution file
+ Source Files in .tar.gz and .zip format
+ This document tells how to install perltidy from the basic source
+ distribution files in .tar.gz or .zip format. These files are
+ identical except for the line endings. The .tar.gz has Unix style
+ line endings, and the .zip file has Windows style line endings. The
+ standard perl MakeMaker method should work for these in most cases.
+
+ Source files in RPM and .deb format
+ The web site also has links to RPM and Debian .deb Linux packages,
+ which may be convenient for some users.
+
+Quick Test Drive
+ If you want to do a quick test of perltidy without doing any
+ installation, get a .tar.gz or a .zip source file and see the section
+ below "Method 2: Installation as a single binary script".
+
+Uninstall older versions
+ In certain circumstances, it is best to remove an older version of
+ perltidy before installing the latest version. These are:
+
+ Uninstall a Version older than 20020225
+ You can use perltidy -v to determine the version number. The first
+ version of perltidy to use Makefile.PL for installation was
+ 20020225, so if your previous installation is older than this, it is
+ best to remove it, because the installation path may now be
+ different. There were up to 3 files these older installations: the
+ script perltidy and possibly two man pages, perltidy.1 and
+ perl2web.1. If you saved your Makefile, you can probably use "make
+ uninstall". Otherwise, you can use a locate or find command to find
+ and remove these files.
+
+ Uninstall older versions when changing installation method
+ If you switch from one installation method to another, the paths to
+ the components of perltidy may change, so it is probably best to
+ remove the older version before installing the new version. If your
+ older installation method had an uninstall option (such as with
+ RPM's and debian packages), use it. Otherwise, you can locate and
+ remove the older files by hand. There are two key files: Tidy.pm and
+ perltidy. In addition, there may be one or two man pages, something
+ like Perl::Tidy.3pm and perltidy.1p. You can use a "locate" and/or
+ "find" command to find and remove these files. After installation,
+ you can verify that the new version of perltidy is working with the
+ "perltidy -v" command.
+
+Two Installation Methods - Overview
+ These are generic instructions. Some system-specific notes and hints are
+ given in later sections.
+
+ Two separate installation methods are possible.
+
+ Method 1: Standard Installation Method
+ The standard method based on MakeMaker should work in a normal perl
+ environment. This is the recommended installation procedure for
+ systems which support it.
+
+ perl Makefile.PL
+ make
+ make test
+ make install
+
+ The "make" command is probably "nmake" under a Windows system. You
+ may need to become root (or administrator) before doing the "make
+ install" step.
+
+ Method 2: Installation as a single binary script
+ If you just want to take perltidy for a quick test drive without
+ installing it, or are having trouble installing modules, you can
+ bundle it all in one independent executable script. This might also
+ be helpful on a system for which the Makefile.PL method does not
+ work, or if you are temporarily a guest on some system, or if you
+ want to try hacking a special version of perltidy without messing up
+ your regular version.
+
+ You just need to uncompress the source distribution, cd down into
+ it, and enter the command:
+
+ perl pm2pl
+
+ which will combine the pieces of perltidy into a single script named
+ perltidy in the current directory. This script should be fully
+ functional. Try it out on a handy perl script, for example
+
+ perl perltidy Makefile.PL
+
+ This should create Makefile.PL.tdy.
+
+ After Installation
+ After installation by either method, verify that the installation
+ worked and that the correct new version is being by entering:
+
+ perltidy -v
+
+ If the version number disagrees with the version number embedded in
+ the distribution file name, search for and remove the old version.
+ For example, under a Unix system, the command "which perltidy" might
+ show where it is. Also, see the above notes on uninstalling older
+ versions.
+
+ On a Unix system running the "bash" shell, if you had a previous
+ installation of perltidy, you may have to use
+
+ hash -r
+
+ to get the shell to find the new one.
+
+ After perltidy is installed, you can find where it will look for
+ configuration files and environment variables on your system with
+ the command:
+
+ perltidy -dpro
+
+ How to Uninstall
+ Unfortunately, the standard Perl installation method does not seem
+ able to do an uninstall.
+
+ But try this:
+
+ make uninstall
+
+ On some systems, it will give you a list of files to remove by hand.
+ If not, you need to find the script perltidy and its module file
+ Tidy.pm, which will be in a subdirectory named Perl in the site
+ library.
+
+ If you installed perltidy with the alternative method, you should
+ just reverse the steps that you used.
+
+ Unix Installation Notes
+ Alternative method - Unix
+ If the alternative method is used, test the script produced by the
+ "pm2pl" perl script:
+
+ perl ./perltidy somefile.pl
+
+ where somefile.pl is any convenient test file, such as Makefile.PL
+ itself. Then,
+
+ 1. If the script is not executable, use
+
+ chmod +x perltidy
+
+ 2. Verify that the initial line in perltidy works for your system by
+ entering:
+
+ ./perltidy -h
+
+ which should produce the usage text and then exit. This should
+ usually work, but if it does not, you will need to change the first
+ line in perltidy to reflect the location of perl on your system. On
+ a Unix system, you might find the path to perl with the command
+ 'which perl'.
+
+ 3. A sample Makefile for this installation method is Makefile.npm.
+ Edit it to have the correct paths.
+
+ You will need to become root unless you change the paths to point to
+ somewhere in your home directory. Then issue the command
+
+ make -f Makefile.npm install
+
+ This installs perltidy and the man page perltidy.1.
+
+ 5. Test the installation using
+
+ perltidy -h
+
+ You should see the usage screen. Then, if you installed the man
+ pages, try
+
+ man perltidy
+
+ which should bring up the manual page.
+
+ If you ever want to remove perltidy, you can remove perltidy and its
+ man pages by hand or use
+
+ make uninstall
+
+ Windows Installation Notes
+ On a Windows 9x/Me system you should CLOSE ANY OPEN APPLICATIONS to
+ avoid losing unsaved data in case of trouble.
+
+ Standard Method - Windows
+ After you unzip the distribution file, the procedure is probably
+ this:
+
+ perl Makefile.PL
+ nmake
+ nmake test
+ nmake install
+
+ You may need to download a copy of unzip to unzip the .zip
+ distribution file; you can get this at
+ http://www.info-zip.org/pub/infozip/UnZip.html
+
+ If you have ActiveState Perl, the installation method is outlined at
+ http://aspn.activestate.com//ASPN/Reference/Products/ActivePerl/faq/
+ Windows/ActivePerl-Winfaq9.html#How_can_I_use_modules_from_CPAN_
+
+ You may need to download a copy of Microsoft's nmake program from
+ ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe
+
+ If you are not familiar with installing modules, or have trouble
+ doing so, and want to start testing perltidy quickly, you may want
+ to use the alternative method instead (next section).
+
+ Alternative Method - Windows
+ From the main installation directory, just enter
+
+ perl pm2pl
+
+ Placing the resulting file perltidy and the example batch file
+ perltidy.bat, located in the examples directory, in your path should
+ work. (You can determine your path by issuing the msdos command
+ "PATH"). However, the batch file probably will not support file
+ redirection. So, for example, to pipe the long help message through
+ 'more', you might have to invoke perltidy with perl directly, like
+ this:
+
+ perl \somepath\perltidy -h | more
+
+ The batch file will not work properly with wildcard filenames, but
+ you may use wildcard filenames if you place them in quotes. For
+ example
+
+ perltidy '*.pl'
+
+ VMS Installation Notes
+ Links to VMS Utilities and Documentation
+ To install perltidy you will need the following utilities Perl, of
+ course, source with VMS goodies available from
+ http://www.sidhe.org/vmsperl or binary available from the Compaq
+ OpenVMS freeware CD. To unpack the source either gunzip and vmstar
+ available from the Compaq OpenVMS freeware CD or zip available from
+ http://www.info-zip.org/
+
+ To build perltidy you can use either MMS, Compaq's VMS equivalent of
+ make, or MMK, an MMS clone available from http://www.madgoat.com.
+
+ Information on running perl under VMS can be found at:
+ http://w4.lns.cornell.edu/~pvhp/perl/VMS.html
+
+ Unpack the source:
+ $ unzip -a perl-tidy-yyyymmdd.zip ! or
+
+ $ unzip /text=auto perl-tidy-yyyymmdd.zip ! or
+
+ $ gunzip perl-tidy-yyyymmdd.tgz
+ $ vmstar perl-tidy-yyyymmdd.tar
+
+ Build and install perltidy under VMS:
+ $ set default [.perl-tidy-yyymmdd]
+ $ perl perltidy.pl
+ $ mmk
+ $ mmk test
+ $ mmk install
+
+ Using Perltidy under VMS
+ Create a symbol. This should be put in a logon script, eg
+ sylogin.com
+
+ $ perltidy == "perl perl_root:[utils]perltidy."
+
+ Default parameters can be placed in a perltidyrc file. Perltidy
+ looks for one in the following places and uses the first found if
+ the logical "PERLTIDY" is a file and the file exists then that is
+ used if the logical "PERLTIDY" is a directory then look for a
+ .perltidyrc file in the directory look for a .perltidyrc file in the
+ user's home directory
+
+ To see where the search is done and which .perltidyrc is used type
+
+ $ perltidy -dpro
+
+ A system "PERLTIDY" logical can be defined pointing to a file with a
+ minimal configuration, and users can defined their own logical to
+ use a personal .perltidyrc file.
+
+ $ define /system perltidy perl_root:[utils]perltidy.rc
+
+ The -x Parameter
+ If you have one of the magic incantations at the start of perl
+ scripts, so that they can be invoked as a .com file, then you will
+ need to use the -x parameter which causes perltidy to skip all lines
+ until it finds a hash bang line eg "#!perl -w". Since it is such a
+ common option this is probably a good thing to put in a .perltidyrc
+ file.
+
+ VMS File Extensions
+ VMS file extensions will use an underscore character instead of a
+ dot, when necessary, to create a valid filename. So
+
+ perltidy myfile.pl
+
+ will generate the output file myfile.pl_tdy instead of
+ myfile.pl.tdy, and so on.
+
+ Mac Installation Notes
+ This release contains a patch by Axel Rose to make perltidy work under
+ MacPerl. The patch is in the 'perltidy' script and prompts the user to
+ interactively enter command line arguments.
+
+ The normal installation process (just dropping the .tgz file on a
+ distribution-provided "installme" script) should work.
+
+ MacPerl users may want to open the "perltidy" script and save it as
+ droplet. Then just use the drag&drop mechanism to provide the file
+ parameter.
+
+ Please be sure enclose in quotes any filenames which contain spaces.
+ This is true for all systems, but worth emphasizing for Mac's, where
+ this is common.
+
+Troubleshooting / Other Operating Systems
+ Is your system missing from the notes above, or are you having trouble?
+ Perltidy is quite portable. The main source of system-dependent
+ programming, and system problems, has been the external system call to
+ perl to perform a syntax check. This can be skipped with the -nsyn
+ parameter:
+
+ perltidy -nsyn filename
+
+ This is the first thing to try if perltidy seems to cause a system to
+ hang in some way. In fact, this has been such a problem with Windows
+ 95/98/Me that the syntax check is deactivated for these systems.
+
+ However, perltidy is also fairly slow, and it may be just taking a long
+ time on a large file, so give it a little time to finish. To illustrate,
+ on a 1.4 GHz PC the following command takes about 0.4 seconds to
+ complete:
+
+ $ time perltidy Makefile.PL
+ real 0m0.398s
+
+ for the small file Makefile.PL supplied with the distribution. On the
+ very large file Tidy.pm (20500 lines, 721k bytes), however, the time
+ increases to 45 seconds:
+
+ $ time perltidy Tidy.pm
+ real 0m45.202s
+
+ Another source of system-dependent programming has to do with locating
+ configuration files. You can see what is going on in the config file
+ search with:
+
+ perltidy -dpro
+
+ If you want to customize where perltidy looks for configuration files,
+ look at the routine 'find_config_file' in module 'Tidy.pm'. You should
+ be able to at least use the '-pro=filename' method under most systems.
+
+ Remember to place quotes (either single or double) around input
+ parameters which contain spaces, such as file names. For example:
+
+ perltidy "file name with spaces"
+
+ Without the quotes, perltidy would look for four files: file, name,
+ with, and spaces.
+
+ If you develop a system-dependent patch that might be of general
+ interest, please let us know.
+
+CONFIGURATION FILE
+ You do not need a configuration file, but you may eventually want to
+ create one to save typing; the tutorial and man page discuss this.
+
+SYSTEM TEMPORARY FILES
+ Perltidy needs to create a system temporary file when it invokes
+ Pod::Html to format pod text under the -html option. For Unix systems,
+ this will normally be a file in /tmp, and for other systems, it will be
+ a file in the current working directory named perltidy.TMP. This file
+ will be removed when the run finishes.
+
+DOCUMENTATION
+ Documentation is contained in .pod format, either in the docs directory
+ or appended to the scripts.
+
+ These documents can also be found at http://perltidy.sourceforge.net
+
+ Reading the brief tutorial should help you use perltidy effectively. The
+ tutorial can be read interactively with perldoc, for example
+
+ cd docs
+ perldoc tutorial.pod
+
+ or else an html version can be made with pod2html:
+
+ pod2html tutorial.pod >tutorial.html
+
+ If you use the Makefile.PL installation method on a Unix system, the
+ perltidy and Perl::Tidy man pages should automatically be installed.
+ Otherwise, you can extract the man pages with the pod2xxxx utilities, as
+ follows:
+
+ cd bin
+ pod2text perltidy >perltidy.txt
+ pod2html perltidy >perltidy.html
+
+ cd lib/Perl
+ pod2text Tidy.pm >Tidy.txt
+ pod2html Tidy.pm >Tidy.html
+
+ After installation, the installation directory of files may be deleted.
+
+ Perltidy is still being developed, so please check sourceforge
+ occasionally for updates if you find that it is useful. New releases are
+ announced on freshmeat.net.
+
+CREDITS
+ Thanks to Michael Cartmell for supplying notes on VMS.
+
+ Thanks to Axel Rose for supplying notes on MacPerl.
+
+FEEDBACK / BUG REPORTS
+ If you see ways to improve these notes, please let us know.
+
+ Bug reports, comments and suggestions are welcome. Attach the smallest
+ piece of code which demonstrates the bug or issue. If appropriate,
+ attach a .LOG file. Your efforts are greatly appreciated!
+
+ Thank You
+
+ Steve Hancock
+ perltidy at users.sourceforge.net
+ http://perltidy.sourceforge.net
projects / perltidy.git / blobdiff