Task Arguments And Rakefile Parameters

Rake allows you to pass parameters from the command line, into the rakefile and to specific tasks. You can do this a few different ways, depending on how you need to call your tasks and whether or not the parameter needs to be available everywhere or only for a specific task.

For complete documentation on these options, see the Rakefile documentation.

Global Parameters

You can pass name=value parameters from the rake command line. For example rake name=value will pass a parameter of name with the value of "value" into the rakefile. You can then access these parameters through the ENV hash.

Here's an example that retrieves an option to set the current build configuration for msbuild:

config = ENV["config"] || "debug"

msbuild :build do |msb|
  msb.options :properties => config
end

You can then call this from the command line and specify the configuration you want: rake build config=release. If you don't specify a configuration, though, it will default to debug mode. This is accomplished by the || "debug" code, which assigns the value of "debug" to the config variable if there is no config parameter passed in.

Task Arguments

Rake also allows you to specify arguments that are specific to a task. To do this, you need to provide one or more parameter names as an array to the task definition. The arguments are then made available through an args parameter in the code block.

task :foo, [:param1, :param2] do |t, args|
  # ...
  puts "Param1 is: #{args.param1}"
  puts "Param2 is: #{args.param2}"
end

Then when calling this from the command line, specify the args in brackets for the task: rake foo[1, 2]. This will print the following the command line:

Param1 is: 1
Param2 is: 2

Here's an example of the nunit task setting a tag to only run tests with a specific tag.

nunit :test, [:tag] do |nunit, args|
  options = ["some", "options", "here"]
  options << "/include=#{args.tag}" if args.tag
  nunit.options = options
end

This can be run from the command line or a build server to only run the tests you want: rake test[SmokeTest].

You can also specify default values for task parameters, if you need to.

nunit :test, [:tag] do |nunit, args|
  args.with_defaults :tag => "SmokeTest"
  nunit.options "/include=#{args.tag}"
end

This will default the tag argument to "SmokeTest" if one is not provided on the command line.

Task Arguments vs. Rake Parameters

The most significant difference between the two options for getting parameters into your build is where the parameters are available.

If you need a parameter to be available outside of a task - for example, if you want to pass a parameter into the Albacore.configure block, then you should use rake's name=value parameters. Also, if you prefer to set up task dependencies in the task definitions through the task :name => [:dependency1, :dependency2] syntax, then you should use the name=value parameters.

If you only need the arguments to be available for a specific task and you will call that task directly from the command line, with those parameters, then you can use the task arguments.

Note that there is no way to specify task arguments when calling a task as a dependency of another task. However, you can manually invoke the task and provide parameters, if you need to:

task :foo, [:myarg] do |t, args|
  puts "the argument is #{args.myarg}"
end

task :bar do
  Rake::Task[:foo].invoke("useless")
end

Now when you call rake bar from the command line, it will produce the following output:

the argument is useless