Class | Rake::Application
In: | lib/rake.rb
Parent: | Object

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

### Methods

add_import add_loader collect_tasks command_line_options const_warning display_prerequisites display_tasks_and_comments do_option handle_options have_rakefile help init load_imports load_rakefile new options rake_require rakefile_location run standard_exception_handling top_level usage

### Included Modules

TaskManager

### Constants

DEFAULT_RAKEFILES | = | ['rakefile', 'Rakefile', 'rakefile.rb', 'Rakefile.rb'].freeze
OPTIONS | = | [ # :nodoc: ['--dry-run', '-n', GetoptLong::NO_ARGUMENT, "Do a dry run without executing actions."], ['--help', '-H', GetoptLong::NO_ARGUMENT, "Display this help message."], ['--libdir', '-I', GetoptLong::REQUIRED_ARGUMENT, "Include LIBDIR in the search path for required modules."], ['--rakelibdir', '-R', GetoptLong::REQUIRED_ARGUMENT, "Auto-import any .rake files in RAKELIBDIR. (default is 'rakelib')"], ['--nosearch', '-N', GetoptLong::NO_ARGUMENT, "Do not search parent directories for the Rakefile."], ['--prereqs', '-P', GetoptLong::NO_ARGUMENT, "Display the tasks and dependencies, then exit."], ['--quiet', '-q', GetoptLong::NO_ARGUMENT, "Do not log messages to standard output."], ['--rakefile', '-f', GetoptLong::OPTIONAL_ARGUMENT, "Use FILE as the rakefile."], ['--require', '-r', GetoptLong::REQUIRED_ARGUMENT, "Require MODULE before executing rakefile."], ['--silent', '-s', GetoptLong::NO_ARGUMENT, "Like --quiet, but also suppresses the 'in directory' announcement."], ['--tasks', '-T', GetoptLong::OPTIONAL_ARGUMENT, "Display the tasks (matching optional PATTERN) with descriptions, then exit."], ['--trace', '-t', GetoptLong::NO_ARGUMENT, "Turn on invoke/execute tracing, enable full backtrace."], ['--usage', '-h', GetoptLong::NO_ARGUMENT, "Display usage."], ['--verbose', '-v', GetoptLong::NO_ARGUMENT, "Log message to standard output (default)."], ['--version', '-V', GetoptLong::NO_ARGUMENT, "Display the program version."], ['--classic-namespace', '-C', GetoptLong::NO_ARGUMENT, "Put Task and FileTask in the top level namespace"], ]

### 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.
top_level_tasks | [R] | List of the top level task names (task names from the command line).

### Public Class methods

new()

Initialize a Rake::Application object.

[Source]

          # File lib/rake.rb, line 1684
    1684:     def initialize
    1685:       super
    1686:       @name = 'rake'
    1687:       @rakefiles = DEFAULT_RAKEFILES.dup
    1688:       @rakefile = nil
    1689:       @pending_imports = []
    1690:       @imported = []
    1691:       @loaders = {}
    1692:       @default_loader = Rake::DefaultLoader.new
    1693:       @original_dir = Dir.pwd
    1694:       @top_level_tasks = []
    1695:       add_loader('rf', DefaultLoader.new)
    1696:       add_loader('rake', DefaultLoader.new)
    1697:     end

### Public Instance methods

add_import(fn)

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

[Source]

          # File lib/rake.rb, line 1964
    1964:     def add_import(fn)
    1965:       @pending_imports << fn
    1966:     end

add_loader(ext, loader)

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

[Source]

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

collect_tasks()

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.

[Source]

          # File lib/rake.rb, line 1951
    1951:     def collect_tasks
    1952:       @top_level_tasks = []
    1953:       ARGV.each do |arg|
    1954:         if arg =~ /^(\w+)=(.*)$/
    1955:           ENV[$1] = $2
    1956:         else
    1957:           @top_level_tasks << arg
    1958:         end
    1959:       end
    1960:       @top_level_tasks.push("default") if @top_level_tasks.size == 0
    1961:     end

command_line_options()

Return a list of the command line options supported by the program.

[Source]

          # File lib/rake.rb, line 1835
    1835:     def command_line_options
    1836:       OPTIONS.collect { |lst| lst[0..-2] }
    1837:     end

const_warning(const_name)

Warn about deprecated use of top level constant names.

[Source]

          # File lib/rake.rb, line 1983
    1983:     def const_warning(const_name)
    1984:       @const_warning ||= false
    1985:       if ! @const_warning
    1986:         $stderr.puts %{WARNING: Deprecated reference to top-level constant '#{const_name}' } +
    1987:           %{found at: #{rakefile_location}} # '
    1988:         $stderr.puts %{    Use --classic-namespace on rake command}
    1989:         $stderr.puts %{    or 'require "rake/classic_namespace"' in Rakefile}
    1990:       end
    1991:       @const_warning = true
    1992:     end

display_prerequisites()

Display the tasks and prerequisites

[Source]

          # File lib/rake.rb, line 1826
    1826:     def display_prerequisites
    1827:       tasks.each do |t|
    1828:         puts "rake #{t.name}"
    1829:         t.prerequisites.each { |pre| puts "    #{pre}" }
    1830:       end
    1831:     end

display_tasks_and_comments()

Display the tasks and dependencies.

[Source]

          # File lib/rake.rb, line 1815
    1815:     def display_tasks_and_comments
    1816:       displayable_tasks = tasks.select { |t|
    1817:         t.comment && t.name =~ options.show_task_pattern
    1818:       }
    1819:       width = displayable_tasks.collect { |t| t.name.length }.max
    1820:       displayable_tasks.each do |t|
    1821:         printf "#{name} %-#{width}s  # %s\n", t.name, t.comment
    1822:       end
    1823:     end

do_option(opt, value)

Do the option defined by `opt` and `value`.

[Source]

          # File lib/rake.rb, line 1840
    1840:     def do_option(opt, value)
    1841:       case opt
    1842:       when '--dry-run'
    1843:         verbose(true)
    1844:         nowrite(true)
    1845:         options.dryrun = true
    1846:         options.trace = true
    1847:       when '--help'
    1848:         help
    1849:         exit
    1850:       when '--libdir'
    1851:         $:.push(value)
    1852:       when '--nosearch'
    1853:         options.nosearch = true
    1854:       when '--prereqs'
    1855:         options.show_prereqs = true
    1856:       when '--quiet'
    1857:         verbose(false)
    1858:       when '--rakefile'
    1859:         @rakefiles.clear
    1860:         @rakefiles << value
    1861:       when '--rakelibdir'
    1862:         options.rakelib = value.split(':')
    1863:       when '--require'
    1864:         begin
    1865:           require value
    1866:         rescue LoadError => ex
    1867:           begin
    1868:             rake_require value
    1869:           rescue LoadError => ex2
    1870:             raise ex
    1871:           end
    1872:         end
    1873:       when '--silent'
    1874:         verbose(false)
    1875:         options.silent = true
    1876:       when '--tasks'
    1877:         options.show_tasks = true
    1878:         options.show_task_pattern = Regexp.new(value || '.')
    1879:       when '--trace'
    1880:         options.trace = true
    1881:         verbose(true)
    1882:       when '--usage'
    1883:         usage
    1884:         exit
    1885:       when '--verbose'
    1886:         verbose(true)
    1887:       when '--version'
    1888:         puts "rake, version #{RAKEVERSION}"
    1889:         exit
    1890:       when '--classic-namespace'
    1891:         require 'rake/classic_namespace'
    1892:         options.classic_namespace = true
    1893:       end
    1894:     end

handle_options()

Read and handle the command line options.

[Source]

          # File lib/rake.rb, line 1897
    1897:     def handle_options
    1898:       options.rakelib = 'rakelib'
    1899:
    1900:       opts = GetoptLong.new(*command_line_options)
    1901:       opts.each { |opt, value| do_option(opt, value) }
    1902:
    1903:       # If class namespaces are requested, set the global options
    1904:       # according to the values in the options structure.
    1905:       if options.classic_namespace
    1906:         $show_tasks = options.show_tasks
    1907:         $show_prereqs = options.show_prereqs
    1908:         $trace = options.trace
    1909:         $dryrun = options.dryrun
    1910:         $silent = options.silent
    1911:       end
    1912:     end

have_rakefile()

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

[Source]

          # File lib/rake.rb, line 1782
    1782:     def have_rakefile
    1783:       @rakefiles.each do |fn|
    1784:         if File.exist?(fn) || fn == ''
    1785:           @rakefile = fn
    1786:           return true
    1787:         end
    1788:       end
    1789:       return false
    1790:     end

help()

Display the rake command line help.

[Source]

          # File lib/rake.rb, line 1798
    1798:     def help
    1799:       usage
    1800:       puts
    1801:       puts "Options are ..."
    1802:       puts
    1803:       OPTIONS.sort.each do |long, short, mode, desc|
    1804:         if mode == GetoptLong::REQUIRED_ARGUMENT
    1805:           if desc =~ /\b([A-Z]{2,})\b/
    1806:             long = long + "=#{$1}"
    1807:           end
    1808:         end
    1809:         printf "  %-20s (%s)\n", long, short
    1810:         printf "      %s\n", desc
    1811:       end
    1812:     end

init(app_name='rake')

Initialize the command line parameters and app name.

[Source]

          # File lib/rake.rb, line 1717
    1717:     def init(app_name='rake')
    1718:       standard_exception_handling do
    1719:         @name = app_name
    1720:         handle_options
    1721:         collect_tasks
    1722:       end
    1723:     end

load_imports()

Load the pending list of imported files.

[Source]

          # File lib/rake.rb, line 1969
    1969:     def load_imports
    1970:       while fn = @pending_imports.shift
    1971:         next if @imported.member?(fn)
    1972:         if fn_task = lookup(fn)
    1973:           fn_task.invoke
    1974:         end
    1975:         ext = File.extname(fn)
    1976:         loader = @loaders[ext] || @default_loader
    1977:         loader.load(fn)
    1978:         @imported << fn
    1979:       end
    1980:     end

load_rakefile()

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

[Source]

          # File lib/rake.rb, line 1726
    1726:     def load_rakefile
    1727:       standard_exception_handling do
    1728:         raw_load_rakefile
    1729:       end
    1730:     end

options()

Application options from the command line

[Source]

          # File lib/rake.rb, line 1753
    1753:     def options
    1754:       @options ||= OpenStruct.new
    1755:     end

rake_require(file_name, paths=$LOAD_PATH, loaded=$")

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

[Source]

          # File lib/rake.rb, line 1916
    1916:     def rake_require(file_name, paths=$LOAD_PATH, loaded=$")
    1917:       return false if loaded.include?(file_name)
    1918:       paths.each do |path|
    1919:         fn = file_name + ".rake"
    1920:         full_path = File.join(path, fn)
    1921:         if File.exist?(full_path)
    1922:           load full_path
    1923:           loaded << fn
    1924:           return true
    1925:         end
    1926:       end
    1927:       fail LoadError, "Can't find #{file_name}"
    1928:     end

rakefile_location()

[Source]

          # File lib/rake.rb, line 1994
    1994:     def rakefile_location
    1995:       begin
    1996:         fail
    1997:       rescue RuntimeError => ex
    1998:         ex.backtrace.find {|str| str =~ /#{@rakefile}/ } || ""
    1999:       end
    2000:     end

run()

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 (`run_tasks`).

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

[Source]

          # File lib/rake.rb, line 1708
    1708:     def run
    1709:       standard_exception_handling do
    1710:         init
    1711:         load_rakefile
    1712:         top_level
    1713:       end
    1714:     end

standard_exception_handling() {|| ...}

Provide standard execption handling for the given block.

[Source]

          # File lib/rake.rb, line 1760
    1760:     def standard_exception_handling
    1761:       begin
    1762:         yield
    1763:       rescue SystemExit, GetoptLong::InvalidOption => ex
    1764:         # Exit silently
    1765:         exit(1)
    1766:       rescue Exception => ex
    1767:         # Exit with error message
    1768:         $stderr.puts "rake aborted!"
    1769:         $stderr.puts ex.message
    1770:         if options.trace
    1771:           $stderr.puts ex.backtrace.join("\n")
    1772:         else
    1773:           $stderr.puts ex.backtrace.find {|str| str =~ /#{@rakefile}/ } || ""
    1774:           $stderr.puts "(See full trace by running task with --trace)"
    1775:         end
    1776:         exit(1)
    1777:       end
    1778:     end

top_level()

Run the top level tasks of a Rake application.

[Source]

          # File lib/rake.rb, line 1733
    1733:     def top_level
    1734:       standard_exception_handling do
    1735:         if options.show_tasks
    1736:           display_tasks_and_comments
    1737:         elsif options.show_prereqs
    1738:           display_prerequisites
    1739:         else
    1740:           top_level_tasks.each { |task_name| self[task_name].invoke }
    1741:         end
    1742:       end
    1743:     end

usage()

Display the program usage line.

[Source]

          # File lib/rake.rb, line 1793
    1793:     def usage
    1794:       puts "rake [-f rakefile] {options} targets..."
    1795:     end

[Validate]