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

[] add_description arg_names clear comment= create_rule define_task enhance execute inspect investigation invoke invoke_prerequisites invoke_with_call_chain name needed? new scope_name set_arg_names source sources task_defined? tasks timestamp to_s

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

[](task_name)

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

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

create_rule(*args, &block)

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_task(*args, &block)

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

new(task_name, app)

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

scope_name(scope, task_name)

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

task_defined?(task_name)

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

tasks()

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_description(description)

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

arg_names()

Name of arguments for this task.

[Source]

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

comment=(description)

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(deps=nil, &block)

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(args)

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

inspect()

[Source]

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

investigation()

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(*args)

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_prerequisites(task_args, invocation_chain)

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

Name of the task, including any namespace qualifiers.

[Source]

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

needed?()

Is this task needed?

[Source]

         # File lib/rake.rb, line 552
    552:     def needed?
    553:       true
    554:     end

set_arg_names(args)

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

source()

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

sources()

[Source]

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

timestamp()

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

to_s()

Return task name

[Source]

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

### Protected Instance methods

invoke_with_call_chain(task_args, invocation_chain)

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]