Pull out the 'recommends' table and refactor to make a bit more

[bioperl-live.git] / INSTALL

# $Id$

Installing BioPerl for Unix

     * 1 BIOPERL INSTALLATION
     * 2 SYSTEM REQUIREMENTS
     * 3 OPTIONAL
     * 4 ADDITIONAL INSTALLATION INFORMATION
     * 5 PRELIMINARY PREPARATION
     * 6 INSTALLING BIOPERL THE EASY WAY USING Build.PL
     * 7 INSTALLING BIOPERL THE EASY WAY USING CPAN
     * 8 WHERE ARE THE MAN PAGES?
     * 9 EXTERNAL PROGRAMS
          * 9.1 Environment Variables
     * 10 THE BIOPERL BUNDLE
     * 11 INSTALLING BIOPERL SCRIPTS
     * 12 INSTALLING BIOPERL IN A PERSONAL MODULE AREA
     * 13 INSTALLING BIOPERL MODULES THE HARD WAY
     * 14 USING MODULES NOT INSTALLED IN THE STANDARD LOCATION
     * 15 THE TEST SYSTEM
     * 16 BUILDING THE OPTIONAL bioperl-ext PACKAGE
          * 16.1 CONFIGURING for BSD and Solaris boxes
          * 16.2 INSTALLATION

BIOPERL INSTALLATION

For the most up-to-date installation instructions please see the
BioPerl wiki:

  http://www.bioperl.org/wiki/Installing_BioPerl

BioPerl has been installed on many forms of Unix, Win9X/NT/2000/XP,
and on Mac OS X (see the PLATFORMS file for more details). Following
are instructions for installing BioPerl for Unix/Linux/Mac OS X;
Windows installation instructions can be found in INSTALL.WIN. For
installing BioPerl for Mac OS X using Fink, see:

http://www.bioperl.org/wiki/Getting_BioPerl#Mac_OS_X_using_fink

SYSTEM REQUIREMENTS

    * Perl 5.6.1 or later; version 5.8 and greater are highly
      recommended. Modules are generally tested against perl 5.8 and
      above.

    * External modules: BioPerl uses functionality provided in other
      Perl modules. Some of these are included in the standard perl
      package but some need to be obtained from the CPAN site. The
      list of external modules is included in the DEPENDENCIES file.

OPTIONAL

   * ANSI C or GNU C compiler (gcc) for XS extensions (the bioperl-ext
     package; see BUILDING THE OPTIONAL bioperl-ext PACKAGE, below).

ADDITIONAL INSTALLATION INFORMATION

   * Additional information on BioPerl and MAC OS:
      * OS 9 - http://bioperl.org/Core/mac-bioperl.html
            NOTE: These are severely out-of-date and require MacPerl
            (the latest version of which is 5.6.1rc1). As such, we do
            not currently support BioPerl on OS 9
      * OS X - Installing using Fink (in Getting BioPerl)

PRELIMINARY PREPARATION

   This is optional, but regardless of your subsequent choice of
   installation method, it will help to carry out the following steps.
   They will increase the likelyhood of installation success
   (especially of optional dependencies).

     * Upgrade CPAN:

 >perl -MCPAN -e shell
 cpan>install Bundle::CPAN
 cpan>q

     * Install/upgrade Module::Build, and make it your preferred
       installer:

 >cpan
 cpan>install Module::Build
 cpan>o conf prefer_installer MB
 cpan>o conf commit
 cpan>q

     * Install the expat library by whatever method is
       appropriate for your system.

     * If your expat library is installed in a non-standard location,
       tell CPAN about it:

 >cpan
 cpan>o conf makepl_arg "EXPATLIBPATH=/non-standard/lib EXPATINCPATH=/non-standard/include"
 cpan>o conf commit

INSTALLING BIOPERL THE EASY WAY USING Build.PL

The advantage of this approach is it's stepwise, so it's easy to stop
and analyze in case of any problem.

Download, then unpack the tar file. For example:

 >tar xvfz BioPerl-1.6.1.tar.gz
 >cd BioPerl-1.6.1

Now issue the build commands:

 >perl Build.PL
 >./Build test

