Class: Rake::Task

Inherits:
Object
  • Object
show all
Defined in:
lib/rake/task.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.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(task_name, app) ⇒ Task

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



82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'lib/rake/task.rb', line 82

def initialize(task_name, app)
  @name            = task_name.to_s
  @prerequisites   = []
  @actions         = []
  @already_invoked = false
  @comments        = []
  @lock            = Monitor.new
  @application     = app
  @scope           = app.current_scope
  @arg_names       = nil
  @locations       = []
end

Instance Attribute Details

#actions ⇒ Object (readonly)

List of actions attached to a task.



19
20
21
 
# File 'lib/rake/task.rb', line 19

def actions
  @actions
end

#application ⇒ Object

Application owning this task.



22
23
24
 
# File 'lib/rake/task.rb', line 22

def application
  @application
end

#locations ⇒ Object (readonly)

File/Line locations of each of the task definitions for this task (only valid if the task was defined with the detect location option set).



30
31
32
 
# File 'lib/rake/task.rb', line 30

def locations
  @locations
end

#prerequisites ⇒ Object (readonly)

List of prerequisites for a task.



16
17
18
 
# File 'lib/rake/task.rb', line 16

def prerequisites
  @prerequisites
end

#scope ⇒ Object (readonly)

Array of nested namespaces names used for task lookup by this task.



25
26
27
 
# File 'lib/rake/task.rb', line 25

def scope
  @scope
end

#sources ⇒ Object 



43
44
45
 
# File 'lib/rake/task.rb', line 43

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.



347
348
349
 
# File 'lib/rake/task.rb', line 347

def [](task_name)
  Rake.application[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.)



334
335
336
 
# File 'lib/rake/task.rb', line 334

def clear
  Rake.application.clear
end

.create_rule(*args, &block) ⇒ Object

Define a rule for synthesizing tasks.



364
365
366
 
# File 'lib/rake/task.rb', line 364

