[bug 2707]

[bioperl-live.git] / INSTALL.WIN

# $Id: INSTALL.WIN,v 1.25 2006-12-06 17:42:27 cjfields Exp $

                         Installing Bioperl on Windows

   Contents

     * 1 Introduction
     * 2 Requirements
     * 3 Installation using the Perl Package Manager
     
          * 3.1 GUI Installation
          * 3.2 Comand-line Installation
          
     * 4 Installation using CPAN or manual installation
     * 5 Bioperl
     * 6 Perl on Windows
     * 7 Bioperl on Windows
     * 8 Beyond the Core

          * 8.1 Setting environment variables
          * 8.2 Installing bioperl-db

     * 9 Bioperl in Cygwin
     * 10 bioperl-db in Cygwin
     * 11 Cygwin tips
     * 12 MySQL and DBD::mysql
     * 13 Expat
     * 14 Directory for temporary files
     * 15 BLAST
     * 16 Compiling C code

Introduction

   This installation guide was written by Barry Moore, Nathan Haigh
   and other Bioperl authors based on the original work of Paul Boutros. The
   guide was updated for the BioPerl wiki by Chris Fields and Nathan
   Haigh.

   Please report problems and/or fixes to the BioPerl mailing list.
   
   An up-to-date version of this document can be found on the BioPerl wiki:
   
   http://www.bioperl.org/wiki/Installing_Bioperl_on_Windows

Requirements

   Only ActivePerl >= 5.8.8.819 is supported by the Bioperl team. Earlier
   versions may work, but we do not support them.

   One of the reason for this requirement is that ActivePerl >= 5.8.8.819 now
   use Perl Package Manager 4 (PPM4). PPM4 is now superior to earlier
   versions and also includes a Graphical User Interface (GUI). In short,
   it's easier for us to produce and maintain a package for installation via
   PPM and also easier for you to do the install! Proceed with earlier
   versions at your own risk.

   To install ActivePerl:

           1) Download the ActivePerl MSI from ActiveState

           2) Run the ActivePerl Installer (accepting all defaults is fine).

Installation using the Perl Package Manager

  GUI Installation

           1) Start the Perl Package Manager GUI from the Start menu.

           2) Go to Edit >> Preferences and click the Repositories tab. Add a
           new repository for each of the following:

                              Repositories to add
       +----------------------------------------------------------------+
       |           Name           |              Location               |
       |--------------------------+-------------------------------------|
       |BioPerl-Release Candidates|[37]http://bioperl.org/DIST/RC       |
       |--------------------------+-------------------------------------|
       |BioPerl-Regular Releases  |[38]http://bioperl.org/DIST          |
       |--------------------------+-------------------------------------|
       |Kobes                     |[39]http://theoryx5.uwinnipeg.ca/ppms|
       |--------------------------+-------------------------------------|
       |Bribes                    |[40]http://www.Bribes.org/perl/ppm   |
       +----------------------------------------------------------------+


           3) Select View >> All Packages.

           4) In the search box type bioperl.

           5) Right click the latest version of Bioperl available and choose
           install.

           5a) From bioperl 1.5.2 onward, all 'optional' pre-requisites will
           be marked for installation. If you see that some of them complain
           about needing a command-line installation (eg. XML::SAX::ExpatXS),
           and you want those particular pre-requisites, stop now (skip step
           6) and see the 'Command-line Installation' section.

           6) Click the green arrow (Run marked actions) to complete the
           installation.

  Comand-line Installation

           1) Follow steps 1) and 2) from 'GUI Installation' above, if you
           haven't done so already.

           2) Open a cmd window by going to Start >> Run and typing 'cmd' and
           pressing return.

           3) Type the following into the cmd window:
            
             ppm-shell
             search bioperl
             install #

            (where the number matches the bioperl version needed) You can use '-force'
            to force install if needed.

