Skip to content
Tutorials Center
My learning

Topics

Lesson 106 of 134 ยท Testing and Tooling

Rake and Automation

Learn Rake, Ruby's build and automation tool - tasks, prerequisites, namespaces, arguments, file tasks, running tasks from code, and a plain-Ruby task runner you can build yourself.

Every project accumulates small chores: run the tests, build the documentation, reset the database, create a release. You can type these commands from memory, or you can give each one a name and write it down once. Rake is Ruby's tool for exactly that. You describe tasks in Ruby code (in a file called Rakefile), say which tasks depend on which, and then run rake task_name from the terminal.

The name is a pun on make, the classic build tool from the 1970s. Make has its own cryptic syntax; Rake's big idea is that the build file is just Ruby, so you have loops, variables, methods and the whole standard library available. Rake ships with Ruby as a bundled gem. In a project with a Gemfile you add gem "rake", and you run tasks with bundle exec rake (see RubyGems and Bundler).

On this page the examples run Rake inside a normal script rather than from a terminal, because our runner executes one Ruby file and has no shell prompt. That is a real technique too: Rake is an ordinary library that you can require. Terminal commands are shown as read-only examples.

Your first tasks

A task has a name, an optional description, and a block of code. Inside a Rakefile the methods task, desc, namespace and friends are available automatically. In a plain script you get them with include Rake::DSL.

Ruby Defining and invoking tasks

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Rake::Task[:hello] looks a task up by name, and invoke runs it. Only tasks with a desc appear in the rake -T listing; a task without one is considered an internal helper, which is why comment is nil for goodbye.

In a real project the file is named Rakefile (no extension), sits in the project root, and holds the same task definitions. Then you run it like this:

Terminal
# read-only example: shell commands, not run here
rake hello          # run one task
rake -T             # list tasks that have a desc
rake -P             # show every task with its prerequisites
rake hello goodbye  # run several, in order
rake                # run the task named "default"

Prerequisites: tasks that depend on tasks

The real power of Rake is dependencies. You write task :deploy => [:test, :build], and when you run deploy, Rake first runs test and build, and only then the body of deploy. A task that several others depend on is still run only once per invocation, even if it is needed in many places. That is the difference between a build tool and a plain list of method calls.

Ruby Dependencies run first, and only once

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

The first invoke printed compile, test, docs, package in that order: compile ran once although both test and docs need it. The second invoke printed nothing at all, because every task was already done. reenable marks a task as not yet run so it can run again. After we reenabled compile and invoked it, compile printed again, but test, docs and package stayed "done", so invoking default afterwards printed nothing.

task default: :package is the modern hash-style spelling of task :default => :package. Both mean the same: "the task named default depends on package". The task named default is what plain rake runs.

Namespaces and arguments

As a project grows, task names collide. A namespace groups tasks under a prefix, written with a colon: db:reset, docs:build. Tasks can also receive arguments, which you declare after the name and read from a second block parameter.

Ruby Namespaces and task arguments

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

From a terminal, arguments go in square brackets: rake "db:seed[10,books]". Quote them, because many shells treat square brackets specially. Arguments are always strings, so convert them with Integer(args[:count]) when you need numbers.

A task can also depend on a task in another namespace by its full name: task :all => ["db:seed", "docs:build"].

Unknown tasks and errors

Ask for a task that does not exist and Rake raises a plain RuntimeError, which you can rescue like any exception. From the terminal you would see the same text without the Ruby stack trace.

Ruby Asking for a task that does not exist

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

The message is Don't know how to build task 'biuld' (See the list of available tasks with rake --tasks), optionally followed by a "Did you mean?" hint. Left unhandled, the error ends the script with a stack trace that points into the Rake library. If a task's own code raises, Rake stops there and the exception propagates, so later tasks never run. That is what you want in a build: a failed test should stop package.

Tasks that build files

Rake descends from make, whose original job was to avoid redoing work. A file task names a file it produces and the files it needs. Rake compares modification times: if the output is missing or older than any input, the block runs; otherwise it is skipped. rule and file tasks are how a Rakefile for C code or for a static website avoids rebuilding everything.

