Class: Rake::Task

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

Overview

A Task is the basic unit of work in a Rakefile. Tasks have associated actions (possibly more than one) and a list of prerequisites. When invoked, a task will first ensure that all of its prerequisites have an opportunity to run and then it will execute its own actions.

Tasks are not usually created directly using the new method, but rather use the file and task convenience methods.

Direct Known Subclasses

FileTask

Constant Summary collapse

TASKS = 
Hash.new
RULES = 
Array.new

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(task_name) ⇒ Task

Create a task named task_name with no actions or prerequisites.. use enhance to add actions and prerequisites.



152
153
154
155
156
157
158
 
# File 'lib/rake.rb', line 152

def initialize(task_name)
  @name = task_name
  @prerequisites = FileList[]
  @actions = []
  @already_invoked = false
  @comment = nil
end

Instance Attribute Details

#comment ⇒ Object

Comment for this task.



138
139
140
 
# File 'lib/rake.rb', line 138

def comment
  @comment
end

#prerequisites ⇒ Object (readonly)

List of prerequisites for a task.



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

def prerequisites
  @prerequisites
end

#sources ⇒ Object 



141
142
143
 
# File 'lib/rake.rb', line 141

def sources
  @sources ||= []
end

Class Method Details

.[](task_name) ⇒ Object

Return a task with the given name. If the task is not currently known, try to synthesize one from the defined rules. If no rules are found, but an existing file matches the task name, assume it is a file task with no dependencies or actions.



270
271
272
273
274
275
276
277
278
279
280
281
282
 
# File 'lib/rake.rb', line 270

def [](task_name)
	task_name = task_name.to_s
	if task = TASKS[task_name]
	  return task
	end
	if task = enhance_with_matching_rule(task_name)
	  return task
	end
	if File.exist?(task_name)
	  return Rake::FileTask.define_task(task_name)
	end
	fail "Don't know how to build task '#{task_name}'"
end

.clear ⇒ Object

Clear the task list. This cause rake to immediately forget all the tasks that have been assigned. (Normally used in the unit tests.)



256
257
258
259
 
# File 'lib/rake.rb', line 256

def clear
	TASKS.clear
	RULES.clear
end

.create_rule(args, &block) ⇒ Object

Define a rule for synthesizing tasks.



303
304
305
306
307
 
# File 'lib/rake.rb', line 303

def create_rule(args, &block)
	pattern, deps = resolve_args(args)
	pattern = Regexp.new(Regexp.quote(pattern) + '$') if String === pattern
	RULES << [pattern, deps, block]
end

.define_task(args, &block) ⇒ Object

Define a task given args and an option block. If a rule with the given name already exists, the prerequisites and actions are added to the existing task. Returns the defined task.



293
294
295
296
297
298
299
300
 
# File 'lib/rake.rb', line 293

def define_task(args, &block)
	task_name, deps = resolve_args(args)
	deps = [deps] if (Symbol === deps) || (String === deps)
	deps = deps.collect {|d| d.to_s }
	t = lookup(task_name)
	t.add_comment($last_comment)
	t.enhance(deps, &block)
end

.enhance_with_matching_rule(task_name, level = 0) ⇒ Object

If a rule can be found that matches the task name, enhance the task with the prerequisites and actions from the rule. Set the source attribute of the task appropriately for the rule. Return the enhanced task or nil of no rule was found.



320
321
322
323
324
325
326
327
328
329
330
331
332
333
 
# File 'lib/rake.rb', line 320

def enhance_with_matching_rule(task_name, level=0)
	fail Rake::RuleRecursionOverflowError,
	  "Rule Recursion Too Deep" if level >= 16
	RULES.each do |pattern, extensions, block|
	  if md = pattern.match(task_name)
	    task = attempt_rule(task_name, extensions, block, level)
	    return task if task
	  end
	end
	nil
rescue Rake::RuleRecursionOverflowError => ex
	ex.add_target(task_name)
	fail ex
end

