Class: Rake::Application

### Home Classes Methods

### In Files

- lib/rake/application.rb

### Parent

Object

### Methods

- ::new
- #add_import
- #add_loader
- #collect_tasks
- #default_task_name
- #deprecate
- #display_error_message
- #display_prerequisites
- #display_tasks_and_comments
- #dynamic_width
- #dynamic_width_stty
- #dynamic_width_tput
- #exit_because_of_exception
- #find_rakefile_location
- #handle_options
- #have_rakefile
- #init
- #invoke_task
- #load_imports
- #load_rakefile
- #options
- #parse_task_string
- #print_rakefile_directory
- #rake_require
- #rakefile_location
- #run
- #run_with_threads
- #standard_exception_handling
- #standard_rake_options
- #system_dir
- #terminal_width
- #top_level
- #trace
- #truncate
- #truncate_output?
- #tty_output=
- #tty_output?
- #unix?
- #windows?

### Included Modules

- Rake::TaskManager
- Rake::TraceOutput

### Files

- MIT-LICENSE
- README.rdoc
- TODO
- command_line_usage.rdoc
- glossary.rdoc
- proto_rake.rdoc
- rakefile.rdoc
- rational.rdoc
- rake-0.4.14.rdoc
- rake-0.4.15.rdoc
- rake-0.5.0.rdoc
- rake-0.5.3.rdoc
- rake-0.5.4.rdoc
- rake-0.6.0.rdoc
- rake-0.7.0.rdoc
- rake-0.7.1.rdoc
- rake-0.7.2.rdoc
- rake-0.7.3.rdoc
- rake-0.8.0.rdoc
- rake-0.8.4.rdoc
- rake-0.8.5.rdoc
- rake-0.8.6.rdoc
- rake-0.8.7.rdoc

### Class/Module Index

Quicksearch

- Rake
- Rake::AltSystem
- Rake::Application
- Rake::Backtrace
- Rake::Cloneable
- Rake::CompositePublisher
- Rake::DSL
- Rake::DefaultLoader
- Rake::EarlyTime
- Rake::FileCreationTask
- Rake::FileList
- Rake::FileTask
- Rake::FileUtilsExt
- Rake::FtpFile
- Rake::FtpUploader
- Rake::InvocationChain
- Rake::InvocationChain::EmptyInvocationChain
- Rake::InvocationExceptionMixin
- Rake::MakefileLoader
- Rake::MultiTask
- Rake::NameSpace
- Rake::PackageTask
- Rake::PseudoStatus
- Rake::RubyForgePublisher
- Rake::RuleRecursionOverflowError
- Rake::SshDirPublisher
- Rake::SshFilePublisher
- Rake::SshFreshDirPublisher
- Rake::Task
- Rake::TaskArgumentError
- Rake::TaskArguments
- Rake::TaskLib
- Rake::TaskManager
- Rake::TestTask
- Rake::TraceOutput
- Rake::Win32
- Rake::Win32::Win32HomeError
- CompositePublisher
- FileUtils
- Module
- Object
- SshDirPublisher
- SshFilePublisher
- SshFreshDirPublisher
- String
- Time

No matching classes.

# Rake::Application

Rake main application object. When invoking `rake` from the command line, a Rake::Application object is created and run.

### Constants

DEFAULT_RAKEFILES

### Attributes

name[R]

The name of the application (typically 'rake')

original_dir[R]

The original directory where rake was invoked.

rakefile[R]

Name of the actual rakefile used.

terminal_columns[RW]

Number of columns on the terminal

top_level_tasks[R]

List of the top level task names (task names from the command line).

### Public Class Methods

new() click to toggle source

Initialize a Rake::Application object.

    # File lib/rake/application.rb, line 41
    def initialize
      super
      @name = 'rake'
      @rakefiles = DEFAULT_RAKEFILES.dup
      @rakefile = nil
      @pending_imports = []
      @imported = []
      @loaders = {}
      @default_loader = Rake::DefaultLoader.new
      @original_dir = Dir.pwd
      @top_level_tasks = []
      add_loader('rb', DefaultLoader.new)
      add_loader('rf', DefaultLoader.new)
      add_loader('rake', DefaultLoader.new)
      @tty_output = STDOUT.tty?
      @terminal_columns = ENV['RAKE_COLUMNS'].to_i
    end

### Public Instance Methods

add_import(fn) click to toggle source

Add a file to the list of files to be imported.

    # File lib/rake/application.rb, line 650
    def add_import(fn)
      @pending_imports << fn
    end

