From 2bfa96ec848f9c8e27006776be17e2f818e58761 Mon Sep 17 00:00:00 2001 From: zzak Date: Sun, 10 Feb 2013 05:26:34 +0000 Subject: * doc/rake/, lib/rake/doc/: Move Rake rdoc files to lib/rake git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@39185 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- doc/rake/README | 196 -------------- doc/rake/command_line_usage.rdoc | 169 ------------ doc/rake/glossary.rdoc | 51 ---- doc/rake/rakefile.rdoc | 557 --------------------------------------- doc/rake/rational.rdoc | 151 ----------- 5 files changed, 1124 deletions(-) delete mode 100644 doc/rake/README delete mode 100644 doc/rake/command_line_usage.rdoc delete mode 100644 doc/rake/glossary.rdoc delete mode 100644 doc/rake/rakefile.rdoc delete mode 100644 doc/rake/rational.rdoc (limited to 'doc') diff --git a/doc/rake/README b/doc/rake/README deleted file mode 100644 index 41668dd727..0000000000 --- a/doc/rake/README +++ /dev/null @@ -1,196 +0,0 @@ -= RAKE -- Ruby Make - -Supporting Rake version: 0.8.6 - -This package contains Rake, a simple ruby build program with -capabilities similar to make. - -Rake has the following features: - -* Rakefiles (rake's version of Makefiles) are completely defined in - standard Ruby syntax. No XML files to edit. No quirky Makefile - syntax to worry about (is that a tab or a space?) - -* Users can specify tasks with prerequisites. - -* Rake supports rule patterns to synthesize implicit tasks. - -* Flexible FileLists that act like arrays but know about manipulating - file names and paths. - -* A library of prepackaged tasks to make building rakefiles easier. For example, - tasks for building tarballs, gems and RDoc output are provided. - -* Supports parallel execution of tasks. - - -== Installation - -=== Gem Installation - -Download and install rake with the following. - - gem install rake - -=== Normal Installation - -You can download the source tarball of the latest version of Rake from - -* http://rubyforge.org/project/showfiles.php?group_id=50 - -Extract the tarball and run - - % ruby install.rb - -from its distribution directory. - -== Usage - -=== Simple Example - -First, you must write a "Rakefile" file which contains the build rules. Here's -a simple example: - - task :default => [:test] - - task :test do - ruby "test/unittest.rb" - end - -This Rakefile has two tasks: - -* A task named "test", which - upon invocation - will run a unit test file in - Ruby. -* A task named "default". This task does nothing by itself, but it has exactly - one dependency, namely the "test" task. Invoking the "default" task will - cause Rake to invoke the "test" task as well. - -Running the "rake" command without any options will cause it to run the -"default" task in the Rakefile: - - % ls - Rakefile test/ - % rake - (in /home/some_user/Projects/rake) - ruby test/unittest.rb - ....unit test output here... - -Type "rake --help" for all available options. - - -=== More Information - -* For details on Rake's command-line invocation, read - doc/command_line_usage.rdoc[http://rake.rubyforge.org/files/doc/command_line_usage_rdoc.html] -* For details on writing Rakefiles, see - doc/rakefile.rdoc[http://rake.rubyforge.org/files/doc/rakefile_rdoc.html]. -* For the original announcement of Rake, see - doc/rational.rdoc[http://rake.rubyforge.org/files/doc/rational_rdoc.html]. -* For a glossary of terms, see - doc/glossary.rdoc[http://rake.rubyforge.org/files/doc/glossary_rdoc.html]. - - -== Development - -=== Source Repository - -Rake is currently hosted at github. The github web page is -http://github.com/jimweirich/rake. The public git clone URL is - -* git://github.com/jimweirich/rake.git - -=== Running the Rake Test Suite - -If you wish to run the unit and functional tests that come with Rake: - -* Install the 'session' gem in order to run the functional tests. -* CD into the top project directory of rake. -* Type one of the following: - - rake # If you have a version of rake installed - ruby -Ilib bin/rake # If you do not have a version of rake installed. - -=== Issues and Bug Reports - -Bugs, features requests and other issues can be logged at - -* http://onestepback.org/redmine/projects/show/rake - -You will need an account to before you can post issues. Register at -http://onestepback.org/redmine/account/register. Or you can send me -an email (at jim dot weirich at gmail dot com) - - -== Online Resources - -=== Rake References - -* Rake Documentation Home: http://docs.rubyrake.org -* Rake Project Page: http://rubyforge.org/projects/rake -* Rake API Documents: http://rake.rubyforge.org -* Rake Source Code Repo: http://github.com/jimweirich/rake -* Rake Git Repo Clone URL: git://github.com/jimweirich/rake.git - -=== Presentations and Articles about Rake - -* Jim Weirich's 2003 RubyConf presentation: http://onestepback.org/articles/buildingwithrake/ -* Martin Fowler's article on Rake: http://martinfowler.com/articles/rake.html - -== Other Make Reinvisionings ... - -Rake is a late entry in the make replacement field. Here are links to -other projects with similar (and not so similar) goals. - -* http://directory.fsf.org/bras.html -- Bras, one of earliest - implementations of "make in a scripting language". -* http://www.a-a-p.org -- Make in Python -* http://www.aromatic.com/tools/jam.txt -- JAM, Java Automated Make -* http://ant.apache.org -- The Ant project -* http://ppt.perl.org/commands/make/index.html -- Make from the Perl - Power Tools implementation. -* http://search.cpan.org/search?query=PerlBuildSystem -- The Perl Build System -* http://make.rubyforge.org -- Rant, another Ruby make tool. - -== Credits - -[Ryan Dlugosz] For the initial conversation that sparked Rake. - -[nobu.nokada@softhome.net] For the initial patch for rule support. - -[Tilman Sauerbeck ] For the recursive rule patch. - -== License - -Rake is available under an MIT-style license. - -:include: MIT-LICENSE - -== Support - -The Rake homepage is http://rake.rubyforge.org. You can find the Rake -RubyForge page at http://rubyforge.org/projects/rake. - -Feel free to submit commits or feature requests. If you send a patch, -remember to update the corresponding unit tests. If fact, I prefer -new feature to be submitted in the form of new unit tests. - -For other information, feel free to ask on the ruby-talk mailing list -(which is mirrored to comp.lang.ruby) or contact -jim dot weirich at gmail.com. - ---- - -= Other stuff - -Author:: Jim Weirich -Requires:: Ruby 1.8.0 or later -License:: Copyright 2003-2008 by Jim Weirich. - Released under an MIT-style license. See the LICENSE file - included in the distribution. - -== Warranty - -This software is provided "as is" and without any express or -implied warranties, including, without limitation, the implied -warranties of merchantibility and fitness for a particular -purpose. diff --git a/doc/rake/command_line_usage.rdoc b/doc/rake/command_line_usage.rdoc deleted file mode 100644 index 688e55a9af..0000000000 --- a/doc/rake/command_line_usage.rdoc +++ /dev/null @@ -1,169 +0,0 @@ -= Rake Command Line Usage - -Rake is invoked from the command line using: - - % rake [options ...] [VAR=VALUE ...] [targets ...] - -Options are: - -[name=value] - Set the environment variable name to value - during the execution of the rake command. You can access - the value by using ENV['name']. - -[--all (-A)] - Used in combination with the -T and -D options, will force - those options to show all the tasks, even the ones without comments. - -[--backtrace{=_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 stdout, then backtrace output is directed to - stardard output. If _output_ is stderr, or if it is - missing, then the backtrace output is sent to standard error. - -[--classic-namespace (-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 require - 'rake/classic_namespace' in your Rakefile to get the - classic behavior. - -[--comments] - Used in combination with the -W options to force the output to - contain commented options only. This is the reverse of - --all. - -[--describe _pattern_ (-D)] - Describe the tasks (matching optional PATTERN), then exit. - -[--dry-run (-n)] - Do a dry run. Print the tasks invoked and executed, but do not - actually execute any of the actions. - -[--execute _code_ (-e)] - Execute some Ruby code and exit. - -[--execute-print _code_ (-p)] - Execute some Ruby code, print the result, and exit. - -[--execute-continue _code_ (-E)] - Execute some Ruby code, then continue with normal task processing. - -[--help (-H)] - Display some help text and exit. - -[--jobs _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 multitask prerequisites. - Also see the -m 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 - -[--job-stats _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 history, then a complete trace - of task history will be displayed on standard output. - -[--libdir _directory_ (-I)] - Add _directory_ to the list of directories searched for require. - -[--multitask (-m)] - Treat all tasks as multitasks. ('make/drake' semantics) - -[--nosearch (-N)] - Do not search for a Rakefile in parent directories. - -[--prereqs (-P)] - Display a list of all tasks and their immediate prerequisites. - -[--quiet (-q)] - Do not echo commands from FileUtils. - -[--rakefile _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. - -[--rakelibdir _rakelibdir_ (-R)] - Auto-import any .rake files in RAKELIBDIR. (default is 'rakelib') - -[--reduce-compat] - - 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. - -[--require _name_ (-r)] - Require _name_ before executing the Rakefile. - -[--rules] - Trace the rules resolution. - -[--silent (-s)] - Like --quiet, but also suppresses the 'in directory' announcement. - -[--suppress-backtrace _pattern_ ] - 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. - -[--system (-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. - -[--no-system (-G)] - Use the project level Rakefile, ignoring the system-wide (global) - rakefiles. - -[--tasks pattern (-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. - -[--trace{=_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 - stdout, then trace output is directed to stardard output. - If _output_ is stderr, or if it is missing, then trace - output is sent to standard error. - -[--verbose (-v)] - Echo the Sys commands to standard output. - -[--version (-V)] - Display the program version and exit. - -[--where pattern (-W)] - Display tasks that match pattern 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. - -[--no-deprecation-warnings (-W)] - Do not display the deprecation warnings. - -In addition, any command line option of the form -VAR=VALUE will be added to the environment hash -ENV and may be tested in the Rakefile. diff --git a/doc/rake/glossary.rdoc b/doc/rake/glossary.rdoc deleted file mode 100644 index a811764091..0000000000 --- a/doc/rake/glossary.rdoc +++ /dev/null @@ -1,51 +0,0 @@ -= Glossary - -[action] - Code to be executed in order to perform a task. Actions in a - rakefile are specified in a code block (usually delimited by - +do+/+end+ pairs. - -[execute] - When a task is executed, all of its actions are performed, in - the order they were defined. Note that unlike - invoke, execute always executes the actions - (without invoking or executing the prerequisites). - -[file task (FileTask)] - A file task is a task whose purpose is to create a file - (which has the same name as the task). When invoked, a file - task will only execute if one or more of the following - conditions are true. - - 1. The associated file does not exist. - 2. A prerequisite has a later time stamp than the existing file. - - Because normal Tasks always have the current time as - timestamp, a FileTask that has a normal Task prerequisite - will always execute. - -[invoke] - When a task is invoked, first we check to see if it has been - invoked before. if it has been, then nothing else is done. - If this is the first time its been invoked, then we invoke - each of its prerequisites. Finally, we check to see if we - need to execute the actions of this task by calling - needed?. Finally, if the task is needed, we execute - its actions. - - NOTE: Currently prerequisites are invoked even if the task is - not needed. This may change in the future. - -[prerequisites] - Every task has a set (possibly empty) of prerequisites. A - prerequisite P to Task T is itself a task that must be invoked - before Task T. - -[rule] - A rule is a recipe for synthesizing a task when no task is - explicitly defined. Rules generally synthesize file tasks. - -[task (Task)] - Basic unit of work in a rakefile. A task has a name, a set of - prerequisites and a list of actions to be performed. - diff --git a/doc/rake/rakefile.rdoc b/doc/rake/rakefile.rdoc deleted file mode 100644 index a00c9fd21e..0000000000 --- a/doc/rake/rakefile.rdoc +++ /dev/null @@ -1,557 +0,0 @@ -= 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] - -NOTE: 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 a.o and b.o. The tasks -for creating a.o and b.o 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 copy_xxx 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 :release task. Multiple -arguments can be passed by separating them with a comma, for example: - - rake name[john,doe] - -Just a few words of caution. The rake task name and its arguments -need to be a single command line argument to rake. This generally -means no spaces. If spaces are needed, then the entire rake + -argument string should be quoted. Something like this: - - rake "name[billy bob, smith]" - -(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 -order to handle named parameters, the task declaration syntax for -tasks has been extended slightly. - -For example, a task that needs a first name and last name might be -declared as: - - task :name, [:first_name, :last_name] - -The first argument is still the name of the task (:name in this case). -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 parameters, the block defining the task -behaviour can now accept a second parameter: - - task :name, [:first_name, :last_name] do |t, args| - puts "First name is #{args.first_name}" - puts "Last name is #{args.last_name}" - end - -The first argument of the block "t" is always bound to the current -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 -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 -where we specify default values for the first and last names: - - task :name, [:first_name, :last_name] do |t, args| - args.with_defaults(:first_name => "John", :last_name => "Dough") - puts "First name is #{args.first_name}" - puts "Last name is #{args.last_name}" - end - -=== Tasks that Expect Parameters and Have Prerequisites - -Tasks that use parameters have a slightly different format for -prerequisites. Use the arrow notation to indicate the prerequisites -for tasks with arguments. For example: - - task :name, [:first_name, :last_name] => [:pre_name] do |t, args| - args.with_defaults(:first_name => "John", :last_name => "Dough") - puts "First name is #{args.first_name}" - puts "Last name is #{args.last_name}" - end - -=== Deprecated Task Parameters Format - -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. The older format may be dropped in future -versions of rake. - -== Accessing Task Programmatically - -Sometimes it is useful to manipulate tasks programmatically in a -Rakefile. To find a task object, use the :[] operator on the -Rake::Task. - -=== Programmatic Task Example - -For example, the following Rakefile defines two tasks. The :doit task -simply prints a simple "DONE" message. The :dont class will lookup -the doit class and remove (clear) all of its prerequisites and -actions. - - task :doit do - puts "DONE" - end - - task :dont do - Rake::Task[:doit].clear - end - -Running this example: - - $ rake doit - (in /Users/jim/working/git/rake/x) - 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 -should be used with cation. - -== Rules - -When a file is named as a prerequisite, but does not have a file task -defined for it, Rake will attempt to synthesize a task by looking at a -list of rules supplied in the Rakefile. - -Suppose we were trying to invoke task "mycode.o", but no task is -defined for it. But the rakefile has a rule that look like this ... - - rule '.o' => ['.c'] do |t| - sh "cc #{t.source} -c -o #{t.name}" - end - -This rule will synthesize any task that ends in ".o". It has a -prerequisite a source file with an extension of ".c" must exist. If -Rake is able to find a file named "mycode.c", it will automatically -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. - -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 -rules with actions that reference the source file. - -=== Advanced Rules - -Any regular expression may be used as the rule pattern. Additionally, -a proc may be used to calculate the name of the source file. This -allows for complex patterns and sources. - -The following rule is equivalent to the example above. - - rule( /\.o$/ => [ - proc {|task_name| task_name.sub(/\.[^.]+$/, '.c') } - ]) do |t| - sh "cc #{t.source} -c -o #{t.name}" - end - -NOTE: Because of a _quirk_ in Ruby syntax, parenthesis are -required on *rule* when the first argument is a regular expression. - -The following rule might be used for Java files ... - - rule '.java' => [ - proc { |tn| tn.sub(/\.class$/, '.java').sub(/^classes\//, 'src/') } - ] do |t| - java_compile(t.source, t.name) - end - -NOTE: +java_compile+ is a hypothetical method that invokes the -java compiler. - -== Importing Dependencies - -Any ruby file (including other rakefiles) can be included with a -standard Ruby +require+ command. The rules and declarations in the -required file are just added to the definitions already accumulated. - -Because the files are loaded _before_ the rake targets are evaluated, -the loaded files must be "ready to go" when the rake command is -invoked. This make generated dependency files difficult to use. By -the time rake gets around to updating the dependencies file, it is too -late to load it. - -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. - -NOTE: 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: - - require 'rake/loaders/makefile' - - file ".depends.mf" => [SRC_LIST] do |t| - sh "makedepend -f- -- #{CFLAGS} -- #{t.prerequisites} > #{t.name}" - end - - 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 -loading. - -== Comments - -Standard Ruby comments (beginning with "#") can be used anywhere it is -legal in Ruby source code, including comments for tasks and rules. -However, if you wish a task to be described using the "-T" switch, -then you need to use the +desc+ command to describe the task. - -=== Example: - - desc "Create a distribution package" - 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 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) - rake clean # Remove any temporary products. - rake clobber # Remove any generated file. - rake clobber_rdoc # Remove rdoc products - rake contrib_test # Run tests for contrib_test - rake default # Default Task - rake install # Install the application - rake lines # Count lines in the main rake file - rake rdoc # Build the rdoc HTML Files - rake rerdoc # Force a rebuild of the RDOC files - rake test # Run tests - rake testall # Run all test targets - -Only tasks with descriptions will be displayed with the "-T" switch. -Use "-P" (or "--prereqs") to get a list of all tasks and their -prerequisites. - -== Namespaces - -As projects grow (and along with it, the number of tasks), it is -common for task names to begin to clash. For example, if you might -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 interfere with -each other. - -For example: - - namespace "main" do - task :build do - # Build the main program - end - end - - namespace "samples" do - task :build do - # Build the sample programs - end - end - - task :build => ["main:build", "samples:build"] - -Referencing a task in a separate namespace can be achieved by -prefixing the task name with the namespace and a colon -(e.g. "main:build" refers to the :build task in the +main+ namespace). -Nested namespaces are supported, so - -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. - -=== FileTasks - -File task names are not scoped by the namespace command. Since the -name of a file task is the name of an actual file in the file system, -it makes little sense to include file task names in name space. -Directory tasks (created by the +directory+ command) are a type of -file task and are also not affected by namespaces. - -=== Name Resolution - -When looking up a task name, rake will start with the current -namespace and attempt to find the name there. If it fails to find a -name in the current namespace, it will search the parent namespaces -until a match is found (or an error occurs if there is no match). - -The "rake" namespace is a special implicit namespace that refers to -the toplevel names. - -If a task name begins with a "^" character, the name resolution will -start in the parent namespace. Multiple "^" characters are allowed. - -Here is an example file with multiple :run tasks and how various names -resolve in different locations. - - task :run - - namespace "one" do - task :run - - namespace "two" do - task :run - - # :run => "one:two:run" - # "two:run" => "one:two:run" - # "one:two:run" => "one:two:run" - # "one:run" => "one:run" - # "^run" => "one:run" - # "^^run" => "rake:run" (the top level task) - # "rake:run" => "rake:run" (the top level task) - end - - # :run => "one:run" - # "two:run" => "one:two:run" - # "^run" => "rake:run" - end - - # :run => "rake:run" - # "one:run" => "one:run" - # "one:two:run" => "one:two:run" - -== FileLists - -FileLists are the way Rake manages lists of files. You can treat a -FileList as an array of strings for the most part, but FileLists -support some additional operations. - -=== Creating a FileList - -Creating a file list is easy. Just give it the list of file names: - - fl = FileList['file1.rb', file2.rb'] - -Or give it a glob pattern: - - fl = FileList['*.rb'] - -== Odds and Ends - -=== do/end versus { } - -Blocks may be specified with either a +do+/+end+ pair, or with curly -braces in Ruby. We _strongly_ recommend using +do+/+end+ to specify the -actions for tasks and rules. Because the rakefile idiom tends to -leave off parentheses on the task/file/rule methods, unusual -ambiguities can arise when using curly braces. - -For example, suppose that the method +object_files+ returns a list of -object files in a project. Now we use +object_files+ as the -prerequisites in a rule specified with actions in curly braces. - - # DON'T DO THIS! - file "prog" => object_files { - # Actions are expected here (but it doesn't work)! - } - -Because curly braces have a higher precedence than +do+/+end+, the -block is associated with the +object_files+ method rather than the -+file+ method. - -This is the proper way to specify the task ... - - # THIS IS FINE - file "prog" => object_files do - # Actions go here - end - ----- - -== See - -* README.rdoc -- Main documentation for Rake. diff --git a/doc/rake/rational.rdoc b/doc/rake/rational.rdoc deleted file mode 100644 index 0e1c33873d..0000000000 --- a/doc/rake/rational.rdoc +++ /dev/null @@ -1,151 +0,0 @@ -= 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 rm command. Also note -the use of "rescue nil" to trap and ignore errors in the rm -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. -- cgit v1.2.3