HACKING.md

   1 # Working with development sources
   2
   3 BioPerl uses [Dist::Zilla](http://dzil.org/) to author releases.  You
   4 will also need the `Dist::Zilla::PluginBundle::BioPerl` installed as
   5 well as its dependencies.  Then, you can run the following commands:
   6
   7     dzil test
   8     dzil install
   9
  10 # The Directory Structure
  11
  12 The bioperl-live repository structure is organized as follows:
  13
  14 * `lib/` - BioPerl modules
  15
  16 * `examples/` - Scripts demonstrating the many uses of BioPerl
  17
  18 * `scripts/` - Useful production-quality scripts with POD documentation
  19
  20 * `t/` - Perl built-in tests, tests are divided into subdirectories
  21   based on the specific classes being tested
  22
  23 * `t/data/` - Data files used for the tests, provides good example data
  24
  25 * `travis_scripts/` - script to customize Travis
  26
  27 ## `Bio::` namespace summary
  28
  29 The BioPerl project is split over multiple Perl module distributions.
  30 The BioPerl distribution is the BioPerl core distribution, including a
  31 selection of modules and namespaces but not all.  For example, the
  32 entire Bio::Biblio is not included in the BioPerl distribution.
  33 Similarly, while many Bio::SearchIO modules in the BioPerl
  34 distribution, there also Bio::SearchIO modules in other distributions
  35 such as Bio-SearchIO-blastxml.
  36
  37 This section describes most of the Bio:: namespaces developed by the
  38 BioPerl project, including those which are not part of the BioPerl
  39 distribution.  For example, the Bio::Biblio and Bio::Assembly are
  40 documented here but are not part of the BioPerl distribution.
  41
  42 * `Bio::Seq` is for *Sequences* (protein and DNA).
  43     * `Bio::PrimarySeq` is a plain sequence (sequence data +
  44       identifiers)
  45     * `Bio::Seq` is a fancier `PrimarySeq`, in that it has annotation
  46       (via `Bio::Annotation::Collection`) and sequence features (via
  47       `Bio::SeqFeatureI` objects, attached via `Bio::FeatureHolderI`).
  48     * `Bio::Seq::RichSeq` is all of the above, plus it has slots for
  49       extra information specific to GenBank/EMBL/SwissProt files.
  50     * `Bio::Seq::LargeSeq` is for sequences which are too big for
  51       fitting into memory.
  52
  53 * `Bio::SeqIO` is for *reading and writing Sequences*.  It is a front
  54   end module for separate driver modules supporting the different
  55   sequence formats.
  56
  57 * `Bio::SeqFeature` represent start/stop/strand-based localised
  58   annotations (features) of sequences
  59     * `Bio::SeqFeature::Generic` is basic catchall
  60     * `Bio::SeqFeature::Similarity` a similarity sequence feature
  61     * `Bio::SeqFeature::FeaturePair` a sequence feature which is
  62       pairwise such as query/hit pairs
  63
  64 * `Bio::SearchIO` is for reading and writing pairwise alignment
  65   reports, like BLAST or FASTA.
  66
  67 * `Bio::Search` is where the alignment objects for `SearchIO` are
  68   defined
  69     * `Bio::Search::Result::GenericResult` is the result object (a
  70       blast query is a `Result` object)
  71     * `Bio::Search::Hit::GenericHit` is the `Hit` object (a query will
  72       have 0 to many hits in a database)
  73     * `Bio::Search::HSP::GenericHSP` is the High-scoring Segment Pair
  74       object defining the alignment(s) of the query and hit.
  75
  76 * `Bio::SimpleAlign` is for multiple sequence alignments
  77
  78 * `Bio::AlignIO` is for reading and writing multiple sequence
  79   alignment formats
  80
  81 * `Bio::Assembly` provides the start of an infrastructure for assemblies and
  82   `Bio::Assembly::IO` *IO converters* for them
  83
  84 * `Bio::DB` is the namespace for database query classes
  85     * `Bio::DB::GenBank/GenPept` are two modules which query NCBI
  86       entrez for sequences.
  87     * `Bio::DB::SwissProt/EMBL` query various EMBL and SwissProt
  88       repositories for a sequences.
  89     * `Bio::DB::GFF` is Lincoln Stein's fast, lightweight feature and
  90       sequence database which is the backend to his
  91       [GBrowse](www.gmod.org) system.
  92     * `Bio::DB::Flat` is a fast implementation of the OBDA flat-file
  93       indexing system (cross-language and cross-platform supported by
  94       O|B|F projects see http://obda.open-bio.org).
  95     * `Bio::DB::BioFetch/DBFetch` for OBDA, Web (HTTP) access to
  96       remote databases.
  97     * `Bio::DB::InMemoryCache/FileCache` (fast local caching of
  98       sequences from remote dbs to speed up your access).
  99     * `Bio::DB::Registry` interface to the OBDA specification for
 100       remote data sources.
 101     * `Bio::DB::Biblio` for access to remote bibliographic databases.
 102     * `Bio::DB::EUtilities` is the initial set of modules used for
 103       generic queried using NCBI's eUtils.
 104
 105 * `Bio::Annotation` collection of annotation objects (comments,
 106   DBlinks, References, and misc key/value pairs)
 107
 108 * `Bio::Coordinate`** is a system for mapping between different
 109   coordinate systems such as DNA to protein or between assemblies
 110
 111 * `Bio::Index` is for locally indexed flatfiles with BerkeleyDB
 112
 113 * `Bio::Tools` contains many *miscellaneous parsers and functions* for different
 114   bioinformatics needs such as:
 115     * Gene prediction parser (Genscan, MZEF, Grail, Genemark)
 116     * Annotation format (GFF)
 117     * Enumerate codon tables and valid sequences symbols (CodonTable,
 118       IUPAC)
 119     * Phylogenetic program parsing (PAML, Molphy, Phylip)
 120
 121 * `Bio::Map` represents genetic and physical map representations
 122
 123 * `Bio::Structure` parse and represent protein structure data
 124
 125 * `Bio::TreeIO` is for reading and writing Tree formats
 126
 127 * `Bio::Tree` is the namespace for all associated Tree classes
 128     * `Bio::Tree::Tree` is the basic tree object
 129     * `Bio::Tree::Node` are the nodes which make up the tree
 130     * `Bio::Tree::Statistics` is for computing statistics for a tree
 131     * `Bio::Tree::TreeFunctionsI` is where specific tree functions are
 132       implemented (like `is_monophyletic` and `lca`)
 133
 134 * `Bio::Biblio` is where bibliographic data and database access
 135   objects are kept
 136
 137 * `Bio::Variation` represent sequences with mutations and variations
 138   applied so one can compare and represent wild-type and mutation
 139   versions of a sequence.
 140
 141 * `Bio::Root` are basic objects for the internals of BioPerl
 142
 143
 144 # Releases
 145
 146 BioPerl currently uses a [semantic versioning](https://semver.org/)
 147 scheme for version numbers.  Basically, a version has three numbers in
 148 the form `MAJOR.MINOR.PATCH`, each of which changes when:
 149
 150 1. `MAJOR` --- incompatible API changes,
 151 2. `MINOR` --- new functionality in a backwards-compatible manner,
 152 3. `PATCH` --- backwards-compatible bug fixes.
 153
 154 ## 1.7 releases
 155
 156 Before 1.7 release, the BioPerl project had a single distribution with
 157 all of BioPerl modules.  During the 1.7 release series, subsets of the
 158 modules were extracted into separate distribution.
 159
 160 ## Pre 1.7 releases
 161
 162 From version 1.0 until 1.6, even numbers (e.g. version 1.4) indicated
 163 stable releases.  Stable releases were well tested and recommended for
 164 most uses.  Odd numbers (e.g. version 1.3) were development releases
 165 which one would only use if interested in the latest features.  The
 166 final number (e.g. in `1.2.1`) is the point or patch release. The
 167 higher the number the more bug fixes has been incorporated. In theory
 168 you can upgrade from one point or patch release to the next with no
 169 changes to your own code (for production cases, obviously check things
 170 out carefully before you switch over).