INSTALL-WIN.md

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