ruby-changes:26463
From: drbrain <ko1@a...>
Date: Fri, 21 Dec 2012 11:34:51 +0900 (JST)
Subject: [ruby-changes:26463] drbrain:r38514 (trunk): * lib/rake/*: Updated to rake 0.9.6
drbrain 2012-12-21 11:34:37 +0900 (Fri, 21 Dec 2012) New Revision: 38514 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=38514 Log: * lib/rake/*: Updated to rake 0.9.6 * doc/rake/*: ditto * test/rake/*: ditto Added files: trunk/doc/rake/release_notes/rake-0.9.0.rdoc trunk/doc/rake/release_notes/rake-0.9.1.rdoc trunk/doc/rake/release_notes/rake-0.9.2.2.rdoc trunk/doc/rake/release_notes/rake-0.9.2.rdoc trunk/doc/rake/release_notes/rake-0.9.3.rdoc trunk/doc/rake/release_notes/rake-0.9.4.rdoc trunk/doc/rake/release_notes/rake-0.9.5.rdoc trunk/doc/rake/release_notes/rake-0.9.6.rdoc Modified files: trunk/ChangeLog trunk/doc/rake/command_line_usage.rdoc trunk/doc/rake/glossary.rdoc trunk/doc/rake/proto_rake.rdoc trunk/doc/rake/rakefile.rdoc trunk/doc/rake/rational.rdoc trunk/doc/rake/release_notes/rake-0.8.7.rdoc trunk/lib/rake/version.rb trunk/test/rake/test_rake_directory_task.rb trunk/test/rake/test_rake_functional.rb trunk/test/rake/test_rake_task.rb trunk/test/rake/test_rake_task_with_arguments.rb Index: doc/rake/command_line_usage.rdoc =================================================================== --- doc/rake/command_line_usage.rdoc (revision 38513) +++ doc/rake/command_line_usage.rdoc (revision 38514) @@ -2,14 +2,26 @@ https://github.com/ruby/ruby/blob/trunk/doc/rake/command_line_usage.rdoc#L2 Rake is invoked from the command line using: - % rake [<em>options</em> ...] [<em>VAR</em>=<em>VALUE</em>] [<em>targets</em> ...] + % rake [options ...] [VAR=VALUE ...] [targets ...] Options are: [<tt><em>name</em>=<em>value</em></tt>] Set the environment variable <em>name</em> to <em>value</em> during the execution of the <b>rake</b> command. You can access - the value by using ENV['<em>name</em>']. + the value by using ENV['<em>name</em>']. + +[<tt>--all</tt> (-A)] + Used in combination with the -T and -D options, will force + those options to show all the tasks, even the ones without comments. + +[<tt>--backtrace</tt>{=_output_} (-n)] + Enable a full backtrace (i.e. like --trace, but without the task + tracing details). The _output_ parameter is optional, but if + specified it controls where the backtrace output is sent. If + _output_ is <tt>stdout</tt>, then backtrace output is directed to + stardard output. If _output_ is <tt>stderr</tt>, or if it is + missing, then the backtrace output is sent to standard error. [<tt>--classic-namespace</tt> (-n)] Import the Task, FileTask, and FileCreateTask into the top-level @@ -18,6 +30,11 @@ Options are: https://github.com/ruby/ruby/blob/trunk/doc/rake/command_line_usage.rdoc#L30 'rake/classic_namespace'</code> in your Rakefile to get the classic behavior. +[<tt>--comments</tt>] + Used in combination with the -W options to force the output to + contain commented options only. This is the reverse of + <tt>--all</tt>. + [<tt>--describe</tt> _pattern_ (-D)] Describe the tasks (matching optional PATTERN), then exit. @@ -31,15 +48,40 @@ Options are: https://github.com/ruby/ruby/blob/trunk/doc/rake/command_line_usage.rdoc#L48 [<tt>--execute-print</tt> _code_ (-p)] Execute some Ruby code, print the result, and exit. -[<tt>--execute-continue</tt> _code_ (-p)] +[<tt>--execute-continue</tt> _code_ (-E)] Execute some Ruby code, then continue with normal task processing. [<tt>--help</tt> (-H)] Display some help text and exit. +[<tt>--jobs</tt> _number_ (-j)] + Specifies the number of active concurrent tasks used. The + suggested value is equal to the number of CPUs. The concurrent + tasks are used to execute the <tt>multitask</tt> prerequisites. + Also see the <tt>-m</tt> option which turns all tasks into + multitasks. + + Sample values: + (no -j) : unlimited concurrent tasks (standard rake behavior) + -j : 2 concurrent tasks (exact number may change) + -j 16 : 16 concurrent tasks + +[<tt>--job-stats</tt> _level_] + + Display job statistics at the completion of the run. By default, + this will display the requested number of active tasks (from the + -j options) and the maximum number of tasks in play at any given + time. + + If the optional _level_ is <tt>history</tt>, then a complete trace + of task history will be displayed on standard output. + [<tt>--libdir</tt> _directory_ (-I)] Add _directory_ to the list of directories searched for require. +[<tt>--multitask</tt> (-m)] + Treat all tasks as multitasks. ('make/drake' semantics) + [<tt>--nosearch</tt> (-N)] Do not search for a Rakefile in parent directories. @@ -60,6 +102,16 @@ Options are: https://github.com/ruby/ruby/blob/trunk/doc/rake/command_line_usage.rdoc#L102 [<tt>--rakelibdir</tt> _rakelibdir_ (-R)] Auto-import any .rake files in RAKELIBDIR. (default is 'rakelib') +[<tt>--reduce-compat</tt>] + + Remove the DSL commands from the Object inheritance hierarchy and + do not define top level constants. This reduces the backwards + compatibility of Rake, but allows rake to be used with software + that would otherwise have conflicting definitions. + + *NOTE:* The next major version of Rake will only be able to be run + in "reduce-compat" mode. + [<tt>--require</tt> _name_ (-r)] Require _name_ before executing the Rakefile. @@ -69,6 +121,11 @@ Options are: https://github.com/ruby/ruby/blob/trunk/doc/rake/command_line_usage.rdoc#L121 [<tt>--silent (-s)</tt>] Like --quiet, but also suppresses the 'in directory' announcement. +[<tt>--suppress-backtrace _pattern_ </tt>] + Line matching the regular expression _pattern_ will be removed + from the backtrace output. Note that the --backtrace option is the + full backtrace without these lines suppressed. + [<tt>--system</tt> (-g)] Use the system wide (global) rakefiles. The project Rakefile is ignored. By default, the system wide rakefiles are used only if no @@ -80,16 +137,18 @@ Options are: https://github.com/ruby/ruby/blob/trunk/doc/rake/command_line_usage.rdoc#L137 Use the project level Rakefile, ignoring the system-wide (global) rakefiles. -[<tt>--tasks</tt> (-T)] +[<tt>--tasks</tt> <em>pattern</em> (-T)] Display a list of the major tasks and their comments. Comments - are defined using the "desc" command. + are defined using the "desc" command. If a pattern is given, then + only tasks matching the pattern are displayed. -[<tt>--trace</tt> (-t)] +[<tt>--trace</tt>{=_output_} (-t)] Turn on invoke/execute tracing. Also enable full backtrace on - errors. - -[<tt>--usage</tt> (-h)] - Display a usage message and exit. + errors. The _output_ parameter is optional, but if specified it + controls where the trace output is sent. If _output_ is + <tt>stdout</tt>, then trace output is directed to stardard output. + If _output_ is <tt>stderr</tt>, or if it is missing, then trace + output is sent to standard error. [<tt>--verbose</tt> (-v)] Echo the Sys commands to standard output. @@ -97,6 +156,14 @@ Options are: https://github.com/ruby/ruby/blob/trunk/doc/rake/command_line_usage.rdoc#L156 [<tt>--version</tt> (-V)] Display the program version and exit. +[<tt>--where</tt> <em>pattern</em> (-W)] + Display tasks that match <em>pattern</em> and the file and line + number where the task is defined. By default this option will + display all tasks, not just the tasks that have descriptions. + +[<tt>--no-deprecation-warnings</tt> (-W)] + Do not display the deprecation warnings. + In addition, any command line option of the form <em>VAR</em>=<em>VALUE</em> will be added to the environment hash <tt>ENV</tt> and may be tested in the Rakefile. Index: doc/rake/rational.rdoc =================================================================== --- doc/rake/rational.rdoc (revision 38513) +++ doc/rake/rational.rdoc (revision 38514) @@ -38,13 +38,13 @@ too much work. And that was the end of https://github.com/ruby/ruby/blob/trunk/doc/rake/rational.rdoc#L38 ... Except I couldn't get the thought out of my head. What exactly would be needed to make the about syntax work as a make file? Hmmm, you would need to register the tasks, you need some way of specifying -dependencies between tasks, and some way of kicking off the process. +dependencies between tasks, and some way of kicking off the process. Hey! What if we did ... and fifteen minutes later I had a working prototype of Ruby make, complete with dependencies and actions. I showed the code to my coworker and we had a good laugh. It was just about a page worth of code that reproduced an amazing amount of the -functionality of make. We were both truely stunned with the power of +functionality of make. We were both truly stunned with the power of Ruby. But it didn't do everything make did. In particular, it didn't have @@ -53,7 +53,7 @@ prerequisite files have a later timestam https://github.com/ruby/ruby/blob/trunk/doc/rake/rational.rdoc#L53 pain to add and so Ruby Make would remain an interesting experiment. ... Except as I walked back to my desk, I started thinking about what -file based dependecies would really need. Rats! I was hooked again, +file based dependencies would really need. Rats! I was hooked again, and by adding a new class and two new methods, file/timestamp dependencies were implemented. @@ -97,7 +97,7 @@ Here's another task with dependencies .. https://github.com/ruby/ruby/blob/trunk/doc/rake/rational.rdoc#L97 end Task :clobber depends upon task :clean, so :clean will be run before -:clobber is executed. +:clobber is executed. Files are specified by using the "file" command. It is similar to the task command, except that the task name represents a file, and the task @@ -115,7 +115,7 @@ Here is a file based dependency that wil https://github.com/ruby/ruby/blob/trunk/doc/rake/rational.rdoc#L115 I normally specify file tasks with string (rather than symbols). Some file names can't be represented by symbols. Plus it makes the -distinction between them more clear to the casual reader. +distinction between them more clear to the casual reader. Currently writing a task for each and every file in the project would be tedious at best. I envision a set of libraries to make this job @@ -133,7 +133,7 @@ created for rake. https://github.com/ruby/ruby/blob/trunk/doc/rake/rational.rdoc#L133 That's it. There's no documentation (other than whats in this message). Does this sound interesting to anyone? If so, I'll continue to clean it up and write it up and publish it on RAA. Otherwise, I'll -leave it as an interesting excerise and a tribute to the power of Ruby. +leave it as an interesting exercise and a tribute to the power of Ruby. Why /might/ rake be interesting to Ruby programmers. I don't know, perhaps ... Index: doc/rake/rakefile.rdoc =================================================================== --- doc/rake/rakefile.rdoc (revision 38513) +++ doc/rake/rakefile.rdoc (revision 38514) @@ -1,4 +1,4 @@ https://github.com/ruby/ruby/blob/trunk/doc/rake/rakefile.rdoc#L1 -= Rakefile Format (as of version 0.8.3) += Rakefile Format (as of version 0.8.7) First of all, there is no special format for a Rakefile. A Rakefile contains executable Ruby code. Anything legal in a ruby script is @@ -27,7 +27,7 @@ parameter that is the name of the task. https://github.com/ruby/ruby/blob/trunk/doc/rake/rakefile.rdoc#L27 === Tasks with Prerequisites -Any prerequisites are given as a list (inclosed in square brackets) +Any prerequisites are given as a list (enclosed in square brackets) following the name and an arrow (=>). task :name => [:prereq1, :prereq2] @@ -45,7 +45,7 @@ following ... https://github.com/ruby/ruby/blob/trunk/doc/rake/rakefile.rdoc#L45 Actions are defined by passing a block to the +task+ method. Any Ruby code can be placed in the block. The block may reference the task -object via the block paramter.. +object via the block parameter. task :name => [:prereq1, :prereq2] do |t| # actions (may reference t) @@ -119,14 +119,14 @@ Rake allows parallel execution of prereq https://github.com/ruby/ruby/blob/trunk/doc/rake/rakefile.rdoc#L119 end In this example, +copy_files+ is a normal rake task. Its actions are -executed whereever all of its prerequisites are done. The big +executed whenever all of its prerequisites are done. The big difference is that the prerequisites (+copy_src+, +copy_bin+ and +copy_doc+) are executed in parallel. Each of the prerequisites are run in their own Ruby thread, possibly allowing faster overall runtime. === Secondary Prerequisites -If any of the primary prerequites of a multitask have common secondary +If any of the primary prerequisites of a multitask have common secondary prerequisites, all of the primary/parallel prerequisites will wait until the common prerequisites have been run. @@ -183,6 +183,22 @@ argument string should be quoted. Somet https://github.com/ruby/ruby/blob/trunk/doc/rake/rakefile.rdoc#L183 (Quoting rules vary between operating systems and shells, so make sure you consult the proper docs for your OS/shell). +=== Tasks Arguments and the Environment + +Task argument values can also be picked up from the environment. For +example, if the "release" task expected a parameter named +"release_version", then either + + rake release[0.8.2] + +or + + RELEASE_VERSION rake release + +will work. Environment variable names must either match the task +parameter exactly, or match an all-uppercase version of the task +parameter. + === Tasks that Expect Parameters Parameters are only given to tasks that are setup to expect them. In @@ -195,10 +211,10 @@ declared as: https://github.com/ruby/ruby/blob/trunk/doc/rake/rakefile.rdoc#L211 task :name, [:first_name, :last_name] The first argument is still the name of the task (:name in this case). -The next to argumements are the names of the parameters expected by +The next two arguments are the names of the parameters expected by :name in an array (:first_name and :last_name in the example). -To access the values of the paramters, the block defining the task +To access the values of the parameters, the block defining the task behaviour can now accept a second parameter: task :name, [:first_name, :last_name] do |t, args| @@ -210,7 +226,8 @@ The first argument of the block "t" is a https://github.com/ruby/ruby/blob/trunk/doc/rake/rakefile.rdoc#L226 task object. The second argument "args" is an open-struct like object that allows access to the task arguments. Extra command line arguments to a task are ignored. Missing command line arguments are -given the nil value. +picked up from matching environment variables. If there are no +matching environment variables, they are given the nil value. If you wish to specify default values for the arguments, you can use the with_defaults method in the task body. Here is the above example @@ -239,11 +256,12 @@ for tasks with arguments. For example: https://github.com/ruby/ruby/blob/trunk/doc/rake/rakefile.rdoc#L256 There is an older format for declaring task parameters that omitted the task argument array and used the :needs keyword to introduce the dependencies. That format is still supported for compatibility, but -is not recommended for use. +is not recommended for use. The older format may be dropped in future +versions of rake. -== Accessing Task Programatically +== Accessing Task Programmatically -Sometimes it is useful to manipulate tasks programatically in a +Sometimes it is useful to manipulate tasks programmatically in a Rakefile. To find a task object, use the <tt>:[]</tt> operator on the <tt>Rake::Task</tt>. @@ -260,7 +278,7 @@ actions. https://github.com/ruby/ruby/blob/trunk/doc/rake/rakefile.rdoc#L278 task :dont do Rake::Task[:doit].clear - end + end Running this example: @@ -269,7 +287,7 @@ Running this example: https://github.com/ruby/ruby/blob/trunk/doc/rake/rakefile.rdoc#L287 DONE $ rake dont doit (in /Users/jim/working/git/rake/x) - $ + $ The ability to programmatically manipulate tasks gives rake very powerful meta-programming capabilities w.r.t. task execution, but @@ -294,7 +312,7 @@ Rake is able to find a file named "mycod https://github.com/ruby/ruby/blob/trunk/doc/rake/rakefile.rdoc#L312 create a task that builds "mycode.o" from "mycode.c". If the file "mycode.c" does not exist, rake will attempt -to recursively synthesize a rule for it. +to recursively synthesize a rule for it. When a task is synthesized from a rule, the +source+ attribute of the task is set to the matching source file. This allows us to write @@ -312,7 +330,7 @@ The following rule is equivalent to the https://github.com/ruby/ruby/blob/trunk/doc/rake/rakefile.rdoc#L330 proc {|task_name| task_name.sub(/\.[^.]+$/, '.c') } ]) do |t| sh "cc #{t.source} -c -o #{t.name}" - end + end <b>NOTE:</b> Because of a _quirk_ in Ruby syntax, parenthesis are required on *rule* when the first argument is a regular expression. @@ -322,7 +340,7 @@ The following rule might be used for Jav https://github.com/ruby/ruby/blob/trunk/doc/rake/rakefile.rdoc#L340 rule '.java' => [ proc { |tn| tn.sub(/\.class$/, '.java').sub(/^classes\//, 'src/') } ] do |t| - java_compile(t.source, t.name) + java_compile(t.source, t.name) end <b>NOTE:</b> +java_compile+ is a hypothetical method that invokes the @@ -340,12 +358,17 @@ invoked. This make generated dependency https://github.com/ruby/ruby/blob/trunk/doc/rake/rakefile.rdoc#L358 the time rake gets around to updating the dependencies file, it is too late to load it. -The +import+ command addresses this by specifying a file to be loaded -_after_ the main rakefile is loaded, but _before_ any targets on the -command line are specified. In addition, if the file name matches an -explicit task, that task is invoked before loading the file. This -allows dependency files to be generated and used in a single rake -command invocation. +The +Rake.import+ command addresses this by specifying a file to be +loaded _after_ the main rakefile is loaded, but _before_ any targets +on the command line are invoked. In addition, if the file name +matches an explicit task, that task is invoked before loading the +file. This allows dependency files to be generated and used in a +single rake command invocation. + +<b>NOTE:</b> Starting in Rake version 0.9.0, the top level +import+ +command is deprecated and we recommend using the scoped +"+Rake.import+" command mentioned above. Future versions of Rake will +drop support for the top level +import+ command. === Example: @@ -355,7 +378,7 @@ command invocation. https://github.com/ruby/ruby/blob/trunk/doc/rake/rakefile.rdoc#L378 sh "makedepend -f- -- #{CFLAGS} -- #{t.prerequisites} > #{t.name}" end - import ".depends.mf" + Rake.import ".depends.mf" If ".depends" does not exist, or is out of date w.r.t. the source files, a new ".depends" file is generated using +makedepend+ before @@ -374,9 +397,9 @@ then you need to use the +desc+ command https://github.com/ruby/ruby/blob/trunk/doc/rake/rakefile.rdoc#L397 task :package => [ ... ] do ... end The "-T" switch (or "--tasks" if you like to spell things out) will -display a list of tasks that have a defined comment. If you use -+desc+ to describe your major tasks, you have a semi-automatic way of -generating a summary of your Rake file. +display a list of tasks that have a description. If you use +desc+ to +describe your major tasks, you have a semi-automatic way of generating +a summary of your Rake file. traken$ rake -T (in /home/.../rake) @@ -403,12 +426,12 @@ common for task names to begin to clash. https://github.com/ruby/ruby/blob/trunk/doc/rake/rakefile.rdoc#L426 have a main program and a set of sample programs built by a single Rakefile. By placing the tasks related to the main program in one namespace, and the tasks for building the sample programs in a -different namespace, the task names will not will not interfer with +different namespace, the task names will not will not interfere with each other. For example: - namespace "main" + namespace "main" do task :build do # Build the main program end @@ -429,7 +452,7 @@ Nested namespaces are supported, so https://github.com/ruby/ruby/blob/trunk/doc/rake/rakefile.rdoc#L452 Note that the name given in the +task+ command is always the unadorned task name without any namespace prefixes. The +task+ command always -defines a task in the current namespace. +defines a task in the current namespace. === FileTasks @@ -499,17 +522,17 @@ Or give it a glob pattern: https://github.com/ruby/ruby/blob/trunk/doc/rake/rakefile.rdoc#L522 == Odds and Ends -=== do/end verses { } +=== do/end versus { } Blocks may be specifi (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/