You want to make it easy to run your project’s unit test suite. You also want the tests to run automatically before you do a new release of your project.

Require the rake/testtask library and create a new Rake::TestTask. Save the following code in a file called Rakefile in the project’s top-level directory (or add it to your existing Rakefile).

	require ' 
rake/testtask'

	Rake::TestTask.new('test') do |t|
	  t.pattern = 'test/**/tc_*.rb'
	  t.warning = true
	end

This Rakefile makes two assumptions:

To execute your test cases, run the command rake test in the project’s top-level directory. The tests are loaded by a new Ruby interpreter with warnings enabled. The output is the same as you’d see from Test::Unit’s console runner.

If it’s easy to trigger the test process, you’ll run your tests more often, and you’ll detect problems sooner. Rake makes it really convenient to run your tests.

We can make the test command even shorter by defining a default task. Just add the following line to the Rakefile. The position within the file doesn’t matter, but to keep things clear, you should put it before other task definitions:

	task "default" => ["test"]

Now, whenever we run rake without an argument, it will invoke the test task. If your Rakefile already has a default task, you should be able to just add the test task to its list of prerequisites. Similarly, if you have a task that packages a new release of your software (like the one defined in Recipe 19.4), you can make the test task a prerequisite. If your tests fail, your package won’t be built and you won’t release a buggy piece of software.

The Rake::TestTask has a special attribute, libs; the entries in this array are added to Ruby’s load path. As mentioned above, the default value is [”lib“], making it possible for your tests to require files in your project’s lib/ subdirectory. Sometimes this default is not enough. Your Ruby code might not be in the lib/ subdirectory. Or worse, your test code might change the current working directory. Since lib/ is a relative path, the default value of libs would start out as a valid source for library files, and then stop being valid when the test code changed the working directory.

We can solve this problem by specifying the absolute path to the project’s lib directory in the Rakefile. Using an absolute path is generally more stable. In this sample Rakefile, we give the load path the absolute path to the lib and test subdirectories. Adding the test directory to the load path is useful if you need to require a library full of test utility methods:

	require ' 
rake/testtask'

	lib_dir = File.expand_path('lib')
	test_dir = File.expand_path('test')

	Rake::TestTask.new("test") do |t|
	    t.libs = [lib_dir, test_dir]
	    t.pattern = "test/**/tc_*.rb"
	    t.warning = true
	end

	require ' 
rake/testtask'

	Rake::TestTask.new('test-file') do |t|
	    t.test_files = ['test/tc_datafile.rb',
	                    'test/tc_datafilewriter.rb',
	                    'test/tc_datafilereader.rb']
	    t.warning = true
	end

	 
Rake::TestTask.new('test-console') do |t|
	    t.test_files = ['test/tc_console.rb',
	                    'test/tc_prettyprinter.rb']
	    t.warning = true
	end

	task 'test' => ['test-file', 'test-console']

You want to automatically create HTML pages from the RDoc formatted comments in your code, and from other RDoc formatted files.

Within your Rakefile, require the rake/rdoctask library and create a new Rake:: RDocTask. Here’s a typical example:

	require 'rake/rdoctask'

	Rake::RDocTask.new('rdoc') do |t|
	  t.rdoc_files.include('README', 'lib/**/*.rb')
	  t.main = 'README'
	  t.title = "MyLib API documentation"
	end

Now you can run the command rake rdoc from a shell in your project’s top-level directory. This particular Rake task creates API documentation for all files under the lib directory (and its subdirectories) whose names end in .rb. Additionally, the RDoc-formatted contents of the top-level README file will appear on the front page of the documentation.

The HTML output files are written under your project’s %(filename)html% directory. To read the documentation, point your browser to %(filename)html/index.html%. The browser will show “MyLib API documentation” (that is, the value of the task’s title) as the page title.

It is common practice among authors of Ruby libraries to document a library’s API with RDoc-formatted text. Since Ruby 1.8.1, a standard Ruby installation contains the rdoc tool, which extracts the RDoc comments from source code and creates nicely formatted HTML pages.

Unlike the tasks you define from scratch with the task method, but like the TestTask covered in Recipe 19.1, Rake::RDocTask.new takes a code block, which is executed immediately at task definition time. The code block lets you customize how your RDoc documentation should look. After running your code block, the Rake:: RDocTask object defines three new Rake tasks:

