Class: Rscons::Builder

Inherits:
Object
  • Object
show all
Defined in:
lib/rscons/builder.rb

Overview

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

Instance Method Summary collapse

Instance Method Details

#create_build_target(options) ⇒ BuildTarget

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).

Parameters:

  • options (Hash) —

    Options to create the BuildTarget with.

Options Hash (options):

  • :env (Environment) —

    The Environment.

  • :target (String) —

    The user-supplied target name.

  • :sources (Array<String>) —

    The user-supplied source file name(s).

  • :vars (Hash, VarSet) —

    Extra construction variables.

Returns:



51
52
53
 
# File 'lib/rscons/builder.rb', line 51

def create_build_target(options)
  BuildTarget.new(options)
end

#default_variables(env) ⇒ Hash

Return a set of default construction variables for the builder.

Parameters:

Returns:

  • (Hash) —

    Default construction variables.



23
24
25
 
# File 'lib/rscons/builder.rb', line 23

def default_variables(env)
  {}
end

#features ⇒ Array<String>

Return a set of build features that this builder provides.

Returns:

  • (Array<String>) —

    Set of build features that this builder provides.



31
32
33
 
# File 'lib/rscons/builder.rb', line 31

def features
  []
end

#finalize(options) ⇒ String, false

Finalize a build operation.

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

Parameters:

  • options (Hash) —

    Options.

Options Hash (options):

  • :target (String) —

    Target file name.

  • :sources (Array<String>) —

    Source file name(s).

  • :cache (Cache) —

    The Cache object.

  • :env (Environment) —

    The Environment executing the builder.

  • :vars (Hash, VarSet) —

    Extra construction variables.

  • :setup_info (Object) —

    Whatever value was returned from this builder’s #setup method call.

  • :command_status (true, false, nil) —

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

  • :tc (ThreadedCommand) —

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

Returns:

  • (String, false) —

    Name of the target file on success or false on failure.

Since:

  • 1.10.0



189
190
 
# File 'lib/rscons/builder.rb', line 189

def finalize(options)
end

#name ⇒ String

Return the name of the builder.

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

Returns:

  • (String) —

    The name of the builder.



14
15
16
 
# File 'lib/rscons/builder.rb', line 14

def name
  self.class.name.split(":").last
end

#produces?(target, source, env) ⇒ Boolean

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

Parameters:

  • target (String) —

    The target file name.

  • source (String) —

    The source file name.

  • env (Environment) —

    The Environment.

Returns:

  • (Boolean) —

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



68
69
70
 
# File 'lib/rscons/builder.rb', line 68

def produces?(target, source, env)
  false
end

#run(target, sources, cache, env, vars) ⇒ ThreadedCommand, ... #run(options) ⇒ ThreadedCommand, ...

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.

Overloads:

  • #run(target, sources, cache, env, vars) ⇒ ThreadedCommand, ...

    Parameters:

    • target (String) —

      Target file name.

    • sources (Array<String>) —

      Source file name(s).

    • cache (Cache) —

      The Cache object.

    • env (Environment) —

      The Environment executing the builder.

    • vars (Hash, VarSet) —

      Extra construction variables.

  • #run(options) ⇒ ThreadedCommand, ...

    Parameters:

    • options (Hash) —

      Run options.

    Options Hash (options):

    • :target (String) —

      Target file name.

    • :sources (Array<String>) —

      Source file name(s).

    • :cache (Cache) —

      The Cache object.

    • :env (Environment) —

      The Environment executing the builder.

    • :vars (Hash, VarSet) —

      Extra construction variables.

    • :setup_info (Object) —

      Whatever value was returned from this builder’s #setup method call.

    Since:

    • 1.10.0

Returns:

  • (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.



155
156
157
 
# File 'lib/rscons/builder.rb', line 155

def run(options)
  raise "This method must be overridden in a subclass"
end

#setup(options) ⇒ Object

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.

Parameters:

  • options (Hash) —

    Options.

Options Hash (options):

  • :target (String) —

    Target file name.

  • :sources (Array<String>) —

    Source file name(s).

  • :env (Environment) —

    The Environment executing the builder.

  • :vars (Hash, VarSet) —

    Extra construction variables.

Returns:

  • (Object) —

    Any object that the builder author wishes to be saved and passed back in to the #run method.

Since:

  • 1.10.0



100
101
 
# File 'lib/rscons/builder.rb', line 100

def setup(options)
end

#standard_build(short_cmd_string, target, command, sources, env, cache) ⇒ String, false

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

Parameters:

  • short_cmd_string (String) —

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

  • target (String) —

    Name of the target file.

  • command (Array<String>) —

    The command to execute to build the target.

  • sources (Array<String>) —

    Source file name(s).

  • env (Environment) —

    The Environment executing the builder.

  • cache (Cache) —

    The Cache object.

Returns:

  • (String, false) —

    The name of the target on success or false on failure.



207
208
209
210
211
212
213
214
215
216
217
 
# 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) ⇒ String?

Register build results from a ThreadedCommand with the cache.

Parameters:

  • options (Hash) —

    Builder finalize options.

Returns:

  • (String, nil) —

    The target name on success or nil on failure.

Since:

  • 1.10.0



265
266
267
268
269
270
271
 
# 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 = {}) ⇒ String, ThreadedCommand

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.

Parameters:

  • short_cmd_string (String) —

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

  • target (String) —

    Name of the target file.

  • command (Array<String>) —

    The command to execute to build the target.

  • sources (Array<String>) —

    Source file name(s).

  • env (Environment) —

    The Environment executing the builder.

  • cache (Cache) —

    The Cache object.

  • options (Hash) (defaults to: {}) —

    Options.

Options Hash (options):

  • :stdout (String) —

    File name to redirect standard output to.

Returns:

Since:

  • 1.10.0



240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
 
# 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