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.

Direct Known Subclasses

FileTask, MultiTask

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.



96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/rake/task.rb', line 96

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       = []
  @invocation_exception = nil
end

Instance Attribute Details

#actions ⇒ Object (readonly)

List of actions attached to a task.



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

def actions
  @actions
end

#already_invoked ⇒ Object (readonly)

Has this task already been invoked? Already invoked tasks will be skipped unless you reenable them.



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

def already_invoked
  @already_invoked
end

#application ⇒ Object

Application owning this task.



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

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



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

def locations
  @locations
end

#prerequisites ⇒ Object (readonly) Also known as: prereqs

List of prerequisites for a task.



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

def prerequisites
  @prerequisites
end

#scope ⇒ Object (readonly)

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



27
28
29
 
# File 'lib/rake/task.rb', line 27

def scope
  @scope
end

#sources ⇒ Object 



49
50
51
52
53
54
55
 
# File 'lib/rake/task.rb', line 49

def sources
  if defined?(@sources)
    @sources
  else
    prerequisites
  end
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.



383
384
385
 
# File 'lib/rake/task.rb', line 383

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



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

def clear
  Rake.application.clear
end

.create_rule(*args, &block) ⇒ Object

Define a rule for synthesizing tasks.



400
401
402
 
# File 'lib/rake/task.rb', line 400

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.



395
396
397
 
# File 'lib/rake/task.rb', line 395

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.



407
408
409
 
# File 'lib/rake/task.rb', line 407

def scope_name(scope, task_name)
  scope.path_with_task_name(task_name)
end

.task_defined?(task_name) ⇒ Boolean

TRUE if the task name is already defined.

Returns:

  • (Boolean) 


388
389
390
 
# File 'lib/rake/task.rb', line 388

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

.tasks ⇒ Object

List of all defined tasks.



375
376
377
 
# File 'lib/rake/task.rb', line 375

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.



289
290
291
292
293
 
# File 'lib/rake/task.rb', line 289

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.



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

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

#arg_description ⇒ Object

Argument description (nil if none).



132
133
134
 
# File 'lib/rake/task.rb', line 132

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

#arg_names ⇒ Object

Name of arguments for this task.



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

def arg_names
  @arg_names || []
end

#clear ⇒ Object

Clear the existing prerequisites, actions, comments, and arguments of a rake task.



148
149
150
151
152
153
154
 
# File 'lib/rake/task.rb', line 148

def clear
  clear_prerequisites
  clear_actions
  clear_comments
  clear_args
  self
end

#clear_actions ⇒ Object

Clear the existing actions on a rake task.



163
164
165
166
 
# File 'lib/rake/task.rb', line 163

def clear_actions
  actions.clear
  self
end

#clear_args ⇒ Object

Clear the existing arguments on a rake task.



175
176
177
178
 
# File 'lib/rake/task.rb', line 175

def clear_args
  @arg_names = nil
  self
end

#clear_comments ⇒ Object

Clear the existing comments on a rake task.



169
170
171
172
 
# File 'lib/rake/task.rb', line 169

def clear_comments
  @comments = []
  self
end

#clear_prerequisites ⇒ Object

Clear the existing prerequisites of a rake task.



157
158
159
160
 
# File 'lib/rake/task.rb', line 157

def clear_prerequisites
  prerequisites.clear
  self
end

#comment ⇒ Object

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



313
314
315
 
# File 'lib/rake/task.rb', line 313

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

#comment=(comment) ⇒ Object

:nodoc:



295
296
297
 
# File 'lib/rake/task.rb', line 295

def comment=(comment) # :nodoc:
  add_comment(comment)
end

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

Enhance a task with prerequisites or actions. Returns self.



111
112
113
114
115
 
# File 'lib/rake/task.rb', line 111

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.



265
266
267
268
269
270
271
272
273
274
 
# File 'lib/rake/task.rb', line 265

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 { |act| act.call(self, args) }
end

#full_comment ⇒ Object

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



307
308
309
 
# File 'lib/rake/task.rb', line 307

def full_comment
  transform_comments("\n")
end

#inspect ⇒ Object

:nodoc:



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

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

#investigation ⇒ Object

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



345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
 
# File 'lib/rake/task.rb', line 345

def investigation
  result = "------------------------------\n".dup
  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(&: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.



181
182
183
184
 
# File 'lib/rake/task.rb', line 181

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.



232
233
234
235
236
237
238
239
240
241
 
# File 'lib/rake/task.rb', line 232

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.



244
245
246
247
248
249
250
251
252
253
 
# File 'lib/rake/task.rb', line 244

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
  # Iterate in reverse to improve performance related to thread waiting and switching
  futures.reverse_each(&:value)
end

#name ⇒ Object

Name of the task, including any namespace qualifiers.



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

def name
  @name.to_s
end

#name_with_args ⇒ Object

Name of task with argument list description.



123
124
125
126
127
128
129
 
# File 'lib/rake/task.rb', line 123

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

#needed? ⇒ Boolean

Is this task needed?

Returns:

  • (Boolean) 


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

def needed?
  true
end

#prerequisite_tasks ⇒ Object

List of prerequisite tasks



58
59
60
 
# File 'lib/rake/task.rb', line 58

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.



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

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.



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

def set_arg_names(args)
  @arg_names = args.map(&:to_sym)
end

#source ⇒ Object

First source from a rule (nil if no sources)



90
91
92
 
# File 'lib/rake/task.rb', line 90

def source
  sources.first
end

#timestamp ⇒ Object

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



283
284
285
 
# File 'lib/rake/task.rb', line 283

def timestamp
  Time.now
end

#to_s ⇒ Object

Return task name



39
40
41
 
# File 'lib/rake/task.rb', line 39

def to_s
  name
end