From ddf242fc855347f429d26f145adc48bb217b0f4d Mon Sep 17 00:00:00 2001 From: =?utf8?q?Carn=C3=AB=20Draug?= Date: Fri, 14 Sep 2018 18:53:59 +0100 Subject: [PATCH] maint: simplify README to cover simple install instructions. Remove instructions on how to install perl on different OS, there's plenty of pages online on how to do it, nothing of this is BioPerl specific. Also link to the CPAN page about how to install perl modules which applies to BioPerl modules. Make reference to how BioPerl project is actually multiple distributions and to install with cpanm by naming the module required. Add new HACKING.md, merge of README and INSTALL files, for users interested in development. --- README.md => HACKING.md | 126 ++++++++++++--------- INSTALL-WIN.md | 156 -------------------------- INSTALL.md | 263 -------------------------------------------- README.md | 284 +++++++++--------------------------------------- 4 files changed, 130 insertions(+), 699 deletions(-) copy README.md => HACKING.md (74%) delete mode 100644 INSTALL-WIN.md delete mode 100644 INSTALL.md rewrite README.md (95%) diff --git a/README.md b/HACKING.md similarity index 74% copy from README.md copy to HACKING.md index 5b631f94f..303f96091 100644 --- a/README.md +++ b/HACKING.md @@ -1,33 +1,3 @@ -[![Build Status](https://travis-ci.org/bioperl/bioperl-live.svg?branch=master)](https://travis-ci.org/bioperl/bioperl-live) -[![Coverage Status](https://coveralls.io/repos/bioperl/bioperl-live/badge.png?branch=master)](https://coveralls.io/r/bioperl/bioperl-live?branch=master) -[![DOI](https://zenodo.org/badge/doi/10.5281/zenodo.16344.svg)](http://dx.doi.org/10.5281/zenodo.16344) -[![Documentation Status](https://readthedocs.org/projects/bioperl/badge/?version=latest)](https://readthedocs.org/projects/bioperl/?badge=latest) - -# Getting Started - -Please see the the [INSTALL](http://bioperl.org/INSTALL.html) or [INSTALL.WIN](http://bioperl.org/INSTALL.WIN.html) documents for installation -instructions. - -# About BioPerl - -BioPerl is a package of public domain Perl tools for computational molecular -biology. - -Our website (http://bioperl.org/) provides an online resource of modules, -scripts, and web links for developers of Perl-based software for life science -research. - -# Contact Information - -* BioPerl mailing list: bioperl-l@bioperl.org - -* Project website : http://bioperl.org/ - -* Bug reports : https://github.com/bioperl/bioperl-live/issues - -Please submit bugs, in particular about documentation which you think is -unclear, or about problems in installation. We are also very interested in functions which don't work the way you think they do! - # The Directory Structure The BioPerl directory structure is organized as follows: @@ -79,7 +49,7 @@ way. BioPerl releases are always available from the website at http://www.bioperl.org/DIST or in CPAN. The latest code can be found at https://github.com/bioperl. -* BioPerl currently uses a sematic numbering scheme to indicate stable release +* BioPerl currently uses a semantic numbering scheme to indicate stable release series vs. development release series. A release number is a three digit number like `1.2.0`. * The *first digit indicates the major release*, the idea being that all the @@ -93,7 +63,7 @@ BioPerl releases are always available from the website at http://www.bioperl.org From the **1.0 release until the 1.6 release** even numbers (e.g. `1.4`) indicated stable releases. Stable releases were well tested and recommended for most uses. Odd numbers (e.g. `1.3`) were development releases which one would only use if one were interested in the latest features. The final number (e.g. in `1.2.1`) is the point or patch release. The higher the number the more bug fixes has been incorporated. In theory you can upgrade from one point or patch release to the next with no changes to your own code (for production cases, obviously check things out carefully before you switch over). -The upcoming **1.7 release** will be the last release series to utilize the alternating 'stable'/'developer' convention. Starting immediately after the final 1.6 branch, we will start splitting BioPerl into several smaller easier-to-manage distributions. These will have independent versions, all likely starting with v1.7.0. **We do not anticipate major API changes in the 1.7.x release series, merely that the code will be restructured in a way to make maintenance more feasible.** We anticipate retaining semantic versioning until the 2.x release. +The upcoming **1.7 release** will be the last release series to utilise the alternating 'stable'/'developer' convention. Starting immediately after the final 1.6 branch, we will start splitting BioPerl into several smaller easier-to-manage distributions. These will have independent versions, all likely starting with v1.7.0. **We do not anticipate major API changes in the 1.7.x release series, merely that the code will be restructured in a way to make maintenance more feasible.** We anticipate retaining semantic versioning until the 2.x release. # Caveats and Warnings @@ -111,15 +81,12 @@ Not all scripts in the `examples/` directory are correct and up-to-date. If you If you are confused about what modules are appropriate when you try and solve a particular issue in bioinformatics we urge you to look at HOWTO documents first. -# A simple module summary +# Module summary -Here is a quick summary of many of the useful modules and how the toolkit is -laid out: +Here is a quick summary of many of the useful modules and how the +toolkit is laid out. Some of these are on their own distribution. -All modules are in the **`Bio/`** namespace, - -* **`Perl`** is for *new users*, and gives a functional interface to the main - parts of the package. +All modules are in the `Bio::` namespace. * **`Seq`** is for *Sequences* (protein and DNA). * `Bio::PrimarySeq` is a plain sequence (sequence data + identifiers) @@ -133,7 +100,7 @@ All modules are in the **`Bio/`** namespace, * **`SeqIO`** is for *reading and writing Sequences*. It is a front end module for separate driver modules supporting the different sequence formats -* **`SeqFeature`** represent *start/stop/strand-based localized annotations (features) of sequences* +* **`SeqFeature`** represent *start/stop/strand-based localised annotations (features) of sequences* * **`Bio::SeqFeature::Generic`** is basic catchall * **`Bio::SeqFeature::Similarity`** a similarity sequence feature * **`Bio::SeqFeature::FeaturePair`** a sequence feature which is pairwise @@ -215,16 +182,75 @@ All modules are in the **`Bio/`** namespace, * **`Root`**, basic objects for the *internals of BioPerl* -# Upgrading from an older version +## The Test System + +The BioPerl test system is located in the `t/` directory and is +automatically run whenever you execute the `./Build test` command. + +The tests have been organised into groups +based upon the specific task or class the module being tested belongs +to. If you want to investigate the behaviour of a specific test such as +the Seq test you would type: + +``` +./Build test --test_files t/Seq/Seq.t --verbose +``` + +The `--test_files` argument can be used multiple times to try a set of test +scripts in one go. The `--verbose` argument 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 +``` + +You can also use the command-line tool `prove` to run tests as well, which +is quite useful if you are developing code: + +``` +prove -lrv t/SearchIO* +``` + +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 stabilises. + +[how to install Docker]: https://docs.docker.com/engine/installation/ +[bioperl/bioperl]: https://hub.docker.com/r/bioperl/bioperl/ +[bioperl/bioperl-deps]: https://hub.docker.com/r/bioperl/bioperl-deps/ + +# Using BioPerl via Docker + +If you don't have Docker installed already, instructions for [how to install Docker] on Linux, MacOSX, and Windows are available online. + +We officially support several builds (latest, stable, and releases) +hosted in the [bioperl/bioperl] repo on Docker Hub. These images do not +have a pre-defined entrypoint. If you have a BioPerl script in the +current directory, you can run it as simple as this: + +``` +docker run -t --rm -v `pwd`:/work -w /work bioperl/bioperl perl my-script.pl +``` -If you have a previously installed version of BioPerl on your system some of -these notes may help you. +Or run an interactive shell: -* Some modules have been removed because they have been superceded by new - development efforts. They are documented in the **`DEPRECATED`** file that is - included in the release. +``` +docker run -ti --rm -v `pwd`:/work -w /work bioperl/bioperl bash +``` -* Some methods, or the Application Programming Interface (API), have changed or - been removed. You may find that scripts which worked with BioPerl 1.4 may give you warnings or may not work at all (although we have tried very hard to - minimize this!). Send an email to the list and we'll be happy to give you - pointers. +You can also build your own Docker image of BioPerl, using the same +base image and pre-built dependencies that we use. Simply build off of +the [bioperl/bioperl-deps] image. diff --git a/INSTALL-WIN.md b/INSTALL-WIN.md deleted file mode 100644 index ebaabba2f..000000000 --- a/INSTALL-WIN.md +++ /dev/null @@ -1,156 +0,0 @@ -# Installing BioPerl on Windows - -# Introduction - -This installation guide was written by Barry Moore, Nathan Haigh -and other BioPerl authors based on the original work of Paul Boutros. The -guide has been updated by Paul Cantalupo and Francisco Ossandon. -*Note* For Windows it is recommended to install BioPerl version 1.6.924 or -newer, since many Windows-specific bugs from previous versions were fixed. - -Please report problems and/or fixes to the BioPerl mailing list. - -# Perl Options - -There are a couple of ways of installing Perl on a Windows machine. One is -to get the most recent build from [Strawberry Perl](http://strawberryperl.com/) -and the other is to get it from [ActiveState](http://www.activestate.com/). -Both are software companies that provide free builds of Perl for Windows -users. - -Strawberry Perl is recommended since is more CPAN-friendly and -because it includes a compiler (gcc), related tools and other external -libraries. These installation steps were verified on December 2015 using -ActivePerl 5.20.2.2002 (5.22 has been released but the MinGW package is not -available for it yet) and Strawberry Perl 5.22.0.1 from a clean install. - -*Note* Only ActivePerl **5.18 or greater** is supported by the BioPerl team. -This is because the necessary MinGW package needed for CPAN installations -is only available for both 32-bit and 64-bit Windows since this version -(32-bit was available on previous versions but only in the Business edition, -see [ActivePerl MinGW PPM webpage](http://www.activestate.com/activeperl/downloads)). - -*Note* Support for installation through ActivePerl Perl Package Manager has been dropped in favor of CPAN. - -# Installing Perl on Windows - -1. Download the [Strawberry Perl MSI](http://strawberryperl.com/releases.html) or [ActivePerl MSI](http://www.activestate.com/activeperl/downloads). -2. Run the Installer (accepting all defaults is fine). - -You can also build Perl yourself (which requires a C compiler). The Perl -source for building it yourself is available from [CPAN](http://www.cpan.org/). -This approach is not recommended unless you have specific reasons for doing so -and know what you're doing. - -[Cygwin](http://en.wikipedia.org/wiki/Cygwin) is a [UNIX](http://en.wikipedia.org/wiki/UNIX) -emulation environment for Windows and comes with its own copy of Perl. Information on Cygwin and BioPerl is found below. - -### Installation using the ActiveState Perl Package Manager - -This installation is not supported nor recommended anymore, because the last -BioPerl package produced for it was the old version 1.6.1 (2009) and many -Windows-specific bugs were fixed in more recent versions 1.6.923 and 1.6.924. -Please install using the CPAN instructions below. - -# CPAN for Strawberry Perl and ActivePerl - -Both CPAN and manual methods ultimately need the accessory compiling program -MinGW, which incorporates the necessary tools like `dmake` and `gcc`. MinGW comes -by default with Strawberry Perl, but must it be installed through PPM for -ActivePerl (CPAN will display a warning if not present). Also, CPAN need to be -upgraded to >= v1.81, [Module::Build](https://metacpan.org/pod/Module::Build) -to be upgraded (>= v0.2805) and [Test::Harness](https://metacpan.org/pod/Test::Harness) to be upgraded to >= v2.62. - -### Dmake for ActivePerl - -1) Install MinGW package through PPM: Using a cmd window type - -`ppm install MinGW`. - -It is `important` to check if ActiveState provides the -[MinGW package](http://code.activestate.com/ppm/MinGW/) for your ActivePerl version, -since each version have to wait its own release. For example, -although MinGW has been available since ActivePerl version 5.18, -the release for newest version 5.22 it's still not available (December 2015). - -### Start the install with CPAN - -1. Open a cmd window by going to `Start >> Run` and typing `cmd` -into the box and pressing return. - -2. Type `cpan` to enter the CPAN shell. - -3. At the `cpan>` prompt, type `install CPAN` to upgrade to the -latest version. - -4. Quit (by typing 'q') and reload CPAN. You may be asked some -configuration questions; accepting defaults is fine. - -5. At the `cpan>` prompt, type `o conf prefer_installer MB` to tell -CPAN to prefer to use `Build.PL` scripts for installation, and the type `o conf commit` to save that choice. - -6. At the `cpan>` prompt, type `install Module::Build`. - -7. At the `cpan>` prompt, type `install Test::Harness`. - -8. At the `cpan>` prompt, type `install Test::Most`. - -### Finish the install with CPAN - -You can now follow the instructions INSTALLING BioPerl THE EASY WAY -USING CPAN in the INSTALL file. - -### Finish the install with BioPerl from GitHub - -For the bleeding edge version install manually using a ZIP file from the -GitHub repository: - -1. Go to [GitHub](https://github.com/BioPerl/BioPerl-live) and press the -`Download ZIP` button. - -2. Extract the archive in the normal way. - -3. In a cmd window `cd` to the directory you extracted to. Eg. if -you extracted to directory 'BioPerl-live', `cd BioPerl-live` - -4. Type `perl Build.PL` and answer the questions appropriately. - -5. Type `perl Build test`. All the tests should pass, but if they don't, -[let us know](https://github.com/BioPerl/BioPerl-live/issues). Your usage of -BioPerl may not be affected by the failure, so you can choose to continue -anyway. - -6. Type `perl Build install` to install BioPerl. - -# BioPerl in Cygwin - -Cygwin is a Unix emulator and shell environment available free at -http://www.cygwin.com. Some users claim that installation of BioPerl is -easier within Cygwin than within Windows, but these may be users with UNIX -backgrounds. A note on Cygwin: it doesn't write to your Registry, it doesn't -alter your system or your existing files in any way, it doesn't create -partitions, it simply creates a `cygwin/` directory and writes all of its -files to that directory. To uninstall Cygwin just delete that directory. - -To get BioPerl running first install the basic Cygwin package as well as -the Cygwin `perl`, `make`, `binutils`, and `gcc` packages. Clicking the View -button in the upper right of the installer window enables you to see -details on the various packages. Then start up Cygwin and follow the -BioPerl installation instructions for UNIX in BioPerl's `INSTALL` file. - -## Cygwin paths - -If you're trying to use some application or resource outside of the Cygwin -directory and you're having a problem remember that Cygwin's path syntax -may not be the correct one. Cygwin understands `/home/jacky` or -`/cygdrive/e/cygwin/home/jacky` (when referring to the E: drive) but the -external resource may want `E:/cygwin/home/jacky`. So your `*rc` files may end -up with paths written in these different syntaxes, depending. - -For example, here's how to set the environmental variable TMPDIR, programs -like BLAST and clustalw need a place to create temporary files: - -``` -setenv TMPDIR e:/cygwin/tmp # csh, tcsh -export TMPDIR=e:/cygwin/tmp # sh, bash -``` diff --git a/INSTALL.md b/INSTALL.md deleted file mode 100644 index 856a7119a..000000000 --- a/INSTALL.md +++ /dev/null @@ -1,263 +0,0 @@ -# BioPerl Installation - -There are two principle ways to get BioPerl onto your system. One (and -the still most common) is to install it locally on your machine. To do -this, refer to and follow the instructions below for installing BioPerl on -Unix, Linux, and Mac OS X. For installing BioPerl on Windows, please -read INSTALL.WIN. The other way is to use a Docker image with a -BioPerl build, whether one we support or one you build yourself. - -# Installing BioPerl locally - -Note that this documentation is for Unix, Linux, and MacOSX. For installing BioPerl on Windows, please read INSTALL.WIN. - -## System Requirments - - * `Perl 5.6.1 or higher` Version 5.10 or higher is highly - recommended. Modules are tested against version 5.14 and - above. - * `make` For Mac OS X, this requires installing the Xcode Developer - Tools. - -## Preliminary Preparation - -These are optional, but regardless of your subsequent choice of -installation method, it will help to carry out the following steps. -They will increase the likelihood of installation success -(especially of the optional dependencies). - -* Upgrade CPAN: - -``` -perl -MCPAN -e shell -``` - -* Install or upgrade `Module::Build`, and make it your preferred installer: - -``` -cpan>install Module::Build -cpan>o conf prefer_installer MB -cpan>o conf commit -``` - -* Install the `expat` library by whatever method is appropriate for your system (e.g. `apt`, `yum`, `homebrew`). - -## Installing BioPerl the Easy Way - -We highly recommend using -[cpanminus](https://metacpan.org/pod/distribution/App-cpanminus/bin/cpanm) for -installing BioPerl and its dependencies. We also highly recommend (if possible) -using a tool like [perlbrew](https://perlbrew.pl) to locally install a modern -version of perl (a version that is higher than perl 5.16). The linked -pages describe how to install each tool; make sure if you install perlbrew that -you follow up with installing `cpanm`: - -``` -perlbrew install-cpanm -``` - -Then, you can install BioPerl: - -``` -cpanm Bio::Perl -``` - -You can also use the older 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 latest BioPerl package: - -``` -cpan>d /bioperl/ - .... - - Distribution C/CJ/CJFIELDS/BioPerl-1.007001.tar.gz - Distribution C/CJ/CJFIELDS/BioPerl-1.007001.tar.gz - Distribution C/CJ/CJFIELDS/BioPerl-1.007001.tar.gz -``` - -And install the most recent: - -``` -cpan>install C/CJ/CJFIELDS/BioPerl-1.007001.tar.gz -``` - -If you've installed everything perfectly and all the network -connections are working then you will pass all the tests run in the -`./Build test` phase. Sometimes you may see a failed test. Remember that -there are over 900 modules in BioPerl and the test suite is running more -than 12000 individual tests, a failed test may not affect your usage -of BioPerl. - -If there's a failed test and you think that the failed test will not -affect how you intend to use BioPerl then do: - -``` -cpan>force install C/CJ/CJFIELDS/BioPerl-1.007001.tar.gz -``` - -If you're concerned about a failed test and need assistance or advice -then contact bioperl-l@bioperl.org, and provide us the detailed -results of the failed install. - -## Installing BioPerl from Github - -**NOTE:** We generally do not recommend installing the latest code from Github -unless you absolutely need the latest bug fixes. - -The very latest version of Bioperl is at github.com. If you want this -version then download it from https://github.com/bioperl/bioperl-live as a -`tar.gz` or `zip` file, or retrieve it using the command line: - -``` -git clone https://github.com/bioperl/bioperl-live.git -cd bioperl-live -``` - -### Using cpanm - -If you have `cpanm`, you can install within the checkout directory by simply using: - -``` -cpanm --interactive . -``` - -to run interative installation, or you can leave out the `--interactive` flag to accept the defaults. - -### Using the Installation Script - -Issue the build commands: - -``` -perl Build.PL -``` - -You will be asked a few questions about installing BioPerl scripts -and running various test suites, hit `return` to accept the defaults. - -Test: - -``` -./Build test -``` - -Install: - -``` -./Build install -``` - -You may need root permissions in order to run `./Build install`, so you -will want to talk to your systems manager if you don't have the necessary -privileges. Or you can install the package in your own home -directory, see INSTALLING BIOPERL USING `local::lib`. - -## Installing Bioperl using `local::lib` - -If you lack permission to install Perl modules into the standard -system directories you can install them in your home directory -using [local::lib](https://metacpan.org/pod/local::lib). The instructions for first installing -`local::lib` are found in the link. - -Once `local::lib` is installed you can install BioPerl using a -command like this: - -``` -perl -MCPAN -Mlocal::lib -e 'CPAN::install(C/CJ/CJFIELDS/BioPerl-1.007001.tar.gz)' -``` - -## 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. - -## The Test System - -The BioPerl test system is located in the `t/` directory and is -automatically run whenever you execute the `./Build test` command. - -The tests have been organized into groups -based upon the specific task or class the module being 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 `--test_files` argument 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 -``` - -You can also use the command-line tool `prove` to run tests as well, which -is quite useful if you are developing code: - -``` -prove -lrv t/SearchIO* -``` - -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. - -[how to install Docker]: https://docs.docker.com/engine/installation/ -[bioperl/bioperl]: https://hub.docker.com/r/bioperl/bioperl/ -[bioperl/bioperl-deps]: https://hub.docker.com/r/bioperl/bioperl-deps/ - -# Using BioPerl via Docker - -If you don't have Docker installed already, instructions for [how to install Docker] on Linux, MacOSX, and Windows are available online. - -We officially support several builds (latest, stable, and releases) -hosted in the [bioperl/bioperl] repo on Docker Hub. These images do not -have a pre-defined entrypoint. If you have a BioPerl script in the -current directory, you can run it as simple as this: - -``` -docker run -t --rm -v `pwd`:/work -w /work bioperl/bioperl perl my-script.pl -``` - -Or run an interactive shell: - -``` -docker run -ti --rm -v `pwd`:/work -w /work bioperl/bioperl bash -``` - -You can also build your own Docker image of BioPerl, using the same -base image and pre-built dependencies that we use. Simply build off of -the [bioperl/bioperl-deps] image. - diff --git a/README.md b/README.md dissimilarity index 95% index 5b631f94f..e7da0e302 100644 --- a/README.md +++ b/README.md @@ -1,230 +1,54 @@ -[![Build Status](https://travis-ci.org/bioperl/bioperl-live.svg?branch=master)](https://travis-ci.org/bioperl/bioperl-live) -[![Coverage Status](https://coveralls.io/repos/bioperl/bioperl-live/badge.png?branch=master)](https://coveralls.io/r/bioperl/bioperl-live?branch=master) -[![DOI](https://zenodo.org/badge/doi/10.5281/zenodo.16344.svg)](http://dx.doi.org/10.5281/zenodo.16344) -[![Documentation Status](https://readthedocs.org/projects/bioperl/badge/?version=latest)](https://readthedocs.org/projects/bioperl/?badge=latest) - -# Getting Started - -Please see the the [INSTALL](http://bioperl.org/INSTALL.html) or [INSTALL.WIN](http://bioperl.org/INSTALL.WIN.html) documents for installation -instructions. - -# About BioPerl - -BioPerl is a package of public domain Perl tools for computational molecular -biology. - -Our website (http://bioperl.org/) provides an online resource of modules, -scripts, and web links for developers of Perl-based software for life science -research. - -# Contact Information - -* BioPerl mailing list: bioperl-l@bioperl.org - -* Project website : http://bioperl.org/ - -* Bug reports : https://github.com/bioperl/bioperl-live/issues - -Please submit bugs, in particular about documentation which you think is -unclear, or about problems in installation. We are also very interested in functions which don't work the way you think they do! - -# The Directory Structure - -The BioPerl directory structure is organized as follows: - -* **`Bio/`** - BioPerl modules - -* **`examples/`** - Scripts demonstrating the many uses of BioPerl - -* **`ide/`** - Files for developing BioPerl using an IDE - -* **`maintenance/`** - BioPerl housekeeping scripts - -* **`models/`** - DIA drawing program generated OO UML for BioPerl classes - (these are quite out-of-date) - -* **`scripts/`** - Useful production-quality scripts with POD documentation - -* **`t/`** - Perl built-in tests, tests are divided into subdirectories - based on the specific classes being tested - -* **`t/data/`** - Data files used for the tests, provides good example data - -* **`travis_scripts/`** - script to customize Travis - -# Documentation - -For documentation on BioPerl see the **HOWTO** documents online at http://bioperl.org/howtos. - -Useful documentation in the form of example code can also be found in the -**`examples/`** and **`scripts/`** directories. The current collection includes -scripts that run BLAST, index flat files, parse PDB structure files, make -primers, retrieve ESTs based on tissue, align protein to nucleotide sequence, -run GENSCAN on multiple sequences, and much more! See `bioscripts.pod` for a -complete listing. - -Individual `*.pm` modules have their own embedded POD documentation as well. A -complete set of hyperlinked POD, or module, documentation is available at -http://www.bioperl.org/. - -Remember that '`perldoc`' is your friend. You can use it to read any file -containing POD formatted documentation without needing any type of translator -(e.g. '`perldoc Bio::SeqIO`'). - -If you used the Build.PL installation, and depending on your platform, you may -have documentation installed as man pages, which can be accessed in the usual -way. - -# Releases - -BioPerl releases are always available from the website at http://www.bioperl.org/DIST or in CPAN. The latest code can be found at https://github.com/bioperl. - -* BioPerl currently uses a sematic numbering scheme to indicate stable release - series vs. development release series. A release number is a three digit - number like `1.2.0`. - * The *first digit indicates the major release*, the idea being that all the - API calls in a major release are reasonably consistent. - * The *second number is the release series*. This is probably the most - important number, and represents added functionality that is - backwards-compatible. - * The *third number is the point or patch release* and represents mainly bug - fixes or additional code that doesn't add significant functionality to the - code base. - -From the **1.0 release until the 1.6 release** even numbers (e.g. `1.4`) indicated stable releases. Stable releases were well tested and recommended for most uses. Odd numbers (e.g. `1.3`) were development releases which one would only use if one were interested in the latest features. The final number (e.g. in `1.2.1`) is the point or patch release. The higher the number the more bug fixes has been incorporated. In theory you can upgrade from one point or patch release to the next with no changes to your own code (for production cases, obviously check things out carefully before you switch over). - -The upcoming **1.7 release** will be the last release series to utilize the alternating 'stable'/'developer' convention. Starting immediately after the final 1.6 branch, we will start splitting BioPerl into several smaller easier-to-manage distributions. These will have independent versions, all likely starting with v1.7.0. **We do not anticipate major API changes in the 1.7.x release series, merely that the code will be restructured in a way to make maintenance more feasible.** We anticipate retaining semantic versioning until the 2.x release. - -# Caveats and Warnings - -When you run the tests with `./Build test` some tests may issue warnings messages or even fail. Sometimes this is because we didn't have anyone to test the test system on the combination of your operating system, version of perl, and associated libraries and other modules. Because BioPerl depends on several -outside libraries we may not be able to test every single combination so if -there are warnings you may find that the package is still perfectly useful. - -If you install the bioperl-run system and run tests when you don't have the -program installed you'll get messages like `program XXX not found, skipping -tests`. That's okay, BioPerl is doing what it is supposed to do. If you wanted -to run the program you'd need to install it first. - -Not all scripts in the `examples/` directory are correct and up-to-date. If you find an issue with a script please submit a bug report to https://github.com/bioperl/bioperl-live/issues and consider helping out in their maintenance. - -If you are confused about what modules are appropriate when you try and solve a -particular issue in bioinformatics we urge you to look at HOWTO documents first. - -# A simple module summary - -Here is a quick summary of many of the useful modules and how the toolkit is -laid out: - -All modules are in the **`Bio/`** namespace, - -* **`Perl`** is for *new users*, and gives a functional interface to the main - parts of the package. - -* **`Seq`** is for *Sequences* (protein and DNA). - * `Bio::PrimarySeq` is a plain sequence (sequence data + identifiers) - * `Bio::Seq` is a fancier `PrimarySeq`, in that it has annotation (via - `Bio::Annotation::Collection`) and sequence features (via `Bio::SeqFeatureI` objects, attached via - `Bio::FeatureHolderI`). - * `Bio::Seq::RichSeq` is all of the above, plus it has slots for extra information specific to GenBank/EMBL/SwissProt files. - * `Bio::Seq::LargeSeq` is for sequences which are too big for - fitting into memory. - -* **`SeqIO`** is for *reading and writing Sequences*. It is a front end module - for separate driver modules supporting the different sequence formats - -* **`SeqFeature`** represent *start/stop/strand-based localized annotations (features) of sequences* - * **`Bio::SeqFeature::Generic`** is basic catchall - * **`Bio::SeqFeature::Similarity`** a similarity sequence feature - * **`Bio::SeqFeature::FeaturePair`** a sequence feature which is pairwise - such as query/hit pairs - -* **`SearchIO`** is for *reading and writing pairwise alignment reports*, like - BLAST or FASTA - -* **`Search`** is where the *alignment objects for `SearchIO` are defined* - * **`Bio::Search::Result::GenericResult`** is the result object (a blast - query is a `Result` object) - * **`Bio::Search::Hit::GenericHit`** is the `Hit` object (a query will have - 0 to many hits in a database) - * **`Bio::Search::HSP::GenericHSP`** is the High-scoring Segment Pair - object defining the alignment(s) of the query and hit. - -* **`SimpleAlign`** is for *multiple sequence alignments* - -* **`AlignIO`** is for *reading and writing multiple sequence alignment - formats* - -* **`Assembly`** provides the start of an *infrastructure for assemblies* and - **`Assembly::IO`** *IO converters* for them - -* **`DB`** is the namespace for *all the database query classes* - * **`Bio::DB::GenBank/GenPept`** are two modules which query NCBI entrez for - sequences - * **`Bio::DB::SwissProt/EMBL`** query various EMBL and SwissProt - repositories for a sequences - * **`Bio::DB::GFF`** is Lincoln Stein's fast, lightweight feature and - sequence database which is the backend to his GBrowse system (see - www.gmod.org) - * **`Bio::DB::Flat`** is a fast implementation of the OBDA flat-file - indexing system (cross-language and cross-platform supported by O|B|F - projects see http://obda.open-bio.org). - * **`Bio::DB::BioFetch/DBFetch`** for OBDA, Web (HTTP) access to remote - databases. - * **`Bio::DB::InMemoryCache/FileCache`** (fast local caching of sequences - from remote dbs to speed up your access). - * **`Bio::DB::Registry`** interface to the OBDA specification for remote - data sources - * **`Bio::DB::Biblio`** for access to remote bibliographic databases. - * **`Bio::DB::EUtilities`** is the initial set of modules used for generic - queried using NCBI's eUtils. - -* **`Annotation`** collection of *annotation objects* (comments, DBlinks, - References, and misc key/value pairs) - -* **`Coordinate`** is a system for *mapping between different coordinate systems* - such as DNA to protein or between assemblies - -* **`Index`** is for *locally indexed flatfiles* with BerkeleyDB - -* **`Tools`** contains many *miscellaneous parsers and functions* for different - bioinformatics needs - * Gene prediction parser (Genscan, MZEF, Grail, Genemark) - * Annotation format (GFF) - * Enumerate codon tables and valid sequences symbols (CodonTable, - IUPAC) - * Phylogenetic program parsing (PAML, Molphy, Phylip) - -* **`Map`** represents *genetic and physical map representations* - -* **`Structure`** - parse and represent *protein structure data* - -* **`TreeIO`** is for reading and writing *Tree formats* - -* **`Tree`** is the namespace for **all associated Tree classes** - * **`Bio::Tree::Tree`** is the basic tree object - * **`Bio::Tree::Node`** are the nodes which make up the tree - * **`Bio::Tree::Statistics`** is for computing statistics for a tree - * **`Bio::Tree::TreeFunctionsI`** is where specific tree functions are - implemented (like `is_monophyletic` and `lca`) - -* **`Bio::Biblio`** is where *bibliographic data and database access objects* - are kept - -* **`Variation`** represent *sequences with mutations and variations* applied so one can compare and represent wild-type and mutation versions of a sequence. - -* **`Root`**, basic objects for the *internals of BioPerl* - -# Upgrading from an older version - -If you have a previously installed version of BioPerl on your system some of -these notes may help you. - -* Some modules have been removed because they have been superceded by new - development efforts. They are documented in the **`DEPRECATED`** file that is - included in the release. - -* Some methods, or the Application Programming Interface (API), have changed or - been removed. You may find that scripts which worked with BioPerl 1.4 may give you warnings or may not work at all (although we have tried very hard to - minimize this!). Send an email to the list and we'll be happy to give you - pointers. +[![DOI](https://zenodo.org/badge/doi/10.5281/zenodo.16344.svg)](http://dx.doi.org/10.5281/zenodo.16344) +[![Build Status](https://travis-ci.org/bioperl/bioperl-live.svg?branch=master)](https://travis-ci.org/bioperl/bioperl-live) +[![Coverage Status](https://coveralls.io/repos/bioperl/bioperl-live/badge.png?branch=master)](https://coveralls.io/r/bioperl/bioperl-live?branch=master) +[![Documentation Status](https://readthedocs.org/projects/bioperl/badge/?version=latest)](https://readthedocs.org/projects/bioperl/?badge=latest) + +# About BioPerl + +BioPerl is a project for development of free and open source Perl +tools for computational molecular biology. For example, it includes +classes for biological sequences, readers of multiple formats, +sequence alignments, database searching objects, and interfaces to +multiple programs such as EMBOSS, ClustalW, and BLAST. + +The BioPerl project has developed multiple module distributions for +different purposes. The one named BioPerl (named after the project) +provides the foundation for all others distributions. + +This is the repository for the BioPerl distribution only. Other +distributions have [their own +repositories](https://github.com/bioperl/). + +# Installation + +BioPerl distribution has the same name as the BioPerl. However, the +BioPerl distribution only includes a subset of the project modules. +Because of this, the meaning of "installing BioPerl" is rarely clear. +Instead of "install BioPerl", the aim must be "install module X". + +[CPAN.org](https://www.cpan.org/modules/INSTALL.html) provides an +overview on how to install and manage Perl modules but the bottom-line +is: + +1. find the module you need, for example `Bio::DB::EUtilities` +2. install it with `cpanm`, for example `cpanm Bio::DB::EUtilities` + +Alternatively, some Linux distributions have packaged BioPerl and have +it available through their package manager. + +# Documentation and Support + +Documentation for individual modules is in POD and can be read on +[metacpan](https://metacpan.org/pod/BioPerl). + +Additional resources and information about the project is available on +the [project website](https://bioperl.org), with discussion happening +on the [bioperl-l@bioperl.org](mailto: bioperl-l@bioperl.org) mailing +list, and on the `#bioperl` channel of the freenode IRC server. + +Bug reports are handle on the distribution github page. + +# Development + +See the [`HACKING.md`](HACKING.md) file for details on the project +structure, such as building from source and running the test suite. -- 2.11.4.GIT