Users Guide Runnables

How Runnables work

Teaching Redcar about every build system in existence would take a long time. Instead, Redcar can read simple json definitions of tasks, build targets and commands.

The syntax of the command schemas looks like this:

{
  "commands":[
    {
      "name":        "gem",
      "command":     "/Users/danlucraft/Programs/jruby/bin/rake gem",
      "description": "Build the gem file redcar-0.3.8dev.gem",
      "type":        "task/ruby/rake"
    },
    {
      "name":        "redcar/runnables",
      "command":     "/Users/danlucraft/Programs/jruby/bin/rake redcar:runnables",
      "description": "Redcar Integration: output runnable info",
      "type":        "task/ruby/rake"
    }
  ],
  "file_runners":[
    {
      "regex":   ".*_spec.rb",
      "name":    "Run as spec",
      "command": "jruby -J-XstartOnFirstThread spec __PATH__",
      "type":    "test/ruby/spec"
    },
    {
      "regex":   ".*.rb",
      "name":    "Run as ruby",
      "command": "ruby __PATH__",
      "type":    "script/ruby"
    }
  ]
}

Commands are predefined command line commands that Redcar will run in the bash shell. File runners are mappings between file name types and command schemas, that allow you to tell Redcar to “Run a tab” and it will find the first matching file runner and execute based on it.

If you want to teach Redcar about your languages task or build system, you should write a program to emit json like this and put it into your-project-root/.redcar/runnables/whatever.json.

How to run rake tasks in Redcar

In order to run rake tasks in Redcar you have to generate the appropriate runnables json for the rake tasks.

Copy this rake task into your project’s Rakefile (which should be in the root of your project’s tree) and run rake redcar:runnables. This should generate .redcar/runnables/*.json and then your rake tasks will appear in the Runnables tree of your project.

You will need to close the Runnables tree and reopen it for Redcar to pick up the changes.

namespace :redcar do
  def hash_with_hash_default
    Hash.new {|h,k| h[k] = hash_with_hash_default }
  end

  require 'json'

  desc "Redcar Integration: output runnable info"
  task :runnables do
    mkdir_p(".redcar/runnables")
    File.open(".redcar/runnables/sync_stdout.rb", "w") do |fout|
      fout.puts <<-RUBY
        $stdout.sync = true
        $stderr.sync = true
      RUBY
    end

    tasks = Rake::Task.tasks
    runnables = []
    ruby_bin = Config::CONFIG["bindir"] + "/ruby -r#{File.dirname(__FILE__)}/.redcar/runnables/sync_stdout.rb " 
    tasks.each do |task|
      name = task.name.gsub(":", "/")
      command = ruby_bin + $0 + " " + task.name
      runnables << {
        "name"        => name,
        "command"     => command, 
        "description" => task.comment,
        "type"        => "task/ruby/rake"
      }
    end
    File.open(".redcar/runnables/rake.json", "w") do |f|
      data = {"commands" => runnables}
      f.puts(JSON.pretty_generate(data))
    end
    File.open(".redcar/runnables/ruby.json", "w") do |f|
      data = {"file_runners" => 
        [
          {
            "regex" =>    ".*.rb$",
            "name" =>     "Run as ruby",
            "command" =>  ruby_bin + "__PATH__",
            "type" =>     "script/ruby"
          }
        ]
      }
      f.puts(JSON.pretty_generate(data))
    end
  end
end