class Rscons::Builder

Class to hold an object that knows how to build a certain type of file.

Public Instance Methods

create_build_target(options) click to toggle source

Create a BuildTarget object for this build target.

Builder sub-classes can override this method to manipulate parameters (for example, add a suffix to the user-given target file name).

@param options [Hash] Options to create the BuildTarget with. @option options [Environment] :env

The Environment.

@option options [String] :target

The user-supplied target name.

@option options [Array<String>] :sources

The user-supplied source file name(s).

@option options [Hash,VarSet] :vars

Extra construction variables.

@return [BuildTarget]

# File lib/rscons/builder.rb, line 51
def create_build_target(options)
  BuildTarget.new(options)
end
default_variables(env) click to toggle source

Return a set of default construction variables for the builder.

@param env [Environment] The Environment.

@return [Hash] Default construction variables.

# File lib/rscons/builder.rb, line 23
def default_variables(env)
  {}
end
features() click to toggle source

Return a set of build features that this builder provides.

@return [Array<String>]

Set of build features that this builder provides.
# File lib/rscons/builder.rb, line 31
def features
  []
end
finalize(options) click to toggle source

Finalize a build operation.

This method is called after the {#run} method if the {#run} method returns a {ThreadedCommand} object.

@since 1.10.0

@param options [Hash]

Options.

@option options [String] :target

Target file name.

@option options [Array<String>] :sources

Source file name(s).

@option options [Cache] :cache

The Cache object.

@option options [Environment] :env

The Environment executing the builder.

@option options [Hash,VarSet] :vars

Extra construction variables.

@option options [Object] :setup_info

Whatever value was returned from this builder's {#setup} method call.

@option options [true,false,nil] :command_status

If the {#run} method returns a {ThreadedCommand}, this field will
contain the return value from executing the command with
Kernel.system().

@option options [ThreadedCommand] :tc

The {ThreadedCommand} object that was returned by the #run method.

@return [String,false]

Name of the target file on success or false on failure.
# File lib/rscons/builder.rb, line 189
def finalize(options)
end
name() click to toggle source

Return the name of the builder.

If not overridden this defaults to the last component of the class name.

@return [String] The name of the builder.

# File lib/rscons/builder.rb, line 14
def name
  self.class.name.split(":").last
end
produces?(target, source, env) click to toggle source

Return whether this builder object is capable of producing a given target file name from a given source file name.

@param target [String]

The target file name.

@param source [String]

The source file name.

@param env [Environment]

The Environment.

@return [Boolean]

Whether this builder object is capable of producing a given target
file name from a given source file name.
# File lib/rscons/builder.rb, line 68
def produces?(target, source, env)
  false
end
run(options) click to toggle source

Run the builder to produce a build target.

The run method supports two different signatures - an older signature with five separate arguments, and a newer one with one Hash argument. A builder author can use either signature, and Rscons will automatically determine which arguments to pass when invoking the run method based on the method's arity.

@overload run(target, sources, cache, env, vars)

@param target [String]
  Target file name.
@param sources [Array<String>]
  Source file name(s).
@param cache [Cache]
  The Cache object.
@param env [Environment]
  The Environment executing the builder.
@param vars [Hash,VarSet]
  Extra construction variables.

@overload run(options)

@since 1.10.0

@param options [Hash]
  Run options.
@option options [String] :target
  Target file name.
@option options [Array<String>] :sources
  Source file name(s).
@option options [Cache] :cache
  The Cache object.
@option options [Environment] :env
  The Environment executing the builder.
@option options [Hash,VarSet] :vars
  Extra construction variables.
@option options [Object] :setup_info
  Whatever value was returned from this builder's {#setup} method call.

@return [ThreadedCommand,String,false]

Name of the target file on success or false on failure.
Since 1.10.0, this method may return an instance of {ThreadedCommand}.
In that case, the build operation has not actually been completed yet
but the command to do so will be executed by Rscons in a separate
thread. This allows for build parallelization. If a {ThreadedCommand}
object is returned, the {#finalize} method will be called after the
command has completed. The {#finalize} method should then be used to
record cache info, if needed, and to return the true result of the
build operation. The builder can store information to be passed in to
the {#finalize} method by populating the :builder_info field of the
{ThreadedCommand} object returned here.
# File lib/rscons/builder.rb, line 155
def run(options)
  raise "This method must be overridden in a subclass"
end
setup(options) click to toggle source

Set up a build operation using this builder.

This method is called when a build target is registered using this builder. This method should not do any building, but should perform any setup needed and register any prerequisite build targets that need to be built before the target being requested here.

If the builder needs no special setup, it does not need to override this method. If there is any information produced in this method that will be needed later in the build, it can be stored in the return value from this method, which will be passed to the {#run} method.

@since 1.10.0

@param options [Hash]

Options.

@option options [String] :target

Target file name.

@option options [Array<String>] :sources

Source file name(s).

@option options [Environment] :env

The Environment executing the builder.

@option options [Hash,VarSet] :vars

Extra construction variables.

@return [Object]

Any object that the builder author wishes to be saved and passed back
in to the {#run} method.
# File lib/rscons/builder.rb, line 100
def setup(options)
end
standard_build(short_cmd_string, target, command, sources, env, cache) click to toggle source

Check if the cache is up to date for the target and if not execute the build command. This method does not support parallelization.

@param short_cmd_string [String]

Short description of build action to be printed when env.echo ==
:short.

@param target [String] Name of the target file. @param command [Array<String>]

The command to execute to build the target.

@param sources [Array<String>] Source file name(s). @param env [Environment] The Environment executing the builder. @param cache [Cache] The Cache object.

@return [String,false]

The name of the target on success or false on failure.
# File lib/rscons/builder.rb, line 207
def standard_build(short_cmd_string, target, command, sources, env, cache)
  unless cache.up_to_date?(target, command, sources, env)
    unless Rscons.phony_target?(target)
      cache.mkdir_p(File.dirname(target))
      FileUtils.rm_f(target)
    end
    return false unless env.execute(short_cmd_string, command)
    cache.register_build(target, command, sources, env)
  end
  target
end
standard_finalize(options) click to toggle source

Register build results from a {ThreadedCommand} with the cache.

@since 1.10.0

@param options [Hash]

Builder finalize options.

@return [String, nil]

The target name on success or nil on failure.
# File lib/rscons/builder.rb, line 265
def standard_finalize(options)
  if options[:command_status]
    target, sources, cache, env = options.values_at(:target, :sources, :cache, :env)
    cache.register_build(target, options[:tc].command, sources, env)
    target
  end
end
standard_threaded_build(short_cmd_string, target, command, sources, env, cache, options = {}) click to toggle source

Check if the cache is up to date for the target and if not create a {ThreadedCommand} object to execute the build command in a thread.

@since 1.10.0

@param short_cmd_string [String]

Short description of build action to be printed when env.echo ==
:short.

@param target [String] Name of the target file. @param command [Array<String>]

The command to execute to build the target.

@param sources [Array<String>] Source file name(s). @param env [Environment] The Environment executing the builder. @param cache [Cache] The Cache object. @param options [Hash] Options. @option options [String] :stdout

File name to redirect standard output to.

@return [String,ThreadedCommand]

The name of the target if it is already up to date or the
{ThreadedCommand} object created to update it.
# File lib/rscons/builder.rb, line 240
def standard_threaded_build(short_cmd_string, target, command, sources, env, cache, options = {})
  if cache.up_to_date?(target, command, sources, env)
    target
  else
    unless Rscons.phony_target?(target)
      cache.mkdir_p(File.dirname(target))
      FileUtils.rm_f(target)
    end
    tc_options = {short_description: short_cmd_string}
    if options[:stdout]
      tc_options[:system_options] = {out: options[:stdout]}
    end
    ThreadedCommand.new(command, tc_options)
  end
end