4.1.1 Task Parameters

Tasks can accept parameters. Parameters are defined by the build script author, and have default values. The user can override parameter values on the command line.

Task parameters are defined by passing a parameter constructed with the Rscons param() method to the :params argument of the task() method. The signature of the param method is:

def param(name, value, takes_arg, description)

For example:

task "build", params: [
  param("myparam", "defaultvalue", true, "My special parameter"),
  param("xyz", nil, false, "Enable the xyz feature"),
] do |task, params|
  env do |env|
    env["CPPDEFINES"] << "SOMEMACRO=#{params["myparam"]}"
    if params["flag"]
      env["CPPDEFINES"] << "ENABLE_FEATURE_XYZ"
    end
  end
end

With the above Rsconscript, the user could invoke Rscons as:

./rscons build --myparam=pvalue --xyz

This would pass in "pvalue" as the value to the "myparam" parameter, and a truthy value ("--xyz") as the value of the "xyz" parameter.

As seen above, task parameter values can be accessed within a task's action block by using the second parameter (params) to the action block. Task parameter values can also be accessed with the Task#[] method on any task object. This allows accessing the parameter values of any task object, not just the task owning the action block being executed.

Example:

task "one", params: param("flag", nil, false, "Enable a flag")

task "two" do
  puts "Task one's flag #{Task["one"]["flag"] ? "is" : "is not"} set"
end

Task parameters can also be referenced via construction variables. Each task parameter is stored in a construction variable. The name for the construction variable is created by joining the task name and the parameter name with a ":" character. For example:

task "build", params: [
  param("heap-size", "1024", true, "Set heap size"),
] do
  env["CPPDEFINES"] << "HEAP_SIZE=${build:heap-size}"
  env.Program("^/myprog", glob("src/**/*.c"))
  env.Install("${configure:prefix}/bin/myprog", "^/myprog")
end