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.



96
97
98
 
# File 'lib/rscons/builder.rb', line 96

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.



203
204
205
206
207
 
# File 'lib/rscons/builder.rb', line 203

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

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



136
137
138
 
# File 'lib/rscons/builder.rb', line 136

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.



104
105
106
107
108
109
110
 
# File 'lib/rscons/builder.rb', line 104

def produces(*side_effects)
  side_effects.each do |side_effect|
    side_effect_expanded = @env.expand(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.



154
155
156
157
158
159
160
161
 
# File 'lib/rscons/builder.rb', line 154

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.



123
124
125
 
# File 'lib/rscons/builder.rb', line 123

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.



180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/rscons/builder.rb', line 180

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.



216
217
218
 
# File 'lib/rscons/builder.rb', line 216

def wait_for(things)
  Array(things)
end