=========================================================================
BioPerl on Windows
==================

1.0 Installation
1.1 PERL on Windows
1.2 External Modules
1.3 Installing Bioperl
1.3.1 Older ActiveState PPMs
1.3.2 ActiveState PPM3
1.3.3 Download Archive
1.3.4 If All Else Fails...
2.0 Windows Specific Behaviour
2.1 Subroutine <name> redefined at location <location> warnings
2.2 Consed
3.0 BioPerl in Cygwin

This introduction was written by Paul Boutros. Please report problems
and/or fixes to the bioperl mailing list, bioperl-l@bioperl.org


1.0 Installation
================

Windows installation of BioPerl requires three steps:
i)   installation of PERL
ii)  installation of external modules
iii) installation of BioPerl itself

I'll quickly summarize my findings on each of those below.

1.1 PERL on Windows
===================

There are a lot of ways of installing PERL on a Windows machine.
The most common is to get the most recent build from
ActiveState.  You can also build PERL yourself (which requires a C
compiler) or download one of the other binary distributions. Or, you
can use Cygwin and its Perl and run Bioperl in this environment. All these
approaches have worked.

The PERL source for building it yourself is available from CPAN
(http://www.cpan.org), as are a few binary distributions.

ActiveState is a software company (http://www.activestate.com) that
provides free builds of PERL for Windows users.  They are currently
(October 2003) providing a very stable build of PERL 5.6.1, and a
version of PERL 5.8.0 is also available.  I suggest that you stick to the
production version of 5.6.1 because it is easier to install the
external modules for 5.6.1.

See section 3.0 for information on Cygwin and Bioperl.

1.2 External Modules
====================

The installation documents supply a very comprehensive list of external
dependencies (i.e. see http://www.bioperl.org/Core/external.shtml).  You
do not need to install external modules for the parts of BioPerl that you
do not intend using.

If you are using ActiveState, I recommend first attempting to download
your external modules via the ActiveState Perl Package Manager (PPM).  To
use it, just go to a command-prompt and type ppm while connected to the
internet.  The software will connect to a repository of available modules
that you can install.  For example, to install IO::String you would type:
"install IO::String"

If you are using ActiveState 5.8.0, you will find that some external
modules are not yet available via ppm.  In that case you will have to
download them directly from cpan (http://www.cpan.org) and follow the
specific build procedures for each module.  This is one major reason for
avoiding the ActiveState 5.8.0 version.

1.3 Installing BioPerl
======================

You have two main choices for installing BioPerl.  If you are using
ActiveState you can use ppm to install with the commands:

1.3.1 Older ActiveState PPMs
================================

PPM> set repository bioperl http://bioperl.org/DIST/
PPM> search bioperl             (shows available bioperl versions)
PPM> install bioperl		(will install the default version)

1.3.2 ActiveState PPM3
================================

ppm> repository add bioperl http://bioperl.org/DIST
ppm> search bioperl		(shows available bioperl versions)

This last command returns a numbered list of the available bioperl
versions.
Select the number of the version you wish to install and type:

ppm> install <number>

1.3.3 Download Archive
======================

You can download BioPerl as a compressed archive from:
http://www.bioperl.org/Core/Latest/index.shtml
This archive can be uncompressed with WinZip (or most other Zip
utilities).

Don't worry if you get a warning saying something like "Archive contains
only one file!  Extract and decompress?".  This is just a variation in how
UNIX and Windows software likes to compress files.  Choose yes, and all
will be well.

You will need use nmake, not make, to utilize this approach.

1.3.4. If All Else Fails....
============================

The BioPerl directory tree should be extracted intact (i.e. ensure "Use
Folder Names" is selected in WinZip) and must be placed so that it is in
your @INC path.  It may be easier to extract the directory tree to another
location and moving the \Bio directory to \perl\site\lib

This approach will not install compiled versions of any modules in the
package, and isn't recommended.

1.4 Testing Installation
========================

It is possible to test your BioPerl installation on windows with "make
test", although this requires having a copy of make utility available on
your system.  If you used ppm to install, this step will not be possible
as activestate doesn't install this information.

2.0 Windows-Specific Behaviour
==============================

Items of windows-specific behaviour are listed below.

2.1 Subroutine <name> redefined at <location> Warnings
======================================================

BioPerl does not get along particularly nicely with the PERL -w flag on
windows systems.  The sample script below shows what happens with many
scripts:

test.pl
###############################################
use Bio::ClusterIO;
my $stream = Bio::ClusterIO->new(
		'-file'		=> $ARGV[0],
		'-format'	=> 'UniGene',
		);
###############################################

c:\> perl -w test.pl Hs.Data
Subroutine new redefined at C:/Perl/site/lib/Bio\Cluster\UniGene.pm line
222.
Subroutine unigene_id redefined at C:/Perl/site/lib/Bio\Cluster\UniGene.pm
line 284.
Subroutine title redefined at C:/Perl/site/lib/Bio\Cluster\UniGene.pm line
306.
Subroutine gene redefined at C:/Perl/site/lib/Bio\Cluster\UniGene.pm line
327.
Subroutine cytoband redefined at C:/Perl/site/lib/Bio\Cluster\UniGene.pm
line 345.
Subroutine mgi redefined at C:/Perl/site/lib/Bio\Cluster\UniGene.pm line
362.
Subroutine locuslink redefined at C:/Perl/site/lib/Bio\Cluster\UniGene.pm
line 390.
Subroutine gnm_terminus redefined at
C:/Perl/site/lib/Bio\Cluster\UniGene.pm line 420.
Subroutine scount redefined at C:/Perl/site/lib/Bio\Cluster\UniGene.pm
line 436.
<and many more like this>

These warnings messages are basically the result of the windows version of
PERL being more cautious than other versions.  These are only warnings
messages, and can safely be ignored.  For production code, you can remove
the -w flag and you will not receive these warnings.

2.2 Consed
==========
The consed module cannot be run under Windows.

3.0 BioPerl in Cygwin
=====================

Cygwin is a Unix emulator and shell environment available free at
www.cygwin.com. BioPerl v. 1.* runs perfectly well within Cygwin. The
only known problem is that DBD::mysql can be tricky to install in
Cygwin and this module is required for the bioperl-db, biosql, and 
bioperl-pipeline external packages. Fortunately there's some good 
instructions online:
http://search.cpan.org/src/JWIED/DBD-mysql-2.1025/INSTALL.html#windows/cygwin.

To get Bioperl running first install the basic Cygwin package as well
as the Cygwin Perl, make, and gcc packages. Clicking the "View" button
in the upper left of the installer enables you to see details on the
various packages. Then follow the BioPerl installation instructions
for Unix in BioPerl's INSTALL file.

One advantage of using Cygwin and Bioperl is that all the external 
modules are available - the same cannot be said of ActiveState's Perl.

=========================================================================