Installation using CPAN or manual installation

   Installation using PPM is preferred since it is easier, but if you run
   into problems, or a ppm isn't available for the version/package of bioperl
   you want, or you want to choose which optional dependencies to install,
   you can install manually by downloading the appropriate package or by
   using CPAN. In fact both methods ultimately need nmake to be
   installed, CPAN to be upgraded to >= v1.81, Module::Build to be installed
   (>= v0.2805) and Test::Harness to be upgraded to >= v2.62:

           1) Download nmake

           2) Double-click to run it, which extracts 3 files. Move both
           NMAKE.EXE and the NMAKE.ERR files to a place in your PATH; if set
           up properly, you can move these to your Perl bin directory,
           normally C:\Perl\bin.

           1) Open a cmd window by going to Start >> Run and typing 'cmd'
           into the box and pressing return.

           2) Type 'cpan' to enter the CPAN shell.

           3) At the cpan> prompt, type 'install CPAN' to upgrade to the
           latest version.

           4) Quit (by typing 'q') and reload cpan. You may be asked some
           configuration questions; accepting defaults is fine.

           5) At the cpan> prompt, type 'o conf prefer_installer MB' to tell
           CPAN to prefer to use Build.PL scripts for installation. Type 'o
           conf commit' to save that choice.

           6) At the cpan> prompt, type 'install Module::Build'.

           7) At the cpan> prompt, type 'install Test::Harness'.

   You can now follow the unix instructions for installing using CPAN, or
   install manually:

           8) Download the .zip version of the package you want.

           9) Extract the archive in the normal way.

           10) In a cmd window 'cd' to the directory you extracted to. Eg. if
           you extracted to directory 'Temp', 'cd Temp\bioperl-1.5.2_100'

           11) Type 'perl Build.PL' and answer the questions appropriately.

           12) Type 'perl Build test'. All the tests should pass, but if they
           don't, let us know. Your usage of Bioperl may not be affected
           by the failure, so you can choose to continue anyway.

           13) Type 'perl Build install' to install Bioperl.

Bioperl

   Bioperl is a large collection of Perl modules (extensions to the
   Perl language) that aid in the task of writing Perl code to deal
   with sequence data in a myriad of ways. Bioperl provides objects for
   various types of sequence data and their associated features and
   annotations. It provides interfaces for analysis of these sequences with a
   wide variety of external programs (BLAST, FASTA, clustalw and
   EMBOSS to name just a few). It provides interfaces to various types of
   databases both remote (GenBank, EMBL etc) and local (MySQL,
   Flat_databases flat files, GFF etc.) for storage and retrieval of
   sequences. And finally with its associated documentation and
   mailing lists, Bioperl represents a community of bioinformatics
   professionals working in Perl who are committed to supporting both
   development of Bioperl and the new users who are drawn to the project.

   While most bioinformatics and computational biology applications are
   developed in UNIX/Linux environments, more and more programs are
   being ported to other operating systems like Windows, and many users
   (often biologists with little background in programming) are looking for
   ways to automate bioinformatics analyses in the Windows environment.

   Perl and Bioperl can be installed natively on Windows NT/2000/XP.
   Most of the functionality of Bioperl is available with this type of
   install. Much of the heavy lifting in bioinformatics is done by programs
   originally developed in lower level languages like C and Pascal
   (e.g. BLAST, clustalw, Staden etc). Bioperl simply acts as
   a wrapper for running and parsing output from these external programs.

   Some of those programs (BLAST for example) are ported to Windows.
   These can be installed and work quite happily with Bioperl in the native
   Windows environment. Some external programs such as Staden and the
   EMBOSS suite of programs can only be installed on Windows by using
   Cygwin and its gcc C compiler (see Bioperl in Cygwin, below).
   Recent attempts to port EMBOSS to Windows, however, have been mostly
   successful.

   If you have a fairly simple project in mind, want to start using Bioperl
   quickly, only have access to a computer running Windows, and/or don't mind
   bumping up against some limitations then Bioperl on Windows may be a
   good place for you to start. For example, downloading a bunch of sequences
   from GenBank and sorting out the ones that have a particular
   annotation or feature works great. Running a bunch of your sequences
   against remote or local BLAST, parsing the output and storing it
   in a MySQL database would be fine also.

   Be aware that most Bioperl developers are working in some type of a
   UNIX environment (Linux, OS X, Cygwin). If you have
   problems with Bioperl that are specific to the Windows environment, you
   may be blazing new ground and your pleas for help on the Bioperl mailing
   list may get few responses (you can but try!) - simply because no one
   knows the answer to your Windows specific problem. If this is or becomes a
   problem for you then you are better off working in some type of UNIX-like
   environment. One solution to this problem that will keep you working on a
   Windows machine it to install Cygwin, a UNIX emulation environment for
   Windows. A number of Bioperl users are using this approach successfully
   and it is discussed in more detail below.

