INSTALL

   1 # $Id$
   2
   3 o BIOPERL INSTALLATION
   4 o SYSTEM REQUIREMENTS
   5 o OPTIONAL
   6 o ADDITIONAL INSTALLATION INFORMATION
   7 o THE BIOPERL BUNDLE
   8 o INSTALLING BIOPERL THE EASY WAY USING CPAN
   9 o INSTALLING BIOPERL THE EASY WAY USING 'make'
  10 o WHERE ARE THE MAN PAGES?
  11 o EXTERNAL PROGRAMS
  12 o INSTALLING BIOPERL SCRIPTS
  13 o INSTALLING BIOPERL IN A PERSONAL MODULE AREA
  14 o INSTALLING BIOPERL MODULES THE HARD WAY
  15 o USING MODULES NOT INSTALLED IN THE STANDARD LOCATION
  16 o THE TEST SYSTEM
  17 o BUILDING THE OPTIONAL bioperl-ext PACKAGE
  18 o DEPENDENCIES AND Bundle::BioPerl
  19
  20
  21 o BIOPERL INSTALLATION
  22
  23    Bioperl has been installed on many forms of Unix, Win9X/NT/2000/XP,
  24    and on Mac OS (see the PLATFORMS file for more details). For
  25    instructions on Unix and Mac OS read on, for installation on Windows
  26    please see the INSTALL.WIN file.
  27
  28
  29 o SYSTEM REQUIREMENTS
  30
  31  - perl 5.005 or later*.
  32
  33  - External modules: Bioperl uses functionality provided in other
  34    Perl modules.  Some of these are included in the standard perl
  35    package but some need to be obtained from the CPAN site. The
  36    list of external modules is included at the bottom of
  37    this INSTALL document.
  38
  39    The CPAN Bioperl Bundle (Bundle::BioPerl) makes installation
  40    of these external modules easy. Simply install the bundle
  41    using your CPAN shell and all necessary modules will be installed.
  42    See THE BIOPERL BUNDLE, below.
  43
  44  * Note that most modules will work with earlier versions of Perl.
  45    The only ones that will not are Bio::SimpleAlign.pm and
  46    the Bio::Index::* modules. If you don't need these modules
  47    and you want to install bioperl using an earlier version of Perl,
  48    edit the "require 5.005;" line in Makefile.PL as necessary.
  49
  50
  51 o OPTIONAL
  52
  53  - ANSI C or Gnu C compiler for XS extensions (bioperl-ext package,
  54    see BUILDING THE OPTIONAL bioperl-ext PACKAGE, below.
  55
  56
  57 o ADDITIONAL INSTALLATION INFORMATION
  58
  59  - Additional information on Bioperl and MAC OS:
  60    OS 9 - http://bioperl.org/Core/mac-bioperl.html
  61    OS X - http://www.tc.umn.edu/~cann0010/Bioperl_OSX_install.html
  62
  63
  64 o THE BIOPERL BUNDLE
  65
  66    You typically need root privileges to install using CPAN.
  67    If you don't have these privileges please see INSTALLING BIOPERL
  68    IN A PERSONAL MODULE AREA for additional information.
  69
  70    Install the Bioperl Bundle using CPAN. One way:
  71
  72      >perl -MCPAN -e "install Bundle::BioPerl"
  73
  74    Another way:
  75
  76      >perl -MCPAN -e shell
  77      cpan>install Bundle::BioPerl
  78
  79
  80 o INSTALLING BIOPERL THE EASY WAY USING CPAN
  81
  82    You can use the CPAN shell to install Bioperl. For example:
  83
  84      >perl -MCPAN -e shell
  85
  86    Then find the name of the Bioperl version you want:
  87
  88      cpan>d /bioperl/
  89      CPAN: Storable loaded ok
  90      Going to read /home/bosborne/.cpan/Metadata
  91      Database was generated on Tue, 24 Feb 2004 23:55:23 GMT
  92      Distribution    B/BI/BIRNEY/bioperl-1.2.tar.gz
  93      Distribution    B/BI/BIRNEY/bioperl-1.4.tar.gz
  94
  95    Now install:
  96
  97      cpan>install B/BI/BIRNEY/bioperl-1.4.tar.gz
  98
  99    If you've installed everything perfectly and all the network
 100    connections are working then you may pass all the tests run
 101    in the 'make test' phase. It's also possible that you may
 102    fail some tests. Possible explanations: problems with local
 103    Perl installation, network problems, previously undetected
 104    bug in Bioperl, flawed test script, problems with CGI script
 105    used for sequence retrieval at public database, and so on.
 106    Remember that there are over 700 modules in Bioperl and the
 107    test suite is running more than 9000 individual tests, a few
 108    failed tests may not affect your usage of Bioperl.
 109
 110    If you decide that the failed tests will not affect how you
 111    intend to use Bioperl and you'd like to install anyway do:
 112
 113      cpan>force install B/BI/BIRNEY/bioperl-1.4.tar.gz
 114
 115    This is what most experienced Bioperl users would do. However,
 116    if you're concerned about a failed test and need assistance
 117    or advice then contact bioperl-l@bioperl.org.
 118
 119
 120 o INSTALLING BIOPERL THE EASY WAY USING 'make'
 121
 122    The advantage of this approach is it's stepwise, so
 123    it's easy to stop and analyze in case of any problem.
 124
 125    Download, then unpack the tar file. For example:
 126
 127      >gunzip bioperl-1.2.tar.gz
 128      >tar xvf bioperl-1.2.tar
 129      >cd bioperl-1.2
 130
 131    Now issue the make commands:
 132
 133      >perl Makefile.PL
 134      >make
 135      >make test
 136
 137    If you've installed everything perfectly and all the network
 138    connections are working then you may pass all the tests run
 139    in the 'make test' phase. It's also possible that you may
 140    fail some tests. Possible explanations: problems with local
 141    Perl installation, network problems, previously undetected
 142    bug in Bioperl, flawed test script, problems with CGI script
 143    using for sequence retrieval at public database, and so on.
 144    Remember that there are over 700 modules in Bioperl and the
 145    test suite is running almost 9000 individual tests, a few
 146    failed tests may not affect your usage of Bioperl.
 147
 148    If you decide that the failed tests will not affect how you
 149    intend to use Bioperl and you'd like to install anyway do:
 150
 151      >make install
 152
 153    This is what most experienced Bioperl users would do. However,
 154    if you're concerned about a failed test and need assistance
 155    or advice then contact bioperl-l@bioperl.org.
 156
 157    To 'make install' you need write permission in the perl5/site_perl/
 158    source area. Usually this will require you becoming root, so
 159    you will want to talk to your systems manager if you don't have
 160    the necessary privileges.
 161
 162    It is also straightforward to install the package outside of the
 163    this standard Perl5 location. See
 164    INSTALLING BIOPERL IN A PERSONAL MODULE AREA, below.
 165
 166
 167 o WHERE ARE THE MAN PAGES?
 168
 169    We had to disable the automatic creation of man pages because
 170    this step was triggering a "line too long" error on some OSs due
 171    to shell constraints. If you'd like to try and create them comment out or
 172    delete the MY::manifypods sub in Makefile.PL before you issue the
 173    'perl Makefile.PL' step.
 174
 175
 176 o EXTERNAL PROGRAMS
 177
 178    Bioperl can interface with some external programs for executing
 179    analyses.  These include clustalw and t_coffee for Multiple
 180    Sequence Alignments (Bio::Tools::Run::Alignment::Clustalw and
 181    Bio::Tools::Run::TCoffee) and blastall,blastpgp, & bl2seq for BLAST
 182    analyses (Bio::Tools::Run::StandAloneBlast), and to all the
 183    programs in the EMBOSS suite (Bio::Factory::EMBOSS).
 184
 185  - Environment Variables
 186
 187    Some modules which run external programs need certain environment
 188    variables set.  If you do not have a local copy of the specific
 189    executable you do not need to set these variables.  Additionally
 190    the modules will attempt to locate the specific applications in
 191    your runtime PATH variable. You may also need to set an environment
 192    variable to tell BioPerl about your network configuration if your
 193    site uses a firewall.
 194
 195    Setting environment variables on unix means adding lines like the
 196    following to your shell *rc file.
 197
 198    For bash or sh:
 199
 200      export BLASTDIR=/data1/blast
 201
 202    For csh or tcsh:
 203
 204      setenv BLASTDIR /data1/blast
 205
 206    Some environment variables include:
 207
 208      BLASTDIR
 209
 210      Specifies where the NCBI blastall, blastpgp,
 211      bl2seq, etc.. are located.  A 'data' directory
 212           could also be present in this directory as well, you could put
 213      your blastable databases here.
 214
 215      BLASTDATADIR or BLASTDB
 216
 217      If one does not want to locate the data dir
 218           within the same dir as where the BLASTDIR variable
 219           points, a BLASTDATADIR or BLASTDB variable can be set to
 220           point to a dir where BLAST database indexes are located.
 221
 222      BLASTMAT
 223
 224      The directory containing the substitution matrices
 225      such as BLOSUM62.
 226
 227
 228      CLUSTALDIR
 229
 230      The directory where the clustalw executable is located.
 231
 232
 233      TCOFFEEDIR
 234
 235      The directory where the t_coffee executable is located.
 236
 237
 238      HTTP_PROXY
 239
 240      If you access the internet via a proxy server then you
 241      can tell the Bioperl modules which require network access
 242      about this by using the HTTP_PROXY environment variable.
 243      The value set includes the proxy address and the port
 244      used (e.g. http://wwwcache.example.com:8080).
 245
 246
 247 o INSTALLING BIOPERL SCRIPTS
 248
 249    Bioperl comes with a set of production-quality scripts that are kept
 250    in the scripts/ directory. You can install these scripts if you'd like,
 251    simply answer the questions on 'make install'. The installation
 252    directory is specified by the INSTALLSCRIPT variable in the Makefile,
 253    the default location is /usr/bin. Installation will copy the scripts
 254    to the specified directory, change the 'PLS' suffix to 'pl', and
 255    prepend 'bp_' to all the script names if they aren't so named already.
 256
 257
 258 o INSTALLING BIOPERL IN A PERSONAL MODULE AREA
 259
 260    If you lack permission to install perl modules into the
 261    standard site_perl/ system area you can configure bioperl to
 262    install itself anywhere you choose. Ideally this would
 263    be a personal perl directory or standard place where you
 264    plan to put all your 'local' or personal perl modules.
 265
 266    Simply pass a parameter to perl as it builds your system
 267    specific makefile.
 268
 269    Example:
 270
 271      >perl Makefile.PL  LIB=/home/users/dag/My_Local_Perl_Modules
 272      >make
 273      >make test
 274      >make install
 275
 276    This tells perl to install bioperl in the desired place, e.g.:
 277
 278      /home/users/dag/My_Local_Perl_Modules/Bio/Seq.pm
 279
 280    Then in your Bioperl script you would write:
 281
 282      use lib "/home/users/dag/My_Local_Perl_Modules";
 283      use Bio::Seq;
 284
 285    The man pages will probably be installed in $LIB/man. For more
 286    information on these sorts of custom installs see the documentation
 287    for ExtUtils::MakeMaker.
 288
 289    You can also use CPAN to install accessory modules in your
 290    local directory. First enter the CPAN shell, then set the
 291    arguments for the command "perl Makefile.PL", like this:
 292
 293      >perl -e shell -MCPAN
 294      cpan>o conf makepl_arg LIB=/home/users/dag/My_Local_Perl_Modules
 295
 296
 297 o INSTALLING BIOPERL MODULES THE HARD WAY
 298
 299    As a last resort, you can simply copy all files in Bio/
 300    to any directory in which you have write privileges. This is
 301    generally NOT recommended since some modules may require
 302    special configuration (currently none do, but don't rely
 303    on this).
 304
 305    You will need to set "use lib '/path/to/my/bioperl/modules';"
 306    in your perl scripts so that you can access these modules if
 307    they are not installed in the standard site_perl/ location.
 308    See above for an example.
 309
 310    To get manpage documentation to work correctly you will have
 311    to configure man so that it looks in the proper directory.
 312    On most systems this will just involve adding an additional
 313    directory to your $MANPATH environment variable.
 314
 315    The installation of the Compile directory can be similarly
 316    redirected, but execute the make commands from the Compile/SW
 317    directory.
 318
 319    If all else fails or are unable to access the perl distribution
 320    directories, ask your system administrator to place the files there
 321    for you. You can always execute perl scripts in the same directory
 322    as the location of the modules (Bio/ in the distribution) since perl
 323    always checks the current working directory when looking for modules.
 324
 325
 326 o USING MODULES NOT INSTALLED IN THE STANDARD LOCATION
 327
 328    You can explicitly tell perl where to look for modules by using the
 329    lib module which comes standard with perl.
 330
 331    Example:
 332
 333        #!/usr/bin/perl
 334
 335        use lib "/home/users/dag/My_Local_Perl_Modules/";
 336        use Bio::Seq;
 337
 338        <...insert whizzy perl code here...>
 339
 340    Or, you can set the environmental variable PERL5LIB:
 341
 342      csh or tcsh:
 343
 344        setenv PERL5LIB /home/users/dag/My_Local_Perl_Modules/
 345
 346      bash or sh:
 347
 348       export PERL5LIB=/home/users/dag/My_Local_Perl_Modules/
 349
 350
 351 o THE TEST SYSTEM
 352
 353    The Bioperl test system is located in the t/ directory and is
 354    automatically run whenever you execute the 'make test' command.
 355    Alternatively if you want to investigate the behavior of a specific
 356    test such as the SeqIO test you would type:
 357
 358       >perl -I. -w t/SeqIO.t
 359
 360    The -I. tells Perl to use the current directory as the include path -
 361    this makes sure you are testing the modules in this directory not
 362    ones installed elsewhere in your PERL5LIB path.
 363    The -w tells Perl to print all warnings.
 364
 365    If you are trying to learn how to use a module, often the test suite
 366    is a good place to look.  All good extreme programmers try and write a
 367    test BEFORE they write the module to insure that their module behaves
 368    the way they expect.  You'll notice some 'ok' and 'skip' commands in
 369    a test, this is part of the Perl test suite that signifies a passed
 370    test with an 'ok N', where N is the test number.  Alternatively you can
 371    tell Perl to skip tests.  This is useful when, for example, your test
 372    detects that the network is not present and thus should skip, not
 373    fail, any tests that require a network connection.
 374
 375
 376 o BUILDING THE OPTIONAL bioperl-ext PACKAGE
 377
 378    The bioperl-ext package contains C code and XS extensions for
 379    various alignment and trace file modules (Bio::Tools::pSW for
 380    DNA Smith-Waterman, Bio::Tools::dpAlign for protein Smith-Waterman,
 381    Bio::SearchDist for EVD fitting of extreme value,
 382    Bio::SeqIO::staden).
 383
 384    This Installation works out-of-the box for all platforms except BSD
 385    and Solaris boxes. For other platforms skip this next paragraph.
 386
 387  - CONFIGURING for BSD and Solaris boxes
 388
 389    You should add the line -fPIC to the CFLAGS line in
 390    Compile/SW/libs/makefile.  This makes the compile generate position
 391    independent code, which is required for these architectures. In
 392    addition, on some Solaris boxes, the generated Makefile does not make
 393    the correct -fPIC/-fpic flags for the C compiler that is used. This
 394    requires manual editing of the generated Makefile to switch case. Try
 395    it out once, and if you get errors, try editing the -fpic line
 396
 397  - INSTALLATION
 398
 399    Move to the directory bioperl-ext. This is available as a separate
 400    package released from ftp://bioperl.org/pub/DIST.  This is where the C
 401    code and XS extension for the bp_sw module is held and execute these
 402    commands: (possibly after making the change for *BSD and Solaris, as
 403    detailed above)
 404
 405      perl Makefile.PL   # makes the system specific makefile
 406                         # Solaris/BSD users might need to edit the Makefile
 407      make               # builds all the libaries
 408      make test          # runs a short test
 409      make install       # installs the package correctly.
 410
 411    This should install the compiled extension. The Bio::Tools::pSW module
 412    will work cleanly now.
 413
 414
 415 o DEPENDENCIES AND Bundle::BioPerl
 416
 417    The following packages are used by Bioperl.  Not all are required for
 418    Bioperl to operate properly, however some functionality will be
 419    missing without them.  You can easily install all of these, except
 420    srsperl.pm, using the Bundle::BioPerl CPAN bundle.
 421
 422    The DBD::mysql, DB_File and XML::Parser modules require other
 423    applications or databases: MySQL, Berkeley DB, and expat respectively.
 424
 425
 426  Module                   Where it is Used
 427  ------------------------------------------------------------------
 428  HTTP::Request::Common    GenBank+GenPept sequence retrieval,
 429                                   remote http Blast jobs
 430                                          Bio::DB::*
 431                                          Bio::Tools::Run::RemoteBlast
 432
 433  LWP::UserAgent           GenBank+GenPept sequence retrieval,
 434                                          remote http Blast jobs
 435                                          Bio::DB::*
 436                                          Bio::Tools::Run::RemoteBlast
 437
 438  AcePerl                         Access to ACeDB databases
 439                                          Bio::DB::Ace
 440
 441  Available at http://stein.cshl.org
 442
 443  IO::String               IO handle to read or write to a string
 444                                   Bio::SeqIO
 445                                          Bio::Variation::*
 446                                          Bio::DB::*
 447                                          Bio::Index::Blast
 448                                          Bio::Tools::*
 449                                          Bio::Biblio::IO
 450                                          Bio::Structure::IO
 451
 452  XML::Parser              Parsing of XML documents
 453                                          Bio::Biblio::IO::medlinexml
 454
 455  Requires expat from http://sourceforge.net/projects/expat/
 456
 457  XML::Writer              Parsing + writing of XML documents
 458                                   Bio::SeqIO::game
 459                                          Bio::Variation::*
 460
 461  XML::Parser::PerlSAX     Parsing of XML documents
 462                                          Bio::SeqIO::game
 463                                          Bio::Variation::*
 464                                          Bio::SearchIO::blastxml
 465                                          Bio::Biblio::IO::medlinexml
 466
 467  XML::Twig                   Parsing of XML documents
 468                                          Bio::Variation::IO::xml
 469                           Bio/DB/Biblio/eutils
 470                           Bio/Graph/IO/psi_xml
 471
 472  File::Temp               Temporary File creation
 473                                          Bio::DB::FileCache
 474                                          Bio::DB::XEMBL
 475
 476  SOAP::Lite               SOAP protocol, XEMBL Services
 477                                          Bio::Biblio::*
 478                                          Bio::DB::XEMBLService
 479
 480  HTML::Parser             HTML parsing of GDB page
 481                                          Bio::DB::GDB
 482
 483  DBD::mysql               Mysql API for loading and querying of Mysql-based
 484                                          GFF feature and BioSQL databases
 485                                          Bio::DB::GFF
 486                                          bioperl-db external package
 487                                          bioperl-pipeline external package
 488
 489  Requires Mysql from www.mysql.org
 490
 491  GD                                   GD graphical drawing library
 492                                          Bio::Graphics
 493
 494  Requires GD library from www.boutell.com/gd
 495
 496
 497  Storable                          Persistent object storage & retrieval
 498                                          Bio::DB::FileCache
 499
 500  Text::Shellwords         Text parser
 501                           Bio::Graphics::FeatureFile
 502
 503  XML::DOM                          XML parser
 504                                          Bio::SeqIO::bsml
 505                           Bio::SeqIO::interpro
 506
 507  DB_File                  Perl access to Berkeley DB
 508                           Bio::DB::Flat
 509                                          Bio::DB::Fasta
 510                           Bio::SeqFeature::Collection
 511                                          Bio::Index::*
 512
 513  Requires Berkeley DB, from Linux RPM or from www.sleepycat.com
 514
 515  Graph::Directed          Generic graph data and algorithms
 516                           Bio::Ontology::SimpleOntologyEngine
 517
 518  Data::Stag::ITextWriter  Structured Tags datastructures
 519                                          Bio::SeqIO::chadoitext
 520
 521  Data::Stag::SxprWriter   Structured Tags datastructures
 522                                          Bio::SeqIO::chadosxpr
 523
 524  Data::Stag::XMLWriter    Structured Tags datastructures
 525                                          Bio::SeqIO::chadoxml
 526
 527  Text::Wrap               Very optional
 528                           Bio::SearchIO::Writer::TextResultWriter
 529
 530  HTML::Entities           Parse BLAST results in XML
 531                                          Bio/SearchIO/blastxml
 532
 533  Class::AutoClass         Used to create objects
 534                           Bio::Graph::SimpleGraph*
 535
 536  Clone                    Used to clone objects
 537                           Bio::Graph::ProteinGraph
 538
 539  XML::SAX                          New style SAX parser
 540                           Bio::SeqIO::bsml_sax
 541
 542  XML::SAX::Base              New style SAX parser
 543                           Bio::SeqIO::tigrxml
 544
 545  XML::SAX::Writer
 546
 547 Convert::Binary::C       Binary Data Conversion using C Types
 548                                    Bio/SeqIO/strider
 549
 550 Spreadsheet::ParseExcel      Read Microsoft Excel files
 551                                             Bio/SeqIO/excel.pm