def create_rule(*args, &block)
  Rake.application.create_rule(*args, &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.



359
360
361
 
# File 'lib/rake/task.rb', line 359

def define_task(*args, &block)
  Rake.application.define_task(self, *args, &block)
end

.scope_name(scope, task_name) ⇒ Object

Apply the scope to the task name according to the rules for this kind of task. Generic tasks will accept the scope as part of the name.



371
372
373
374
 
# File 'lib/rake/task.rb', line 371

def scope_name(scope, task_name)
#        (scope + [task_name]).join(':')
  scope.path_with_task_name(task_name)
end

.task_defined?(task_name) ⇒ Boolean

TRUE if the task name is already defined.

Returns:

  • (Boolean) 


352
353
354
 
# File 'lib/rake/task.rb', line 352

def task_defined?(task_name)
  Rake.application.lookup(task_name) != nil
end

.tasks ⇒ Object

List of all defined tasks.



339
340
341
 
# File 'lib/rake/task.rb', line 339

def tasks
  Rake.application.tasks
end

Instance Method Details

#add_description(description) ⇒ Object

Add a description to the task. The description can consist of an option argument list (enclosed brackets) and an optional comment.



254
255
256
257
258
 
# File 'lib/rake/task.rb', line 254

def add_description(description)
  return unless description
  comment = description.strip
  add_comment(comment) if comment && ! comment.empty?
end

#all_prerequisite_tasks ⇒ Object

List of all unique prerequisite tasks including prerequisite tasks’ prerequisites. Includes self when cyclic dependencies are found.



60
61
62
63
64
 
# File 'lib/rake/task.rb', line 60

def all_prerequisite_tasks
  seen = {}
  collect_prerequisites(seen)
  seen.values
end

#arg_description ⇒ Object

Argument description (nil if none).



117
118
119
 
# File 'lib/rake/task.rb', line 117

def arg_description # :nodoc:
  @arg_names ? "[#{arg_names.join(',')}]" : nil
end

#arg_names ⇒ Object

Name of arguments for this task.



122
123
124
 
# File 'lib/rake/task.rb', line 122

def arg_names
  @arg_names || []
end

#clear ⇒ Object

Clear the existing prerequisites and actions of a rake task.



133
134
135
136
137
138
 
# File 'lib/rake/task.rb', line 133

def clear
  clear_prerequisites
  clear_actions
  clear_comments
  self
end

#clear_actions ⇒ Object

Clear the existing actions on a rake task.



147
148
149
150
 
# File 'lib/rake/task.rb', line 147

def clear_actions
  actions.clear
  self
end

#clear_comments ⇒ Object

Clear the existing comments on a rake task.



153
154
155
156
 
# File 'lib/rake/task.rb', line 153

def clear_comments
  @comments = []
  self
end

#clear_prerequisites ⇒ Object

Clear the existing prerequisites of a rake task.



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

def clear_prerequisites
  prerequisites.clear
  self
end

#comment ⇒ Object

First line (or sentence) of all comments. Multiple comments are separated by a “/”.



277
278
279
 
# File 'lib/rake/task.rb', line 277

def comment
  transform_comments(" / ") { |c| first_sentence(c) }
end

#comment=(comment) ⇒ Object 



260
261
262
 
# File 'lib/rake/task.rb', line 260

def comment=(comment)
  add_comment(comment)
end

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

Enhance a task with prerequisites or actions. Returns self.



96
97
98
99
100
 
# File 'lib/rake/task.rb', line 96

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

#execute(args = nil) ⇒ Object

Execute the actions associated with this task.



223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
 
# File 'lib/rake/task.rb', line 223

def execute(args=nil)
  args ||= EMPTY_TASK_ARGS
  if application.options.dryrun
    application.trace "** Execute (dry run) #{name}"
    return
  end
  application.trace "** Execute #{name}" if application.options.trace
  application.enhance_with_matching_rule(name) if @actions.empty?
  @actions.each do |act|
    case act.arity
    when 1
      act.call(self)
    else
      act.call(self, args)
    end
  end
end

#full_comment ⇒ Object

Full collection of comments. Multiple comments are separated by newlines.



271
272
273
 
# File 'lib/rake/task.rb', line 271

def full_comment
  transform_comments("\n")
end

#inspect ⇒ Object 



37
38
39
 
# File 'lib/rake/task.rb', line 37

def inspect
  "<#{self.class} #{name} => [#{prerequisites.join(', ')}]>"
end

#investigation ⇒ Object

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



309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
 
# File 'lib/rake/task.rb', line 309

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 = prerequisite_tasks
  prereqs.sort! { |a, b| a.timestamp <=> b.timestamp }
  prereqs.each do |p|
    result << "--#{p.name} (#{p.timestamp})\n"
  end
  latest_prereq = prerequisite_tasks.map { |pre| pre.timestamp }.max
  result <<  "latest-prerequisite time: #{latest_prereq}\n"
  result << "................................\n\n"
  return result
end

#invoke(*args) ⇒ Object

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



159
160
161
162
 
# File 'lib/rake/task.rb', line 159

def invoke(*args)
  task_args = TaskArguments.new(arg_names, args)
  invoke_with_call_chain(task_args, InvocationChain::EMPTY)
end

#invoke_prerequisites(task_args, invocation_chain) ⇒ Object

Invoke all the prerequisites of a task.



191
192
193
194
195
196
197
198
199
200
 
# File 'lib/rake/task.rb', line 191

def invoke_prerequisites(task_args, invocation_chain) # :nodoc:
  if application.options.always_multitask
    invoke_prerequisites_concurrently(task_args, invocation_chain)
  else
    prerequisite_tasks.each { |p|
      prereq_args = task_args.new_scope(p.arg_names)
      p.invoke_with_call_chain(prereq_args, invocation_chain)
    }
  end
end

#invoke_prerequisites_concurrently(task_args, invocation_chain) ⇒ Object

Invoke all the prerequisites of a task in parallel.



203
204
205
206
207
208
209
210
211
 
# File 'lib/rake/task.rb', line 203

def invoke_prerequisites_concurrently(task_args, invocation_chain)# :nodoc:
  futures = prerequisite_tasks.map do |p|
    prereq_args = task_args.new_scope(p.arg_names)
    application.thread_pool.future(p) do |r|
      r.invoke_with_call_chain(prereq_args, invocation_chain)
    end
  end
  futures.each { |f| f.value }
end

#name ⇒ Object

Name of the task, including any namespace qualifiers.



103
104
105
 
# File 'lib/rake/task.rb', line 103

def name
  @name.to_s
end

#name_with_args ⇒ Object

Name of task with argument list description.



108
109
110
111
112
113
114
 
# File 'lib/rake/task.rb', line 108

def name_with_args # :nodoc:
  if arg_description
    "#{name}#{arg_description}"
  else
    name
  end
end

#needed? ⇒ Boolean

Is this task needed?

Returns:

  • (Boolean) 


242
243
244
 
# File 'lib/rake/task.rb', line 242

def needed?
  true
end

#prerequisite_tasks ⇒ Object

List of prerequisite tasks



48
49
50
 
# File 'lib/rake/task.rb', line 48

def prerequisite_tasks
  prerequisites.map { |pre| lookup_prerequisite(pre) }
end

#reenable ⇒ Object

Reenable the task, allowing its tasks to be executed if the task is invoked again.



128
129
130
 
# File 'lib/rake/task.rb', line 128

def reenable
  @already_invoked = false
end

#set_arg_names(args) ⇒ Object

Set the names of the arguments for this task. args should be an array of symbols, one for each argument name.



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

def set_arg_names(args)
  @arg_names = args.map { |a| a.to_sym }
end

#source ⇒ Object

First source from a rule (nil if no sources)



76
77
78
 
# File 'lib/rake/task.rb', line 76

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.



248
249
250
 
# File 'lib/rake/task.rb', line 248

def timestamp
  Time.now
end

#to_s ⇒ Object

Return task name



33
34
35
 
# File 'lib/rake/task.rb', line 33

def to_s
  name
end