This is the README file for the Bioperl central distribution, version 0.06 # $Id: README,v 1.8.2.2 2000/04/01 18:00:23 dag Exp $ o About Bioperl Thanks for downloading this distribution! Bioperl is an association of developers of public domain Perl tools for computational molecular biology. Our website http://bio.perl.org provides an online resource for modules, scripts, and web links for developers of Perl-based software for life science research. o Contact info Bioperl developers: vsns-bcd-perl-guts@lists.uni-bielefeld.de Project website : http://bio.perl.org Project FTP server: bio.perl.org (anonymous FTP ok) Bug reports : http://bio.perl.org/bioperl-bugs/ bioperl-bugs@bio.perl.org Please send us bugs, in particular about documentation which you think is unclear or problems in installation. We are also very interested in functions which don't work the way you think they do! o System requirements - Not tested on anything but common forms of Unix - perl 5.004 or later (*). - ANSI C or Gnu C compiler for XS extensions - LWP (libwww-perl) modules for running network BLAST analyses (available from CPAN http://www.perl.com/CPAN/). * Note that most modules will work with earlier versions of perl. The only ones that will not are Bio::SimpleAlign.pm and the Bio::Index::* modules. If you don't need these modules and you want to install bioperl using an earlier version of perl, edit the "require 5.004;" line in Makefile.PL as necessary. o Documentation The "meta" documentation can be found in the bioperl.pod file. This should be the starting point for you to read about what bioperl is, how to use it and who wrote it. (The rest of this file will tell you how to install bioperl) Use your favorite pod2* translator turn it into the format of choice or view it directly via perldoc. For example, go perldoc bioperl or in this directory go pod2text bioperl.pod | more pod2html, which comes with Perl, can be used to create web-browser navigable documentation files. Individual .pm modules have their own embedded POD documentation as well. Remember 'perldoc' is your friend. You can use this to read any file containing POD formatted documentation without needing any type of translator. o Install directions THE EASY WAY The Bioperl modules are distributed as a tar file in standard perl CPAN distribution form. This means that installation is very simple. Once you have unpacked the tar distribution there is a directory called bioperl-xx/, which is where this file is. Move into that directory (you may well be already in the right place!) and issue the following commands: perl Makefile.PL # makes a system-specific makefile make # makes the distribution make test # runs the test code make install # [may need root access for system install. # See below for how to get around this.] This should build, test and install the distribution cleanly on your system. This installs the main perl part of bioperl, which is the majority of the bioperl modules. There is one module (Bio::Tools::pSW) which needs a compiled extension. This needs an extra installation step. The directions for installing this are given below - it is almost as easy as installing the standard distribution, so don't worry! You may have some errors from the pod2man part of the installation, such as /usr/bin/pod2man: Unrecognized pod directive in paragraph 168 of Bio/Tools/Blast.pm: head3 You don't need to worry about them: they do not effect the documentation processing. To install you need write permission in the perl5/site_perl/ source area. Quite often this will require you (or someone else) becoming root, so you will want to talk to your systems manager if you don't have the necessary access. It is possible to install the package outside of the standard Perl5 location. See below for details. INSTALLING THE COMPILED EXTENSIONS You need the bioperl-ext package for the compiled extensions. This Installation works out-of-the box for all platforms except *BSD and Solaris boxes. For notes on this, read on. For other platforms, skip ahead to the next section, BUILDING THE COMPILED EXTENSIONS. INSTALLING for *BSD and Solaris boxes. You should add the line -fPIC to the CFLAGS line in 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 BUILDING THE COMPILED EXTENSIONS Move to the directory Compile/SW. 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 # Solaris/BSD users might need to edit the Makefile here 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. INSTALLING TO USE Readseq Edit the top of Bio::Parse.pm to show the path to readseq, ie edit ## Uncomment the $OK stuff (it is mentioned twice to ## shut strict up. Set $READSEQ_PATH to the full path ## to the readseq executable. ## $OK = "Y"; ## $OK = "Y"; my $READSEQ_PATH=undef; to something like ## Uncomment the $OK stuff (it is mentioned twice to ## shut strict up. Set $READSEQ_PATH to the full path ## to the readseq executable. $OK = "Y"; $OK = "Y"; my $READSEQ_PATH='/usr/local/bin/readseq'; The use of readseq like this has been officially 'deprecated', waiting for a better system in 0.06 which will be much more transparent as to what is going on. INSTALLING BIOPERL IN A PERSONAL OR PRIVATE 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. Note: you _must_ have write permission to this area. Simply pass a parameter to perl as it builds your system specific makefile. Example: perl Makefile.PL PREFIX=/home/dag/My_Local_Perl_Modules make make test make install This will cause perl to install the bioperl modules in: /home/dag/My_Perl_Modules/lib/perl5/site_perl/ And the bioperl man pages will go in: /home/dag/My_Perl_Modules/lib/perl5/man/ To specify a directory besides lib/perl5/site_perl, or if there are still permission problems, include an INSTALLSITELIB directive along with the PREFIX: perl Makefile.PL PREFIX=/home/dag/perl INSTALLSITELIB=/home/dag/perl/lib See below for how to use modules that are not installed in the standard Perl5 location. THE HARD WAY :) INSTALLING BIOPERL MODULES: LAST RESORT 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 below 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 or 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 PERL 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/My_Local_Perl_Modules/"; use Bio::Seq; <...insert whizzy perl code here...>