README.rdoc in bio-1.4.2 vs README.rdoc in bio-1.4.3
- old
+ new
@@ -1,17 +1,18 @@
--
= README.rdoc - README for BioRuby
Copyright:: Copyright (C) 2001-2007 Toshiaki Katayama <k@bioruby.org>,
Copyright (C) 2008 Jan Aerts <jandot@bioruby.org>
+ Copyright (C) 2011-2012 Naohisa Goto <ng@bioruby.org>
License:: The Ruby License
* The above statement is limited to this file. See below about BioRuby's
copyright and license.
++
= BioRuby
-Copyright (C) 2001-2011 Toshiaki Katayama <k@bioruby.org>
+Copyright (C) 2001-2012 Toshiaki Katayama <k@bioruby.org>
BioRuby is an open source Ruby library for developing bioinformatics
software. Object oriented scripting language Ruby has many features
suitable for bioinformatics research, for example, clear syntax to
express complex objects, regular expressions for text handling as
@@ -33,17 +34,20 @@
services including KEGG API can be easily utilized by BioRuby.
== FOR MORE INFORMATION
+See RELEASE_NOTES.rdoc for news and important changes in this version.
+
=== Documents in this distribution
-==== General information
+==== Release notes, important changes and issues
README.rdoc:: This file. General information and installation procedure.
RELEASE_NOTES.rdoc:: News and important changes in this release.
KNOWN_ISSUES.rdoc:: Known issues and bugs in BioRuby.
+doc/RELEASE_NOTES-1.4.2.rdoc:: News and incompatible changes from 1.4.1 to 1.4.2.
doc/RELEASE_NOTES-1.4.1.rdoc:: News and incompatible changes from 1.4.0 to 1.4.1.
doc/RELEASE_NOTES-1.4.0.rdoc:: News and incompatible changes from 1.3.1 to 1.4.0.
doc/Changes-1.3.rdoc:: News and incompatible changes from 1.2.1 to 1.3.0.
doc/Changes-0.7.rd:: News and incompatible changes from 0.6.4 to 1.2.1.
@@ -54,20 +58,24 @@
doc/KEGG_API.rd:: Documents about KEGG API, including usage of Bio::KEGG::API.
==== BioRuby development
ChangeLog:: History of changes.
+doc/ChangeLog-before-1.4.2:: changes before 1.4.2.
doc/ChangeLog-before-1.3.1:: changes before 1.3.1.
README_DEV.rdoc:: Describes ways to contribute to the BioRuby project, including coding styles and documentation guidelines.
==== Documents written in Japanese
doc/Tutorial.rd.ja:: BioRuby Tutorial written in Japanese.
doc/Tutorial.rd.ja.html:: HTML version of Tutorial.rd.ja.
doc/KEGG_API.rd.ja:: Japanese translation of KEGG_API.rd.
+==== Sample codes
+In sample/, There are many sample codes and demo scripts.
+
=== WWW
BioRuby's official website is at http://bioruby.org/.
You will find links to related resources including downloads,
mailing lists, Wiki documentation etc. in the top page.
@@ -105,51 +113,67 @@
== REQUIREMENTS
* Ruby 1.8.6 or later (except Ruby 1.9.0) -- http://www.ruby-lang.org/
- * Ruby 1.8.7-p352 or later is recommended.
- * Not yet fully ready with Ruby 1.9, although many components can now work
- in Ruby 1.9.1 and Ruby 1.9.2.
+ * Ruby 1.9.3-p194 or later, or Ruby 1.8.7-p358 or later is recommended.
+ * See KNOWN_ISSUES.rdoc for Ruby version specific problems.
== OPTIONAL REQUIREMENTS
Some optional libraries can be utilized to extend BioRuby's functionality.
-If your needs meets the following conditions, install them from the "Ruby
-Application Archive" at http://raa.ruby-lang.org/, RubyForge at
-http://rubyforge.org/, or the following web sites.
+If your needs meets the following conditions, install them by using RubyGems,
+or download and install from the "Ruby Application Archive" (RAA) at
+http://raa.ruby-lang.org/, RubyForge at http://rubyforge.org/, GitHub at
+http://github.com/, or the following web sites.
For faster parsing of the BLAST XML output format:
* {RAA:xmlparser}[http://raa.ruby-lang.org/project/xmlparser/]
+ * For Ruby 1.8: {gem install xmlparser}[http://rubygems.org/gems/xmlparser]
+ * For Ruby 1.9: http://www.yoshidam.net/Ruby.html#xmlparser
+ * In both cases, {The Expat XML Parser}[http://expat.sourceforge.net/]
+ and C compiler will be required.
Creating faster flatfile index using Berkley DB:
-* {RAA:bdb}[http://raa.ruby-lang.org/project/bdb/]
-
+* {GitHub:ruby-bdb}[https://github.com/knu/ruby-bdb]
+ (which took over {RAA:bdb}[http://raa.ruby-lang.org/project/bdb/])
+ (No RubyGems available)
+ * {Oracle Berkeley DB}[http://www.oracle.com/technetwork/database/berkeleydb/index.html] and C compiler will be required.
+
Accessing BioSQL database created by other Open Bio* libraries:
-* {RubyForge:ActiveRecord}[http://rubyforge.org/projects/activerecord/]
- and at least one driver (or adapter) from
- {RubyForge:MySQL/Ruby}[http://rubyforge.org/projects/mysql-ruby/],
- {RubyForge:postgres-pr}[http://rubyforge.org/projects/postgres-pr], or
- {RubyForge:ActiveRecord Oracle enhanced adapter}[http://rubyforge.org/projects/oracle-enhanced/].
+* {gem install activerecord}[http://rubygems.org/gems/activerecord]
+ and at least one driver (or adapter):
+ * {gem install mysql}[http://rubygems.org/gems/mysql] or
+ {gem install mysql2}[http://rubygems.org/gems/mysql2]
+ * {gem install pg}[http://rubygems.org/gems/pg]
+ * {gem install sqlite-ruby}[http://rubygems.org/gems/sqlite-ruby] or
+ {gem install sqlite3}[http://rubygems.org/gems/sqlite3]
+ * {gem install activerecord-oracle_enhanced-adapter}[http://rubygems.org/gems/activerecord-oracle_enhanced-adapter]
For parsing PhyloXML format files:
-* {RubyForge:libxml-ruby}[http://libxml.rubyforge.org/] (Ruby language
- bindings for the {GNOME Libxml2 XML toolkit}[http://xmlsoft.org/])
+* {gem install libxml-ruby}[http://rubygems.org/gems/libxml-ruby]
+ * {GNOME Libxml2 XML toolkit}[http://xmlsoft.org/] and C compiler will be
+ required.
+(Only for Ruby 1.9.x) For using SOAP web services e.g. KEGG API:
+* {gem install soap4r-ruby1.9}[https://rubygems.org/gems/soap4r-ruby1.9]
+ * For Ruby 1.8.x, SOAP4R is bundled within the Ruby 1.8.x release.
+
+
== INSTALL
=== INSTALL by using RubyGems (recommended)
If you are using RubyGems, just type
- % gems install bio
+ % gem install bio
Alternatively, manually download bio-X.X.X.gem from
http://rubyforge.org/projects/bioruby/ and install it by using gems command.
RubyGems is bundled with Ruby 1.9.1 or later. For Ruby 1.8.7 or earlier,
@@ -178,21 +202,50 @@
% ruby setup.rb config
% ruby setup.rb setup
% su
# ruby setup.rb install
-You can run tests by
+You can run
- % ruby setup.rb test
-
-and run
-
% ruby setup.rb --help
for more details.
+=== Running self-test
+
+To check if bioruby works fine on a machine, self-test codes are bundled.
+Note that some tests may need internet connection.
+
+To run tests,
+
+ % ruby test/runner.rb
+
+If you are using Ruby 1.8.x and you want to use components installed by using
+RubyGems, explicit loading of RubyGems may be needed.
+
+ % ruby -rubygems test/runner.rb
+
+Alternatively, testrb, the test runner command of ruby, can be used.
+
+ % testrb test/
+
+With testrb, you can select tests to run, for example,
+
+ % testrb test/unit
+
+For those familiar with Rake,
+
+ % rake test
+
+also works.
+
+Before reporting test failure, please check KNOWN_ISSUES.rdoc about known
+platform-dependent issues. We are happy if you write patches to solve the
+issues.
+
+
== SETUP
If you want to use the OBDA (Open Bio Database Access) to obtain database
entries, copy a sample configuration file in the BioRuby distribution
@@ -251,9 +304,22 @@
As written in the file COPYING, see the file LEGAL for files distributed
under different license. For example, setup.rb which comes from
{RAA:setup}[http://raa.ruby-lang.org/project/setup/] developed by Minero Aoki
(http://i.loveruby.net/en/projects/setup/) is licensed under LGPL 2.1.
+
+
+== REFERENCE
+
+If you use BioRuby in academic research, please consider citing the following
+publication.
+
+* BioRuby: Bioinformatics software for the Ruby programming language.
+ Naohisa Goto, Pjotr Prins, Mitsuteru Nakao, Raoul Bonnal, Jan Aerts and
+ Toshiaki Katayama.
+ Bioinformatics (2010) 26(20): 2617-2619.
+ * {doi: 10.1093/bioinformatics/btq475}[http://bioinformatics.oxfordjournals.org/content/26/20/2617]
+ * {PMID: 20739307}[http://www.ncbi.nlm.nih.gov/pubmed/20739307]
== CONTACT
Current staff of the BioRuby project can be reached by sending e-mail