Perl on Windows

   There are a couple of ways of installing Perl on a Windows machine. The
   most common and easiest is to get the most recent build from
   ActiveState, a software company that provides free builds of Perl for
   Windows users. The current (October 2006) build is ActivePerl 5.8.8.819.
   Bioperl also works on Perl 5.6.x, but due to installation problems etc,
   only ActivePerl 5.8.8.819 or later is supported for WinXP installation.
   To install ActivePerl on Windows:

           1) Download the ActivePerl MSI from
           http://www.activestate.com/Products/ActivePerl/.

           2) Run the ActivePerl Installer (accepting all defaults is fine).

   You can also build Perl yourself (which requires a C compiler) or download
   one of the other binary distributions. The Perl source for building it
   yourself is available from CPAN, as are a few other binary
   distributions that are alternatives to ActiveState. This approach is not
   recommended unless you have specific reasons for doing so and know what
   you're doing. If that's the case you probably don't need to be reading
   this guide.

   Cygwin is a UNIX emulation environment for Windows and comes with
   its own copy of Perl.

   Information on Cygwin and Bioperl is found below.

Bioperl on Windows

   Perl is a programming language that has been extended a lot by the
   addition of external modules.

   These modules work with the core language to extend the functionality of
   Perl.

   Bioperl is one such extension to Perl. These modular extensions to
   Perl sometimes depend on the functionality of other Perl modules and this
   creates a dependency. You can't install module X unless you have already
   installed module Y. Some Perl modules are so fundamentally useful that the
   Perl developers have included them in the core distribution of Perl - if
   you've installed Perl then these modules are already installed. Other
   modules are freely available from CPAN, but you'll have to install them
   yourself if you want to use them. Bioperl has such dependencies.

   Bioperl is actually a large collection of Perl modules (over 1000
   currently) and these modules are split into seven packages. These seven
   packages are:

   +------------------------------------------------------------------------+
   |    Bioperl Group     |                    Functions                    |
   |----------------------+-------------------------------------------------|
   |bioperl (the core)    |Most of the main functionality of Bioperl        |
   |----------------------+-------------------------------------------------|
   |bioperl-run           |Wrappers to a lot of external programs           |
   |----------------------+-------------------------------------------------|
   |bioperl-ext           |Interaction with some alignment functions and the|
   |                      |Staden package                                   |
   |----------------------+-------------------------------------------------|
   |bioperl-db            |Using Bioperl with BioSQL and local relational   |
   |                      |databases                                        |
   |----------------------+-------------------------------------------------|
   |bioperl-microarray    |Microarray specific functions                    |
   |----------------------+-------------------------------------------------|
   |bioperl-pedigree      |manipulating genotype, marker, and individual    |
   |                      |data for linkage studies                         |
   |----------------------+-------------------------------------------------|
   |bioperl-gui           |Some preliminary work on a graphical user        |
   |                      |interface to some Bioperl functions              |
   +------------------------------------------------------------------------+

   The Bioperl core is what most new users will want to start with. Bioperl
   (the core) and the Perl modules that it depends on can be easily installed
   with the perl package Manager PPM. PPM is an ActivePerl utility for
   installing Perl modules on systems using ActivePerl. PPM will look online
   (you have to be connected to the internet of course) for files (these
   files end with .ppd) that tell it how to install the modules you want and
   what other modules your new modules depends on. It will then download and
   install your modules and all dependent modules for you.

   These .ppd files are stored online in PPM repositories. ActiveState
   maintains the largest PPM repository and when you installed ActivePerl PPM
   was installed with directions for using the ActiveState repositories.
   Unfortunately the ActiveState repositories are far from complete and other
   ActivePerl users maintain their own PPM repositories to fill in the gaps.
   Installing will require you to direct PPM to look in three new
   repositories as detailed in Installation Guide.

   Once PPM knows where to look for Bioperl and it's dependencies you simply
   tell PPM to search for packages with a particular name, select those of
   interest and then tell PPM to install the selected packages.

