Class Rake::Task
In: lib/rake.rb
Parent: Object

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

Methods

Attributes

application  [RW]  Application owning this task.
comment  [R]  Comment for this task. Restricted to a single line of no more than 50 characters.
full_comment  [R]  Full text of the (possibly multi-line) comment.
prerequisites  [R]  List of prerequisites for a task.
scope  [R]  Array of nested namespaces names used for task lookup by this task.
sources  [W]  List of sources for task.

Public Class methods

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.rb, line 638
638:       def [](task_name)
639:         Rake.application[task_name]
640:       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.rb, line 625
625:       def clear
626:         Rake.application.clear
627:       end

Define a rule for synthesizing tasks.

[Source]

     # File lib/rake.rb, line 655
655:       def create_rule(*args, &block)
656:         Rake.application.create_rule(*args, &block)
657:       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.rb, line 650
650:       def define_task(*args, &block)
651:         Rake.application.define_task(self, *args, &block)
652:       end

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

[Source]

     # File lib/rake.rb, line 447
447:     def initialize(task_name, app)
448:       @name = task_name.to_s
449:       @prerequisites = FileList[]
450:       @actions = []
451:       @already_invoked = false
452:       @full_comment = nil
453:       @comment = nil
454:       @lock = Mutex.new
455:       @application = app
456:       @scope = app.current_scope
457:       @arg_names = nil
458:     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.rb, line 662
662:       def scope_name(scope, task_name)
663:         (scope + [task_name]).join(':')
664:       end

TRUE if the task name is already defined.

[Source]

     # File lib/rake.rb, line 643
643:       def task_defined?(task_name)
644:         Rake.application.lookup(task_name) != nil
645:       end

List of all defined tasks.

[Source]

     # File lib/rake.rb, line 630
630:       def tasks
631:         Rake.application.tasks
632:       end

Public Instance methods

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.rb, line 564
564:     def add_description(description)
565:       return if ! description
566:       comment = description.strip
567:       add_comment(comment) if comment && ! comment.empty?
568:     end

Name of arguments for this task.

[Source]

     # File lib/rake.rb, line 487
487:     def arg_names
488:       @arg_names || []
489:     end

Writing to the comment attribute is the same as adding a description.

[Source]

     # File lib/rake.rb, line 571
571:     def comment=(description)
572:       add_description(description)
573:     end

Enhance a task with prerequisites or actions. Returns self.

[Source]

     # File lib/rake.rb, line 461
461:     def enhance(deps=nil, &block)
462:       @prerequisites |= deps if deps
463:       @actions << block if block_given?
464:       self
465:     end

Execute the actions associated with this task.

[Source]

     # File lib/rake.rb, line 532
532:     def execute(args)
533:       if application.options.dryrun
534:         puts "** Execute (dry run) #{name}"
535:         return
536:       end
537:       if application.options.trace
538:         puts "** Execute #{name}"
539:       end
540:       application.enhance_with_matching_rule(name) if @actions.empty?
541:       @actions.each do |act|
542:         case act.arity
543:         when 1
544:           act.call(self)
545:         else
546:           act.call(self, args)
547:         end
548:       end
549:     end

[Source]

     # File lib/rake.rb, line 430
430:     def inspect
431:       "<#{self.class} #{name} => [#{prerequisites.join(', ')}]>"
432:     end

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

[Source]

     # File lib/rake.rb, line 600
600:     def investigation
601:       result = "------------------------------\n"
602:       result << "Investigating #{name}\n"
603:       result << "class: #{self.class}\n"
604:       result <<  "task needed: #{needed?}\n"
605:       result <<  "timestamp: #{timestamp}\n"
606:       result << "pre-requisites: \n"
607:       prereqs = @prerequisites.collect {|name| application[name]}
608:       prereqs.sort! {|a,b| a.timestamp <=> b.timestamp}
609:       prereqs.each do |p|
610:         result << "--#{p.name} (#{p.timestamp})\n"
611:       end
612:       latest_prereq = @prerequisites.collect{|n| application[n].timestamp}.max
613:       result <<  "latest-prerequisite time: #{latest_prereq}\n"
614:       result << "................................\n\n"
615:       return result
616:     end

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

[Source]

     # File lib/rake.rb, line 492
492:     def invoke(*args)
493:       task_args = TaskArguments.new(arg_names, args)
494:       invoke_with_call_chain(task_args, InvocationChain::EMPTY)
495:     end

Invoke all the prerequisites of a task.

[Source]

     # File lib/rake.rb, line 514
514:     def invoke_prerequisites(task_args, invocation_chain)
515:       @prerequisites.each { |n|
516:         prereq = application[n, @scope]
517:         prereq_args = task_args.new_scope(prereq.arg_names)
518:         prereq.invoke_with_call_chain(prereq_args, invocation_chain)
519:       }
520:     end

Name of the task, including any namespace qualifiers.

[Source]

     # File lib/rake.rb, line 468
468:     def name
469:       @name.to_s
470:     end

Is this task needed?

[Source]

     # File lib/rake.rb, line 552
552:     def needed?
553:       true
554:     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.rb, line 594
594:     def set_arg_names(args)
595:       @arg_names = args.map { |a| a.to_sym }
596:     end

First source from a rule (nil if no sources)

[Source]

     # File lib/rake.rb, line 441
441:     def source
442:       @sources.first if defined?(@sources)
443:     end

[Source]

     # File lib/rake.rb, line 436
436:     def sources
437:       @sources ||= []
438:     end

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

[Source]

     # File lib/rake.rb, line 558
558:     def timestamp
559:       @prerequisites.collect { |p| application[p].timestamp }.max || Time.now
560:     end

Return task name

[Source]

     # File lib/rake.rb, line 426
426:     def to_s
427:       name
428:     end

Protected Instance methods

Same as invoke, but explicitly pass a call chain to detect circular dependencies.

[Source]

     # File lib/rake.rb, line 499
499:     def invoke_with_call_chain(task_args, invocation_chain)
500:       new_chain = InvocationChain.append(self, invocation_chain)
501:       @lock.synchronize do
502:         if application.options.trace
503:           puts "** Invoke #{name} #{format_trace_flags}"
504:         end
505:         return if @already_invoked
506:         @already_invoked = true
507:         invoke_prerequisites(task_args, new_chain)
508:         execute(task_args) if needed?
509:       end
510:     end

[Validate]