Detroit

Detroit’s main configuration file is called toolchain. Toolchains define the specific tool instances that a project will utilize. Toolchains can be written in a few different formats thanks to the flexibility of Ruby. All formats are equivalent. Which format you use is strictly a regard of your personal preference.

Ruby-based Toolchain Scripts

Tool Method Notation

Traditionally a Ruby-based toolchain script is dominated by calls to the tool method with an optional instance name and a setter block.

tool :myself do |s|
    s.class  = :Announce
    s.mailto = "transfire@gmail.com"
    s.active = true
  end

  tool :rdoc do |r|
    r.include = [ 'lib', '[A-Z]*' ]
    r.exclude = [ 'Gemfile' ]
  end

In the first example the tool is given an arbitrary tool name and the tool type is given via the class setting. (This setting can also be called just tool, they are synonymous, but class reads better when used with the tool method.) If the tool type is not specified, it is assumed to be same as the tool instance name. In the above example rdoc is taken to be both the type of tool and the name of the particular instance.

A few years ago, Sinatra came along and popularized the use of the #set method. A simple addition to Detroit’s toolchain evaluator allows for this arguably cleaner notation:

tool :myself do
    set :tooltype, :Announce
    set :mailto, "transfire@gmail.com"
    set :priority, -1
    set :active, true
  end

  tool :rdoc do
    set :include, [ 'lib', '[A-Z]*' ]
    set :exclude, [ 'Gemfile' ]
  end

The #set method also allows for nested set blocks to define hash values.

tool :rubyforge do
    set :sitemap do
      set :site, name
    end
    set :active, false
  end

The setting active defaults to true if not given, so is not strictly needed in the above examples, but it is convenient to have if a tool ever needs to be deactivate temporarily –more convenient than remarking out a whole tool entry.

Almost all options have standard defaults so it is sometimes possible for a tool entry to be written as simply as:

tool :rdoc

Tool Name Notation

Thanks to some straight-forward meta-programming, a Ruby-based toolchain can also be written in a more concise notation by using the name of the tool’s class as a method. This can be followed by a settings block, as with the above examples, or passed a settings hash. In which case an toolchain script can look like:

Announce   :mailto   => "ruby-talk@ruby-lang.org",
             :active   => true

  Announce   :myself,
             :mailto   => "transfire@gmail.com",
             :priority => -1
             :active   => true

  Gem        :spec     => false,
             :active   => true

  DNote      :priority => -1,
             :active   => true

  RI         :exclude  => [],
             :active   => true

  RDoc       :include  => [ 'lib', '[A-Z]*' ],
             :exclude  => [ 'Gemfile' ]

  Testrb     :active   => true

  Rubyforge  :sitemap  => {
               :site => name
             },
             :active   => false

This format is convenient in that it reduces the amount of extraneous syntax needed to define tool instances. With Ruby 1.9+ it can be even more conisce using the new Hash syntax.

Announce :myself,
    mailto: "transfire@gmail.com",
    priority: -1,
    active: true

YAML-based Toolchain Scripts

We have saved the most concise notation for last. The YAML format is essentially the same as the traditional Ruby format except that the main key provides the tool instance name and the type is a setting which defaults to the name. Also, notice the start document indicator (---). This indicator MUST BE USED for the file to be recognized as YAML, rather than Ruby.

---

  announce:
    mailto: transfire@gmail.com
    active: true

  myself:
    tool:   Announce
    mailto: transfire@gmail.com
    active: true

  gem:
    autospec: false
    active:   true

  dnote:
    priority: -1
    active:   true

  rdoc:
    include: [ "lib", "[A-Z]*" ]
    exclude: [ "Gemfile" ]

  ri:
    exclude: []
    active:  true

  stats:
    priority: -1
    active:   true

  testrb:
    active: true

  rubyforge:
    type: forge
    sitemap:
      site: <% name %>
    active: false

Notice we used the the alternate setting tool instead of class for the myself announce tool instance. The effect is exactly the same.

Also notice the last entry, the YAML format supports ERB and provides access to project metadata via the ERB’s binding.

With the Ruby format it is easy enough to load external library using standard require and load methods. Since the YAML format supports ERB it can be used to achieve the same effect.

---
  <% require 'some/external/library' %>