If you've installed everything perfectly and all the network
connections are working then you may pass all the tests run in the
'./Build test' phase. It's also possible that you may fail some tests.
Possible explanations: problems with local Perl installation, network
problems, previously undetected bug in BioPerl, flawed test script,
problems with CGI script using for sequence retrieval at public
database, and so on. Remember that there are over 900 modules in
BioPerl and the test suite is running more than 12000 individual
tests, a few failed tests may not affect your usage of BioPerl.

If you decide that the failed tests will not affect how you intend to
use BioPerl and you'd like to install anyway, or if all tests were
fine, do:

 >./Build install

This is what most experienced BioPerl users would do. However, if
you're concerned about a failed test and need assistance or advice
then contact bioperl-l@bioperl.org. (You could provide us the detailed
results of the failed test(s): see the `THE TEST SYSTEM' below for
information on how to generate such results.)

To './Build install' you need write permission in the
perl5/site_perl/source area (or similar, depending on your
environment). Usually this will require you becoming root, so you will
want to talk to your systems manager if you don't have the necessary
privileges.

It is also straightforward to install the package outside of the this
standard Perl5 location. See INSTALLING BIOPERL IN A PERSONAL MODULE
AREA, below.

INSTALLING BIOPERL THE EASY WAY USING CPAN

You can use the CPAN shell to install BioPerl. For example:

 >perl -MCPAN -e shell
 
Or you might have the cpan alias installed:

 >cpan

Then find the name of the BioPerl version you want:

 cpan>d /bioperl/
 CPAN: Storable loaded ok
 Going to read /home/bosborne/.cpan/Metadata
 Database was generated on Mon, 20 Nov 2006 05:24:36 GMT
 
 ....
 
 Distribution B/BI/BIRNEY/bioperl-1.2.tar.gz
 Distribution B/BI/BIRNEY/bioperl-1.4.tar.gz
 Distribution C/CJ/CJFIELDS/BioPerl-1.6.1.tar.gz

Now install:

 cpan>install C/CJ/CJFIELDS/BioPerl-1.6.1.tar.gz

If you've installed everything perfectly and all the network
connections are working then you may pass all the tests run in the
'./Build test' phase. It's also possible that you may fail some tests.
Possible explanations: problems with local Perl installation, network
problems, previously undetected bug in BioPerl, flawed test script,
problems with CGI script used for sequence retrieval at public
database, and so on. Remember that there are over 900 modules in
BioPerl and the test suite is running more than 12000 individual
tests, a few failed tests may not affect your usage of BioPerl.

If you decide that the failed tests will not affect how you intend to
use BioPerl and you'd like to install anyway do:

 cpan>force install C/CJ/CJFIELDS/BioPerl-1.6.1.tar.gz

This is what most experienced BioPerl users would do. However, if
you're concerned about a failed test and need assistance or advice
then contact bioperl-l@bioperl.org. (You could provide us the detailed
results of the failed test(s): see the `THE TEST SYSTEM' below for
information on how to generate such results.)

WHERE ARE THE MAN PAGES?

Previously, when using Makefile.PL (no longer covered in this
documentation), we had to disable the automatic creation of man pages
because this step was triggering a "line too long" error on some OSs
due to shell constraints. If you want man pages installed use the
Build.PL installation process discussed above. 

EXTERNAL PROGRAMS

BioPerl can interface with some external programs for executing
analyses. These include clustalw and t_coffee for Multiple Sequence
Alignment (Bio::Tools::Run::Alignment::Clustalw and
Bio::Tools::Run::Alignment::TCoffee) and blastall, blastpgp, and
bl2seq for BLAST analyses (Bio::Tools::Run::StandAloneBlast), and to
all the programs in the EMBOSS suite (Bio::Factory::EMBOSS).  Most
of the modules which 'wrap' these programs are located in the separate
bioperl-run distribution; however, two commonly-used modules are still
distributed with the BioPerl core (Bio::Tools::Run::StandAloneBlast,
Bio::Tools::Run::RemoteBlast).  

    Environment Variables

Some modules which run external programs need certain environment
variables set. If you do not have a local copy of the specific
executable you do not need to set these variables. Additionally the
modules will attempt to locate the specific applications in your
runtime PATH variable. You may also need to set an environment
variable to tell BioPerl about your network configuration if your site
uses a firewall.

Setting environment variables on unix means adding lines like the
following to your shell *rc file.

   For bash or sh:

 export BLASTDIR=/data1/blast

   For csh or tcsh:

 setenv BLASTDIR /data1/blast

