Class: Rake::Task

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



492
493
494
495
496
497
498
499
500
501
502
503
 
# File 'lib/rake.rb', line 492

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

Instance Attribute Details

#actions ⇒ Object (readonly)

List of actions attached to a task.



455
456
457
 
# File 'lib/rake.rb', line 455

def actions
  @actions
end

#application ⇒ Object

Application owning this task.



458
459
460
 
# File 'lib/rake.rb', line 458

def application
  @application
end

#comment ⇒ Object

Comment for this task. Restricted to a single line of no more than 50 characters.



462
463
464
 
# File 'lib/rake.rb', line 462

def comment
  @comment
end

#full_comment ⇒ Object (readonly)

Full text of the (possibly multi-line) comment.



465
466
467
 
# File 'lib/rake.rb', line 465

def full_comment
  @full_comment
end

#prerequisites ⇒ Object (readonly)

List of prerequisites for a task.



452
453
454
 
# File 'lib/rake.rb', line 452

def prerequisites
  @prerequisites
end

#scope ⇒ Object (readonly)

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



468
469
470
 
# File 'lib/rake.rb', line 468

def scope
  @scope
end

#sources ⇒ Object 



481
482
483
 
# File 'lib/rake.rb', line 481

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.



709
710
711
 
# File 'lib/rake.rb', line 709

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



696
697
698
 
# File 'lib/rake.rb', line 696

def clear
  Rake.application.clear
end

.create_rule(*args, &block) ⇒ Object

Define a rule for synthesizing tasks.



726
727
728
 
# File 'lib/rake.rb', line 726

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.



721
722
723
 
# File 'lib/rake.rb', line 721

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.



733
734
735
 
# File 'lib/rake.rb', line 733

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

.task_defined?(task_name) ⇒ Boolean

TRUE if the task name is already defined.

Returns:

  • (Boolean) 


714
715
716
 
# File 'lib/rake.rb', line 714

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

.tasks ⇒ Object

List of all defined tasks.



701
702
703
 
# File 'lib/rake.rb', line 701

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.



635
636
637
638
639
 
# File 'lib/rake.rb', line 635

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

#arg_description ⇒ Object

Argument description (nil if none).



527
528
529
 
# File 'lib/rake.rb', line 527

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

#arg_names ⇒ Object

Name of arguments for this task.



532
533
534
 
# File 'lib/rake.rb', line 532

def arg_names
  @arg_names || []
end

#clear ⇒ Object

Clear the existing prerequisites and actions of a rake task.



543
544
545
546
547
 
# File 'lib/rake.rb', line 543

def clear
  clear_prerequisites
  clear_actions
  self
end

#clear_actions ⇒ Object

Clear the existing actions on a rake task.



556
557
558
559
 
# File 'lib/rake.rb', line 556

def clear_actions
  actions.clear
  self
end

#clear_prerequisites ⇒ Object

Clear the existing prerequisites of a rake task.



550
551
552
553
 
# File 'lib/rake.rb', line 550

def clear_prerequisites
  prerequisites.clear
  self
end

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

Enhance a task with prerequisites or actions. Returns self.



506
507
508
509
510
 
# File 'lib/rake.rb', line 506

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.



602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
 
# File 'lib/rake.rb', line 602

def execute(args=nil)
  args ||= EMPTY_TASK_ARGS
  if application.options.dryrun
    puts "** Execute (dry run) #{name}"
    return
  end
  if application.options.trace
    puts "** Execute #{name}"
  end
  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

#inspect ⇒ Object 



475
476
477
 
# File 'lib/rake.rb', line 475

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

#investigation ⇒ Object

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



671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
 
# File 'lib/rake.rb', line 671

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 = @prerequisites.collect {|name| application[name]}
  prereqs.sort! {|a,b| a.timestamp <=> b.timestamp}
  prereqs.each do |p|
    result << "--#{p.name} (#{p.timestamp})\n"
  end
  latest_prereq = @prerequisites.collect{|n| application[n].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. Prerequites are invoked first.



562
563
564
565
 
# File 'lib/rake.rb', line 562

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.



584
585
586
587
588
589
590
 
# File 'lib/rake.rb', line 584

def invoke_prerequisites(task_args, invocation_chain) # :nodoc:
  @prerequisites.each { |n|
    prereq = application[n, @scope]
    prereq_args = task_args.new_scope(prereq.arg_names)
    prereq.invoke_with_call_chain(prereq_args, invocation_chain)
  }
end

#name ⇒ Object

Name of the task, including any namespace qualifiers.



513
514
515
 
# File 'lib/rake.rb', line 513

def name
  @name.to_s
end

#name_with_args ⇒ Object

Name of task with argument list description.



518
519
520
521
522
523
524
 
# File 'lib/rake.rb', line 518

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

#needed? ⇒ Boolean

Is this task needed?

Returns:

  • (Boolean) 


623
624
625
 
# File 'lib/rake.rb', line 623

def needed?
  true
end

#reenable ⇒ Object

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



538
539
540
 
# File 'lib/rake.rb', line 538

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.



665
666
667
 
# File 'lib/rake.rb', line 665

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)



486
487
488
 
# File 'lib/rake.rb', line 486

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.



629
630
631
 
# File 'lib/rake.rb', line 629

def timestamp
  @prerequisites.collect { |p| application[p].timestamp }.max || Time.now
end

#to_s ⇒ Object

Return task name



471
472
473
 
# File 'lib/rake.rb', line 471

def to_s
  name
end