Beyond the Core

   You may find that you want some of the features of other Bioperl groups
   like bioperl-run or bioperl-db. Currently, plans include setting up PPM
   packages for installing these parts of Bioperl; check this by doing a
   Bioperl search in PPM.  If these are not available, though, you can use
   the following instructions for installing the other distributions.

   For this you will need a Windows version of the program make
   called nmake:

   http://download.microsoft.com/download/vc15/Patch/1.52/W95/EN-US/Nmake15.exe

   You will also want to have a willingness to experiment. You'll have to
   read the installation documents for each component that you want to
   install, and use nmake where the instructions call for make, like so:

 perl Makefile.PL
 nmake
 nmake test
 nmake install

   'nmake test' will likely produce lots of warnings, many of these can be
   safely ignored (these stem from the excessively paranoid '-w' flag in
   ActivePerl). You will have to determine from the installation documents
   what dependencies are required, and you will have to get them, read their
   documentation and install them first. It is recommended that you look
   through the PPM repositories for any modules before resorting to using
   nmake as there isn't any guarantee modules built using nmake will work.
   The details of this are beyond the scope of this guide. Read the
   documentation. Search Google. Try your best, and if you get stuck consult
   with others on the BioPerl mailing list.

    Setting environment variables

   Some modules and tools such as Bio::Tools::Run::StandAloneBlast and
   clustal_w, require that environment variables are set; a few examples
   are listed in the INSTALL document. Different versions of Windows utilize
   different methods for setting these variables. NOTE: The instructions that
   comes with the BLAST executables for setting up BLAST on Windows are
   out-of-date. Go to the following web address for instructions on setting
   up standalone BLAST for Windows:
   http://www.ncbi.nlm.nih.gov/staff/tao/URLAPI/pc_setup.html

     * For Windows XP, go here. This does not require a reboot but all
       active shells will not reflect any changes made to the environment.
     * For older versions (Windows 95 to ME), generally editing the
       C:\autoexec.bat file to add a variable works. This requires a reboot.
       Here's an example:

 set BLASTDB=C:\blast\data

   For either case, you can check the variable this way:

 C:\Documents and Settings\Administrator>echo %BLASTDB%
 C:\blast\data

   Some versions of Windows may have problems differentiating forward and
   back slashes used for directories. In general, always use backslashes (\).
   If something isn't working properly try reversing the slashes to see if it
   helps.

   For setting up Cygwin environment variables quirks, see an example
   below.

    Installing bioperl-db

   bioperl-db now works for Windows w/o installing CygWin. This has
   primarily been tested on WinXP using MySQL5, but it is expected that other
   bioperl-db supported databases (PostgreSQL, Oracle) should work.

   You will need Bioperl rel. 1.5.2, a relational database (I use MySQL5 here
   as an example), and the Perl modules DBI and DBD::mysql, which
   can be installed from PPM as desribed above (make sure the additional
   repositories for Kobes and Bribes are added, they will have the latest
   releases). Do NOT try using nmake with these modules as they will not
   build correctly under Windows! The PPM builds, by Randy Kobes, have been
   modified and tested specifically for Windows and ActivePerl.

   NOTE: we plan on having a PPM for bioperl-db available along with the
   regular bioperl 1.5.2 release PPM. We will post instructions at that
   time on using PPM to install bioperl-db.

   To begin, follow instructions detailed in the Installation Guide for
   adding the three new repositories (Bioperl, Kobes and Bribes). Then
   install the following packages:

           1) DBI
           2) DBD-mysql

   The next step involves creating a database. The following steps are for
   MySQL5:

 >mysqladmin -u root -p create bioseqdb
 Enter password: **********

   The database needs to be loaded with the BioSQL schema, which can be
   downloaded as a tarball here.

 >mysql -u root -p bioseqdb < biosqldb-mysql.sql
 Enter password: **********

   Download bioperl-db from CVS. Use the following to install the
   modules:

 perl Makefile.PL
 nmake

   Now, for testing out bioperl-db, make a copy of the file
   DBHarness.conf.example in the bioperl-db test subdirectory (bioperl-db\t).
   Rename it to DBHarness.biosql.conf, and modify it for your database setup
   (particularly the user, password, database name, and driver). Save the
   file, change back to the main bioperl-db directory, and run 'nmake test'.
   You may see lots of the following lines,

 ....
 Subroutine Bio::Annotation::Reference::(eq redefined at C:/Perl/lib/overload.pm line 25,
     <GEN0> line 1.
 Subroutine new redefined at C:\Perl\src\bioperl\bioperl-live/Bio\Annotation\Reference.pm line 80,
     <GEN0> line 1.
 ....

   which can be safely ignored (again, these come from ActivePerl's paranoid
   '-w' flag). All tests should pass. NOTE : tests should be run with
   a clean database with the BiOSQL schema loaded, but w/o taxonomy loaded
   (see below).

   To install, run:

 nmake install

   It is recommended that you load the taxonomy database using the script
   load_ncbi_taxonomy.pl included in biosql-schema\scripts. You will need to
   download the latest taxonomy files. This can be accomplished using the
   -download flag in load_ncbi_taxonomy.pl, but it will not 'untar' the file
   correctly unless you have GNU tar present in your PATH (which most Windows
   users will not have), thus causing the following error:

 >load_ncbi_taxonomy.pl -download -driver mysql -dbname bioseqdb -dbuser root -dbpass **********
 The system cannot find the path specified.
 Loading NCBI taxon database in taxdata:
         ... retrieving all taxon nodes in the database
         ... reading in taxon nodes from nodes.dmp
 Couldn't open data file taxdata/nodes.dmp: No such file or directory rollback ineffective with
 AutoCommit enabled at C:\Perl\src\bioperl\biosql-schema\scripts\load_ncbi_taxonomy.pl line 818.
 Rollback ineffective while AutoCommit is on at
 C:\Perl\src\bioperl\biosql-schema\scripts\load_ncbi_taxonomy.pl line 818.
 rollback failed: Rollback ineffective while AutoCommit is on

   Use a file decompression utility like 7-Zip to 'untar' the files in
   the folder (if using 7-Zip, this can be accomplished by right-clicking on
   the file and using the option 'Extract here'). Rerun the script without
   the -download flag to load the taxonomic information. Be patient, as this
   can take quite a while:

 >load_ncbi_taxonomy.pl -driver mysql -dbname bioseqdb -dbuser root -dbpass **********

 Loading NCBI taxon database in taxdata:
         ... retrieving all taxon nodes in the database
         ... reading in taxon nodes from nodes.dmp
         ... insert / update / delete taxon nodes
         ... (committing nodes)
         ... rebuilding nested set left/right values
         ... reading in taxon names from names.dmp
         ... deleting old taxon names
         ... inserting new taxon names
         ... cleaning up
 Done.

   Now, load the database with your sequences using the script
   load_seqdatabase.pl, in bioperl-db's bioperl-db\script directory:

 C:\Perl\src\bioperl\bioperl-db\scripts\biosql>load_seqdatabase.pl -drive mysql
                               -dbname bioseqdb -dbuser root -dbpass **********
 Loading NP_249092.gpt ...
 Done.

   You may see occasional errors depending on the sequence format, which is a
   non-platform-related issue. Many of these are due to not having an updated
   taxonomic database and may be rectified by updating the taxonomic
   information as detailed in load_ncbi_taxonomy.pl's POD.

   Thanks to Baohua Wang, who found the initial Windows-specific problem in
   Bio::Root::Root that led to this fix, to Sendu Bala for fixing
   Bug #1938, and to Hilmar Lapp for his input.

Bioperl in Cygwin

   Cygwin is a Unix emulator and shell environment available free at
   http://www.cygwin.com. Bioperl v. 1.* supposedly runs well within Cygwin,
   though the latest release has not been tested with Cygwin yet. Some
   users claim that installation of Bioperl is easier within Cygwin than
   within Windows, but these may be users with UNIX backgrounds. A note on
   Cygwin: it doesn't write to your Registry, it doesn't alter your system or
   your existing files in any way, it doesn't create partitions, it simply
   creates a cygwin/ directory and writes all of its files to that directory.
   To uninstall Cygwin just delete that directory.

   One advantage of using Bioperl in Cygwin is that all the external modules
   are available through CPAN - the same cannot be said of ActiveState's PPM
   utility.

   To get Bioperl running first install the basic Cygwin package as well as
   the Cygwin perl, make, binutils, and gcc packages. Clicking the View
   button in the upper right of the installer window enables you to see
   details on the various packages. Then start up Cygwin and follow the
   Bioperl installation instructions for UNIX in Bioperl's INSTALL file
   (for example, THE BIOPERL BUNDLE and INSTALLING BIOPERL THE EASY WAY USING
   CPAN).

bioperl-db in Cygwin

   This package is installed using the instructions contained in the package,
   without modification. Since postgres is a package within Cygwin this is
   probably the easiest of the 3 platforms supported in bioperl-db to
   install (postgres, Mysql, Oracle).

Cygwin tips

   If you can, install Cygwin on a drive or partition that's
   NTFS-formatted, not FAT32-formatted. When you install Cygwin on
   a FAT32 partition you will not be able to set permissions and ownership
   correctly. In most situations this probably won't make any difference but
   there may be occasions where this is a problem.

   If you're trying to use some application or resource outside of Cygwin
   directory and you're having a problem remember that Cygwin's path syntax
   may not be the correct one. Cygwin understands /home/jacky or
   /cygdrive/e/cygwin/home/jacky (when referring to the E: drive) but the
   external resource may want E:/cygwin/home/jacky. So your *rc files may end
   up with paths written in these different syntaxes, depending.

MySQL and DBD::mysql

   You may want to install a relational database in order to use BioPerl
   db, BioSQL or OBDA. The easiest way to install Mysql is to use
   the Windows binaries available at http://www.mysql.com. Note that
   Windows does not have sockets, so you need to force the Mysql connections
   to use TCP/IP instead. Do this by using the -h, or host, option from the
   command-line. Example:

 >mysql -h 127.0.0.1 -u <user> -p<password> <database>

   Alternatively you could install postgres instead of MySQL, postgres is
   already a package in Cygwin.

   One known issue 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:

     * Instructions included with DBD::mysql:
     
       http://search.cpan.org/src/JWIED/DBD-mysql-2.1025/INSTALL.html#windows/cygwin
       
     * Additional instructions if you run into any problems; this
       information is more up-to-date, covers post-2.9 DBD::mysql quirks in
       Cygwin.
       
       http://rage.against.org/installingdbdmysqlInCygwin

Expat

   Note that expat comes with Cygwin (it's used by the modules
   XML::Parser and XML::SAX::ExpatXS, which are used by certain
   Bioperl modules).

Directory for temporary files

   Set the environmental variable TMPDIR, programs like BLAST and
   clustalw need a place to create temporary files. e.g.:

 setenv TMPDIR e:/cygwin/tmp     # csh, tcsh
 export TMPDIR=e:/cygwin/tmp    # sh, bash

   This is not the syntax that Cygwin understands, which would be something
   like /cygdrive/e/cygwin/tmp or /tmp, this is the syntax that a Windows
   application expects.

   If this variable is not set correctly you'll see errors like this when you
   run Bio::Tools::Run::StandAloneBlast:

   ------------- EXCEPTION: Bio::Root::Exception -------------
   MSG: Could not open /tmp/gXkwEbrL0a: No such file or directory
   STACK: Error::throw
   ..........

   [edit]

BLAST

   If you want use BLAST we recommend that the Windows binary be obtained
   from NCBI (ftp://ftp.ncbi.nih.gov/blast/executables/LATEST/ - the
   file will be named something like blast-2.2.13-ia32-win32.exe). Then
   follow the Windows instructions in README.bls. You will also need to set
   the BLASTDIR environment variable to reflect the directory which holds the
   blast executable and data folder. You may also want to set other variables
   to reflect the location of your databases and substitution matrices if
   they differ from the location of your blast executables; see
   Installing Bioperl for Unix for more details.

Compiling C code

   Although we've recommended using the BLAST and MySQL binaries
   you should be able to compile just about everything else from source code
   using Cygwin's gcc. You'll notice when you're installing Cygwin that many
   different libraries are also available (gd, jpeg, etc.).