The beginning of a gem factory
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.
Lets do an example an see what happens:
When we type
emerald FancyTest in the console. Emerald generated the following structure for us:
- gem directory
- binaries directory, used to invoke your gems from the console
- this is our executable after installing the gem
- this is a bare gemspec, where you can define dependencies, tests, documentation, …
- the lib directory is the applications main directory where all classes and modules are found
- the main class of the application
- with the rakefile you can perform tasks that are described in the next section in detail
- the readme is used in the rdoc and is a starting point for users of your application
- directory for all your tests
- this is the test case for our application that contains a bare unit test case layout
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
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.