add_loader(ext, loader) click to toggle source

Add a loader to handle imported files ending in the extension `ext`.

    # File lib/rake/application.rb, line 123
    def add_loader(ext, loader)
      ext = ".#{ext}" unless ext =~ /^\./
      @loaders[ext] = loader
    end

collect_tasks() click to toggle source

Collect the list of tasks on the command line. If no tasks are given, return a list containing only the default task. Environmental assignments are processed at this time as well.

    # File lib/rake/application.rb, line 631
    def collect_tasks
      @top_level_tasks = []
      ARGV.each do |arg|
        if arg =~ /^(\w+)=(.*)$/
          ENV[$1] = $2
        else
          @top_level_tasks << arg unless arg =~ /^-/
        end
      end
      @top_level_tasks.push(default_task_name) if @top_level_tasks.empty?
    end

default_task_name() click to toggle source

Default task name ("default"). (May be overridden by subclasses)

    # File lib/rake/application.rb, line 645
    def default_task_name
      "default"
    end

deprecate(old_usage, new_usage, call_site) click to toggle source

Warn about deprecated usage.

Example:

    Rake.application.deprecate("import", "Rake.import", caller.first)

    # File lib/rake/application.rb, line 198
    def deprecate(old_usage, new_usage, call_site)
      unless options.ignore_deprecate
        $stderr.puts "WARNING: '#{old_usage}' is deprecated.  " +
          "Please use '#{new_usage}' instead.\n" +
          "    at #{call_site}"
      end
    end

display_error_message(ex) click to toggle source

Display the error message that caused the exception.

    # File lib/rake/application.rb, line 181
    def display_error_message(ex)
      trace "#{name} aborted!"
      trace ex.message
      if options.backtrace
        trace ex.backtrace.join("\n")
      else
        trace Backtrace.collapse(ex.backtrace).join("\n")
      end
      trace "Tasks: #{ex.chain}" if has_chain?(ex)
      trace "(See full trace by running task with --trace)" unless options.backtrace
    end

display_prerequisites() click to toggle source

Display the tasks and prerequisites

    # File lib/rake/application.rb, line 319
    def display_prerequisites
      tasks.each do |t|
        puts "#{name} #{t.name}"
        t.prerequisites.each { |pre| puts "    #{pre}" }
      end
    end

display_tasks_and_comments() click to toggle source

Display the tasks and comments.

    # File lib/rake/application.rb, line 243
    def display_tasks_and_comments
      displayable_tasks = tasks.select { |t|
        (options.show_all_tasks || t.comment) && t.name =~ options.show_task_pattern
      }
      case options.show_tasks
      when :tasks
        width = displayable_tasks.collect { |t| t.name_with_args.length }.max || 10
        max_column = truncate_output? ? terminal_width - name.size - width - 7 : nil

        displayable_tasks.each do |t|
          printf "#{name} %-#{width}s  # %s\n",
            t.name_with_args, max_column ? truncate(t.comment, max_column) : t.comment
        end
      when :describe
        displayable_tasks.each do |t|
          puts "#{name} #{t.name_with_args}"
          comment = t.full_comment || ""
          comment.split("\n").each do |line|
            puts "    #{line}"
          end
          puts
        end
      when :lines
        displayable_tasks.each do |t|
          t.locations.each do |loc|
            printf "#{name} %-30s %s\n",t.name_with_args, loc
          end
        end
      else
        fail "Unknown show task mode: '#{options.show_tasks}'"
      end
    end

dynamic_width() click to toggle source

Calculate the dynamic width of the

    # File lib/rake/application.rb, line 288
    def dynamic_width
      @dynamic_width ||= (dynamic_width_stty.nonzero? || dynamic_width_tput)
    end

dynamic_width_stty() click to toggle source

    # File lib/rake/application.rb, line 292
    def dynamic_width_stty
      %{stty size 2>/dev/null}.split[1].to_i
    end

dynamic_width_tput() click to toggle source

    # File lib/rake/application.rb, line 296
    def dynamic_width_tput
      %{tput cols 2>/dev/null}.to_i
    end

exit_because_of_exception(ex) click to toggle source

Exit the program because of an unhandle exception. (may be overridden by subclasses)

    # File lib/rake/application.rb, line 176
    def exit_because_of_exception(ex)
      exit(false)
    end

