6 o ADDITIONAL INSTALLATION INFORMATION
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?
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
17 o BUILDING THE OPTIONAL bioperl-ext PACKAGE
18 o DEPENDENCIES AND Bundle::BioPerl
21 o BIOPERL INSTALLATION
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.
31 - perl 5.005 or later*.
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.
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.
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.
53 - ANSI C or Gnu C compiler for XS extensions (bioperl-ext package,
54 see BUILDING THE OPTIONAL bioperl-ext PACKAGE, below.
57 o ADDITIONAL INSTALLATION INFORMATION
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
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.
70 Install the Bioperl Bundle using CPAN. One way:
72 >perl -MCPAN -e "install Bundle::BioPerl"
77 cpan>install Bundle::BioPerl
80 o INSTALLING BIOPERL THE EASY WAY USING CPAN
82 You can use the CPAN shell to install Bioperl. For example:
86 Then find the name of the Bioperl version you want:
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
97 cpan>install B/BI/BIRNEY/bioperl-1.4.tar.gz
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.
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:
113 cpan>force install B/BI/BIRNEY/bioperl-1.4.tar.gz
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.
120 o INSTALLING BIOPERL THE EASY WAY USING 'make'
122 The advantage of this approach is it's stepwise, so
123 it's easy to stop and analyze in case of any problem.
125 Download, then unpack the tar file. For example:
127 >gunzip bioperl-1.2.tar.gz
128 >tar xvf bioperl-1.2.tar
131 Now issue the make commands:
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.
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:
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.
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.
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.
167 o WHERE ARE THE MAN PAGES?
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.
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).
185 - Environment Variables
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.
195 Setting environment variables on unix means adding lines like the
196 following to your shell *rc file.
200 export BLASTDIR=/data1/blast
204 setenv BLASTDIR /data1/blast
206 Some environment variables include:
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.
215 BLASTDATADIR or BLASTDB
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.
224 The directory containing the substitution matrices
230 The directory where the clustalw executable is located.
235 The directory where the t_coffee executable is located.
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).
247 o INSTALLING BIOPERL SCRIPTS
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.
258 o INSTALLING BIOPERL IN A PERSONAL MODULE AREA
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.
266 Simply pass a parameter to perl as it builds your system
271 >perl Makefile.PL LIB=/home/users/dag/My_Local_Perl_Modules
276 This tells perl to install bioperl in the desired place, e.g.:
278 /home/users/dag/My_Local_Perl_Modules/Bio/Seq.pm
280 Then in your Bioperl script you would write:
282 use lib "/home/users/dag/My_Local_Perl_Modules";
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.
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:
293 >perl -e shell -MCPAN
294 cpan>o conf makepl_arg LIB=/home/users/dag/My_Local_Perl_Modules
297 o INSTALLING BIOPERL MODULES THE HARD WAY
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
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.
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.
315 The installation of the Compile directory can be similarly
316 redirected, but execute the make commands from the Compile/SW
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.
326 o USING MODULES NOT INSTALLED IN THE STANDARD LOCATION
328 You can explicitly tell perl where to look for modules by using the
329 lib module which comes standard with perl.
335 use lib "/home/users/dag/My_Local_Perl_Modules/";
338 <...insert whizzy perl code here...>
340 Or, you can set the environmental variable PERL5LIB:
344 setenv PERL5LIB /home/users/dag/My_Local_Perl_Modules/
348 export PERL5LIB=/home/users/dag/My_Local_Perl_Modules/
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:
358 >perl -I. -w t/SeqIO.t
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.
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.
376 o BUILDING THE OPTIONAL bioperl-ext PACKAGE
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,
384 This Installation works out-of-the box for all platforms except BSD
385 and Solaris boxes. For other platforms skip this next paragraph.
387 - CONFIGURING for BSD and Solaris boxes
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
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
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.
411 This should install the compiled extension. The Bio::Tools::pSW module
412 will work cleanly now.
415 o DEPENDENCIES AND Bundle::BioPerl
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.
422 The DBD::mysql, DB_File and XML::Parser modules require other
423 applications or databases: MySQL, Berkeley DB, and expat respectively.
426 Module Where it is Used
427 ------------------------------------------------------------------
428 HTTP::Request::Common GenBank+GenPept sequence retrieval,
429 remote http Blast jobs
431 Bio::Tools::Run::RemoteBlast
433 LWP::UserAgent GenBank+GenPept sequence retrieval,
434 remote http Blast jobs
436 Bio::Tools::Run::RemoteBlast
438 AcePerl Access to ACeDB databases
441 Available at http://stein.cshl.org
443 IO::String IO handle to read or write to a string
452 XML::Parser Parsing of XML documents
453 Bio::Biblio::IO::medlinexml
455 Requires expat from http://sourceforge.net/projects/expat/
457 XML::Writer Parsing + writing of XML documents
461 XML::Parser::PerlSAX Parsing of XML documents
464 Bio::SearchIO::blastxml
465 Bio::Biblio::IO::medlinexml
467 XML::Twig Parsing of XML documents
468 Bio::Variation::IO::xml
472 File::Temp Temporary File creation
476 SOAP::Lite SOAP protocol, XEMBL Services
478 Bio::DB::XEMBLService
480 HTML::Parser HTML parsing of GDB page
483 DBD::mysql Mysql API for loading and querying of Mysql-based
484 GFF feature and BioSQL databases
486 bioperl-db external package
487 bioperl-pipeline external package
489 Requires Mysql from www.mysql.org
491 GD GD graphical drawing library
494 Requires GD library from www.boutell.com/gd
497 Storable Persistent object storage & retrieval
500 Text::Shellwords Text parser
501 Bio::Graphics::FeatureFile
507 DB_File Perl access to Berkeley DB
510 Bio::SeqFeature::Collection
513 Requires Berkeley DB, from Linux RPM or from www.sleepycat.com
515 Graph::Directed Generic graph data and algorithms
516 Bio::Ontology::OBOEngine
518 Data::Stag::ITextWriter Structured Tags datastructures
519 Bio::SeqIO::chadoitext
521 Data::Stag::SxprWriter Structured Tags datastructures
522 Bio::SeqIO::chadosxpr
524 Data::Stag::XMLWriter Structured Tags datastructures
527 Text::Wrap Very optional
528 Bio::SearchIO::Writer::TextResultWriter
530 HTML::Entities Parse BLAST results in XML
531 Bio/SearchIO/blastxml
533 Class::AutoClass Used to create objects
534 Bio::Graph::SimpleGraph*
536 Clone Used to clone objects
537 Bio::Graph::ProteinGraph
539 XML::SAX New style SAX parser
542 XML::SAX::Base New style SAX parser
547 Convert::Binary::C Binary Data Conversion using C Types
550 Spreadsheet::ParseExcel Read Microsoft Excel files