Now we know enough to integrate the Rake::RDocTask into a more useful Rakefile. Suppose we want a task that uploads the documentation to RubyForge (or another site), and a general cleanup task that removes the generated HTML-documentation as well as all backup files in the project directory. To keep the example simple, I’ve inserted comments instead of the actual commands for uploading and removing the files; see Recipes 19.3 and 19.8 for more realistic examples.

	require 'rake/rdoctask'

	Rake::RDocTask.new('rdoc') do |t|
	  t.rdoc_files.include('README', 'lib/**/*.rb')
	  t.main = 'README'
	  t.title = "MyLib API documentation"
	end

	desc 'Upload documentation to RubyForge.'
	task 'upload' => 'rdoc' do
	   # command(s) to upload html/ and contents to RubyForge
	end
	desc 'Remove generated and backup files.'
	task 'clobber' => 'clobber_rdoc' do
	    # command(s) to remove all files ending in ~ or .bak
	end

Finally, we make the default task dependent on the rdoc task, so that RDoc gets built automatically when you invoke rake with no task. If there already is a default task, this code will simply add another dependency to the existing task:

	task :default => ['rdoc']

You want to clean up files that aren’t actually part of your project: generated files, backup files, and so on.

Within your Rakefile, require the rake/clean library to get access to the clean and clobber tasks. Put glob patterns for all your generated files in the CLOBBER FileList. Put glob patterns for all other scratch files in the CLEAN FileList.

By default, CLEAN also includes the patterns **/*~, **/*.bak, and **/core. Here’s a typical set of CLOBBER and CLEAN files:

	require ' 
rake/clean'

	# Include the "pkg" and "doc" directories and their contents.
	# Include all files ending in ".o" in the current directory
	# and its subdirectories (recursively).
	CLOBBER.include('pkg', 'doc', '**/*.o')

	# Include InstalledFiles and .config: files created by setup.rb.
	# Include temporary files created during test run.
	CLEAN.include('InstalledFiles', '.config', 'test/**/*.tmp')

Run rake clean to remove all files specified by the CLEAN filelist, and rake clobber to remove the files specified by both file lists.

The rake/clean library initializes the constants CLEAN and CLOBBER to new Rake:: FileList instances. It also defines the tasks clean and clobber, making clean a prerequisite of clobber. The idea is that rake clean removes any files that might need to be recreated once your program changes, while rake clobber returns your source tree to a completely pristine state.

Other Rake libraries define cleanup tasks that remove certain products of their main tasks. An example: the packaging libraries create a task called clobber_package, and make it a prerequisite of clobber. Running rake clobber on such a project removes the package files: you don’t have to explicitly include them in your CLOBBER list.

You can do the same thing for your own tasks: rather than manipulate CLEAN and CLOBBER, you can create a custom cleanup task and make it a prerequisite of clean or clobber. The following code is a different way of making sure that rake clobber removes any precompiled object files:

	desc 'Remove all object files.'
	task 'clobber_objects' do
	  rm_f FileList['**/*.o']
	end

	# Make clobber_objects a prerequisite of the preexisting clobber task
	task 'clobber' => 'clobber_objects'

Now you can run rake clobber_objects to remove all object files, and rake clobber to remove all other unwanted files as well.

You want to automatically build a gem package for your application or library whenever you do a release.

Require the rake/gempackagetask library within your Rakefile, and create a Gem:: Specification instance that describes your project. Feed it to the Rake:: GemPackageTask constructor, which automatically defines a number of gem-related tasks:

	require 'rake/gempackagetask'

	# Create a gem specification
	gem_spec = Gem::Specification.new do |s|
	  s.name = 'docbook'
	  s.version = '1.0.0'
	  s.summary = 'DocBook formatting program and library.'

	  # Files containing Test::Unit test cases.
	  s.test_files = FileList['tests/**/*']

	  # Executable scripts under the "bin" directory.
	  s.executables = ['voc']

	  # List of other files to be included.
	  s.files = FileList['README', 'ChangeLog', 'lib/**/*.rb']
	end

	Rake::GemPackageTask.new(gem_spec) do |pkg|
	  pkg.need_zip = false
	  pkg.need_tar = false
	end

Run the command rake package, and (assuming those files actually exist), Rake will build a gem file docbook-1.0.0.gem under the pkg/ directory.

The RubyGems library provides the Gem::Specification class, and Rake provides the Rake::GemPackageTask class that uses it. Creating a new Rake::GemPackageTask object automatically defines the three tasks: package, clobber_package, and repackage.

The package task builds a gem inside the project’s pkg/ directory. The clobber_package task removes the pkg/ directory and its contents. The repackage task just invokes clobber_package to remove any old package file, and then invokes package to rebuild them from scratch.

The example above sets to false the attributes need_zip and need_tar of the Rake::GemPackageTask. If you set them to true, then in addition to a gem you’ll get a ZIP file and a gzipped tar archive containing the same files as the gem. Note that Rake uses the zip and tar command-line tools, so if your system doesn’t provide them (the way a standard Windows installation doesn’t), the package task won’t be able to create these ZIP or tar archives.