find_rakefile_location() click to toggle source

    # File lib/rake/application.rb, line 555
    def find_rakefile_location
      here = Dir.pwd
      while ! (fn = have_rakefile)
        Dir.chdir("..")
        if Dir.pwd == here || options.nosearch
          return nil
        end
        here = Dir.pwd
      end
      [fn, here]
    ensure
      Dir.chdir(Rake.original_dir)
    end

handle_options() click to toggle source

Read and handle the command line options.

    # File lib/rake/application.rb, line 520
    def handle_options
      options.rakelib = ['rakelib']
      options.trace_output = $stderr

      OptionParser.new do |opts|
        opts.banner = "rake [-f rakefile] {options} targets..."
        opts.separator ""
        opts.separator "Options are ..."

        opts.on_tail("-h", "--help", "-H", "Display this help message.") do
          puts opts
          exit
        end

        standard_rake_options.each { |args| opts.on(*args) }
        opts.environment('RAKEOPT')
      end.parse!
    end

have_rakefile() click to toggle source

True if one of the files in RAKEFILES is in the current directory. If a match is found, it is copied into @rakefile.

    # File lib/rake/application.rb, line 214
    def have_rakefile
      @rakefiles.each do |fn|
        if File.exist?(fn)
          others = FileList.glob(fn, File::FNM_CASEFOLD)
          return others.size == 1 ? others.first : fn
        elsif fn == ''
          return fn
        end
      end
      return nil
    end

init(app_name='rake') click to toggle source

Initialize the command line parameters and app name.

    # File lib/rake/application.rb, line 78
    def init(app_name='rake')
      standard_exception_handling do
        @name = app_name
        handle_options
        collect_tasks
      end
    end

invoke_task(task_string) click to toggle source

private ----------------------------------------------------------------

    # File lib/rake/application.rb, line 140
    def invoke_task(task_string)
      name, args = parse_task_string(task_string)
      t = self[name]
      t.invoke(*args)
    end

load_imports() click to toggle source

Load the pending list of imported files.

    # File lib/rake/application.rb, line 655
    def load_imports
      while fn = @pending_imports.shift
        next if @imported.member?(fn)
        if fn_task = lookup(fn)
          fn_task.invoke
        end
        ext = File.extname(fn)
        loader = @loaders[ext] || @default_loader
        loader.load(fn)
        @imported << fn
      end
    end

load_rakefile() click to toggle source

Find the rakefile and then load it and any pending imports.

    # File lib/rake/application.rb, line 87
    def load_rakefile
      standard_exception_handling do
        raw_load_rakefile
      end
    end

options() click to toggle source

Application options from the command line

    # File lib/rake/application.rb, line 129
    def options
      @options ||= OpenStruct.new
    end

