INSTALL

   1 BIOPERL INSTALLATION
   2
   3 The following are instructions for installing BioPerl on
   4 Unix, Linux, and Mac OS X. Windows installation instructions can be
   5 found in INSTALL.WIN.
   6
   7
   8 SYSTEM REQUIREMENTS
   9
  10     * Perl 5.6.1 or later; version 5.8 and greater are highly
  11       recommended. Modules are generally tested against perl 5.8 and
  12       above.
  13     * make. For Mac OS X, this requires installing the Xcode Developer
  14       Tools.
  15
  16
  17 PRELIMINARY PREPARATION
  18
  19 These are optional, but regardless of your subsequent choice of
  20 installation method, it will help to carry out the following steps.
  21 They will increase the likelyhood of installation success
  22 (especially of optional dependencies).
  23
  24      * Upgrade CPAN:
  25
  26  >perl -MCPAN -e shell
  27  cpan>install Bundle::CPAN
  28
  29      * Install/upgrade Module::Build, and make it your preferred
  30        installer:
  31
  32  >cpan
  33  cpan>install Module::Build
  34  cpan>o conf prefer_installer MB
  35  cpan>o conf commit
  36
  37      * Install the expat library by whatever method is
  38        appropriate for your system (e.g. yum, homebrew).
  39
  40
  41 INSTALLING BIOPERL THE EASY WAY USING CPAN
  42
  43 You can use the CPAN shell to install BioPerl. For example:
  44
  45  >perl -MCPAN -e shell
  46
  47 Or you might have the cpan alias installed:
  48
  49  >cpan
  50
  51 Then find the name of the latest BioPerl package:
  52
  53  cpan>d /bioperl/
  54
  55  ....
  56
  57 Distribution    CJFIELDS/BioPerl-1.6.901.tar.gz
  58 Distribution    CJFIELDS/BioPerl-1.6.922.tar.gz
  59 Distribution    CJFIELDS/BioPerl-1.6.923.tar.gz
  60
  61 And install:
  62
  63  cpan>install CJFIELDS/BioPerl-1.6.923.tar.gz
  64
  65 If you've installed everything perfectly and all the network
  66 connections are working then you will pass all the tests run in the
  67 './Build test' phase. Sometimes you may see a failed test. Remember that
  68 there are over 900 modules in BioPerl and the test suite is running more
  69 than 12000 individual tests, a failed test may not affect your usage
  70 of BioPerl.
  71
  72 If there's a failed test and you think that the failed test will not
  73 affect how you intend to use BioPerl then do:
  74
  75  cpan>force install C/CJ/CJFIELDS/BioPerl-1.6.923.tar.gz
  76
  77 If you're concerned about a failed test and need assistance or advice
  78 then contact bioperl-l@bioperl.org, and provide us the detailed
  79 results of the failed install.
  80
  81
  82 INSTALLING BIOPERL FROM GITHUB
  83
  84 The very latest version of Bioperl is at github.com. If you want this
  85 version then download it from https://github.com/bioperl/bioperl-live
  86 as a *zip file, or retrieve it using the command line:
  87
  88  >git clone https://github.com/bioperl/bioperl-live.git
  89  >cd bioperl-live
  90
  91 If you've downloaded the *zip file then unzip that and cd to the
  92 BioPerl directory.
  93
  94 Issue the build commands:
  95
  96  >perl Build.PL
  97
  98 You will be asked a few questions about installing BioPerl scripts
  99 and running various test suites, hit <return> to accept the defaults.
 100
 101 Test and install:
 102
 103  >./Build test
 104  >./Build install
 105
 106 You may need root permissions in order to run './Build install', so you
 107 will want to talk to your systems manager if you don't have the necessary
 108 privileges.
 109
 110 It is also straightforward to install the package in your own home
 111 directory, see INSTALLING BIOPERL USING local::lib, below.
 112
 113
 114 INSTALLING BIOPERL USING local::lib
 115
 116 If you lack permission to install Perl modules into the standard
 117 system directories you can install them in your home directory
 118 using local::lib. The instructions for first installing
 119 local::lib are found here:
 120
 121 http://search.cpan.org/search?query=local%3A%3Alib
 122
 123 Once local::lib is installed you can install BioPerl using a
 124 command like this:
 125
 126  >perl -MCPAN -Mlocal::lib -e 'CPAN::install(C/CJ/CJFIELDS/BioPerl-1.6.923.tar.gz)'
 127
 128
 129 EXTERNAL PROGRAMS
 130
 131 BioPerl can interface with some external programs for executing
 132 analyses. These include clustalw and t_coffee for Multiple Sequence
 133 Alignment (Bio::Tools::Run::Alignment::Clustalw and
 134 Bio::Tools::Run::Alignment::TCoffee) and blastall, blastpgp, and
 135 bl2seq for BLAST analyses (Bio::Tools::Run::StandAloneBlast), and to
 136 all the programs in the EMBOSS suite (Bio::Factory::EMBOSS).  Most
 137 of the modules which 'wrap' these programs are located in the separate
 138 bioperl-run distribution; however, two commonly-used modules are still
 139 distributed with the BioPerl core (Bio::Tools::Run::StandAloneBlast,
 140 Bio::Tools::Run::RemoteBlast).
 141
 142     * Environment Variables
 143
 144 Some modules which run external programs need certain environment
 145 variables set. If you do not have a local copy of the specific
 146 executable you do not need to set these variables. Additionally the
 147 modules will attempt to locate the specific applications in your
 148 runtime PATH variable. You may also need to set an environment
 149 variable to tell BioPerl about your network configuration if your site
 150 uses a firewall.
 151
 152 Setting environment variables on unix means adding lines like the
 153 following to your shell *rc file.
 154
 155    For bash or sh:
 156
 157  export BLASTDIR=/data1/blast
 158
 159    For csh or tcsh:
 160
 161  setenv BLASTDIR /data1/blast
 162
 163 Some environment variables include:
 164
 165 +------------------------------------------------------------------------+
 166 | Env. Variable |                      Description                       |
 167 |---------------+--------------------------------------------------------|
 168 |               |Specifies where the NCBI blastall, blastpgp, bl2seq,    |
 169 |BLASTDIR       |etc.. are located. A 'data' directory could also be     |
 170 |               |present in this directory as well, you could put your   |
 171 |               |blastable databases here.                               |
 172 |---------------+--------------------------------------------------------|
 173 |               |If one does not want to locate the data dir within the  |
 174 |BLASTDATADIR or|same dir as where the BLASTDIR variable points, a       |
 175 |BLASTDB        |BLASTDATADIR or BLASTDB variable can be set to point to |
 176 |               |a dir where BLAST database indexes are located.         |
 177 |---------------+--------------------------------------------------------|
 178 |BLASTMAT       |The directory containing the substitution matrices such |
 179 |               |as BLOSUM62.                                            |
 180 |---------------+--------------------------------------------------------|
 181 |CLUSTALDIR     |The directory where the clustalw executable is located. |
 182 |---------------+--------------------------------------------------------|
 183 |TCOFFEEDIR     |The directory where the t_coffee executable is located. |
 184 |---------------+--------------------------------------------------------|
 185 |               |If you access the internet via a proxy server then you  |
 186 |               |can tell the BioPerl modules which require network      |
 187 |               |access about this by using the http_proxy environment   |
 188 |http_proxy     |variable. The value set includes the proxy address and  |
 189 |               |the port, with optional username/password for           |
 190 |               |authentication purposes                                 |
 191 |               |(e.g. http://USERNAME:PASSWORD@proxy.example.com:8080). |
 192 +------------------------------------------------------------------------+
 193
 194
 195 INSTALLING BIOPERL SCRIPTS
 196
 197 BioPerl comes with a set of production-quality scripts that are
 198 kept in the scripts/ directory. You can install these scripts if you'd
 199 like, simply answer the questions during 'perl Build.PL'.
 200 The installation directory can be specified by:
 201
 202  perl Build.PL
 203  ./Build install --install_path script=/foo/scripts
 204
 205 By default they install to /usr/bin or similar, depending on platform.
 206
 207
 208 THE TEST SYSTEM
 209
 210 The BioPerl test system is located in the t/ directory and is
 211 automatically run whenever you execute the './Build test' command.
 212
 213 For the 1.6 release and beyond, tests have been organized into groups
 214 based upon the specific task or class the module being tested belongs
 215 to. If you want to investigate the behavior of a specific test such as
 216 the Seq test you would type:
 217
 218  >./Build test --test_files t/Seq/Seq.t --verbose
 219
 220 The --test_files argument can be used multiple times to try a set of test
 221 scripts in one go. The --verbose arguement outputs the detailed test results,
 222 instead of just the summary you see during './Build test'.
 223
 224 The '--test-files' argument can also work as a glob. For instance, to
 225 run tests on all SearchIO modules, use the following:
 226
 227  >./Build test --test_files t/SearchIO* --verbose
 228
 229 If you are trying to learn how to use a module, often the test suite
 230 is a good place to look. All good extreme programmers try and write a
 231 test BEFORE they write the module to insure that their module behaves
 232 the way they expect. You'll notice some 'ok' and 'skip' commands in a
 233 test, this is part of the Perl test suite that signifies a passed test
 234 with an 'ok N', where N is the test number. Alternatively you can tell
 235 Perl to skip tests. This is useful when, for example, your test
 236 detects that the network is not present and thus should skip, not
 237 fail, any tests that require a network connection.
 238
 239 The core developers have indicated that future releases of BioPerl
 240 will require that new modules come with a test suite with some minimal
 241 tests.  Modules that lack adequate tests or could otherwise be
 242 considered 'unstable' will be moved into a separate developer
 243 distribution until adequate tests are added and the API stablizes.