INSTALL.md

   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 # System Requirments
   8
   9  * `Perl 5.6.1 or higher` Version 5.10 or higher is highly
  10    recommended. Modules are tested against version 5.14 and
  11    above.
  12  * `make` For Mac OS X, this requires installing the Xcode Developer
  13    Tools.
  14
  15 # Preliminary Preparation
  16
  17 These are optional, but regardless of your subsequent choice of
  18 installation method, it will help to carry out the following steps.
  19 They will increase the likelihood of installation success
  20 (especially of the optional dependencies).
  21
  22 * Upgrade CPAN:
  23
  24 ```
  25 perl -MCPAN -e shell
  26 ```
  27
  28 * Install or upgrade `Module::Build`, and make it your preferred installer:
  29
  30 ```
  31 cpan>install Module::Build
  32 cpan>o conf prefer_installer MB
  33 cpan>o conf commit
  34 ```
  35
  36 * Install the `expat` library by whatever method is appropriate for your system (e.g. `apt`, `yum`, `homebrew`).
  37
  38 # Installing BioPerl the Easy Way
  39
  40 We highly recommend using
  41 [cpanminus](https://metacpan.org/pod/distribution/App-cpanminus/bin/cpanm) for
  42 installing BioPerl and its dependencies. We also highly recommend (if possible)
  43 using a tool like [perlbrew](https://perlbrew.pl) to locally install a modern
  44 version of perl (a version that is higher than perl 5.16).  The linked
  45 pages describe how to install each tool; make sure if you install perlbrew that
  46 you follow up with installing `cpanm`:
  47
  48 ```
  49 perlbrew install-cpanm
  50 ```
  51
  52 Then, you can install BioPerl:
  53
  54 ```
  55 cpanm Bio::Perl
  56 ```
  57
  58 You can also use the older CPAN shell to install BioPerl. For example:
  59
  60 ```
  61 perl -MCPAN -e shell
  62 ```
  63
  64 Or you might have the `cpan` alias installed:
  65
  66 ```
  67 cpan
  68 ```
  69
  70 Then find the name of the latest BioPerl package:
  71
  72 ```
  73 cpan>d /bioperl/
  74  ....
  75
  76  Distribution    CJFIELDS/BioPerl-1.6.901.tar.gz
  77  Distribution    CJFIELDS/BioPerl-1.6.922.tar.gz
  78  Distribution    CJFIELDS/BioPerl-1.6.924.tar.gz
  79 ```
  80
  81 And install the most recent:
  82
  83 ```
  84 cpan>install CJFIELDS/BioPerl-1.6.924.tar.gz
  85 ```
  86
  87 If you've installed everything perfectly and all the network
  88 connections are working then you will pass all the tests run in the
  89 `./Build test` phase. Sometimes you may see a failed test. Remember that
  90 there are over 900 modules in BioPerl and the test suite is running more
  91 than 12000 individual tests, a failed test may not affect your usage
  92 of BioPerl.
  93
  94 If there's a failed test and you think that the failed test will not
  95 affect how you intend to use BioPerl then do:
  96
  97 ```
  98 cpan>force install C/CJ/CJFIELDS/BioPerl-1.6.923.tar.gz
  99 ```
 100
 101 If you're concerned about a failed test and need assistance or advice
 102 then contact bioperl-l@bioperl.org, and provide us the detailed
 103 results of the failed install.
 104
 105 # Installing BioPerl from Github
 106
 107 **NOTE:** We generally do not recommend installing the latest code from Github
 108 unless you absolutely need the latest bug fixes.
 109
 110 The very latest version of Bioperl is at github.com. If you want this
 111 version then download it from https://github.com/bioperl/bioperl-live as a
 112 `tar.gz` or `zip` file, or retrieve it using the command line:
 113
 114 ```
 115 git clone https://github.com/bioperl/bioperl-live.git
 116 cd bioperl-live
 117 ```
 118
 119 ## Using cpanm
 120
 121 If you have `cpanm`, you can install within the checkout directory by simply using:
 122
 123 ```
 124 cpanm --interactive .
 125 ```
 126
 127 to run interative installation, or you can leave out the `--interactive` flag to accept the defaults.
 128
 129 ## Using the Installation Script
 130
 131 Issue the build commands:
 132
 133 ```
 134 perl Build.PL
 135 ```
 136
 137 You will be asked a few questions about installing BioPerl scripts
 138 and running various test suites, hit `return` to accept the defaults.
 139
 140 Test:
 141
 142 ```
 143 ./Build test
 144 ```
 145
 146 Install:
 147
 148 ```
 149 ./Build install
 150 ```
 151
 152 You may need root permissions in order to run `./Build install`, so you
 153 will want to talk to your systems manager if you don't have the necessary
 154 privileges. Or you can install the package in your own home
 155 directory, see INSTALLING BIOPERL USING `local::lib`.
 156
 157 # Installing Bioperl using `local::lib`
 158
 159 If you lack permission to install Perl modules into the standard
 160 system directories you can install them in your home directory
 161 using [local::lib](https://metacpan.org/pod/local::lib). The instructions for first installing
 162 `local::lib` are found in the link.
 163
 164 Once `local::lib` is installed you can install BioPerl using a
 165 command like this:
 166
 167 ```
 168 perl -MCPAN -Mlocal::lib -e 'CPAN::install(C/CJ/CJFIELDS/BioPerl-1.6.924.tar.gz)'
 169 ```
 170
 171 # Installing BioPerl Scripts
 172
 173 BioPerl comes with a set of production-quality scripts that are
 174 kept in the scripts/ directory. You can install these scripts if you'd
 175 like, simply answer the questions during `perl Build.PL`.
 176 The installation directory can be specified by:
 177
 178 ```
 179 perl Build.PL ./Build install --install_path script=/foo/scripts
 180 ```
 181
 182 By default they install to `/usr/bin` or similar, depending on platform.
 183
 184 # The Test System
 185
 186 The BioPerl test system is located in the `t/` directory and is
 187 automatically run whenever you execute the `./Build test` command.
 188
 189 The tests have been organized into groups
 190 based upon the specific task or class the module being tested belongs
 191 to. If you want to investigate the behavior of a specific test such as
 192 the Seq test you would type:
 193
 194 ```
 195 ./Build test --test_files t/Seq/Seq.t --verbose
 196 ```
 197
 198 The `--test_files` argument can be used multiple times to try a set of test
 199 scripts in one go. The `--verbose` arguement outputs the detailed test results, instead of just the summary you see during `./Build test`.
 200
 201 The `--test-files` argument can also work as a glob. For instance, to run tests on all SearchIO modules, use the following:
 202
 203 ```
 204 ./Build test --test_files t/SearchIO* --verbose
 205 ```
 206
 207 You can also use the command-line tool `prove` to run tests as well, which
 208 is quite useful if you are developing code:
 209
 210 ```
 211 prove -lrv t/SearchIO*
 212 ```
 213
 214 If you are trying to learn how to use a module, often the test suite
 215 is a good place to look. All good extreme programmers try and write a
 216 test BEFORE they write the module to insure that their module behaves
 217 the way they expect. You'll notice some `ok` and `skip` commands in a
 218 test, this is part of the Perl test suite that signifies a passed test
 219 with an 'ok N', where N is the test number. Alternatively you can tell
 220 Perl to skip tests. This is useful when, for example, your test
 221 detects that the network is not present and thus should skip, not
 222 fail, any tests that require a network connection.
 223
 224 The core developers have indicated that future releases of BioPerl
 225 will require that new modules come with a test suite with some minimal
 226 tests.  Modules that lack adequate tests or could otherwise be
 227 considered 'unstable' will be moved into a separate developer
 228 distribution until adequate tests are added and the API stablizes.