update debian/watch for cpan location instead of sourceforge

[perltidy.git] / INSTALL

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