Rake Part 6: Clean and Clobber

If you're a Ruby programmer, you've almost certainly used Rake, the build utility created by the late Jim Weirich. But you might not realize just how powerful and flexible a tool it can be. I certainly didn't, until I decided to use it as the basis for Quarto, my e-book production toolchain.

This post is part of a series on Rake, starting with the basics and then moving on to advanced usage. It originated as a series of RubyTapas videos published to subscribers in August-September 2013. Each post begins with a video, followed by the script for those who prefer reading to viewing.

My hope in publishing these episodes for free is that more people will come to know and love the full power of this ubiquitous but under-appreciated tool. If you are grateful for Rake, please consider donating to the Weirich Fund in Jim's memory.

In the last episode we defined a Rake task to clean up the products of our build script. It did this through the simple expedient of recursively removing the outputs directory.

Sometimes cleanup isn’t that simple. Today, we’re going to start with a somewhat modified version of the Rakefile we’ve been developing.

As before, we’re converting Markdown files to HTML. Unlike in the immediately preceding episode, the HTML files will be generated next to their source files—there are no separate source and output directories.

In addition to the rule for building Markdown files to HTML, we’ve added some new rules. We now have a rule for concatenating all the HTML fragment files into a single book.html. Then there’s a rule to convert the book.html into an EPUB format ebook using the ebook-convert command from the Calibre ebook package. Finally, there’s a rule to take the EPUB file and convert it into a Kindle-compatible .mobi file using Amazon’s kindlegen.

As a last tweak, we’ve updated the :default rule to depend on these .epub and .mobi targets.

This build script produces two different categories of file:

  • It generates intermediate files. All of the HTML files fall into this category. Another name for these files is temporary files, since they aren’t needed once the full build process has finished.
  • It also generates deliverable ebook files. These files are the end goal of the whole process.

When it comes to automatically cleaning up our project directory, we’d like to treat these two categories of files differently. At times we may want to clean up just the intermediate files, leaving the ebook products intact. At other times we may want to blow away every generated file and start with a clean slate.

We could write our own tasks to handle these two types of cleanup. Or, we could make use of Rake’s optional rake/clean library.

To use rake/clean, we first require it. Once we do this, a new global constant called CLEAN is available to us. This constant is a FileList, which is initially empty.

We can use the CLEAN list to tell Rake which files are intermediate files. First, let’s add the list of HTML files generated from Markdown files

Then we’ll add the concatenated book.html to the list.

Next, we’ll add files to another list called CLOBBER. This list tells Rake which files are considered final products. To the CLOBBER list, we add the .epub and .mobi ebook files.

We could have added these files to the CLEAN and CLOBBER lists all in one place in the Rakefile. But by making each addition next to the rules for building that file, we make it more likely that if we ever remove or change those rules, we’ll remember update the associated entry in the CLEAN or CLOBBER list.

When we go to the command line and tell Rake to list the available tasks with the rake -T command, we can see that there are two tasks available that we didn’t define: clean, and clobber.

We run rake without any arguments first, to build our ebook files. When we list the files in the project, we can see various .html intermediate files as well as the final product .epub and .mobi files.

If we then run rake clean, we don’t see any output. But when we list the project contents again, we can see that all the .html files have disappeared:

If we then run rake clobber, we see a bunch of warnings about files that could not be found. That’s because clobber first executes the clean task, which we already ran. That task is trying to remove a bunch of files which are already gone. Don’t worry though; these warnings are harmless and can be safely ignored.

When we look at the project contents after running clobber, we can see that the ebook files have vanished along with the intermediate files.

And that’s all there is to it—with rake/clean, we should never again need to write our own project cleanup tasks to remove build files. We can just add the appropriate files or file patterns to the CLEAN and CLOBBER lists, and let Rake do the rest. Happy hacking!

(This post is also available in Japanese from Nilquebe Blog.)

I hope you've enjoyed this episode/article on Rake. If you've learned something today, please consider "paying it forward" by donating to the Weirich Fund, to help carry on Jim's legacy of educating programmers. If you want to see more videos like this one, check out RubyTapas. If you want to learn more about Rake, check out my book-in-progress The Rake Field Manual.

P.S. Have you used Rake in a particularly interesting way? I want to hear from you.