parse_task_string(string) click to toggle source

    # File lib/rake/application.rb, line 146
    def parse_task_string(string)
      if string =~ /^([^\[]+)(\[(.*)\])$/
        name = $1
        args = $3.split(/\s*,\s*/)
      else
        name = string
        args = []
      end
      [name, args]
    end

print_rakefile_directory(location) click to toggle source

    # File lib/rake/application.rb, line 569
    def print_rakefile_directory(location)
      $stderr.puts "(in #{Dir.pwd})" unless
        options.silent or original_dir == location
    end

rake_require(file_name, paths=$LOAD_PATH, loaded=$") click to toggle source

Similar to the regular Ruby `require` command, but will check for *.rake files in addition to *.rb files.

    # File lib/rake/application.rb, line 541
    def rake_require(file_name, paths=$LOAD_PATH, loaded=$")
      fn = file_name + ".rake"
      return false if loaded.include?(fn)
      paths.each do |path|
        full_path = File.join(path, fn)
        if File.exist?(full_path)
          Rake.load_rakefile(full_path)
          loaded << fn
          return true
        end
      end
      fail LoadError, "Can't find #{file_name}"
    end

rakefile_location(backtrace=caller) click to toggle source

    # File lib/rake/application.rb, line 668
    def rakefile_location(backtrace=caller)
      backtrace.map { |t| t[/([^:]+):/,1] }

      re = /^#{@rakefile}$/
      re = /#{re.source}/ if windows?

      backtrace.find { |str| str =~ re } || ''
    end

run() click to toggle source

Run the Rake application. The run method performs the following three steps:

- Initialize the command line options (`init`).

- Define the tasks (`load_rakefile`).

- Run the top level tasks (`top_level`).

If you wish to build a custom rake command, you should call `init` on your application. Then define any tasks. Finally, call `top_level` to run your top level tasks.

    # File lib/rake/application.rb, line 69
    def run
      standard_exception_handling do
        init
        load_rakefile
        top_level
      end
    end

run_with_threads() click to toggle source

Run the given block with the thread startup and shutdown.

    # File lib/rake/application.rb, line 107
    def run_with_threads
      thread_pool.gather_history if options.job_stats == :history

      yield

      thread_pool.join
      if options.job_stats
        stats = thread_pool.statistics
        puts "Maximum active threads: #{stats[:max_active_threads]}"
        puts "Total threads in play:  #{stats[:total_threads_in_play]}"
      end
      ThreadHistoryDisplay.new(thread_pool.history).show if options.job_stats == :history
    end

standard_exception_handling() click to toggle source

Provide standard exception handling for the given block.

    # File lib/rake/application.rb, line 158
    def standard_exception_handling
      begin
        yield
      rescue SystemExit => ex
        # Exit silently with current status
        raise
      rescue OptionParser::InvalidOption => ex
        $stderr.puts ex.message
        exit(false)
      rescue Exception => ex
        # Exit with error message
        display_error_message(ex)
        exit_because_of_exception(ex)
      end
    end

standard_rake_options() click to toggle source

A list of all the standard options used in rake, suitable for passing to OptionParser.

    # File lib/rake/application.rb, line 340
    def standard_rake_options
      sort_options(
        [
          ['--all', '-A', "Show all tasks, even uncommented ones",
            lambda { |value|
              options.show_all_tasks = value
            }
          ],
          ['--backtrace=[OUT]', "Enable full backtrace.  OUT can be stderr (default) or stdout.",
            lambda { |value|
              options.backtrace = true
              select_trace_output(options, 'backtrace', value)
            }
          ],
          ['--comments', "Show commented tasks only",
            lambda { |value|
              options.show_all_tasks = !value
            }
          ],
          ['--describe', '-D [PATTERN]', "Describe the tasks (matching optional PATTERN), then exit.",
            lambda { |value|
              select_tasks_to_show(options, :describe, value)
            }
          ],
          ['--dry-run', '-n', "Do a dry run without executing actions.",
            lambda { |value|
              Rake.verbose(true)
              Rake.nowrite(true)
              options.dryrun = true
              options.trace = true
            }
          ],
          ['--execute',  '-e CODE', "Execute some Ruby code and exit.",
            lambda { |value|
              eval(value)
              exit
            }
          ],
          ['--execute-print',  '-p CODE', "Execute some Ruby code, print the result, then exit.",
            lambda { |value|
              puts eval(value)
              exit
            }
          ],
          ['--execute-continue',  '-E CODE',
            "Execute some Ruby code, then continue with normal task processing.",
            lambda { |value| eval(value) }
          ],
          ['--jobs',  '-j [NUMBER]',
            "Specifies the maximum number of tasks to execute in parallel. (default:2)",
            lambda { |value| options.thread_pool_size = [(value || 2).to_i,2].max }
          ],
          ['--job-stats [LEVEL]',
            "Display job statistics. LEVEL=history displays a complete job list",
            lambda { |value|
              if value =~ /^history/
                options.job_stats = :history
              else
                options.job_stats = true
              end
            }
          ],
          ['--libdir', '-I LIBDIR', "Include LIBDIR in the search path for required modules.",
            lambda { |value| $:.push(value) }
          ],
          ['--multitask', '-m', "Treat all tasks as multitasks.",
            lambda { |value| options.always_multitask = true }
          ],
          ['--no-search', '--nosearch', '-N', "Do not search parent directories for the Rakefile.",
            lambda { |value| options.nosearch = true }
          ],
          ['--prereqs', '-P', "Display the tasks and dependencies, then exit.",
            lambda { |value| options.show_prereqs = true }
          ],
          ['--quiet', '-q', "Do not log messages to standard output.",
            lambda { |value| Rake.verbose(false) }
          ],
          ['--rakefile', '-f [FILE]', "Use FILE as the rakefile.",
            lambda { |value|
              value ||= ''
              @rakefiles.clear
              @rakefiles << value
            }
          ],
          ['--rakelibdir', '--rakelib', '-R RAKELIBDIR',
            "Auto-import any .rake files in RAKELIBDIR. (default is 'rakelib')",
            lambda { |value| options.rakelib = value.split(File::PATH_SEPARATOR) }
          ],
          ['--require', '-r MODULE', "Require MODULE before executing rakefile.",
            lambda { |value|
              begin
                require value
              rescue LoadError => ex
                begin
                  rake_require value
                rescue LoadError
                  raise ex
                end
              end
            }
          ],
          ['--rules', "Trace the rules resolution.",
            lambda { |value| options.trace_rules = true }
          ],
          ['--silent', '-s', "Like --quiet, but also suppresses the 'in directory' announcement.",
            lambda { |value|
              Rake.verbose(false)
              options.silent = true
            }
          ],
          ['--suppress-backtrace PATTERN', "Suppress backtrace lines matching regexp PATTERN. Ignored if --trace is on.",
            lambda { |value|
              options.suppress_backtrace_pattern = Regexp.new(value)
            }
          ],
          ['--system',  '-g',
            "Using system wide (global) rakefiles (usually '~/.rake/*.rake').",
            lambda { |value| options.load_system = true }
          ],
          ['--no-system', '--nosystem', '-G',
            "Use standard project Rakefile search paths, ignore system wide rakefiles.",
            lambda { |value| options.ignore_system = true }
          ],
          ['--tasks', '-T [PATTERN]', "Display the tasks (matching optional PATTERN) with descriptions, then exit.",
            lambda { |value|
              select_tasks_to_show(options, :tasks, value)
            }
          ],
          ['--trace=[OUT]', '-t', "Turn on invoke/execute tracing, enable full backtrace. OUT can be stderr (default) or stdout.",
            lambda { |value|
              options.trace = true
              options.backtrace = true
              select_trace_output(options, 'trace', value)
              Rake.verbose(true)
            }
          ],
          ['--verbose', '-v', "Log message to standard output.",
            lambda { |value| Rake.verbose(true) }
          ],
          ['--version', '-V', "Display the program version.",
            lambda { |value|
              puts "rake, version #{RAKEVERSION}"
              exit
            }
          ],
          ['--where', '-W [PATTERN]', "Describe the tasks (matching optional PATTERN), then exit.",
            lambda { |value|
              select_tasks_to_show(options, :lines, value)
              options.show_all_tasks = true
            }
          ],
          ['--no-deprecation-warnings', '-X', "Disable the deprecation warnings.",
            lambda { |value|
              options.ignore_deprecate = true
            }
          ],
        ])
    end

system_dir() click to toggle source

The directory path containing the system wide rakefiles.

    # File lib/rake/application.rb, line 605
    def system_dir
      @system_dir ||=
        begin
          if ENV['RAKE_SYSTEM']
            ENV['RAKE_SYSTEM']
          else
            standard_system_dir
          end
        end
    end

terminal_width() click to toggle source

    # File lib/rake/application.rb, line 276
    def terminal_width
      if @terminal_columns.nonzero?
        result = @terminal_columns
      else
        result = unix? ? dynamic_width : 80
      end
      (result < 10) ? 80 : result
    rescue
      80
    end

top_level() click to toggle source

Run the top level tasks of a Rake application.

    # File lib/rake/application.rb, line 94
    def top_level
      run_with_threads do
        if options.show_tasks
          display_tasks_and_comments
        elsif options.show_prereqs
          display_prerequisites
        else
          top_level_tasks.each { |task_name| invoke_task(task_name) }
        end
      end
    end

trace(*strings) click to toggle source

    # File lib/rake/application.rb, line 326
    def trace(*strings)
      options.trace_output ||= $stderr
      trace_on(options.trace_output, *strings)
    end

truncate(string, width) click to toggle source

    # File lib/rake/application.rb, line 308
    def truncate(string, width)
      if string.nil?
        ""
      elsif string.length <= width
        string
      else
        ( string[0, width-3] || "" ) + "..."
      end
    end

truncate_output?() click to toggle source

We will truncate output if we are outputting to a TTY or if we've been given an explicit column width to honor

    # File lib/rake/application.rb, line 238
    def truncate_output?
      tty_output? || @terminal_columns.nonzero?
    end

tty_output=( tty_output_state ) click to toggle source

Override the detected TTY output state (mostly for testing)

    # File lib/rake/application.rb, line 232
    def tty_output=( tty_output_state )
      @tty_output = tty_output_state
    end

tty_output?() click to toggle source

True if we are outputting to TTY, false otherwise

    # File lib/rake/application.rb, line 227
    def tty_output?
      @tty_output
    end

unix?() click to toggle source

    # File lib/rake/application.rb, line 300
    def unix?
      RbConfig::CONFIG['host_os'] =~ /(aix|darwin|linux|(net|free|open)bsd|cygwin|solaris|irix|hpux)/
    end

windows?() click to toggle source

    # File lib/rake/application.rb, line 304
    def windows?
      Win32.windows?
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.