INSTALL

   1 LATEST VERSION
   2
   3 The current version of BioPerl is 1.6.924 (https://metacpan.org/pod/BioPerl).
   4
   5 BIOPERL INSTALLATION
   6
   7 The following are instructions for installing BioPerl on
   8 Unix, Linux, and Mac OS X. Windows installation instructions can be
   9 found in INSTALL.WIN.
  10
  11
  12 SYSTEM REQUIREMENTS
  13
  14  * `Perl 5.6.1 or higher` Version 5.8 or higher is highly
  15    recommended. Modules are tested against version 5.8 and
  16    above.
  17  * `make` For Mac OS X, this requires installing the Xcode Developer
  18    Tools.
  19
  20
  21 PRELIMINARY PREPARATION
  22
  23 These are optional, but regardless of your subsequent choice of
  24 installation method, it will help to carry out the following steps.
  25 They will increase the likelihood of installation success
  26 (especially of the optional dependencies).
  27
  28 * Upgrade CPAN:
  29
  30 perl -MCPAN -e shell
  31
  32 * Install or upgrade `Module::Build`, and make it your preferred installer:
  33
  34 cpan>install Module::Build
  35 cpan>o conf prefer_installer MB
  36 cpan>o conf commit
  37
  38 * Install the *expat* library by whatever method is appropriate for your system (e.g. `apt`, `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.924.tar.gz
  60
  61 And install the most recent:
  62
  63 cpan>install CJFIELDS/BioPerl-1.6.924.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:
 102
 103 ./Build test
 104
 105 Install:
 106
 107 ./Build install
 108
 109 You may need root permissions in order to run `./Build install`, so you
 110 will want to talk to your systems manager if you don't have the necessary
 111 privileges. Or you can install the package in your own home
 112 directory, see INSTALLING BIOPERL USING local::lib.
 113
 114
 115 INSTALLING BIOPERL USING local::lib
 116
 117 If you lack permission to install Perl modules into the standard
 118 system directories you can install them in your home directory
 119 using `local::lib`. The instructions for first installing
 120 `local::lib` are found here:
 121
 122 https://metacpan.org/pod/local::lib
 123
 124 Once `local::lib` is installed you can install BioPerl using a
 125 command like this:
 126
 127 perl -MCPAN -Mlocal::lib -e 'CPAN::install(C/CJ/CJFIELDS/BioPerl-1.6.924.tar.gz)'
 128
 129 INSTALLING BIOPERL SCRIPTS
 130
 131 BioPerl comes with a set of production-quality scripts that are
 132 kept in the scripts/ directory. You can install these scripts if you'd
 133 like, simply answer the questions during `perl Build.PL`.
 134 The installation directory can be specified by:
 135
 136 perl Build.PL
 137 ./Build install --install_path script=/foo/scripts
 138
 139 By default they install to */usr/bin* or similar, depending on platform.
 140
 141
 142 THE TEST SYSTEM
 143
 144 The BioPerl test system is located in the *t/* directory and is
 145 automatically run whenever you execute the `./Build test` command.
 146
 147 The tests have been organized into groups
 148 based upon the specific task or class the module being tested belongs
 149 to. If you want to investigate the behavior of a specific test such as
 150 the Seq test you would type:
 151
 152 ./Build test --test_files t/Seq/Seq.t --verbose
 153
 154 The `--test_files` argument can be used multiple times to try a set of test
 155 scripts in one go. The `--verbose` arguement outputs the detailed test results, instead of just the summary you see during `./Build test`.
 156
 157 The `--test-files` argument can also work as a glob. For instance, to
 158 run tests on all SearchIO modules, use the following:
 159
 160 ./Build test --test_files t/SearchIO* --verbose
 161
 162 If you are trying to learn how to use a module, often the test suite
 163 is a good place to look. All good extreme programmers try and write a
 164 test BEFORE they write the module to insure that their module behaves
 165 the way they expect. You'll notice some `ok` and `skip` commands in a
 166 test, this is part of the Perl test suite that signifies a passed test
 167 with an 'ok N', where N is the test number. Alternatively you can tell
 168 Perl to skip tests. This is useful when, for example, your test
 169 detects that the network is not present and thus should skip, not
 170 fail, any tests that require a network connection.
 171
 172 The core developers have indicated that future releases of BioPerl
 173 will require that new modules come with a test suite with some minimal
 174 tests.  Modules that lack adequate tests or could otherwise be
 175 considered 'unstable' will be moved into a separate developer
 176 distribution until adequate tests are added and the API stablizes.