README

   1 This is the README file for the Bioperl central distribution,
   2 version 0.04.4
   3
   4 # $Id$
   5
   6
   7 o About Bioperl
   8
   9  Thanks for downloading this distribution!
  10
  11  Bioperl is an association of developers of public
  12  domain Perl tools for computational molecular
  13  biology.
  14
  15  Our website http://bio.perl.org provides an online
  16  resource for modules, scripts, and web links for
  17  developers of Perl-based software for life
  18  science research.
  19
  20
  21 o Contact info
  22
  23  Bioperl developers: vsns-bcd-perl-guts@lists.uni-bielefeld.de
  24
  25  Project website   : http://bio.perl.org
  26  Project FTP server: bio.perl.org (anonymous FTP ok)
  27
  28  Bug reports       : http://bio.perl.org/bioperl-bugs/
  29                      bioperl-bugs@bio.perl.org
  30
  31  Please send us bugs, in particular about documentation which you
  32  think is unclear or problems in installation. We are also very
  33  interested in functions which don't work the way you think they do!
  34
  35 o System requirements
  36
  37   - Not tested on anything but common forms of Unix
  38   - perl 5.003 or later (5.004 recommended; not much 5.005 testing)
  39   - ANSI C or Gnu C compiler for XS extensions
  40
  41 o Documentation
  42
  43   The "meta" documentation can be found in the bioperl.pod file.
  44   This should be the starting point for you to read about what
  45   bioperl is, how to use it and who wrote it. (The rest of this
  46   file will tell you how to install bioperl)
  47
  48   Use your favorite pod2* translator turn it into the format of
  49   choice or view it directly via perldoc.
  50
  51   For example, go
  52
  53   perldoc bioperl
  54
  55   or in this directory go
  56
  57   pod2text bioperl.pod | more
  58
  59   pod2html, which comes with Perl, can be used to create web-browser
  60   navigable documentation files.
  61
  62   Individual .pm modules have their own embedded POD documentation
  63   as well.
  64
  65   Remember 'perldoc' is your friend. You can use this to read any
  66   file containing POD formatted documentation without needing any type
  67   of translator.
  68
  69
  70 o Install directions
  71
  72 THE EASY WAY
  73
  74 The Bioperl modules are distributed as a tar file in standard perl
  75 CPAN distribution form. This means that installation is very
  76 simple. Once you have unpacked the tar distribution there is a
  77 directory called bioperl-xx/, which is where this file is.  Move into
  78 that directory (you may well be already in the right place!) and
  79 issue the following commands:
  80
  81   perl Makefile.PL   # makes a system-specific makefile
  82   make               # makes the distribution
  83   make test          # runs the test code
  84   make install       # [may need root access for system install.
  85                      #  See below for how to get around this.]
  86
  87 This should build, test and install the distribution cleanly on your
  88 system.  This installs the main perl part of bioperl, which is the
  89 majority of the bioperl modules. There is one module (Bio::Tools::pSW)
  90 which needs a compiled extension. This needs an extra installation
  91 step. The directions for installing this are given below - it is
  92 almost as easy as installing the standard distribution, so don't
  93 worry!
  94
  95 You may have some errors from the pod2man part of the installation,
  96 such as
  97
  98 /usr/bin/pod2man: Unrecognized pod directive in paragraph 168 of Bio/Tools/Blast.pm: head3
  99
 100 You don't need to worry about them: they do not effect the documentation
 101 processing.
 102
 103 To install you need write permission in the perl5/site_perl/ source area.
 104 Quite often this will require you (or someone else) becoming root,
 105 so you will want to talk to your systems manager if you don't
 106 have the necessary access.
 107
 108 It is possible to install the package outside of the standard Perl5
 109 location. See below for details.
 110
 111 To install the Compiled extension for pSW you will need to read the
 112 next section of the manual.
 113
 114
 115 INSTALLING THE COMPILED EXTENSIONS
 116
 117 Move to the directory Compile/SW. This is where the C code and XS
 118 extension for the bp_sw module is held and execute these commands:
 119
 120   perl Makefile.PL   # makes the system specific makefile
 121   make               # builds all the libaries
 122   make test          # runs a short test
 123   make install       # installs the package correctly.
 124
 125 This should install the compiled extension. The Bio::Tools::pSW module
 126 will work cleanly now.
 127
 128
 129 INSTALLING BIOPERL IN A PERSONAL OR PRIVATE MODULE AREA
 130
 131 If you lack permission to install perl modules into the
 132 standard site_perl/ system area you can configure bioperl to
 133 install itself anywhere you choose. Ideally this would
 134 be a personal perl directory or standard place where you
 135 plan to put all your 'local' or personal perl modules.
 136
 137 Note: you _must_ have write permission to this area.
 138
 139 Simply pass a parameter to perl as it builds your system
 140 specific makefile.
 141
 142 Example:
 143
 144   perl Makefile.PL  PREFIX=/home/dag/My_Local_Perl_Modules
 145   make
 146   make test
 147   make install
 148
 149 This will cause perl to install the bioperl modules in:
 150 /home/dag/My_Perl_Modules/lib/perl5/site_perl/
 151
 152 And the bioperl man pages will go in:
 153 /home/dag/My_Perl_Modules/lib/perl5/man/
 154
 155 To specify a directory besides lib/perl5/site_perl,
 156 or if there are still permission problems, include
 157 an INSTALLSITELIB directive along with the PREFIX:
 158
 159   perl Makefile.PL  PREFIX=/home/dag/perl INSTALLSITELIB=/home/dag/perl/lib
 160
 161 See below for how to use modules that are not installed in the
 162 standard Perl5 location.
 163
 164
 165 THE HARD WAY :)
 166
 167 INSTALLING BIOPERL MODULES: LAST RESORT
 168
 169 As a last resort, you can simply copy all files in Bio/
 170 to any directory in which you have write privileges. This is
 171 generally NOT recommended since some modules may require
 172 special configuration (currently none do, but don't rely
 173 on this.
 174
 175 You will need to set "use lib '/path/to/my/bioperl/modules';"
 176 in your perl scripts so that you can access these modules if
 177 they are not installed in the standard site_perl/ location.
 178 See below for an example.
 179
 180 To get manpage documentation to work correctly you will have
 181 to configure man so that it looks in the proper directory.
 182 On most systems this will just involve adding an additional
 183 directory to your $MANPATH environment variable.
 184
 185 The installation of the Compile directory can be similarly
 186 redirected, but execute the make commands from the Compile/SW
 187 directory.
 188
 189 If all else fails or are unable to access the perl distribution
 190 directories, ask your system administrator to place the files there
 191 for you. You can always execute perl scripts in the same directory
 192 as the location of the modules (Bio/ in the distribution) since perl
 193 always checks the current working directory when looking for modules.
 194
 195
 196 USING MODULES NOT INSTALLED IN THE STANDARD PERL LOCATION
 197
 198 You can explicitly tell perl where to look for modules by using the
 199 lib module which comes standard with perl.
 200
 201 Example:
 202
 203    #!/usr/bin/perl
 204
 205    use lib "/home/users/dag/My_Local_Perl_Modules/";
 206    use Bio::Seq;
 207
 208    <...insert whizzy perl code here...>
 209