bioruby-gem

BioGem is a scaffold generator for those Bioinformaticans who want to start coding an application or a library for using/extending BioRuby’s core library and sharing it through rubygems.org . Biogems are listed at biogems.info

The basic idea is to simplify and promote a modular approach to the BioRuby package.

BioGem is not reinventing the wheel just putting together different tools like Jeweler and Bundler modifying their original behavior when needed. Jeweler is used to create the initial scaffold, setting up git for versioning, releasing it to github.com and/or rubygems.org and packaging. Bundler is used used for setting up a predefined developing environment.

Remind that

Jeweler is based on rake $ rake -T in your project directory gives you an overview of the available actions
GitHub.com and RubyGems.org are two different services and you need to create different accounts for them if you already use GitHub.com you are already all set for using BioGem

BioGems Official Plugin Archive

biogems.info/

Biogem Tutorial

The latest version is on github.com/helios/bioruby-gem/blob/master/Tutorial.rdoc

./file.Tutorial.html

Contributing to bioruby-gem

Check out the latest master to make sure the feature hasn’t been implemented or the bug hasn’t been fixed yet
Check out the issue tracker to make sure someone already hasn’t requested it and/or contributed it
Fork the project
Start a feature/bugfix branch
Commit and push until you are happy with your contribution
Make sure to add tests for it. This is important so I don’t break it in a future version unintentionally.
Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

Step by Step

gem install jeweler
jeweler bioruby-mystuff
cd bioruby_mysuff
bundle install
rake version:write
rake gemspec
rake install

Some of these steps have been condensed:

gem install bio-gem

$ biogem mystuff

pass just the simple name, it will add bioruby- for the first level directory and for the github repository BUT you’ll require the library with bio-mystuff (and this will be the name used on rubygems)

creates a basic gem structure with a default dependencies for bioruby (bio) version 1.4.2

|-- bin [optional = --with-bin]
|   `-- biomystuff (executable)        
|-- Gemfile
|-- Gemfile.lock
|-- LICENSE.txt
|-- README.rdoc
|-- Rakefile
|-- lib
|   `-- bio-mystuff.rb
|-- conf[optional = --with-db]
|   `-- database.yml put here the configuration of your database like in a rails app
|-- db  [optional = --with-db] empty but put here your datasets or database(SQLite3?)
|   |-- seeds.rb a file containing the preloaded datasets, they will be loaded during db setup process
|   `-- migrate directory for migration, you must create migrations by hand, there is a template inside.
`-- test
    |-- data [optional = --with-test-data]
    |-- helper.rb
    `-- test_bio-mystuff.rb

$ cd bioruby-mystuff
$ rake version:write (Initial Updated version: 0.0.0)
$ rake gemspec

$ rake install (for local test)
hack, git add and commit
- NOTE: It’s very important that you add new and changed files so they can be included in the gem you will create, otherwise the files will not be include and you’ll end up with a broken gem with missing files.
$ rake git:release (Before releasing on github or rubygems please see the Notes For Developers). Note: the brand new project is automatically uploaded on GitHub at creation time.
WHEN you have finished with the hacking you can release the gem by typing:
- $ rake release
if you want to make a new release version: major, minor or patch version you can use
- $ rake version:bump:(major | minor | patch) the release will be increased by 1 and when you’ll release it’ll be updated. Note that in GitHub, bumping the version will create a tag with this version and your repository.So for every version you release there is a tag associated.

Options

These are the available options, they come from biogem and from jeweler. I don't know if in the future I'll keep all of them.

Usage: biogem [options] reponame e.g. biogem the-perfect-gem

--directory [DIRECTORY]      specify the directory to generate into

These options are for BioGem

--meta                       create a meta package, just the Rakefile, Gemfile, Licence, Readme. This options takes the precedence over every other option.
--with-bin                   create the bin directory and an executable template script called bioreponame
--with-db                    create the database directory for a db application-library
--with-test-data             create the data directory inside the test directory if the user need to set up a test with its own dataset
--with-engine [NAMESPACE]    create a Rails engine with the namespace given in input. Dy default set up the environment to use an SQLite3 database

These options are for Jeweler

    --rspec                      generate rspec code examples
    --shoulda                    generate shoulda tests
    --testunit                   generate test/unit tests
    --bacon                      generate bacon specifications
    --testspec                   generate test/spec tests
    --minitest                   generate minitest tests
    --micronaut                  generate micronaut examples
    --riot                       generate riot tests
    --shindo                     generate shindo tests

    --[no-]bundler               use bundler for managing dependencies
    --cucumber                   generate cucumber stories in addition to the other tests

    --reek                       generate rake task for reek
    --roodi                      generate rake task for roodi

    --summary [SUMMARY]          specify the summary of the project
    --description [DESCRIPTION]  specify a description of the project

    --user-name [USER_NAME]      the user's name, ie that is credited in the LICENSE
    --user-email [USER_EMAIL]    the user's email, ie that is credited in the Gem specification

    --github-username [GITHUB_USERNAME]
                                 name of the user on GitHub to set the project up under
    --github-token [GITHUB_TOKEN]
                                 GitHub token to use for interacting with the GitHub API
    --git-remote [GIT_REMOTE]    URI to set the git origin remote to
    --homepage [HOMEPAGE]        the homepage for your project (defaults to the GitHub repo)
    --no-create-repo                create the repository on GitHub (repo is created by default)

    --yard                       use yard for documentation
    --rdoc                       use rdoc for documentation