.lookup(task_name) ⇒ Object

Lookup a task. Return an existing task if found, otherwise create a task of the current type.



311
312
313
314
 
# File 'lib/rake.rb', line 311

def lookup(task_name)
	name = task_name.to_s
	TASKS[name] ||= self.new(task_name)
end

.task_defined?(task_name) ⇒ Boolean

TRUE if the task name is already defined.

Returns:

  • (Boolean) 


285
286
287
288
 
# File 'lib/rake.rb', line 285

def task_defined?(task_name)
	task_name = task_name.to_s
	TASKS[task_name]
end

.tasks ⇒ Object

List of all defined tasks.



262
263
264
 
# File 'lib/rake.rb', line 262

def tasks
	TASKS.keys.sort.collect { |tn| Rake::Task[tn] }
end

Instance Method Details

#add_comment(comment) ⇒ Object

Add a comment to the task. If a comment alread exists, separate the new comment with “ / ”.



218
219
220
221
222
223
224
225
226
227
 
# File 'lib/rake.rb', line 218

def add_comment(comment)
  return if ! $last_comment
  if @comment 
	@comment << " / "
  else
	@comment = ''
  end
  @comment << $last_comment
  $last_comment = nil
end

#enhance(deps = nil, &block) ⇒ Object

Enhance a task with prerequisites or actions. Returns self.



161
162
163
164
165
 
# File 'lib/rake.rb', line 161

def enhance(deps=nil, &block)
  @prerequisites |= deps if deps
  @actions << block if block_given?
  self
end

#execute ⇒ Object

Execute the actions associated with this task.



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

def execute
  if $dryrun
	puts "** Execute (dry run) #{name}"
	return
  end
  if $trace
	puts "** Execute #{name}"
  end
  self.class.enhance_with_matching_rule(name) if @actions.empty?
  @actions.each { |act| result = act.call(self) }
end

#investigation ⇒ Object

Return a string describing the internal state of a task. Useful for debugging.



231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
 
# File 'lib/rake.rb', line 231

def investigation
  result = "------------------------------\n"
  result << "Investigating #{name}\n" 
  result << "class: #{self.class}\n"
  result <<  "task needed: #{needed?}\n"
  result <<  "timestamp: #{timestamp}\n"
  result << "pre-requisites: \n"
  prereqs = @prerequisites.collect {|name| Rake::Task[name]}
  prereqs.sort! {|a,b| a.timestamp <=> b.timestamp}
  prereqs.each do |p|
	result << "--#{p.name} (#{p.timestamp})\n"
  end
  latest_prereq = @prerequisites.collect{|n| Rake::Task[n].timestamp}.max
  result <<  "latest-prerequisite time: #{latest_prereq}\n"
  result << "................................\n\n"
  return result
end

#invoke ⇒ Object

Invoke the task if it is needed. Prerequites are invoked first.



173
174
175
176
177
178
179
180
181
 
# File 'lib/rake.rb', line 173

def invoke
  if $trace
	puts "** Invoke #{name} #{format_trace_flags}"
  end
  return if @already_invoked
  @already_invoked = true
  @prerequisites.each { |n| Rake::Task[n].invoke }
  execute if needed?
end

#name ⇒ Object

Name of the task.



168
169
170
 
# File 'lib/rake.rb', line 168

def name
  @name.to_s
end

#needed? ⇒ Boolean

Is this task needed?

Returns:

  • (Boolean) 


206
207
208
 
# File 'lib/rake.rb', line 206

def needed?
  true
end

#source ⇒ Object

First source from a rule (nil if no sources)



146
147
148
 
# File 'lib/rake.rb', line 146

def source
  @sources.first if defined?(@sources)
end

#timestamp ⇒ Object

Timestamp for this task. Basic tasks return the current time for their time stamp. Other tasks can be more sophisticated.



212
213
214
 
# File 'lib/rake.rb', line 212

def timestamp
  @prerequisites.collect { |p| Rake::Task[p].timestamp }.max || Time.now
end