The package task recreates a package file only if it doesn’t already exist, or if you’ve updated one of your input files since you last built the package. The most common problem you’ll run into here is that you’ll decide to stop packaging a certain file. Rake won’t recognize the change (since the file is gone), and running rake package won’t do anything. To force a rebuild of your package file(s), run rake repackage.

You want to gather statistics about your Ruby project, like the total number of lines of code.

Here’s a class that parses Ruby source files and gathers statistics. Put this in scriptlines.rb in your project’s top-level directory.

	# scriptlines.rb
	# A ScriptLines instance analyses a Ruby script and maintains
	# counters for the total number of lines, lines of 
code, etc.
	class ScriptLines

	  attr_reader :name
	  attr_accessor :bytes, :lines, :lines_of_code, :comment_lines

	  LINE_FORMAT = '%8s %8s %8s %8s %s'

	  def self.headline
	    sprintf LINE_FORMAT, "BYTES", "LINES", "LOC", "COMMENT", "FILE"
	  end

	  # The 'name' argument is usually a filename
	  def initialize(name)
	    @name = name
	    @bytes = 0
	    @lines = 0    # total number of lines
	    @lines_of_code = 0
	    @comment_lines = 0
	  end

	  # Iterates over all the lines in io (io might be a file or a
	  # string), analyses them and appropriately increases the counter
	  # attributes.
	  def read(io)
	    in_multiline_comment = false
	    io.each { |line|
	      @lines += 1
	      @bytes += line.size
	      case line
	      when /^=begin(s|$)/
	        in_multiline_comment = true
	        @comment_lines += 1
	      when /^=end(s|$)/:
	        @comment_lines += 1
	        in_multiline_comment = false
	      when /^s*#/
	        @comment_lines += 1
	      when /^s*$/
	        # empty/whitespace only line
	      else
	        if in_multiline_comment
	          @comment_lines += 1
	        else
	          @lines_of_code += 1
	        end
	      end
	    }
	  end

	  # Get a new ScriptLines instance whose counters hold the
	  # sum of self and other.
	  def +(other)
	    sum = self.dup
	    sum.bytes += other.bytes
	    sum.lines += other.lines
	    sum.lines_of_ 
code += other.lines_of_code
	    sum.comment_lines += other.comment_lines
	    sum
	  end

	  # Get a formatted string containing all counter numbers and the
	  # name of this instance.
	  def to_s
	    sprintf LINE_FORMAT,
	      @bytes, @lines, @lines_of_code, @comment_lines, @name
	  end
	end

To tie the class into your build system, give your Rakefile a stats task like the following. This task assumes that the Rakefile and scriptlines.rb are in the same directory:

	task 'stats' do
	  require 'scriptlines'

	  files = FileList['lib/**/*.rb']

	  puts ScriptLines.headline
	  sum = ScriptLines.new("TOTAL (#{files.size} file(s))")

	  # Print stats for each file.
	  files.each do |fn|
	    File.open(fn) do |file|
	      script_lines = ScriptLines.new(fn)
	      script_lines.read(file)
	      sum += script_lines
	      puts script_lines
	    end
	  end

	  # Print total stats.
	  puts sum
	end

ScriptLines performs a very basic parsing of Ruby code: it divides a source file into blank lines, comment lines, and lines containing Ruby code. If you want more detailed information, you can include each file and get more information about the defined classes and methods with reflection or an extension like Parse Tree.

Invoke the stats task to run all the Ruby scripts beneath your lib/ directory through ScriptLines. The following example output is for the highline library:

	$ rake stats
	(in /usr/local/lib/ruby/gems/1.8/gems/highline-1.0.1)
	BYTES  LINES    LOC  COMMENT   FILE
	18626    617    360    196   lib/highline.rb
	12745    375    168    181   lib/highline/menu.rb
	15760    430    181    227   lib/highline/question.rb
	801       25      7     14   lib/highline/import.rb
	47932   1447    716    618   TOTAL (4 scripts)

BYTES is the file size in bytes, LINES the number of total lines in each file, LOC stands for “Lines Of Code,” and COMMENT is the number of comment-only lines.

These simple metrics are good for gauging the complexity of a project, but don’t use them as a measure of day-to-day progress. Complexity is not the same as progress, and a good day’s work might consist of replacing a hundred lines of code with ten.

You want to automatically update your project’s web site on RubyForge (or some other site) with generated documentation or custom pages.

As seen in Recipe 19.2, Rake provides a RDocTask for generating RDoc documentation:

	require 'rake/rdoctask'

	html_dir = 'doc/html'
	library = 'MyLib'
	Rake::RDocTask.new('rdoc') do |t|
	  t.rdoc_files.include('README', 'lib/**/*.rb')
	  t.main = 'README'
	  t.title = "#{library} API documentation"
	  t.rdoc_dir = html_dir
	end

