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

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.


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.


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

def default_variables(env)
  {}
end

#featuresArray<String>

Return a 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.

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.

Since:

  • 1.10.0


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

def finalize(options)
end

#nameString

Return the name of the builder.

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


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.


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(options) ⇒ ThreadedCommand, ...

    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


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.

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.

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.


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.

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.

Options Hash (options):

  • :stdout (String)

    File name to redirect standard output to.

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