INSTALL-WIN.md

   1
   2                          Installing Bioperl on Windows
   3
   4    Contents
   5
   6      * 1 Introduction
   7      * 2 Perl Options
   8      * 3 Installing Perl on Windows
   9      * 4 CPAN for Strawberry Perl and ActivePerl
  10      * 5 Bioperl in Cygwin
  11
  12 1 Introduction
  13
  14 This installation guide was written by Barry Moore, Nathan Haigh
  15 and other Bioperl authors based on the original work of Paul Boutros. The
  16 guide has been updated by Paul Cantalupo and Francisco Ossandon.
  17 *Note* For Windows it is recommended to install BioPerl version 1.6.924 or
  18 newer, since many Windows-specific bugs from previous versions were fixed.
  19
  20 Please report problems and/or fixes to the BioPerl mailing list.
  21
  22 2 Perl Options
  23
  24 There are a couple of ways of installing Perl on a Windows machine. One is
  25 to get the most recent build from [Strawberry Perl](http://strawberryperl.com/)
  26 and the other is to get it from [ActiveState](http://www.activestate.com/).
  27 Both are software companies that provide free builds of Perl for Windows
  28 users.
  29
  30 Strawberry Perl is recommended since is more CPAN-friendly and
  31 because it includes a compiler (gcc), related tools and other external
  32 libraries. These installation steps were verified on December 2015 using
  33 ActivePerl 5.20.2.2002 (5.22 has been released but the MinGW package is not
  34 available for it yet) and Strawberry Perl 5.22.0.1 from a clean install.
  35
  36 *Note* Only ActivePerl **5.18 or greater** is supported by the BioPerl team.
  37 This is because the necessary MinGW package needed for CPAN installations
  38 is only available for both 32-bit and 64-bit Windows since this version
  39 (32-bit was available on previous versions but only in the Business edition,
  40 see [ActivePerl MinGW PPM webpage](http://www.activestate.com/activeperl/downloads)).
  41
  42 *Note* Support for installation through ActivePerl Perl Package Manager has been dropped in favor of CPAN.
  43
  44 3 Installing Perl on Windows
  45
  46 1. Download the [Strawberry Perl MSI](http://strawberryperl.com/releases.html) or [ActivePerl MSI](http://www.activestate.com/activeperl/downloads).
  47 2. Run the Installer (accepting all defaults is fine).
  48
  49 You can also build Perl yourself (which requires a C compiler). The Perl
  50 source for building it yourself is available from [CPAN](http://www.cpan.org/).
  51 This approach is not recommended unless you have specific reasons for doing so
  52 and know what you're doing.
  53
  54 [Cygwin](http://en.wikipedia.org/wiki/Cygwin) is a [UNIX](http://en.wikipedia.org/wiki/UNIX)
  55 emulation environment for Windows and comes with its own copy of Perl. Information on Cygwin and Bioperl is found below.
  56
  57 ### Installation using the ActiveState Perl Package Manager
  58
  59 This installation is not supported nor recommended anymore, because the last
  60 BioPerl package produced for it was the old version 1.6.1 (2009) and many
  61 Windows-specific bugs were fixed in more recent versions 1.6.923 and 1.6.924.
  62 Please install using the CPAN instructions below.
  63
  64 4 CPAN for Strawberry Perl and ActivePerl
  65
  66 Both CPAN and manual methods ultimately need the accessory compiling program
  67 MinGW, which incorporates the necessary tools like dmake and gcc. MinGW comes
  68 by default with Strawberry Perl, but must it be installed through PPM for
  69 ActivePerl (CPAN will display a warning if not present). Also, CPAN need to be
  70 upgraded to >= v1.81, [Module::Build](https://metacpan.org/pod/Module::Build)
  71 to be upgraded (>= v0.2805) and [Test::Harness](https://metacpan.org/pod/Test::Harness) to be upgraded to >= v2.62.
  72
  73 ### Dmake for ActivePerl
  74
  75 1) Install MinGW package through PPM: Using a cmd window type
  76
  77 `ppm install MinGW`.
  78
  79 It is `important` to check if ActiveState provides the
  80 [MinGW package](http://code.activestate.com/ppm/MinGW/) for your ActivePerl version,
  81 since each version have to wait its own release. For example,
  82 although MinGW has been available since ActivePerl version 5.18,
  83 the release for newest version 5.22 it's still not available (December 2015).
  84
  85 ### Start the install with CPAN
  86
  87 1) Open a cmd window by going to `Start >> Run` and typing `cmd`
  88 into the box and pressing return.
  89
  90 2) Type `cpan` to enter the CPAN shell.
  91
  92 3) At the `cpan>` prompt, type `install CPAN` to upgrade to the
  93 latest version.
  94
  95 4) Quit (by typing 'q') and reload CPAN. You may be asked some
  96 configuration questions; accepting defaults is fine.
  97
  98 5) At the `cpan>` prompt, type `o conf prefer_installer MB` to tell
  99 CPAN to prefer to use `Build.PL` scripts for installation, and the type `o conf commit` to save that choice.
 100
 101 6) At the `cpan>` prompt, type `install Module::Build`.
 102
 103 7) At the `cpan>` prompt, type `install Test::Harness`.
 104
 105 8) At the `cpan>` prompt, type `install Test::Most`.
 106
 107 ### Finish the install with CPAN
 108
 109 You can now follow the instructions INSTALLING BIOPERL THE EASY WAY
 110 USING CPAN in the INSTALL file.
 111
 112 ### Finish the install with BioPerl from GitHub
 113
 114 For the bleeding edge version install manually using a ZIP file from the
 115 GitHub repository:
 116
 117 1) Go to [GitHub](https://github.com/bioperl/bioperl-live) and press the
 118 `Download ZIP` button.
 119
 120 2) Extract the archive in the normal way.
 121
 122 3) In a cmd window `cd` to the directory you extracted to. Eg. if
 123 you extracted to directory 'bioperl-live', `cd bioperl-live`
 124
 125 4) Type `perl Build.PL` and answer the questions appropriately.
 126
 127 5) Type `perl Build test`. All the tests should pass, but if they don't,
 128 [let us know](https://github.com/bioperl/bioperl-live/issues). Your usage of
 129 Bioperl may not be affected by the failure, so you can choose to continue
 130 anyway.
 131
 132 6) Type `perl Build install` to install Bioperl.
 133
 134 5 Bioperl in Cygwin
 135
 136 Cygwin is a Unix emulator and shell environment available free at
 137 http://www.cygwin.com. Some users claim that installation of Bioperl is
 138 easier within Cygwin than within Windows, but these may be users with UNIX
 139 backgrounds. A note on Cygwin: it doesn't write to your Registry, it doesn't
 140 alter your system or your existing files in any way, it doesn't create
 141 partitions, it simply creates a *cygwin/* directory and writes all of its
 142 files to that directory. To uninstall Cygwin just delete that directory.
 143
 144 To get Bioperl running first install the basic Cygwin package as well as
 145 the Cygwin `perl`, `make`, `binutils`, and `gcc` packages. Clicking the View
 146 button in the upper right of the installer window enables you to see
 147 details on the various packages. Then start up Cygwin and follow the
 148 Bioperl installation instructions for UNIX in Bioperl's INSTALL file.
 149
 150 Cygwin paths
 151
 152 If you're trying to use some application or resource outside of the Cygwin
 153 directory and you're having a problem remember that Cygwin's path syntax
 154 may not be the correct one. Cygwin understands */home/jacky* or
 155 */cygdrive/e/cygwin/home/jacky* (when referring to the E: drive) but the
 156 external resource may want *E:/cygwin/home/jacky*. So your *rc files may end
 157 up with paths written in these different syntaxes, depending.
 158
 159 For example, here's how to set the environmental variable TMPDIR, programs
 160 like BLAST and clustalw need a place to create temporary files:
 161
 162      setenv TMPDIR e:/cygwin/tmp    # csh, tcsh
 163      export TMPDIR=e:/cygwin/tmp    # sh, bash