To upload your generated documentation to RubyForge, use this task along with the upload-docs task defined below. The Unix scp command-line tool does the actual work of uploading:

	# Define your RubyForge username and your project's Unix name here:
	rubyforge_user = 'user'
	rubyforge_project = 'project'
	rubyforge_path = "/var/www/gforge-projects/#{rubyforge_project}/"
	desc 'Upload documentation to RubyForge.'
	task 'upload-docs' => ['rdoc'] do
	     sh "scp -r #{html_dir}/* " +
	         "#{rubyforge_user}@rubyforge.org:#{rubyforge_path}"
	end

Set off the publishing process by invoking rake upload-docs. The upload-docs task has the rdoc task as a prerequisite, so the HTML pages under doc/html/ will be created if necessary.

Then scp prompts for your RubyForge account password. Enter it, and all files under doc/html/ and its subdirectories will be uploaded to RubyForge. The docs will become available under http://project.rubyforge.org/, where “project” is the Unix name of your project. Now your users can read your RDoc online without having to generate it themselves. Your documentation will also show up in web search results.

Rake’s sh method starts an instance of the OS’s standard shell. This feature is used to run the scp command-line tool. This means that this recipe will only work if scp is installed on your system.

The scp command copies all the files that the RDoc placed under doc/html/, to the root of your project’s web site on the RubyForge server. In effect, the main page of the API documentation will appear as your project’s homepage. Some RubyForge projects don’t have a custom homepage, so this is a good place to put the RDoc. If you want a custom homepage, just copy the RDoc into a different directory by changing rubyforge_path:

	rubyforge_path =  "/var/www/gforge-projects/#{rubyforge_project}/rdoc/"

You’ll have to manually create the rdoc directory before you can use the scp shortcut. After that, the generated RDoc will show up at http://project.rubyforge.org/rdoc/, and you can link to it from your custom homepage with a relative link to rdoc/.

You can make Rake upload your custom homepage as well, of course. Just add an upload-site task that uploads your custom homepage and other web content. Make upload-site and upload-docs prerequisites of an overarching publish task:

	website_dir = 'site'
	desc 'Update project website to RubyForge.'
	task 'upload-site' do
	  sh "scp -r #{website_dir}/* " +
	    "#{rubyforge_user}@rubyforge.org:/var/www/gforge-projects/project/"
	end

	desc 'Update API docs and project website to RubyForge.'
	task 'publish' => ['upload-docs', 'upload-site']

Now you can run rake publish to update the generated API documentation, and upload it together with the rest of the web site to RubyForge. The publish task can be just one more prerequisite for an overarching release task.

Of course, you can use this same technique if you’re using a web host other than RubyForge: just change the destination host of the scp command.

Your build process takes too long to run. Rake finishes copying one set of files only to start copying another set. You could save time by running these tasks in parallel, instead of stringing them one after another.

Define a task using the multitask function instead of task. Each of that task’s prerequisites will be run in a separate thread.

In this code, I’ll define two long-running tasks:

	task 'copy_docs' do
	  # Simulate a large disk copy.
	  sleep 5
	end

	task 'compile_extensions' do
	  # Simulate a C compiler compiling a bunch of files.
	  sleep 10
	end

	task 'build_serial' => ['copy_docs', 'compile_extensions']
	multitask 'build_parallel' => ['copy_docs', 'compile_extensions']

The build_serial task runs in about 15 seconds, but the build_parallel task does the same thing in about 10 seconds.

A multitask runs just like a normal task, except that each of its dependencies runs in a separate thread. When running the dependencies of a multitask, Rake first finds any common secondary dependencies of these dependencies, and runs them first. It then spawns a separate thread for each dependency, so that they can run simultaneously.

Consider three tasks, ice_cream, cheese, and yogurt, all of which have a dependency on buy_milk. You can run the first three tasks in separate threads with a multitask, but Rake will run buy_milk before creating the threads. Otherwise, ice_cream, cheese, and yogurt would all trigger buy_milk, wasting time.

When your tasks spend a lot of time blocking on I/O operations (as many Rake tasks do), using a multitask can speed up your builds. Unfortunately, it can also cause the same problems you’ll see with any multithreaded code. If you’ve got a fancy Rakefile, in which the tasks keep state inside Ruby data structures, you’ll need to synchronize access to those data structures to prevent multithreading problems.

You may also have problems converting a task to a multitask if your dependencies are set up incorrectly. Take the following example:

	task 'build' => ['compile_extensions', 'run_tests', 'generate_rdoc']

The unit tests can’t run if the compiled extensions aren’t available, so :compile_extensions shouldn’t be in this list at all: it should be a dependency of :run_tests. You might not notice this problem as long as you’re using task (because :compile_extensions runs before :run_tests anyway), but if you switch to a multitask your tests will start failing. Fixing your dependencies will solve the problem.

The multitask method is available only in Rake 0.7.0 and higher.