class Rake::Task
######################################################################### 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.
Attributes
List of actions attached to a task.
Application
owning this task.
Comment for this task. Restricted to a single line of no more than 50 characters.
Full text of the (possibly multi-line) comment.
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).
List of prerequisites for a task.
Array of nested namespaces names used for task lookup by this task.
List of sources for task.
Public Class Methods
Source
# File lib/rake/task.rb 321 def [](task_name) 322 Rake.application[task_name] 323 end
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.
Source
# File lib/rake/task.rb 308 def clear 309 Rake.application.clear 310 end
Clear the task list. This cause rake to immediately forget all the tasks that have been assigned. (Normally used in the unit tests.)
Source
# File lib/rake/task.rb 338 def create_rule(*args, &block) 339 Rake.application.create_rule(*args, &block) 340 end
Define a rule for synthesizing tasks.
Source
# File lib/rake/task.rb 333 def define_task(*args, &block) 334 Rake.application.define_task(self, *args, &block) 335 end
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.
Source
# File lib/rake/task.rb 71 def initialize(task_name, app) 72 @name = task_name.to_s 73 @prerequisites = [] 74 @actions = [] 75 @already_invoked = false 76 @full_comment = nil 77 @comment = nil 78 @lock = Monitor.new 79 @application = app 80 @scope = app.current_scope 81 @arg_names = nil 82 @locations = [] 83 end
Create a task named task_name
with no actions or prerequisites. Use enhance
to add actions and prerequisites.
Source
# File lib/rake/task.rb 345 def scope_name(scope, task_name) 346 (scope + [task_name]).join(':') 347 end
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.
Source
# File lib/rake/task.rb 326 def task_defined?(task_name) 327 Rake.application.lookup(task_name) != nil 328 end
TRUE if the task name is already defined.
Source
# File lib/rake/task.rb 313 def tasks 314 Rake.application.tasks 315 end
List of all defined tasks.
Public Instance Methods
Source
# File lib/rake/task.rb 247 def add_description(description) 248 return if ! description 249 comment = description.strip 250 add_comment(comment) if comment && ! comment.empty? 251 end
Add a description to the task. The description can consist of an option argument list (enclosed brackets) and an optional comment.
Source
# File lib/rake/task.rb 112 def arg_names 113 @arg_names || [] 114 end
Name of arguments for this task.
Source
# File lib/rake/task.rb 123 def clear 124 clear_prerequisites 125 clear_actions 126 self 127 end
Clear the existing prerequisites and actions of a rake task.
Source
# File lib/rake/task.rb 136 def clear_actions 137 actions.clear 138 self 139 end
Clear the existing actions on a rake task.
Source
# File lib/rake/task.rb 130 def clear_prerequisites 131 prerequisites.clear 132 self 133 end
Clear the existing prerequisites of a rake task.
Source
# File lib/rake/task.rb 254 def comment=(description) 255 add_description(description) 256 end
Writing to the comment attribute is the same as adding a description.
Source
# File lib/rake/task.rb 86 def enhance(deps=nil, &block) 87 @prerequisites |= deps if deps 88 @actions << block if block_given? 89 self 90 end
Enhance a task with prerequisites or actions. Returns self.
Source
# File lib/rake/task.rb 214 def execute(args=nil) 215 args ||= EMPTY_TASK_ARGS 216 if application.options.dryrun 217 $stderr.puts "** Execute (dry run) #{name}" 218 return 219 end 220 if application.options.trace 221 $stderr.puts "** Execute #{name}" 222 end 223 application.enhance_with_matching_rule(name) if @actions.empty? 224 @actions.each do |act| 225 case act.arity 226 when 1 227 act.call(self) 228 else 229 act.call(self, args) 230 end 231 end 232 end
Execute the actions associated with this task.
Source
# File lib/rake/task.rb 44 def inspect 45 "<#{self.class} #{name} => [#{prerequisites.join(', ')}]>" 46 end
Source
# File lib/rake/task.rb 283 def investigation 284 result = "------------------------------\n" 285 result << "Investigating #{name}\n" 286 result << "class: #{self.class}\n" 287 result << "task needed: #{needed?}\n" 288 result << "timestamp: #{timestamp}\n" 289 result << "pre-requisites: \n" 290 prereqs = prerequisite_tasks 291 prereqs.sort! {|a,b| a.timestamp <=> b.timestamp} 292 prereqs.each do |p| 293 result << "--#{p.name} (#{p.timestamp})\n" 294 end 295 latest_prereq = prerequisite_tasks.collect { |pre| pre.timestamp }.max 296 result << "latest-prerequisite time: #{latest_prereq}\n" 297 result << "................................\n\n" 298 return result 299 end
Return a string describing the internal state of a task. Useful for debugging.
Source
# File lib/rake/task.rb 142 def invoke(*args) 143 if application.options.threads == 1 144 invoke_serial(*args) 145 else 146 invoke_parallel(*args) 147 end 148 end
Invoke the task if it is needed. Prerequisites are invoked first.
Source
# File lib/rake/task.rb 93 def name 94 @name.to_s 95 end
Name of the task, including any namespace qualifiers.
Source
# File lib/rake/task.rb 55 def prerequisite_tasks 56 prerequisites.collect { |pre| lookup_prerequisite(pre) } 57 end
List of prerequisite tasks
Source
# File lib/rake/task.rb 118 def reenable 119 @already_invoked = false 120 end
Reenable the task, allowing its tasks to be executed if the task is invoked again.
Source
# File lib/rake/task.rb 277 def set_arg_names(args) 278 @arg_names = args.map { |a| a.to_sym } 279 end
Set the names of the arguments for this task. args
should be an array of symbols, one for each argument name.
Source
# File lib/rake/task.rb 65 def source 66 @sources.first if defined?(@sources) 67 end
First source from a rule (nil if no sources)
Source
# File lib/rake/task.rb 241 def timestamp 242 prerequisite_tasks.collect { |pre| pre.timestamp }.max || Time.now 243 end
Timestamp for this task. Basic tasks return the current time for their time stamp. Other tasks can be more sophisticated.
Private Instance Methods
Source
# File lib/rake/task.rb 188 def add_chain_to(exception, new_chain) 189 exception.extend(InvocationExceptionMixin) unless exception.respond_to?(:chain) 190 exception.chain = new_chain if exception.chain.nil? 191 end
Source
# File lib/rake/task.rb 260 def add_comment(comment) 261 if @full_comment 262 @full_comment << " / " 263 else 264 @full_comment = '' 265 end 266 @full_comment << comment 267 if @full_comment =~ /\A([^.]+?\.)( |$)/ 268 @comment = $1 269 else 270 @comment = @full_comment 271 end 272 end
Add a comment to the task. If a comment already exists, separate the new comment with “ / ”.
Source
# File lib/rake/task.rb 205 def format_trace_flags 206 flags = [] 207 flags << "first_time" unless @already_invoked 208 flags << "not_needed" unless needed? 209 flags.empty? ? "" : "(" + flags.join(", ") + ")" 210 end
Format the trace flags for display.
Source
# File lib/rake/task.rb 59 def lookup_prerequisite(prerequisite_name) 60 application[prerequisite_name, @scope] 61 end