Ruby A file task runs only when needed

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

The first run built shout.txt. The second skipped the block because shout.txt was newer than greeting.txt. After we touched the input, the third run rebuilt. Rake also gives you a FileList for matching files with patterns (FileList["lib/**/*.rb"]), and helpers such as sh "command" to run shell commands, mkdir_p, cp and rm_f. These come from FileUtils and echo the command they run.

A typical Rakefile

Rake is usually met in the form of a Rakefile with test, lint and release tasks. Here is the classic shape. It is a read-only example, because it uses Rake::TestTask, which needs a test/ folder of files and a terminal:

Ruby
# read-only example: Rakefile in the project root
require "rake/testtask"

Rake::TestTask.new(:test) do |t|
  t.libs << "lib" << "test"
  t.pattern = "test/**/*_test.rb"
end

desc "Run RuboCop"
task :lint do
  sh "bundle exec rubocop"
end

desc "Build the gem"
task build: :test do
  sh "gem build my_gem.gemspec"
end

task default: %i[test lint]

Running bundle exec rake now runs the tests and then the linter. Read Minitest for the test files and Style and Linting for RuboCop.

Rails apps use Rake heavily too: rails db:migrate and rails assets:precompile are Rake tasks defined by the framework. You can add your own in lib/tasks/*.rake. See Ruby on Rails Overview.

When Rake is not needed: a plain-Ruby task runner

Rake does three things: it gives tasks names, it orders them by dependencies, and it runs each at most once. That is a small amount of logic. Writing it yourself once is the best way to understand it, and it is also a valid choice for a tiny script that should not depend on anything.

Ruby A tiny task runner without Rake

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

This runner uses Data.define for a small immutable record (see Structs and Data), and shows two checks Rake also performs: it detects a circular dependency (a needs b needs a), and it reports an unknown task. Real Rake adds file tasks, arguments, namespaces, parallel execution (rake -m) and a command-line tool, which is why you use it for real projects.

Practical advice

  • Keep task bodies short. Put real logic in a class or module under lib/, and let the task call it. Then you can test the logic with Minitest like any other code.
  • Always write desc for tasks users should run. rake -T is the documentation of your project's chores.
  • Express order with prerequisites, not with calls to Rake::Task#invoke inside bodies, unless you must. Prerequisites show up in rake -P and keep the graph visible.
  • Do not forget bundle exec, so the locked gem versions are used.
  • Pick one tool. Some projects use a Makefile, a bin/ folder of scripts, or a Justfile instead. Rake is the natural choice when the people on the project already know Ruby.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does task :deploy => [:test, :build] mean?

    The right side of => lists prerequisites. Rake runs them (each at most once) before the task's own block.
  2. 2. You call Rake::Task[:build].invoke twice in a row. What happens the second time?

    A task runs once per process unless you call reenable. Prerequisites that are done are also skipped.
  3. 3. How do you pass arguments to a task from the shell?

    Arguments go in square brackets directly after the task name, and the whole thing is quoted so the shell does not interpret the brackets.
  4. 4. What makes a Rake file task different from a normal task?

    File tasks compare modification times, which lets Rake skip work whose result is already up to date.
  5. 5. Where should the main logic of a complicated chore live?

    Plain classes can be tested and reused; a short task that just calls them stays easy to read.

Summary

  • Rake runs named tasks defined in a Rakefile written in plain Ruby; rake -T lists tasks that have a desc.
  • Prerequisites express order: task a: :b runs b first, and each task runs once per run unless you reenable it.
  • Namespaces group task names (db:seed), and arguments are passed as rake "db:seed[10,books]" and read from the args block parameter.
  • File tasks rebuild an output only when it is missing or older than its inputs.
  • Rake is a normal library: require 'rake' and include Rake::DSL let you define and invoke tasks from any script.
  • Keep task bodies short, put logic in testable classes, and run with bundle exec rake.

Next: Style and Linting