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 modifing their original behaviour 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

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.1

|– 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)

  • 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

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)
    --create-repo                create the repository on GitHub

    --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 # 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 # Regenreate 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 and you MUST create a repository for your new bioruby plugin. 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.

  • Before start developing open Rakefile and modify the gem.summary and gem.description. These parameters are very important 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 is under the control of you git repository, so there is no need to modify the Rakefile or the tasks for including some file, directory etc to you project; just git add your_file_or_directory. Remeber to modify .gitignore to exclude files.

  • Explore the rake tasks with

    • $ 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

TODO

  • better command line, wrap or re-implement some of the funcionalities provided by Bundler and Jeweler

  • use YAML for database configuration

Copyright © 2010 Raoul J.P. Bonnal. See LICENSE.txt for further details.