123456789_123456789_123456789_123456789_123456789_

Class: Rake::Task

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Subclasses:
FileCreationTask, FileTask, MultiTask
Inherits: Object
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.

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new(task_name, app) ⇒ Task

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

[ GitHub ] 

  


# File 'lib/rake/task.rb', line 99



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


  







Class Method Details



  

    .[](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.


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 404



def [](task_name)
  Rake.application[task_name]
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.)


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 391



def clear
  Rake.application.clear
end


  








  

    .create_rule(*args, &block)  
  



  

    

Define a rule for synthesizing tasks.


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 421



def create_rule(*args, &block)
  Rake.application.create_rule(*args, &block)
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.


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 416



def define_task(*args, &block)
  Rake.application.define_task(self, *args, &block)
end


  








  

    .format_deps(deps)  
  



  

    

Format dependencies parameter to pass to task.


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 373



def self.format_deps(deps)
  deps = [deps] unless deps.respond_to?(:to_ary)
  deps.map { |d| Rake.from_pathname(d).to_s }
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.


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 428



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.


  





  


  [ GitHub ]


  

  


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



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


  








  

    .tasks  
  



  

    

List of all defined tasks.


  



  [ GitHub ]


  

  


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



def tasks
  Rake.application.tasks
end


  







Instance Attribute Details



  

    #actions   (readonly)
  



  

    

List of actions attached to a task.


  



  [ GitHub ]


  

  


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



attr_reader :actions


  








  

    #already_invoked   (readonly)
  



  

    

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


  



  [ GitHub ]


  

  


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



attr_reader :already_invoked


  








  

    #application   (rw)
  



  

    

Application owning this task.


  



  [ GitHub ]


  

  


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



attr_accessor :application


  








  

    #comment   (rw)
  



  

    

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


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 322



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


  








  

    #comment=(comment)   (rw)
  

  

    This method is for internal use only.
  

  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 304



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


  








  

    #locations   (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).


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 35



attr_reader :locations


  








  

    #needed?  ⇒ Boolean  (readonly)
  



  

    

Is this task needed?


  





  


  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 286



def needed?
  true
end


  








  

    #order_only_prerequisites   (readonly)
  



  

    

List of order only prerequisites for a task.


  



  [ GitHub ]


  

  


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



attr_reader :order_only_prerequisites


  








  

    #prereqs   (readonly)
  



  

    

Alias for #prerequisites.


  



  [ GitHub ]


  

  


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



alias prereqs prerequisites


  








  

    #prerequisites   (readonly)
    Also known as: #prereqs
  



  

    

List of prerequisites for a task.


  



  [ GitHub ]


  

  


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



attr_reader :prerequisites


  








  

    #scope   (readonly)
  



  

    

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


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 30



attr_reader :scope


  








  

    #sources   (rw)
  

  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 52



def sources
  if defined?(@sources)
    @sources
  else
    prerequisites
  end
end


  








  

    #sources=(value)   (rw)
  



  

    

List of sources for task.


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 51



attr_writer :sources


  







Instance Method Details



  

    #add_chain_to(exception, new_chain)   (private)
  

  

    This method is for internal use only.
  

  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 229



def add_chain_to(exception, new_chain) # :nodoc:
  exception.extend(InvocationExceptionMixin) unless
    exception.respond_to?(:chain)
  exception.chain = new_chain if exception.chain.nil?
end


  








  

    #add_comment(comment)   (private)
  

  

    This method is for internal use only.
  

  [ GitHub ]


  

  


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



def add_comment(comment) # :nodoc:
  return if comment.nil?
  @comments << comment unless @comments.include?(comment)
end


  








  

    #add_description(description)  
  



  

    

Add a description to the task.  The description can consist of an option argument list (enclosed brackets) and an optional comment.


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 298



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


  








  

    #all_prerequisite_tasks  
  



  

    

List of all unique prerequisite tasks including prerequisite tasks’ prerequisites. Includes self when cyclic dependencies are found.


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 77



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


  








  

    #arg_description  
  

  

    This method is for internal use only.
  



  

    

Argument description (nil if none).


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 136



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


  








  

    #arg_names  
  



  

    

Name of arguments for this task.


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 141



def arg_names
  @arg_names || []
end


  








  

    #clear  
  



  

    

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


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 153



def clear
  clear_prerequisites
  clear_actions
  clear_comments
  clear_args
  self
end


  








  

    #clear_actions  
  



  

    

Clear the existing actions on a rake task.


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 168



def clear_actions
  actions.clear
  self
end


  








  

    #clear_args  
  



  

    

Clear the existing arguments on a rake task.


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 180



def clear_args
  @arg_names = nil
  self
end


  








  

    #clear_comments  
  



  

    

Clear the existing comments on a rake task.


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 174



def clear_comments
  @comments = []
  self
end


  








  

    #clear_prerequisites  
  



  

    

Clear the existing prerequisites of a rake task.


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 162



def clear_prerequisites
  prerequisites.clear
  self
