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 invoke_task load_imports load_rakefile new options parse_task_string rake_require rakefile_location run standard_exception_handling top_level truncate

### Included Modules

TaskManager

### Constants

DEFAULT_RAKEFILES | = | ['rakefile', 'Rakefile', 'rakefile.rb', 'Rakefile.rb'].freeze
OPTIONS | = | [ # :nodoc: ['--classic-namespace', '-C', GetoptLong::NO_ARGUMENT, "Put Task and FileTask in the top level namespace"], ['--describe', '-D', GetoptLong::OPTIONAL_ARGUMENT, "Describe the tasks (matching optional PATTERN), then exit."], ['--rakefile', '-f', GetoptLong::OPTIONAL_ARGUMENT, "Use FILE as the rakefile."], ['--help', '-h', '-H', GetoptLong::NO_ARGUMENT, "Display this help message."], ['--libdir', '-I', GetoptLong::REQUIRED_ARGUMENT, "Include LIBDIR in the search path for required modules."], ['--dry-run', '-n', GetoptLong::NO_ARGUMENT, "Do a dry run without executing actions."], ['--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."], ['--require', '-r', GetoptLong::REQUIRED_ARGUMENT, "Require MODULE before executing rakefile."], ['--rakelibdir', '-R', GetoptLong::REQUIRED_ARGUMENT, "Auto-import any .rake files in RAKELIBDIR. (default is 'rakelib')"], ['--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."], ['--verbose', '-v', GetoptLong::NO_ARGUMENT, "Log message to standard output (default)."], ['--version', '-V', GetoptLong::NO_ARGUMENT, "Display the program version."], ]

### 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 1854
    1854:     def initialize
    1855:       super
    1856:       @name = 'rake'
    1857:       @rakefiles = DEFAULT_RAKEFILES.dup
    1858:       @rakefile = nil
    1859:       @pending_imports = []
    1860:       @imported = []
    1861:       @loaders = {}
    1862:       @default_loader = Rake::DefaultLoader.new
    1863:       @original_dir = Dir.pwd
    1864:       @top_level_tasks = []
    1865:       add_loader('rf', DefaultLoader.new)
    1866:       add_loader('rake', DefaultLoader.new)
    1867:     end

### Public Instance methods

add_import(fn)

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

[Source]

          # File lib/rake.rb, line 2173
    2173:     def add_import(fn)
    2174:       @pending_imports << fn
    2175:     end

add_loader(ext, loader)

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

[Source]

          # File lib/rake.rb, line 1917
    1917:     def add_loader(ext, loader)
    1918:       ext = ".#{ext}" unless ext =~ /^\./
    1919:       @loaders[ext] = loader
    1920:     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 2160
    2160:     def collect_tasks
    2161:       @top_level_tasks = []
    2162:       ARGV.each do |arg|
    2163:         if arg =~ /^(\w+)=(.*)$/
    2164:           ENV[$1] = $2
    2165:         else
    2166:           @top_level_tasks << arg
    2167:         end
    2168:       end
    2169:       @top_level_tasks.push("default") if @top_level_tasks.size == 0
    2170:     end

command_line_options()

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

[Source]

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

const_warning(const_name)

Warn about deprecated use of top level constant names.

[Source]

          # File lib/rake.rb, line 2192
    2192:     def const_warning(const_name)
    2193:       @const_warning ||= false
    2194:       if ! @const_warning
    2195:         $stderr.puts %{WARNING: Deprecated reference to top-level constant '#{const_name}' } +
    2196:           %{found at: #{rakefile_location}} # '
    2197:         $stderr.puts %{    Use --classic-namespace on rake command}
    2198:         $stderr.puts %{    or 'require "rake/classic_namespace"' in Rakefile}
    2199:       end
    2200:       @const_warning = true
    2201:     end

display_prerequisites()

Display the tasks and prerequisites

[Source]

          # File lib/rake.rb, line 2031
    2031:     def display_prerequisites
    2032:       tasks.each do |t|
    2033:         puts "rake #{t.name}"
    2034:         t.prerequisites.each { |pre| puts "    #{pre}" }
    2035:       end
    2036:     end

display_tasks_and_comments()

Display the tasks and dependencies.

[Source]

          # File lib/rake.rb, line 2000
    2000:     def display_tasks_and_comments
    2001:       displayable_tasks = tasks.select { |t|
    2002:         t.comment && t.name =~ options.show_task_pattern
    2003:       }
    2004:       if options.full_description
    2005:         displayable_tasks.each do |t|
    2006:           puts "rake #{t.name_with_args}"
    2007:           t.full_comment.split("\n").each do |line|
    2008:             puts "    #{line}"
    2009:           end
    2010:           puts
    2011:         end
    2012:       else
    2013:         width = displayable_tasks.collect { |t| t.name_with_args.length }.max || 10
    2014:         max_column = 80 - name.size - width - 7
    2015:         displayable_tasks.each do |t|
    2016:           printf "#{name} %-#{width}s  # %s\n",
    2017:             t.name_with_args, truncate(t.comment, max_column)
    2018:         end
    2019:       end
    2020:     end

do_option(opt, value)

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

[Source]

          # File lib/rake.rb, line 2045
    2045:     def do_option(opt, value)
    2046:       case opt
    2047:       when '--describe'
    2048:         options.show_tasks = true
    2049:         options.show_task_pattern = Regexp.new(value || '.')
    2050:         options.full_description = true
    2051:       when '--dry-run'
    2052:         verbose(true)
    2053:         nowrite(true)
    2054:         options.dryrun = true
    2055:         options.trace = true
    2056:       when '--help'
    2057:         help
    2058:         exit
    2059:       when '--libdir'
    2060:         $:.push(value)
    2061:       when '--nosearch'
    2062:         options.nosearch = true
    2063:       when '--prereqs'
    2064:         options.show_prereqs = true
    2065:       when '--quiet'
    2066:         verbose(false)
    2067:       when '--rakefile'
    2068:         @rakefiles.clear
    2069:         @rakefiles << value
    2070:       when '--rakelibdir'
    2071:         options.rakelib = value.split(':')
    2072:       when '--require'
    2073:         begin
    2074:           require value
    2075:         rescue LoadError => ex
    2076:           begin
    2077:             rake_require value
    2078:           rescue LoadError => ex2
    2079:             raise ex
    2080:           end
    2081:         end
    2082:       when '--silent'
    2083:         verbose(false)
    2084:         options.silent = true
    2085:       when '--tasks'
    2086:         options.show_tasks = true
    2087:         options.show_task_pattern = Regexp.new(value || '.')
    2088:         options.full_description = false
    2089:       when '--trace'
    2090:         options.trace = true
    2091:         verbose(true)
    2092:       when '--verbose'
    2093:         verbose(true)
    2094:       when '--version'
    2095:         puts "rake, version #{RAKEVERSION}"
    2096:         exit
    2097:       when '--classic-namespace'
    2098:         require 'rake/classic_namespace'
    2099:         options.classic_namespace = true
    2100:       end
    2101:     end

handle_options()

Read and handle the command line options.

[Source]

          # File lib/rake.rb, line 2104
    2104:     def handle_options
    2105:       options.rakelib = ['rakelib']
    2106:
    2107:       opts = GetoptLong.new(*command_line_options)
    2108:       opts.each { |opt, value| do_option(opt, value) }
    2109:
    2110:       # If class namespaces are requested, set the global options
    2111:       # according to the values in the options structure.
    2112:       if options.classic_namespace
    2113:         $show_tasks = options.show_tasks
    2114:         $show_prereqs = options.show_prereqs
    2115:         $trace = options.trace
    2116:         $dryrun = options.dryrun
    2117:         $silent = options.silent
    2118:       end
    2119:     rescue NoMethodError => ex
    2120:       raise GetoptLong::InvalidOption, "While parsing options, error = #{ex.class}:#{ex.message}"
    2121:     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 1972
    1972:     def have_rakefile
    1973:       @rakefiles.each do |fn|
    1974:         if File.exist?(fn) || fn == ''
    1975:           @rakefile = fn
    1976:           return true
    1977:         end
    1978:       end
    1979:       return false
    1980:     end

help()

Display the rake command line help.

[Source]

          # File lib/rake.rb, line 1983
    1983:     def help
    1984:       puts "rake [-f rakefile] {options} targets..."
    1985:       puts
    1986:       puts "Options are ..."
    1987:       puts
    1988:       OPTIONS.sort.each do |long, short, mode, desc|
    1989:         if mode == GetoptLong::REQUIRED_ARGUMENT
    1990:           if desc =~ /\b([A-Z]{2,})\b/
    1991:             long = long + "=#{$1}"
    1992:           end
    1993:         end
    1994:         printf "  %-20s (%s)\n", long, short
    1995:         printf "      %s\n", desc
    1996:       end
    1997:     end

init(app_name='rake')

Initialize the command line parameters and app name.

[Source]

          # File lib/rake.rb, line 1887
    1887:     def init(app_name='rake')
    1888:       standard_exception_handling do
    1889:         @name = app_name
    1890:         handle_options
    1891:         collect_tasks
    1892:       end
    1893:     end

invoke_task(task_string)

private —————————————————————-

[Source]

          # File lib/rake.rb, line 1929
    1929:     def invoke_task(task_string)
    1930:       name, args = parse_task_string(task_string)
    1931:       t = self[name]
    1932:       t.invoke(*args)
    1933:     end

load_imports()

Load the pending list of imported files.

[Source]

          # File lib/rake.rb, line 2178
    2178:     def load_imports
    2179:       while fn = @pending_imports.shift
    2180:         next if @imported.member?(fn)
    2181:         if fn_task = lookup(fn)
    2182:           fn_task.invoke
    2183:         end
    2184:         ext = File.extname(fn)
    2185:         loader = @loaders[ext] || @default_loader
    2186:         loader.load(fn)
    2187:         @imported << fn
    2188:       end
    2189:     end

load_rakefile()

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

[Source]

          # File lib/rake.rb, line 1896
    1896:     def load_rakefile
    1897:       standard_exception_handling do
    1898:         raw_load_rakefile
    1899:       end
    1900:     end

options()

Application options from the command line

[Source]

          # File lib/rake.rb, line 1923
    1923:     def options
    1924:       @options ||= OpenStruct.new
    1925:     end

parse_task_string(string)

[Source]

          # File lib/rake.rb, line 1935
    1935:     def parse_task_string(string)
    1936:       if string =~ /^([^\[]+)(\[(.*)\])$/
    1937:         name = $1
    1938:         args = $3.split(/\s*,\s*/)
    1939:       else
    1940:         name = string
    1941:         args = []
    1942:       end
    1943:       [name, args]
    1944:     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 2125
    2125:     def rake_require(file_name, paths=$LOAD_PATH, loaded=$")
    2126:       return false if loaded.include?(file_name)
    2127:       paths.each do |path|
    2128:         fn = file_name + ".rake"
    2129:         full_path = File.join(path, fn)
    2130:         if File.exist?(full_path)
    2131:           load full_path
    2132:           loaded << fn
    2133:           return true
    2134:         end
    2135:       end
    2136:       fail LoadError, "Can't find #{file_name}"
    2137:     end

rakefile_location()

[Source]

          # File lib/rake.rb, line 2203
    2203:     def rakefile_location
    2204:       begin
    2205:         fail
    2206:       rescue RuntimeError => ex
    2207:         ex.backtrace.find {|str| str =~ /#{@rakefile}/ } || ""
    2208:       end
    2209:     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 1878
    1878:     def run
    1879:       standard_exception_handling do
    1880:         init
    1881:         load_rakefile
    1882:         top_level
    1883:       end
    1884:     end

standard_exception_handling() {|| ...}

Provide standard execption handling for the given block.

[Source]

          # File lib/rake.rb, line 1947
    1947:     def standard_exception_handling
    1948:       begin
    1949:         yield
    1950:       rescue SystemExit => ex
    1951:         # Exit silently with current status
    1952:         exit(ex.status)
    1953:       rescue SystemExit, GetoptLong::InvalidOption => ex
    1954:         # Exit silently
    1955:         exit(1)
    1956:       rescue Exception => ex
    1957:         # Exit with error message
    1958:         $stderr.puts "rake aborted!"
    1959:         $stderr.puts ex.message
    1960:         if options.trace
    1961:           $stderr.puts ex.backtrace.join("\n")
    1962:         else
    1963:           $stderr.puts ex.backtrace.find {|str| str =~ /#{@rakefile}/ } || ""
    1964:           $stderr.puts "(See full trace by running task with --trace)"
    1965:         end
    1966:         exit(1)
    1967:       end
    1968:     end

top_level()

Run the top level tasks of a Rake application.

[Source]

          # File lib/rake.rb, line 1903
    1903:     def top_level
    1904:       standard_exception_handling do
    1905:         if options.show_tasks
    1906:           display_tasks_and_comments
    1907:         elsif options.show_prereqs
    1908:           display_prerequisites
    1909:         else
    1910:           top_level_tasks.each { |task_name| invoke_task(task_name) }
    1911:         end
    1912:       end
    1913:     end

truncate(string, width)

[Source]

          # File lib/rake.rb, line 2022
    2022:     def truncate(string, width)
    2023:       if string.length <= width
    2024:         string
    2025:       else
    2026:         string[0, width-3] + "..."
    2027:       end
    2028:     end

[Validate]