Some environment variables include:

+------------------------------------------------------------------------+
| Env. Variable |                      Description                       |
|---------------+--------------------------------------------------------|
|               |Specifies where the NCBI blastall, blastpgp, bl2seq,    |
|BLASTDIR       |etc.. are located. A 'data' directory could also be     |
|               |present in this directory as well, you could put your   |
|               |blastable databases here.                               |
|---------------+--------------------------------------------------------|
|               |If one does not want to locate the data dir within the  |
|BLASTDATADIR or|same dir as where the BLASTDIR variable points, a       |
|BLASTDB        |BLASTDATADIR or BLASTDB variable can be set to point to |
|               |a dir where BLAST database indexes are located.         |
|---------------+--------------------------------------------------------|
|BLASTMAT       |The directory containing the substitution matrices such |
|               |as BLOSUM62.                                            |
|---------------+--------------------------------------------------------|
|CLUSTALDIR     |The directory where the clustalw executable is located. |
|---------------+--------------------------------------------------------|
|TCOFFEEDIR     |The directory where the t_coffee executable is located. |
|---------------+--------------------------------------------------------|
|               |If you access the internet via a proxy server then you  |
|               |can tell the BioPerl modules which require network      |
|               |access about this by using the http_proxy environment   |
|http_proxy     |variable. The value set includes the proxy address and  |
|               |the port, with optional username/password for           |
|               |authentication purposes                                 |
|               |(e.g. http://USERNAME:PASSWORD@proxy.example.com:8080). |
+------------------------------------------------------------------------+

THE BIOPERL BUNDLE

Users of previous versions of BioPerl may remember Bundle::BioPerl.
You no longer need to install Bundle::BioPerl. Instead, the normal
installation process will ask you if you'd like to install optional
external module dependencies that BioPerl has.

A full list of BioPerl dependencies can be found in the DEPENDENCIES
file included with this distribution.

INSTALLING BIOPERL SCRIPTS

BioPerl comes with a set of production-quality scripts that are
kept in the scripts/ directory. You can install these scripts if you'd
like, simply answer the questions during 'perl Build.PL'.
The installation directory can be specified by:

 perl Build.PL
 ./Build install --install_path script=/foo/scripts
 
By default they install to /usr/bin or similar, depending on platform.

INSTALLING BIOPERL IN A PERSONAL MODULE AREA

If you lack permission to install perl modules into the standard
site_perl/ system area you can configure BioPerl to install itself
anywhere you choose. Ideally this would be a personal perl directory
or standard place where you plan to put all your 'local' or personal
perl modules.

   Example:

 >perl Build.PL --install_base /home/users/dag
 >./Build test
 >./Build install

This tells perl to install all the various parts of bioperl in the
desired place, e.g. creating:

   /home/users/dag/lib/perl5/Bio/Perl.pm

Then in your BioPerl script you would write:

 use lib "/home/users/dag/lib/perl5/";
 use Bio::Perl;

For more information on these sorts of custom installs see the
documentation for Module::Build.

If you are used to using something like:

 >perl Makefile.PL PREFIX=/home/users/dag

You can get similar behaviour by using this instead:

 >perl Build.PL --prefix /home/users/dag

For more information, see Module::Build::Cookbook documentation for
Installing_in_the_same_location_as_ExtUtils::MakeMaker

You can also use CPAN to install modules in your local directory.
First enter the CPAN shell, then set the arguments for the commands
"perl Makefile.PL" and "./Build install", like this:

 >perl -e shell -MCPAN
 cpan>o conf makepl_arg LIB=/home/users/dag/My_Local_Perl_Modules
 cpan>o conf mbuild_install_arg "--install_path lib=/home/users/dag/My_Local_Perl_Modules"
 cpan>o conf commit

INSTALLING BIOPERL MODULES THE HARD WAY

As a last resort, you can simply copy all files in Bio/ to any
directory in which you have write privileges. This is generally NOT
recommended since some modules may require special configuration
(currently none do, but don't rely on this).

You will need to set "use lib '/path/to/my/bioperl/modules';" in your
perl scripts so that you can access these modules if they are not
installed in the standard site_perl/ location. See above for an
example.

To get manpage documentation to work correctly you will have to
configure man so that it looks in the proper directory. On most
systems this will just involve adding an additional directory to your
$MANPATH environment variable.

The installation of the Compile directory can be similarly redirected,
but execute the make commands from the Compile/SW directory.

If all else fails and you are unable to access the perl distribution
directories, ask your system administrator to place the files there
for you. You can always execute perl scripts in the same directory as
the location of the modules (Bio/ in the distribution) since perl
always checks the current working directory when looking for modules.

USING MODULES NOT INSTALLED IN THE STANDARD LOCATION

You can explicitly tell perl where to look for modules by using the
Lib module which comes standard with perl.

   Example:

 #!/usr/bin/perl
 use lib "/home/users/dag/lib/perl5/";
 use Bio::Perl;
 #<...insert whizzy perl code here...>

Or, you can set the environmental variable PERL5LIB:

   csh or tcsh:

 setenv PERL5LIB /home/users/dag/lib/perl5/

   bash or sh:

 export PERL5LIB=/home/users/dag/lib/perl5/

THE TEST SYSTEM

The BioPerl test system is located in the t/ directory and is
automatically run whenever you execute the './Build test' command
(having previously run 'Perl Build.PL'; if you have already installed
BioPerl answer 'no' to script installation to get nicer test output
later). 

For the 1.6 release and beyond, tests have been organized into groups
based upon the specific task or class the module ibeing tested belongs
to. If you want to investigate the behavior of a specific test such as
the Seq test you would type: 

 >./Build test --test_files t/Seq/Seq.t --verbose

The ./ ensures you are using the Build script in the current directory
to make sure you are testing the modules in this directory not ones
installed elsewhere. The --test_files arguement can be used multiple
times to try a set of test scripts in one go. The --verbose arguement
outputs the detailed test results, instead of just the summary you see
during './Build test'.

The '--test-files' argument can also work as a glob. For instance, to
run tests on all SearchIO modules, use the following:

 >./Build test --test_files t/SearchIO* --verbose

If you are trying to learn how to use a module, often the test suite
is a good place to look. All good extreme programmers try and write a
test BEFORE they write the module to insure that their module behaves
the way they expect. You'll notice some 'ok' and 'skip' commands in a
test, this is part of the Perl test suite that signifies a passed test
with an 'ok N', where N is the test number. Alternatively you can tell
Perl to skip tests. This is useful when, for example, your test
detects that the network is not present and thus should skip, not
fail, any tests that require a network connection.

The core developers have indicated that future releases of BioPerl
will require that new modules come with a test suite with some minimal
tests.  Modules that lack adequate tests or could otherwise be
considered 'unstable' will be moved into a separate developer
distribution until adequate tests are added and the API stablizes.

BUILDING THE OPTIONAL bioperl-ext PACKAGE

The bioperl-ext package contains C code and XS extensions for various
alignment and trace file modules (Bio::Tools::pSW for DNA
Smith-Waterman, Bio::Tools::dpAlign for protein Smith-Waterman,
Bio::SearchDist for EVD fitting of extreme value, Bio::SeqIO::staden).

This Installation may work out-of-the box for most platforms except
BSD and Solaris boxes. For other platforms skip this next paragraph.
Of note, the code for bioperl-ext has not been updated along with the
rest of bioperl, so one may expect to see some issues. If so, please
report them to the BioPerl mailing list. Patches for these modules are
always welcome.

    CONFIGURING for BSD and Solaris boxes

You should add the line -fPIC to the CFLAGS line in
Compile/SW/libs/makefile. This makes the compile generate position
independent code, which is required for these architectures. In
addition, on some Solaris boxes, the generated Makefile does not make
the correct -fPIC/-fpic flags for the C compiler that is used. This
requires manual editing of the generated Makefile to switch case. Try
it out once, and if you get errors, try editing the -fpic line

    INSTALLATION

Move to the directory bioperl-ext. This is available as a separate
package released from ftp://bioperl.org/pub/bioperl/DIST. This is
where the C code and XS extension for the bp_sw module is held and
execute these commands: (possibly after making the change for BSD and
Solaris, as detailed above)

 perl Makefile.PL   # makes the system specific makefile
 make          # builds all the libaries
 make test     # runs a short test
 make install  # installs the package correctly.

This should install the compiled extension. The Bio::Tools::pSW module
will work cleanly now.