Class: Rscons::Builder

Inherits:
Object
  • Object
show all
Defined in:
lib/rscons/builder.rb,
lib/rscons/builders/mixins/object.rb

Overview

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

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options) ⇒ Builder

Create an instance of the Builder to build a target.

Parameters:

  • options (Hash) —

    Options.

Options Hash (options):

  • :target (String, Symbol) —

    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.



72
73
74
75
76
77
78
79
 
# File 'lib/rscons/builder.rb', line 72

def initialize(options)
  @target = options[:target]
  @sources = options[:sources]
  @cache = options[:cache]
  @env = options[:env]
  @vars = options[:vars]
  @side_effects = Set.new
end

Instance Attribute Details

#build_step ⇒ Integer

Returns Build step.

Returns:

  • (Integer) —

    Build step.



56
57
58
 
# File 'lib/rscons/builder.rb', line 56

def build_step
  @build_step
end

#cache ⇒ Cache

Returns Cache instance.

Returns:

  • (Cache) —

    Cache instance.



40
41
42
 
# File 'lib/rscons/builder.rb', line 40

def cache
  @cache
end

#env ⇒ Environment

Returns The Environment performing the build operation.

Returns:



44
45
46
 
# File 'lib/rscons/builder.rb', line 44

def env
  @env
end

#preferred_ld ⇒ String? (readonly)

Returns Preferred linker for this object file, or a construction variable reference thereto.

Returns:

  • (String, nil) —

    Preferred linker for this object file, or a construction variable reference thereto.



6
7
8
 
# File 'lib/rscons/builders/mixins/object.rb', line 6

def preferred_ld
  @preferred_ld
end

#side_effects ⇒ Set<String>

Returns Side effect file(s) produced when this builder runs.

Returns:

  • (Set<String>) —

    Side effect file(s) produced when this builder runs.



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

def side_effects
  @side_effects
end

#sources ⇒ Array<String>

Returns Source file name(s).

Returns:

  • (Array<String>) —

    Source file name(s).



36
37
38
 
# File 'lib/rscons/builder.rb', line 36

def sources
  @sources
end

#target ⇒ String, Symbol

Returns Target file name.

Returns:

  • (String, Symbol) —

    Target file name.



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

def target
  @target
end

#vars ⇒ Hash, VarSet

Returns Construction variables used to perform the build operation.

Returns:

  • (Hash, VarSet) —

    Construction variables used to perform the build operation.



48
49
50
 
# File 'lib/rscons/builder.rb', line 48

def vars
  @vars
end

Class Method Details

.extra_path ⇒ String?

Return a String specifying an extra path component used to differentiate build targets built by this builder from others.

Returns:

  • (String, nil) —

    Extra path component used to differentiate build targets built by this builder from others.



17
18
 
# File 'lib/rscons/builder.rb', line 17

def extra_path
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.



25
26
27
 
# File 'lib/rscons/builder.rb', line 25

def name
  super.split(":").last
end

Instance Method Details

#depends(*user_deps) ⇒ void

This method returns an undefined value.

Manually record a given build target as depending on the specified files.

Parameters:

  • user_deps (Array<String>) —

    Dependency files.



104
105
106
 
# File 'lib/rscons/builder.rb', line 104

def depends(*user_deps)
  @env.depends(@target, *user_deps)
end

#finalize_command(options = {}) ⇒ true

Register build results from a Command with the cache.

Parameters:

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

    Builder finalize options.

Options Hash (options):

  • :stdout (String) —

    File name to redirect standard output to.

Returns:

  • (true) —

    Return value for #run method.



211
212
213
214
215
 
# File 'lib/rscons/builder.rb', line 211

def finalize_command(options = {})
  sources = options[:sources] || @sources
  @cache.register_build(@target, @command, sources, @env)
  true
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.



86
87
88
 
# File 'lib/rscons/builder.rb', line 86

def name
  self.class.name
end

#nop? ⇒ Boolean

Return whether the builder is a no-op.

Returns:

  • (Boolean) —

    Whether the builder is a no-op.



94
95
96
 
# File 'lib/rscons/builder.rb', line 94

def nop?
  false
end

#print_run_message(short_description, command) ⇒ void

This method returns an undefined value.

Print the builder run message, depending on the Environment's echo mode.

Parameters:

  • short_description (String) —

    Builder short description, printed if the echo mode is :short, or if there is no command.

  • command (Array<String>) —

    Builder command, printed if the echo mode is :command.



144
145
146
 
# File 'lib/rscons/builder.rb', line 144

def print_run_message(short_description, command)
  @env.print_builder_run_message(self, short_description, command)
end

#produces(*side_effects) ⇒ void

This method returns an undefined value.

Manually record the given side effect file(s) as being produced when the named target is produced.



112
113
114
115
116
117
118
 
# File 'lib/rscons/builder.rb', line 112

def produces(*side_effects)
  side_effects.each do |side_effect|
    side_effect_expanded = @env.expand_path(@env.expand_varref(side_effect))
    @env.register_side_effect(side_effect_expanded)
    @side_effects << side_effect_expanded
  end
end

#register_command(short_description, command, options = {}) ⇒ Object

Create a Command object to execute the build command in a thread.

Parameters:

  • short_description (String) —

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

  • command (Array<String>) —

    The command to execute.

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

    Options.

Options Hash (options):

  • :stdout (String) —

    File name to redirect standard output to.

Returns:

  • (Object) —

    Return value for #run method.



162
163
164
165
166
167
168
169
 
# File 'lib/rscons/builder.rb', line 162

def register_command(short_description, command, options = {})
  command_options = {}
  if options[:stdout]
    command_options[:system_options] = {out: options[:stdout]}
  end
  print_run_message(short_description, @command)
  wait_for(Command.new(command, self, command_options))
end

#run(options) ⇒ Object

Run the builder to produce a build target.

Parameters:

  • options (Hash) —

    Run options.

Returns:

  • (Object) —

    If the build operation fails, this method should return false. If the build operation succeeds, this method should return true. If the build operation is not yet complete and is waiting on other operations, this method should return the return value from the #wait_for method.



131
132
133
 
# File 'lib/rscons/builder.rb', line 131

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

#standard_command(short_description, command, options = {}) ⇒ Object

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

Parameters:

  • short_description (String) —

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

  • command (Array<String>) —

    The command to execute.

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

    Options.

Options Hash (options):

  • :sources (Array<String>) —

    Sources to override @sources.

  • :stdout (String) —

    File name to redirect standard output to.

Returns:

  • (Object) —

    Return value for #run method.



188
189
190
191
192
193
194
195
196
197
198
199
200
 
# File 'lib/rscons/builder.rb', line 188

def standard_command(short_description, command, options = {})
  @command = command
  sources = options[:sources] || @sources
  if @cache.up_to_date?(@target, @command, sources, @env)
    true
  else
    unless Rscons.phony_target?(@target)
      @cache.mkdir_p(File.dirname(@target))
      FileUtils.rm_f(@target)
    end
    register_command(short_description, @command, options)
  end
end

#wait_for(things) ⇒ Object

A builder can indicate to Rscons that it needs to wait for a separate operation to complete by using this method. The return value from this method should be returned from the builder's #run method.

Parameters:

  • things (Builder, Command, Thread, Array<Builder, Command, Thread>) —

    Builder(s) or Command(s) or Thread(s) that this builder needs to wait for.



224
225
226
 
# File 'lib/rscons/builder.rb', line 224

def wait_for(things)
  Array(things)
end