ruby-changes:27133
From: zzak <ko1@a...>
Date: Sun, 10 Feb 2013 14:26:47 +0900 (JST)
Subject: [ruby-changes:27133] zzak:r39185 (trunk): * doc/rake/, lib/rake/doc/: Move Rake rdoc files to lib/rake
zzak 2013-02-10 14:26:34 +0900 (Sun, 10 Feb 2013) New Revision: 39185 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=39185 Log: * doc/rake/, lib/rake/doc/: Move Rake rdoc files to lib/rake Added directories: trunk/lib/rake/doc/ Added files: trunk/lib/rake/doc/README trunk/lib/rake/doc/command_line_usage.rdoc trunk/lib/rake/doc/glossary.rdoc trunk/lib/rake/doc/rakefile.rdoc trunk/lib/rake/doc/rational.rdoc Removed files: trunk/doc/rake/README trunk/doc/rake/command_line_usage.rdoc trunk/doc/rake/glossary.rdoc trunk/doc/rake/rakefile.rdoc trunk/doc/rake/rational.rdoc Modified files: trunk/ChangeLog Index: doc/rake/command_line_usage.rdoc =================================================================== --- doc/rake/command_line_usage.rdoc (revision 39184) +++ doc/rake/command_line_usage.rdoc (revision 39185) @@ -1,169 +0,0 @@ https://github.com/ruby/ruby/blob/trunk/doc/rake/command_line_usage.rdoc#L0 -= Rake Command Line Usage - -Rake is invoked from the command line using: - - % 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>']. - -[<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 - scope to be compatible with older versions of Rake. Alternatively - you can include the line <code>require - '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. - -[<tt>--dry-run</tt> (-n)] - Do a dry run. Print the tasks invoked and executed, but do not - actually execute any of the actions. - -[<tt>--execute</tt> _code_ (-e)] - Execute some Ruby code and exit. - -[<tt>--execute-print</tt> _code_ (-p)] - Execute some Ruby code, print the result, and exit. - -[<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. - -[<tt>--prereqs</tt> (-P)] - Display a list of all tasks and their immediate prerequisites. - -[<tt>--quiet</tt> (-q)] - Do not echo commands from FileUtils. - -[<tt>--rakefile</tt> _filename_ (-f)] - Use _filename_ as the name of the rakefile. The default rakefile - names are +rakefile+ and +Rakefile+ (with +rakefile+ taking - precedence). If the rakefile is not found in the current - directory, +rake+ will search parent directories for a match. The - directory where the Rakefile is found will become the current - directory for the actions executed in the Rakefile. - -[<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. - -[<tt>--rules</tt>] - Trace the rules resolution. - -[<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 - project Rakefile is found. On Unix-like system, the system wide - rake files are located in $HOME/.rake. On a windows system they - are stored in $APPDATA/Rake. - -[<tt>--no-system</tt> (-G)] - Use the project level Rakefile, ignoring the system-wide (global) - rakefiles. - -[<tt>--tasks</tt> <em>pattern</em> (-T)] - Display a list of the major tasks and their comments. Comments - are defined using the "desc" command. If a pattern is given, then - only tasks matching the pattern are displayed. - -[<tt>--trace</tt>{=_output_} (-t)] - Turn on invoke/execute tracing. Also enable full backtrace on - 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. - -[<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 39184) +++ doc/rake/rational.rdoc (revision 39185) @@ -1,151 +0,0 @@ https://github.com/ruby/ruby/blob/trunk/doc/rake/rational.rdoc#L0 -= Why rake? - -Ok, let me state from the beginning that I never intended to write this -code. I'm not convinced it is useful, and I'm not convinced anyone -would even be interested in it. All I can say is that Why's onion truck -must by been passing through the Ohio valley. - -What am I talking about? ... A Ruby version of Make. - -See, I can sense you cringing already, and I agree. The world certainly -doesn't need yet another reworking of the "make" program. I mean, we -already have "ant". Isn't that enough? - -It started yesterday. I was helping a coworker fix a problem in one of -the Makefiles we use in our project. Not a particularly tough problem, -but during the course of the conversation I began lamenting some of the -shortcomings of make. In particular, in one of my makefiles I wanted to -determine the name of a file dynamically and had to resort to some -simple scripting (in Ruby) to make it work. "Wouldn't it be nice if you -could just use Ruby inside a Makefile" I said. - -My coworker (a recent convert to Ruby) agreed, but wondered what it -would look like. So I sketched the following on the whiteboard... - - "What if you could specify the make tasks in Ruby, like this ..." - - task "build" do - java_compile(...args, etc ...) - end - - "The task function would register "build" as a target to be made, - and the block would be the action executed whenever the build - system determined that it was time to do the build target." - -We agreed that would be cool, but writing make from scratch would be WAY -too much work. And that was the end of that! - -... 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. -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 truly stunned with the power of -Ruby. - -But it didn't do everything make did. In particular, it didn't have -timestamp based file dependencies (where a file is rebuilt if any of its -prerequisite files have a later timestamp). Obviously THAT would be a -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 dependencies would really need. Rats! I was hooked again, -and by adding a new class and two new methods, file/timestamp -dependencies were implemented. - -Ok, now I was really hooked. Last night (during CSI!) I massaged the -code and cleaned it up a bit. The result is a bare-bones replacement -for make in exactly 100 lines of code. - -For the curious, you can see it at ... -* doc/proto_rake.rdoc - -Oh, about the name. When I wrote the example Ruby Make task on my -whiteboard, my coworker exclaimed "Oh! I have the perfect name: Rake ... -Get it? Ruby-Make. Rake!" He said he envisioned the tasks as leaves -and Rake would clean them up ... or something like that. Anyways, the -name stuck. - -Some quick examples ... - -A simple task to delete backup files ... - - task :clean do - Dir['*~'].each {|fn| rm fn rescue nil} - end - -Note that task names are symbols (they are slightly easier to type -than quoted strings ... but you may use quoted string if you would -rather). Rake makes the methods of the FileUtils module directly -available, so we take advantage of the <tt>rm</tt> command. Also note -the use of "rescue nil" to trap and ignore errors in the <tt>rm</tt> -command. - -To run it, just type "rake clean". Rake will automatically find a -Rakefile in the current directory (or above!) and will invoke the -targets named on the command line. If there are no targets explicitly -named, rake will invoke the task "default". - -Here's another task with dependencies ... - - task :clobber => [:clean] do - rm_r "tempdir" - end - -Task :clobber depends upon task :clean, so :clean will be run before -: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 -will be run only if the file doesn't exist, or if its modification time -is earlier than any of its prerequisites. - -Here is a file based dependency that will compile "hello.cc" to -"hello.o". - - file "hello.cc" - file "hello.o" => ["hello.cc"] do |t| - srcfile = t.name.sub(/\.o$/, ".cc") - sh %{g++ #{srcfile} -c -o #{t.name}} - end - -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. - -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 -easier. For instance, perhaps something like this ... - - require 'rake/ctools' - Dir['*.c'].each do |fn| - c_source_file(fn) - end - -where "c_source_file" will create all the tasks need to compile all the -C source files in a directory. Any number of useful libraries could be -created for rake. - -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 exercise and a tribute to the power of Ruby. - -Why /might/ rake be interesting to Ruby programmers. I don't know, -perhaps ... - -* No weird make syntax (only weird Ruby syntax :-) -* No need to edit or read XML (a la ant) -* Platform independent build scripts. -* Will run anywhere Ruby exists, so no need to have "make" installed. - If you stay away from the "sys" command and use things like - 'ftools', you can have a perfectly platform independent - build script. Also rake is only 100 lines of code, so it can - easily be packaged along with the rest of your code. - -So ... Sorry for the long rambling message. Like I said, I never -intended to write this code at all. Index: doc/rake/rakefile.rdoc =================================================================== --- doc/rake/rakefile.rdoc (revision 39184) +++ doc/rake/rakefile.rdoc (revision 39185) @@ -1,557 +0,0 @@ https://github.com/ruby/ruby/blob/trunk/doc/rake/rakefile.rdoc#L0 -= 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 -allowed in a Rakefile. - -Now that we understand there is no special syntax in a Rakefile, there -are some conventions that are used in a Rakefile that are a little -unusual in a typical Ruby program. Since a Rakefile is tailored to -specifying tasks and actions, the idioms used in a Rakefile are -designed to support that. - -So, what goes into a Rakefile? - -== Tasks - -Tasks are the main unit of work in a Rakefile. Tasks have a name -(usually given as a symbol or a string), a list of prerequisites (more -symbols or strings) and a list of actions (given as a block). - -=== Simple Tasks - -A task is declared by using the +task+ method. +task+ takes a single -parameter that is the name of the task. - - task :name - -=== Tasks with Prerequisites - -Any prerequisites are given as a list (enclosed in square brackets) -following the name and an arrow (=>). - - task :name => [:prereq1, :prereq2] - -<b>NOTE:</b> Although this syntax looks a little funky, it is legal -Ruby. We are constructing a hash where the key is :name and the value -for that key is the list of prerequisites. It is equivalent to the -following ... - - hash = Hash.new - hash[:name] = [:prereq1, :prereq2] - task(hash) - -=== Tasks with Actions - -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 parameter. - - task :name => [:prereq1, :prereq2] do |t| - # actions (may reference t) - end - -=== Multiple Definitions - -A task may be specified more than once. Each specification adds its -prerequisites and actions to the existing definition. This allows one -part of a rakefile to specify the actions and a different rakefile -(perhaps separately generated) to specify the dependencies. - -For example, the following is equivalent to the single task -specification given above. - - task :name - task :name => [:prereq1] - task :name => [:prereq2] - task :name do |t| - # actions - end - -== File Tasks - -Some tasks are designed to create a file from one or more other files. -Tasks that generate these files may be skipped if the file already -exists. File tasks are used to specify file creation tasks. - -File tasks are declared using the +file+ method (instead of the +task+ -method). In addition, file tasks are usually named with a string -rather than a symbol. - -The following file task creates a executable program (named +prog+) -given two object files name <tt>a.o</tt> and <tt>b.o</tt>. The tasks -for creating <tt>a.o</tt> and <tt>b.o</tt> are not shown. - - file "prog" => ["a.o", "b.o"] do |t| - sh "cc -o #{t.name} #{t.prerequisites.join(' ')}" - end - -== Directory Tasks - -It is common to need to create directories upon demand. The -+directory+ convenience method is a short-hand for creating a FileTask -that creates the directory. For example, the following declaration -... - - directory "testdata/examples/doc" - -is equivalent to ... - - file "testdata" do |t| mkdir t.name end - file "testdata/examples" do |t| mkdir t.name end - file "testdata/examples/doc" do |t| mkdir t.name end - -The +directory+ method does not accept prerequisites or actions, but -both prerequisites and actions can be added later. For example ... - - directory "testdata" - file "testdata" => ["otherdata"] - file "testdata" do - cp Dir["standard_data/*.data"], "testdata" - end - -== Tasks with Parallel Prerequisites - -Rake allows parallel execution of prerequisites using the following syntax: - - multitask :copy_files => [:copy_src, :copy_doc, :copy_bin] do - puts "All Copies Complete" - end - -In this example, +copy_files+ is a normal rake task. Its actions are -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 prerequisites of a multitask have common secondary -prerequisites, all of the primary/parallel prerequisites will wait -until the common prerequisites have been run. - -For example, if the <tt>copy_<em>xxx</em></tt> tasks have the -following prerequisites: - - task :copy_src => [:prep_for_copy] - task :copy_bin => [:prep_for_copy] - task :copy_doc => [:prep_for_copy] - -Then the +prep_for_copy+ task is run before starting all the copies in -parallel. Once +prep_for_copy+ is complete, +copy_src+, +copy_bin+, -and +copy_doc+ are all run in parallel. Note that +prep_for_copy+ is -run only once, even though it is referenced in multiple threads. - -=== Thread Safety - -The Rake internal data structures are thread-safe with respect -to the multitask parallel execution, so there is no need for the user -to do extra synchronization for Rake's benefit. However, if there are -user data structures shared between the parallel prerequisites, the -user must do whatever is necessary to prevent race conditions. - -== Tasks with Arguments - -Prior to version 0.8.0, rake was only able to handle command line -arguments of the form NAME=VALUE that were passed into Rake via the -ENV hash. Many folks had asked for some kind of simple command line -arguments, perhaps using "--" to separate regular task names from -argument values on the command line. The problem is that there was no -easy way to associate positional arguments on the command line with -different tasks. Suppose both tasks :a and :b expect a command line -argument: does the first value go with :a? What if :b is run first? -Should it then get the first command line argument. - -Rake 0.8.0 solves this problem by explicitly passing values directly -to the tasks that need them. For example, if I had a release task -that required a version number, I could say: - - rake release[0.8.2] - -And the string "0.8.2" will be passed to the :relea (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/