About

Rake is ruby’s version of Make, and is specifically geared towards building Ruby packages, gems, and suchlike.

This is a re-organized, re-formatted, and much more basic version of Greg Houston’s wonderful (and very copy/pasteable) Rake quick reference over at Pastie. I assume familiarity with make and ant concepts here.

[Full Rake Documentation]

[print_link]

Index

• Running Rake
• Defining Tasks
  • Default Task
  • Dependencies/Pre-Requisites
  • Defining Task Execution
  • Describing a Task
  • Adding to an Existing Task
• Files and Directories
  • File Lists
  • Create a Directory
  • Copy a File
  • File Path Manipulation
• Including More Tasks
• Custom Task Generators
• Clean and Clobber Tasks
• RDoc Tasks
• Unit Test Tasks
• Gem Tasks

table.ruby td, table.ruby th { border: 1px solid #ccc; padding: 3px; }
table.ruby tr.alt td, table.ruby tr.alt th { background-color: #ccc; }
table.ruby th { text-align: left; width: 125px; }
table.ruby pre { background-color: #fff; }

Running Rake

rake	Runs the :default task in Rakefile (or (Rakefile|rakefile)[.rb], searching up parent directories)
rake target1 target2	Runs the :target1 and :target2 tasks.
rake -f source.rb	Runs with source.rb as the Rakefile
rake -n	Dry run.

Defining Tasks

Default Task


task :default => :target


Dependencies/Pre-requisites


task :target => :dependency
task :target => [:dependency1, :dependency2]


Defining Task Execution

task :target [=> :dependency] do (|taskObject|)
    ... stuff ...
    ... taskObject.investigation ...
end

Describing a Task

desc "Describes what the upcoming task will do"
task :target ...

Adding to an Existing Task

task :target => :depend1

task :target => :depend2

task :target => do
    ...
end

Files and Directories

File Lists

Works on files that exist on the system already.

FileList['data/**/*', 'out/file.txt'].exclude('*.bak')
FileList[...].exclude { |path| path =~ /ignore/ }


Create a Directory

directory 'parent/child'
task :target => 'parent/child'

rake 'parent/child' or rake target

Copy a File Task

file 'path/target.txt' => 'path/source.txt' do
    cp 'path/source.txt', 'path/target.txt' [, :verbose => true]
end
task :target => 'path/target.txt'

rake 'path/target.txt' or rake target

FileList['data/*'].each do |source|
    target = source.sub('.data', '.out')
    file target => source do
        cp source, target, :verbose => true
    end
    desc "copies all data files"
    task :copy_data_files => target
end

rake copy_data_files

File Path Manipulation

[Rake String Extensions]

Replace extension/suffix

'path/file.txt'.ext( 'html')

Path mapping

'path/file.txt'.pathmap('%format'), where %p : full path %f : file name only %n : file name, no extension %x : file’s extension %X : full path without extension %d : directory path only %2d : two-depth directory path from the top %-2d : two-depth directory path from the bottom %% : percent sign %{pattern, replacement; patt2, repl2}p : replacement(s) for any of the above codes %{pattern,*}p : give a block {|m| block} to replace the match

Including More Tasks

Include directly	require 'tasks'
Include after entire file	import 'post-tasks'
Import on commandline	rake -R=rakelib

Custom Task Generators

In get-pastie.rb:

require 'rake/tasklib'

# Retrieve the Pastie text for Greg's Rake quick reference.
class GetPastie < Rake::TaskLib
    attr_accessor :name, :id, :target

    # initialize sets the name and calls a block to get
    #   the rest of the options
    def initialize( name=:get_pastie )
        @name = name
        yield self if block_given?
        define
    end

    # define creates the new task(s)
    def define
        raise "id must be defined" if @id.nil?
        raise "target must be defined" if @target.nil?
        require 'open-uri'
        desc "download http://pastie.org/pastes/#{@id} to #{target}"
        task @name do
            open(@target,"w").write(open("http://pastie.org/pastes/#{@id}/download").read)
        end
    end
end

In Rakefile:

require 'get-pastie.rb'
GetPastie.new do |t|
    t.id = 239387 # the first quick ref published
    t.target = 'out/pastie_239387.rb'
end
# Name the task explicitly
GetPastie.new(:get_latest_pastie) do |t|
    t.id = 242691  # most recent as of 2008 Dec 28
    t.target = 'out/rake-quick-ref.rb'
end

rake get_pastie and rake get_latest_pastie

Clean and Clobber Tasks

require 'rake/clean'

CLEAN.add 'file-or-directory-to-delete'
CLEAN.include 'glob'
CLEAN.exclude 'dont-remove-this'

CLOBBER.add 'really-clean-this'

rake clean or rake clobber

RDoc Tasks

[RDocTask]

require 'rake/rdoctask'
Rake::RDocTask.new do |rd|
  rd.main = "README.rdoc"
  rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
end

rake rdoc or rake clobber_rdoc or rake rerdoc

Unit Test Tasks

[TestTask]

require 'rake/testtask'
Rake::TestTask.new do |t|
    t.libs << "test"
    t.test_files = FileList['test/test*.rb']
    t.verbose = true
end

rake test

Gem Tasks

[GemPackageTask] [Gem Specification Reference]

require 'rubygems'
spec = Gem::Specification.new do |s|
    s.name = 'mygem'
    s.version = '0.1'
    # ...etc ...
end

require 'rake/gempackagetask'
Rake::GemPackageTask.new(spec) do |package|
    package.need_zip = true
    package.need_tar = true
end

require 'rake/clean'
CLEAN.include('pkg')

rake package

[print_link]