end


  








  

    #collect_prerequisites(seen)   (protected)
  

  

    This method is for internal use only.
  

  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 83



def collect_prerequisites(seen) # :nodoc:
  prerequisite_tasks.each do |pre|
    next if seen[pre.name]
    seen[pre.name] = pre
    pre.collect_prerequisites(seen)
  end
end


  








  

    #enhance(deps = nil, &block)  
  



  

    

Enhance a task with prerequisites or actions.  Returns self.


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 115



def enhance(deps=nil, &block)
  @prerequisites |= deps if deps
  @actions << block if block_given?
  self
end


  








  

    #execute(args = nil)  
  



  

    

Execute the actions associated with this task.


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 270



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?
  if opts = Hash.try_convert(args) and !opts.empty?
    @actions.each { |act| act.call(self, args, **opts)}
  else
    @actions.each { |act| act.call(self, args)}
  end
end


  








  

    #first_sentence(string)   (private)
  



  

    

Get the first sentence in a string. The sentence is terminated by the first period, exclamation mark, or the end of the line. Decimal points do not count as periods.


  



  [ GitHub ]


  

  


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



def first_sentence(string)
  string.split(/(?<=\w)(\.|!)[ \t]|(\.$|!)|\n/).first
end


  








  

    #format_trace_flags   (private)
  



  

    

Format the trace flags for display.


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 261



def format_trace_flags
  flags = []
  flags << "first_time" unless @already_invoked
  flags << "not_needed" unless needed?
  flags.empty? ? "" : "(" + flags.join(", ") + ")"
end


  








  

    #full_comment  
  



  

    

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


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 316



def full_comment
  transform_comments("\n")
end


  








  

    #inspect  
  

  

    This method is for internal use only.
  

  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 46



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


  








  

    #investigation  
  



  

    

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


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 354



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)  
  



  

    

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


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 186



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)  
  

  

    This method is for internal use only.
  



  

    

Invoke all the prerequisites of a task.


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 237



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)  
  

  

    This method is for internal use only.
  



  

    

Invoke all the prerequisites of a task in parallel.


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 249



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


  








  

    #invoke_with_call_chain(task_args, invocation_chain)   (protected)
  



  

    

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



If multiple tasks depend on this one in parallel, they will all fail if the first execution of this task fails.


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 197



def invoke_with_call_chain(task_args, invocation_chain)
  new_chain = Rake::InvocationChain.append(self, invocation_chain)
  @lock.synchronize do
    begin
      if application.options.trace
        application.trace "** Invoke #{name} #{format_trace_flags}"
      end

      if @already_invoked
        if @invocation_exception
          if application.options.trace
            application.trace "** Previous invocation of #{name} failed #{format_trace_flags}"
          end
          raise @invocation_exception
        else
          return
        end
      end

      @already_invoked = true

      invoke_prerequisites(task_args, new_chain)
      execute(task_args) if needed?
    rescue Exception => ex
      add_chain_to(ex, new_chain)
      @invocation_exception = ex
      raise ex
    end
  end
end


  








  

    #lookup_prerequisite(prerequisite_name)   (private)
  

  

    This method is for internal use only.
  

  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 65



def lookup_prerequisite(prerequisite_name) # :nodoc:
  scoped_prerequisite_task = application[prerequisite_name, @scope]
  if scoped_prerequisite_task == self
    unscoped_prerequisite_task = application[prerequisite_name]
  end
  unscoped_prerequisite_task || scoped_prerequisite_task
end


  








  

    #name  
  



  

    

Name of the task, including any namespace qualifiers.


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 122



def name
  @name.to_s
end


  








  

    #name_with_args  
  

  

    This method is for internal use only.
  



  

    

Name of task with argument list description.


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 127



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


  








  

    #prerequisite_tasks  
  



  

    

List of prerequisite tasks


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 61



def prerequisite_tasks
  (prerequisites + order_only_prerequisites).map { |pre| lookup_prerequisite(pre) }
end


  








  

    #reenable  
  



  

    

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


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 147



def reenable
  @already_invoked = false
  @invocation_exception = nil
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.


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 348



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


  








  

    #source  
  



  

    

First source from a rule (nil if no sources)


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 93



def source
  sources.first
end


  








  

    #timestamp  
  



  

    

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


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 292



def timestamp
  Time.now
end


  








  

    #to_s  
  



  

    

Return task name


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 42



def to_s
  name
end


  








  

    #transform_comments(separator, &block)   (private)
  



  

    

Transform the list of comments as specified by the block and join with the separator.


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 328



def transform_comments(separator, &block)
  if @comments.empty?
    nil
  else
    block ||= lambda { |c| c }
    @comments.map(&block).join(separator)
  end
end


  








  

    #|(deps)  
  



  

    

Add order only dependencies.


  



  [ GitHub ]


  

  


# File 'lib/rake/task.rb', line 379



def |(deps)
  @order_only_prerequisites |= Task.format_deps(deps) - @prerequisites
  self
end