4.6.2.4 Custom Builder Operation

In order for a builder to run, the builder class must implement a the Builder#run() method. Generally, the run() method will use the source file(s) to produce the target file. Here is an example of a trivial builder:

class Rscons::Builders::Custom < Rscons::Builder
  def run(options)
    File.open(@target, "w") do |fh|
      fh.write("Target file created.")
    end
    true
  end
end

4.6.2.4.1 Return Value

4.6.2.4.2 Printing Build Status

A builder should print a status line when it produces a build target. The Builder#print_run_message method can be used to print the builder status line. This method supports a limited markup syntax to identify and color code the build target and/or source(s). Here is our Custom builder example extended to print its status:

class Rscons::Builders::Custom < Rscons::Builder
  def run(options)
    print_run_message("Creating <target>#{@target}<reset> from Custom builder", nil)
    File.open(@target, "w") do |fh|
      fh.write("Target file created.")
    end
    true
  end
end

4.6.2.4.3 Custom Builder Cache Usage - Only Rebuild When Necessary

Whenever possible, a builder should keep track of information necessary to know whether the target file(s) need to be rebuilt. The Rscons::Cache object is the mechanism by which to keep track of this information. The Cache object provides two methods: #up_to_date? and #register_build which can be used to check if a built file is still up-to-date, and to register build information for a subsequent check. Here is a Custom builder which combines its source files similar to what the cat command would do:

class Rscons::Builders::Custom < Rscons::Builder
  def run(options)
    unless @cache.up_to_date?(@target, nil, @sources, @env)
      print_run_message("Combining <source>#{Util.short_format_paths(@sources)}<reset> => <target>#{@target}<reset>", nil)
      File.open(@target, "wb") do |fh|
        @sources.each do |source|
          fh.write(File.read(source, mode: "rb"))
        end
      end
      @cache.register_build(@target, nil, @sources, @env)
    end
    true
  end
end

This builder would rebuild the target file and print its run message if the target file or any of the source file(s) were changed, but otherwise would be silent and not re-combine the source files.

Note that generally the same arguments should be passed to @cache.register_build and @cache.up_to_date?.

4.6.2.4.4 Custom Builder Parallelization

The Rscons scheduler can parallelize builders to take advantage of multiple processor cores. Taking advantage of this ability to parallelize requires the builder author to author the builder in a particular way. The #run() method of each builder is called from Rscons in the main program thread. However, the builder may execute a subcommand, spawn a thread, or register other builders to execute as a part of doing its job. In any of these cases, the builder's run method should make use of Builder#wait_for to "sleep" until one of the items being waited for has completed.

4.6.2.4.4.1 Using a Ruby Thread to Parallelize a Builder

Here is an example of using a Ruby thread to parallelize a builder:

class MyBuilder < Rscons::Builder
  def run(options)
    if @thread
      true
    else
      print_run_message("#{name} #{target}", nil)
      @thread = Thread.new do
        sleep 2
        FileUtils.touch(@target)
      end
      wait_for(@thread)
    end
  end
end

env do |env|
  env.add_builder(MyBuilder)
  env.MyBuilder("foo")
end

It is up to the author of the thread logic to only perform actions that are thread-safe. It is not safe to call other Rscons methods, for example, registering other builders or using the Cache, from a thread other than the one that calls the #run() method.

4.6.2.4.4.2 Executing a Subcommand from a Custom Builder

It is a very common case that a builder will execute a subcommand which produces the build target. This is how most of the built-in Rscons builders execute. A low-level way to handle this is for the builder to construct an instance of the Rscons::Command class and then wait_for the Command object. However, this is a common enough case that Rscons provides a few convenience methods to handle this: