all debian patches are now upstream

[perltidy.git] / INSTALL.md

# 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. 

# Troubleshooting / Other Operating Systems

If there seems to be a problem locating a configuration file, 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 the many programmers who have documented problems, made suggestions and sent patches.  

# FEEDBACK / BUG REPORTS

If you see ways to improve these notes, please let us know.

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)

To report a new bug or problem, use the link on this page .