-h, --help                       display this help and exit

Tasks

rake build               # Build gem into pkg/
rake clobber_rcov        # Remove rcov products for rcov
rake clobber_rdoc        # Remove rdoc products
rake console[script]     # Start IRB with all runtime dependencies loaded
rake db:create           # Create the database from config/database.yml for the current default (use db:create:all to create all dbs in the config)
rake db:drop             # Drops the database for the current default (use db:drop:all to drop all databases)
rake db:fixtures:load    # Load fixtures into the current environment's database.
rake db:migrate          # Migrate the database (options: VERSION=x, VERBOSE=false).
rake db:migrate:status   # Display status of migrations
rake db:rollback         # Rolls the schema back to the previous version (specify steps w/ STEP=n).
rake db:schema:dump      # Create a db/schema.rb file that can be portably used against any DB supported by AR
rake db:schema:load      # Load a schema.rb file into the database
rake db:seed             # Load the seed data from db/seeds.rb
rake db:setup            # Create the database, load the schema, and initialize with the seed data (use db:reset to also drop the db first)
rake db:structure:dump   # Dump the database structure to an SQL file
rake db:version          # Retrieves the current schema version number
rake gemcutter:release   # Release gem to Gemcutter
rake gemspec             # Generate and validate gemspec
rake gemspec:debug       # Display the gemspec for debugging purposes, as jeweler knows it (not from the filesystem)
rake gemspec:generate    # Regenerate the gemspec on the filesystem
rake gemspec:release     # Regenerate and validate gemspec, and then commits and pushes to git
rake gemspec:validate    # Validates the gemspec on the filesystem
rake git:release         # Tag and push release to git.
rake install             # Build and install gem using `gem install`
rake rcov                # Analyze code coverage with tests
rake rdoc                # Build the rdoc HTML Files
rake release             # Release gem
rake rerdoc              # Force a rebuild of the RDOC files
rake test                # Run tests
rake version             # Displays the current version
rake version:bump:major  # Bump the major version by 1
rake version:bump:minor  # Bump the a minor version by 1
rake version:bump:patch  # Bump the patch version by 1
rake version:write       # Writes out an explicit version.

NoTes For Developers

A GitHub Account is required. The name of the repository follows this rules: bioruby-mystuff

on your local directory you will see bioruby-mystuff but on rubygems you will publish bio-mystuff. This is a clash of namespaces but I think in this way makes more sense.

* It's VERY IMPORTANT you set up your GitHub environment correctly, please follow the official guide http://help.github.com/set-your-user-name-email-and-github-token/ (USERNAME, EMAIL, TOKEN are very very important)

Before start developing open Rakefile and modify the gem.summary and gem.description. These parameters are fundamental because let you describe your gem and why we need it. If you let them by default the gem will not be packed, it’s just a countermeasure :-)
Update your rubygems environment
Keep in mind that Jeweler handles everything using the local git repository, so there is no need to modify the Rakefile or the tasks for including files, directories; just git add your_file_or_directory. Remember to modify .gitignore to exclude unwanted files.
Explore the rake tasks with
- $ bundle exec rake -T
Help
- please use help $ biogem -h to discover other options for creating rspec or cucumber tests

DataBaseConnection

Is a best practices, at least for me, to have a dummy class which establishes the connection with the database and inherit that class by the models. The benefit of this approach is to have multiple connections available at the same time in case you are developing/using multiple gems with different databases. This file is located in lib/bio/kb

module Bio
  module KB
    class DummyMySpecialDB < ActiveRecord::Base
      self.abstract_class = true
      establish_connection(:adapter =>'sqlite3',:database =>"#{File.dirname(__FILE__)}/../../../db/yourdb.sqlite3")
    end
  end
end

or you can use the configuration file db/database.yml and add this code to the module above. Note I don’t like very much to add every time this code so in a future release I’ll find out a way to add it automatically, probably overwriting the configurations call.

root_path = File.join(File.dirname(__FILE__),"../../../")
configurations = YAML.load_file(File.join(root_path,"conf/database.yml"))
configurations.each_pair do |key, db_info|
  db_info["database"] = File.join(root_path, db_info["database"]) if db_info["adapter"]=='sqlite3'
end
establish_connection(configurations["default"])

This code is necessary because the db is inside the gem and you can’t know where the file will be installed ( using the YAML config file.)

The model must be located in a directory structure like lib/bio/kb/yourclass this is important because ActiveRecord can map the namespace with the directory tree.

module Bio
  module KB
    module MySpecialDB
      class Mytable < Bio::KB::DummyMySpecialDB
      end
    end
 end
end

Seeds

Before populate you seeds.rb file you must declare a model. The model is declared in the usual Rails’ way, see above.

#Use this file to load a default dataset into your database
%w(Raoul Toshiaki Francesco).each do |coder|
  Bio::KB::MySpecialDB::Example.create(:name=>coder, :tag=>"bioruby", :type=>"developer")
end

StepByStep

Toshiaki Katayama wrote a step by step guide for a bio-foobar plugin @ bioruby.open-bio.org/wiki/BiogemInstallation.

BioRuby’s Wiki Official Documentation

bioruby.open-bio.org/wiki/Plugins
biogems.info/ official collector for BioRuby plugins

TODO

better command line, wrap or re-implement some of the funcionalities provided by Bundler and Jeweler
use YAML for database configuration