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.



80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/rscons/builder.rb', line 80

def initialize(options)
  @target = options[:target]
  @abstarget = Util.absolute_path(@target)
  @sources = Array(options[:sources])
  @abssources = @sources.map do |source|
    Util.absolute_path(source)
  end
  @cache = options[:cache]
  @env = options[:env]
  @vars = options[:vars]
  @side_effects = Set.new
end

Instance Attribute Details

#abssources ⇒ Array<String, Symbol> (readonly)

Returns Absolute source file names.

Returns:

  • (Array<String, Symbol>) —

    Absolute source file names.



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

def abssources
  @abssources
end

#abstarget ⇒ String, Symbol (readonly)

Returns Absolute target file name.

Returns:

  • (String, Symbol) —

    Absolute target file name.



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

def abstarget
  @abstarget
end

#build_step ⇒ Integer

Returns Build step.

Returns:

  • (Integer) —

    Build step.



64
65
66
 
# File 'lib/rscons/builder.rb', line 64

def build_step
  @build_step
end

#cache ⇒ Cache (readonly)

Returns Cache instance.

Returns:

  • (Cache) —

    Cache instance.



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

def cache
  @cache
end

#env ⇒ Environment (readonly)

Returns The Environment performing the build operation.

Returns:



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

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> (readonly)

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

Returns:

  • (Set<String>) —

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



60
61
62
 
# File 'lib/rscons/builder.rb', line 60

def side_effects
  @side_effects
end

#sources ⇒ Array<String, Symbol> (readonly)

Returns Source file names.

Returns:

  • (Array<String, Symbol>) —

    Source file names.



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

def sources
  @sources
end

#target ⇒ String, Symbol (readonly)

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.



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

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.



108
109
110
 
# File 'lib/rscons/builder.rb', line 108

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.



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

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.



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

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.



148
149
150
 
# File 'lib/rscons/builder.rb', line 148

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.



116
117
118
119
120
121
122
 
# File 'lib/rscons/builder.rb', line 116

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



166
167
168
169
170
171
172
173
 
# File 'lib/rscons/builder.rb', line 166

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.



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

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.



192
193
194
195
196
197
198
199
200
201
202
203
204
 
# File 'lib/rscons/builder.rb', line 192

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.



228
229
230
 
# File 'lib/rscons/builder.rb', line 228

def wait_for(things)
  Array(things)
end