Posts tagged ‘github’

Emerald

The beginning of a gem factory

A while ago I started to collect my development tools and snippets and put them in my toolbox at github. I will now start to present each of my tools starting with Emerald.

Emerald is a good starting point as it is a RubyGem that creates a bare directory structure for another gem. The default structure, it generates, is:

  [gemname]
    - bin
      [gemname]
    - lib
      [gemname].rb
    - tests
      tc_[gemname].rb
    rakefile
    README
    [gemname].gemspec

If you do not want to generate all directories you simply specify the directories you want from the command line, e.g. emerald gemname lib tests to create only the lib and tests directories.

  • The bin directory contains the executable (named after the gem) which requires the class in the lib directory.
  • The main class lies in the lib directory and contains a bare structure – the class definition and an initialize method
  • The test for the main class is in the tests directory. It is named after the main class and sets a require statement for the main class, so it can be used in the tests. It contains a basic (setup, _tc_method and _teardown_) method structure. All you have to do, is write your tests.

Example

Lets do an example an see what happens:

When we type emerald FancyTest in the console. Emerald generated the following structure for us:

fancy_test
gem directory
fancy_test/bin
binaries directory, used to invoke your gems from the console
fancy_test/bin/fancy_test
this is our executable after installing the gem
fancy_test/fancy_test.gemspec
this is a bare gemspec, where you can define dependencies, tests, documentation, …
fancy_test/lib
the lib directory is the applications main directory where all classes and modules are found
fancy_test/lib/fancy_test.rb
the main class of the application
fancy_test/rakefile
with the rakefile you can perform tasks that are described in the next section in detail
fancy_test/README
the readme is used in the rdoc and is a starting point for users of your application
fancy_test/tests
directory for all your tests
fancy_test/tests/tc_fancy_test.rb
this is the test case for our application that contains a bare unit test case layout

Rakefile

The real magic of Emerald is in the Rakefile. It has predefined tasks to

  • create new classes + associated tests
  • create the gem from the gemspec
  • generate rdoc documentation for development or release
  • run your tests.

The latest gem is stored in the pkg directory, all previous gems are deleted. It is assumed that old gems are no longer needed, because you have them stored in your SCM (don’t you?) and would otherwise just litter up this directory. All this saves a developer a lot of typing and leads to a standard gem development, where you can easily find your way through a gem.

Here is a complete listing of all rake tasks:

  Tasks:
    rake class n=Klass # generate class with test
   GEMS
    rake clear_packages # clear packages
    rake clobber_package # Remove package products
    rake clobber_rdoc # Remove rdoc products
    rake clobber_rdoc_dev # Remove rdoc products
    rake gem # create gem package / Build the gem file
    rake package # Build all the packages
   DOCS
    rake rdoc # Build the rdoc HTML Files
    rake rdoc_dev # Build the rdoc_dev HTML Files
    rake repackage # Force a rebuild of the package files
    rake rerdoc # Force a rebuild of the RDOC files
    rake rerdoc_dev # Force a rebuild of the RDOC files
   TESTS
    rake test # run tests normally
    rake test TEST=just_one_file.rb # run just one test file.
    rake test TESTOPTS="-v" # run in verbose mode

Conclusion

Emerald is designed to keep repetive tasks away from the developer. I do not say that the structure it generates is perfect for everyone. It is just the way I like to write my gems. It does encourage you to write tests and not to leave them out of your programs, because each class you generate has an associated test case.

In my case this gem design pattern has led to a cleaner programming style.

Advertisements

October 1, 2008 at 9:59 pm Leave a comment


Recent Posts

Archives

del.icio.us

Feeds