diff options
Diffstat (limited to 'doc/rake')
| -rw-r--r-- | doc/rake/CHANGES | 440 | ||||
| -rw-r--r-- | doc/rake/README | 196 | ||||
| -rw-r--r-- | doc/rake/command_line_usage.rdoc | 102 | ||||
| -rw-r--r-- | doc/rake/example/Rakefile1 | 38 | ||||
| -rw-r--r-- | doc/rake/example/Rakefile2 | 35 | ||||
| -rw-r--r-- | doc/rake/example/a.c | 6 | ||||
| -rw-r--r-- | doc/rake/example/b.c | 6 | ||||
| -rw-r--r-- | doc/rake/example/main.c | 11 | ||||
| -rw-r--r-- | doc/rake/glossary.rdoc | 51 | ||||
| -rw-r--r-- | doc/rake/jamis.rb | 591 | ||||
| -rw-r--r-- | doc/rake/proto_rake.rdoc | 127 | ||||
| -rw-r--r-- | doc/rake/rakefile.rdoc | 534 | ||||
| -rw-r--r-- | doc/rake/rational.rdoc | 151 | ||||
| -rw-r--r-- | doc/rake/release_notes/rake-0.8.7.rdoc | 55 |
14 files changed, 2343 insertions, 0 deletions
diff --git a/doc/rake/CHANGES b/doc/rake/CHANGES new file mode 100644 index 0000000000..3b1a02b812 --- /dev/null +++ b/doc/rake/CHANGES @@ -0,0 +1,440 @@ + += Rake Changelog + +== Version 0.8.7 + +* Fixed EXEEXT for JRuby on windows. + +== Version 0.8.6 + +* Minor fixes to the RDoc generation (removed dependency on darkfish + and removed inline source option). + +== Version 0.8.5 + +* Better support for the system command on Windows. + +== Version 0.8.4 + +* Preserve case when locating rakefiles (patch from James + M. Lawrence/quix) + +* Better support for windows paths in the test task (patch from Simon + Chiang/bahuvrihi) + +* Windows system dir search order is now: HOME, HOMEDRIVE + HOMEPATH, + APPDATA, USERPROFILE (patch from Luis Lavena) + +* MingGW is now recognized as a windows platform. (patch from Luis + Lavena) + +* Numerous fixes to the windows test suite (patch from Luis Lavena). + +* Improved Rakefile case insensitivity testing (patch from Luis + Lavena). + +* Fixed stray ARGV option problem that was interfering with + Test::Unit::Runner. + +* Fixed default verbose mode (was accidently changed to false). + +* Removed reference to manage_gem to fix the warning produced by the + gem package task. + +== Version 0.8.3 + +* Enhanced the system directory detection in windows. We now check + HOMEDRIVE/HOMEPATH and USERPROFILE if APPDATA isn't found. (Patch + supplied by James Tucker). Rake no long aborts if it can't find the + directory. + +* Added fix to handle ruby installations in directories with spaces in + their name. + +== Version 0.8.2 + +* Fixed bug in package task so that it will include the subdir + directory in the package for testing. (Bug found by Adam Majer) + +* Added ENV var to rakefile to prevent OS X from including extended + attribute junk in a tar file. (Bug found by Adam Majer) + +* Fixed filename dependency order bug in test_inspect_pending and + test_to_s_pending. (Bug found by Adam Majer) + +* Fixed check for file utils options to make them immune to the + symbol/string differences. (Patch supplied by Edwin Pratomo) + +* Fixed bug with rules involving multiple source (Patch supplied by + Emanuel Indermühle) + +* Switched from getoptlong to optparse (patches supplied by Edwin + Pratomo) + +* The -T option will now attempt to dynamically sense the size of the + terminal. RAKE_COLUMNS will override any dynamic sensing. + +* FileList#clone and FileList#dup have better sematics w.r.t. taint + and freeze. + +* Added ability clear prerequisites, and/or actions from an existing + task. + +* Added the ability to reenable a task to be invoked a second time. + +* Changed RDoc test task to have no default template. This makes it + easier for the tempate to pick up the template from the environment. + +* Changed from using Mutex to Monitor. Evidently Mutex causes thread + join errors when Ruby is compiled with -disable-pthreads. (Patch + supplied by Ittay Dror) + +* Fixed bug in makefile parser that had problems with extra spaces in + file task names. (Patch supplied by Ittay Dror) + +* Added a performance patch for reading large makefile dependency + files. (Patch supplied by Ittay Dror) + +* Default values for task arguments can easily be specified with the + :with_defaults method. (Idea for default argument merging supplied + by (Adam Q. Salter) + +* The -T output will only self-truncate if the output is a tty. + However, if RAKE_COLUMNS is explicitly set, it will be honored in + any case. (Patch provided by Gavin Stark). + +* Numerous fixes for running under windows. A big thanks to Bheeshmar + Redheendran for spending a good part of the afternoon at the + Lonestar Ruby Conference to help me work out these issues. + +== Version 0.8.1 + +* Removed requires on parsedate.rb (in Ftptools) +* Removed ftools from rake.rb. Made it options in sys.rb + +== Version 0.8.0 + +* Added task parameters (e.g. "rake build[version7]") +* Made task parameters passable to prerequisites. +* Comments are limited to 80 columns or so (suggested by Jamis Buck). +* Added -D to display full comments (suggested by Jamis Buck). +* The rake program will set the status value used in any explicit + exit(n) calls. (patch provided by Stephen Touset) +* Fixed error in functional tests that were not including session (and + silently skipping the functionl tests. +* Removed --usage and make -h the same as -H. +* Make a prettier inspect for tasks. + +== Version 0.7.3 + +* Added existing and existing! methods to FileList +* FileLists now claim to be Arrays (via is_a?) to get better support + from the FileUtil module. +* Added init and top_level for custom rake applications. + +== Version 0.7.2 + +* Error messages are now send to stderr rather than stdout (from + Payton Quackenbush). +* Better error handling on invalid command line arguments (from Payton + Quackenbush). +* Added rcov task and updated unit testing for better code coverage. +* Fixed some bugs where the application object was going to the global + appliation instead of using its own data. +* Added square and curly bracket patterns to FileList#include (Tilman + Sauerbeck). +* Added plain filename support to rule dependents (suggested by Nobu + Nakada). +* Added pathmap support to rule dependents. +* Added a 'tasks' method to a namespace to get a list of tasks + associated with the namespace. +* Fixed the method name leak from FileUtils (bug found by Glenn + Vanderburg). +* Added rake_extension to handle detection of extension collisions. +* Added test for noop, bad_option and verbose flags to sh command. +* Removed dependency on internal fu_xxx functions from FileUtils. +* Added a 'shame' task to the Rakefile. +* Added tar_command and zip_command options to the Package task. +* Added a description to the gem task in GemPackageTask. +* Fixed a bug when rules have multiple prerequisites (patch by Joel + VanderWerf) +* Added a protected 'require "rubygems"' to test/test_application to + unbreak cruisecontrol.rb. +* Added the handful of RakeFileUtils to the private method as well. +* Added block based exclusion. +* The clean task will no longer delete 'core' if it is a directory. +* Removed rake_dup. Now we just simply rescue a bad dup. +* Refactored the FileList reject logic to remove duplication. +* Removed if __FILE__ at the end of the rake.rb file. + +== Version 0.7.1 + +* Added optional filter parameter to the --tasks command line option. +* Added flatten to allow rule transform procs to return lists of + prereqs (Joel VanderWerf provided patch). +* Added pathmap to String and FileList. +* The -r option will now load .rake files (but a straight require + doesn't yet). NOTE: This is experimental ... it may be + discontinued. +* The -f option without a value will disable the search for a + Rakefile. The assumption is that the -r files are adequate. +* Fixed the safe_ln function to fall back to cp in more error + scenarios. + +== Version 0.7.0 + +* Added Rake.original_dir to return the original starting directory of + the rake application. +* Added safe_ln support for openAFS (from Ludvig Omholt). +* Added --trace reminder on short exception messages (David Heinemeier + Hansson suggestion). +* Added multitask declaration that executes prerequisites in + parallel. (Doug Young providied an initial implementation). +* Fixed missing_const hack to be compatible with Rails. (Jamis Buck + supplied test case). +* Made the RDoc task default to internal (in-process) RDoc formatting. + The old behavior is still available by setting the +external+ flag + to true. +* Rakefiles are now loaded with the expanded path to prevent + accidental polution from the Ruby load path. +* The +namespace+ command now returns a NameSpace object that can be + used to lookup tasks defined in that namespace. This allows for + better anonymous namespace behavior. +* Task objects my now be used in prerequisite lists directly. + +== Version 0.6.1 + +* Rebuilt 0.6.0 gem without signing. + +== Version 0.6.0 + +* Fixed file creation bug in the unit tests (caused infinite loop on + windows). +* Fixed bug where session based functional tests were run under + windows. +* Fixed bug in directory tasks so that updating a directory will not + retrigger file tasks depending on the directory (see + FileCreationTask and EarlyTime). +* Added egrep to FileList +* ruby command now runs same ruby version as rake. +* Added investigation to task object. (suggested by Martin Fowler) +* Added ruby_opts to the test task to allow arbitrary ruby options to + be passed to the test script. (Greg Fast) +* Fixed the test loader to ignore options. (Greg Fast) +* Moved Task, FileTask, FileCreationTask and RakeApp into the Rake + module namespace. Old style namespace behavior can be invoked via + the --classic-namespace option. (requested by Kelly Felkins). +* GemTask is now sensitive to the gem platform (Masao Mutoh). +* A non-existing file prerequisite will no longer cause an exception + (Philipp Neubeck). +* Multiple prerequisites on Rake rules now allowed (initial patch + supplied by Stuart Jansen). + +== Version 0.5.4 + +* Added double quotes to the test runner. +* Added .svn to default ignore list. +* Updated FileList#include to support nested arrays and filelists. + +== Version 0.5.3 + +* Added support for importing Rakefile and other dependencies. +* Fixed bug so that now rules can chain off of existing tasks as well + as existing files. +* Fixed verbose flag bug in the testing task. Shortened some failure + messages. +* Make FileUtils methods private at the top level module to avoid + accidental method leaking into other objects. +* Added test loader option to test task. "testrb" is no longer the + default test loader. It is now eating syntax errors that should + halt the unit tests. +* Revamped FileList so that it works more like and array (addressed + flatten bug). Added many tests around file list. +* Added +ext+ method to both String and FileList. + +== Version 0.5.0 + +* Fixed documentation that was lacking the Rake module name (Tilman + Sauerbeck). +* Added tar.gz and tar.bz2 support to package task (Tilman Sauerbeck). +* Recursive rules are now supported (Tilman Sauerbeck). +* Added warning option for the Test Task (requested by Eric Hodel). +* The jamis rdoc template is only used if it exists. +* Added fix for Ruby 1.8.2 test/unit and rails problem. +* Added contributed rake man file (Jani Monoses). +* Added Brian Candler's fix for problems in --trace and --dry-run + mode. + +== Version 0.4.15 + +* Fixed a bug that prevented the TESTOPTS flag from working with the + revised for 1.8.2 test task. +* Updated the docs on --trace to indicate that it also enables a full + backtrace on errors. + +== Version 0.4.14 + +* Modified the TestTask to workaround the Ruby 1.8.2 change in + autoexecuting unit tests. + +== Version 0.4.13 + +* Fixed the dry-run flag so it is operating again. +* Multiple arguments to sh and ruby commands will not be interpreted + by the shell (patch provided by Jonathan Paisley). + +== Version 0.4.12 + +* Added --silent (-s) to suppress the (in directory) rake message. + +== Version 0.4.11 + +* Changed the "don't know how to rake" message (finally) +* Changes references to a literal "Rakefile" to reference the global + variable $rakefile (which contains the actual name of the rakefile). + +== Version 0.4.10 + +* Added block support to the "sh" command, allowing users to take + special actions on the result of the system call. E.g. + + sh "shell_command" do |ok, res| + puts "Program returned #{res.exitstatus}" if ! ok + end + +== Version 0.4.9 + +* Switched to Jamis Buck's RDoc template. +* Removed autorequire from Rake's gem spec. This prevents the Rake + libraries from loading while using rails. + +== Version 0.4.8 + +* Added support for .rb versions of Rakefile. +* Removed \\\n's from test task. +* Fixed Ruby 1.9 compatibility issue with FileList. + +== Version 0.4.7 + +* Fixed problem in FileList that caused Ruby 1.9 to go into infinite + recursion. Since to_a was removed from Object, it does not need to + added back into the list of methods to rewrite in FileList. (Thanks + to Kent Sibilev for pointing this out). + +== Version 0.4.6 +* Removed test version of ln in FileUtils that prevented safe_ln from + using ln. + +== Version 0.4.5 +* Upgraded comments in TestTask. +* FileList to_s and inspect now automatically resolve pending changes. +* FileList#exclude properly returns the FileList. + +== Version 0.4.4 +* Fixed initialization problem with @comment. +* Now using multi -r technique in TestTask. Switch Rakefile back to + using the built-in test task macros because the rake runtime is no + longer needed. +* Added 'TEST=filename' and 'TESTOPTS=options' to the Test Task + macros. +* Allow a +test_files+ attribute in test tasks. This allows more + flexibility in specifying test files. + +== Version 0.4.3 +* Fixed Comment leakage. + +== Version 0.4.2 +* Added safe_ln that falls back to a copy if a file link is not supported. +* Package builder now uses safe_ln. + +== Version 0.4.1 +* Task comments are now additive, combined with "/". +* Works with (soon to be released) rubygems 0.6.2 (or 0.7.0) + +== Version 0.4.0 +* FileList now uses deferred loading. The file system is not searched + until the first call that needs the file names. +* VAR=VALUE options are now accepted on the command line and are + treated like environment variables. The values may be tested in a + Rakefile by referencing ENV['VAR']. +* File.mtime is now used (instead of File.new().mtime). + +== Version 0.3.2.x + +* Removed some hidden dependencies on rubygems. Tests now will test + gems only if they are installed. +* Removed Sys from some example files. I believe that is that last + reference to Sys outside of the contrib area. +* Updated all copyright notices to include 2004. + +== Version 0.3.2 + +* GEM Installation now works with the application stub. + +== Version 0.3.1 + +* FileLists now automatically ignore CVS, .bak, ! +* GEM Installation now works. + +== Version 0.3.0 + +Promoted 0.2.10. + +== Version 0.2.10 +General + +* Added title to Rake's rdocs +* Contrib packages are no longer included in the documentation. + +RDoc Issues + +* Removed default for the '--main' option +* Fixed rendering of the rdoc options +* Fixed clean/clobber confusion with rerdoc +* 'title' attribute added + +Package Task Library Issues + +* Version (or explicit :noversion) is required. +* +package_file+ attribute is now writable + +FileList Issues + +* Dropped bang version of exclude. Now using ant-like include/exclude semantics. +* Enabled the "yield self" idiom in FileList#initialize. + +== Version 0.2.9 + +This version contains numerous changes as the RubyConf.new(2003) +presentation was being prepared. The changes include: + +* The monolithic rubyapp task library is in the process of being + dropped in favor of lighter weight task libraries. + +== Version 0.2.7 + +* Added "desc" for task descriptions. +* -T will now display tasks with descriptions. +* -P will display tasks and prerequisites. +* Dropped the Sys module in favor of the 1.8.x FileUtils module. Sys + is still supported in the contrib area. + +== Version 0.2.6 + +* Moved to RubyForge + +== Version 0.2.5 + +* Switched to standard ruby app builder. +* Added no_match option to file matcher. + +== Version 0.2.4 + +* Fixed indir, which neglected to actually change directories. + +== Version 0.2.3 + +* Added rake module for a help target +* Added 'for_files' to Sys +* Added a $rakefile constant +* Added test for selecting proper rule with multiple targets. diff --git a/doc/rake/README b/doc/rake/README new file mode 100644 index 0000000000..41668dd727 --- /dev/null +++ b/doc/rake/README @@ -0,0 +1,196 @@ += 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 + +[<b>Ryan Dlugosz</b>] For the initial conversation that sparked Rake. + +[<b>nobu.nokada@softhome.net</b>] For the initial patch for rule support. + +[<b>Tilman Sauerbeck <tilman@code-monkey.de></b>] 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 <jim.weirich@gmail.com> +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 new file mode 100644 index 0000000000..c60e53f51a --- /dev/null +++ b/doc/rake/command_line_usage.rdoc @@ -0,0 +1,102 @@ += Rake Command Line Usage + +Rake is invoked from the command line using: + + % rake [<em>options</em> ...] [<em>VAR</em>=<em>VALUE</em>] [<em>targets</em> ...] + +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>--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>--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_ (-p)] + Execute some Ruby code, then continue with normal task processing. + +[<tt>--help</tt> (-H)] + Display some help text and exit. + +[<tt>--libdir</tt> _directory_ (-I)] + Add _directory_ to the list of directories searched for require. + +[<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>--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>--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> (-T)] + Display a list of the major tasks and their comments. Comments + are defined using the "desc" command. + +[<tt>--trace</tt> (-t)] + Turn on invoke/execute tracing. Also enable full backtrace on + errors. + +[<tt>--usage</tt> (-h)] + Display a usage message and exit. + +[<tt>--verbose</tt> (-v)] + Echo the Sys commands to standard output. + +[<tt>--version</tt> (-V)] + Display the program version and exit. + +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. diff --git a/doc/rake/example/Rakefile1 b/doc/rake/example/Rakefile1 new file mode 100644 index 0000000000..39f8bcceb0 --- /dev/null +++ b/doc/rake/example/Rakefile1 @@ -0,0 +1,38 @@ +# Example Rakefile -*- ruby -*- + +task :default => [:main] + +file "a.o" => ["a.c"] do |t| + src = t.name.sub(/\.o$/, '.c') + sh "gcc #{src} -c -o #{t.name}" +end + +file "b.o" => ["b.c"] do |t| + src = t.name.sub(/\.o$/, '.c') + sh "gcc #{src} -c -o #{t.name}" +end + +file "main.o" => ["main.c"] do |t| + src = t.name.sub(/\.o$/, '.c') + sh "gcc #{src} -c -o #{t.name}" +end + +OBJFILES = ["a.o", "b.o", "main.o"] +task :obj => OBJFILES + +file "main" => OBJFILES do |t| + sh "gcc -o #{t.name} main.o a.o b.o" +end + +task :clean do + rm_f FileList['*.o'] + Dir['*~'].each { |fn| rm_f fn } +end + +task :clobber => [:clean] do + rm_f "main" +end + +task :run => ["main"] do + sh "./main" +end diff --git a/doc/rake/example/Rakefile2 b/doc/rake/example/Rakefile2 new file mode 100644 index 0000000000..35310eceb5 --- /dev/null +++ b/doc/rake/example/Rakefile2 @@ -0,0 +1,35 @@ +# Example Rakefile -*- ruby -*- +# Using the power of Ruby + +task :default => [:main] + +def ext(fn, newext) + fn.sub(/\.[^.]+$/, newext) +end + +SRCFILES = Dir['*.c'] +OBJFILES = SRCFILES.collect { |fn| ext(fn,".o") } + +OBJFILES.each do |objfile| + srcfile = ext(objfile, ".c") + file objfile => [srcfile] do |t| + sh "gcc #{srcfile} -c -o #{t.name}" + end +end + +file "main" => OBJFILES do |t| + sh "gcc -o #{t.name} main.o a.o b.o" +end + +task :clean do + rm_f FileList['*.o'] + Dir['*~'].each { |fn| rm_f fn } +end + +task :clobber => [:clean] do + rm_f "main" +end + +task :run => ["main"] do + sh "./main" +end diff --git a/doc/rake/example/a.c b/doc/rake/example/a.c new file mode 100644 index 0000000000..620e6f8007 --- /dev/null +++ b/doc/rake/example/a.c @@ -0,0 +1,6 @@ +#include <stdio.h> + +void a() +{ + printf ("In function a\n"); +} diff --git a/doc/rake/example/b.c b/doc/rake/example/b.c new file mode 100644 index 0000000000..9b24aa1273 --- /dev/null +++ b/doc/rake/example/b.c @@ -0,0 +1,6 @@ +#include <stdio.h> + +void b() +{ + printf ("In function b\n"); +} diff --git a/doc/rake/example/main.c b/doc/rake/example/main.c new file mode 100644 index 0000000000..a04558a251 --- /dev/null +++ b/doc/rake/example/main.c @@ -0,0 +1,11 @@ +#include <stdio.h> + +extern void a(); +extern void b(); + +int main () +{ + a(); + b(); + return 0; +} diff --git a/doc/rake/glossary.rdoc b/doc/rake/glossary.rdoc new file mode 100644 index 0000000000..0ca1869306 --- /dev/null +++ b/doc/rake/glossary.rdoc @@ -0,0 +1,51 @@ += Glossary + +[<b>action</b>] + 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. + +[<b>execute</b>] + When a task is executed, all of its actions are performed, in + the order they were defined. Note that unlike + <tt>invoke</tt>, <tt>execute</tt> always executes the actions + (without invoking or executing the prerequisites). + +[<b>file task</b> (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. + +[<b>invoke</b>] + 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 + <tt>needed?</tt>. 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. + +[<b>prerequisites</b>] + Every task has a set (possiblity empty) of prerequisites. A + prerequisite P to Task T is itself a task that must be invoked + before Task T. + +[<b>rule</b>] + A rule is a recipe for synthesizing a task when no task is + explicitly defined. Rules generally synthesize file tasks. + +[<b>task</b> (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/jamis.rb b/doc/rake/jamis.rb new file mode 100644 index 0000000000..c7439d88ea --- /dev/null +++ b/doc/rake/jamis.rb @@ -0,0 +1,591 @@ +module RDoc +module Page + +FONTS = "\"Bitstream Vera Sans\", Verdana, Arial, Helvetica, sans-serif" + +STYLE = <<CSS +a { + color: #00F; + text-decoration: none; +} + +a:hover { + color: #77F; + text-decoration: underline; +} + +body, td, p { + font-family: %fonts%; + background: #FFF; + color: #000; + margin: 0px; + font-size: small; +} + +#content { + margin: 2em; +} + +#description p { + margin-bottom: 0.5em; +} + +.sectiontitle { + margin-top: 1em; + margin-bottom: 1em; + padding: 0.5em; + padding-left: 2em; + background: #005; + color: #FFF; + font-weight: bold; + border: 1px dotted black; +} + +.attr-rw { + padding-left: 1em; + padding-right: 1em; + text-align: center; + color: #055; +} + +.attr-name { + font-weight: bold; +} + +.attr-desc { +} + +.attr-value { + font-family: monospace; +} + +.file-title-prefix { + font-size: large; +} + +.file-title { + font-size: large; + font-weight: bold; + background: #005; + color: #FFF; +} + +.banner { + background: #005; + color: #FFF; + border: 1px solid black; + padding: 1em; +} + +.banner td { + background: transparent; + color: #FFF; +} + +h1 a, h2 a, .sectiontitle a, .banner a { + color: #FF0; +} + +h1 a:hover, h2 a:hover, .sectiontitle a:hover, .banner a:hover { + color: #FF7; +} + +.dyn-source { + display: none; + background: #FFE; + color: #000; + border: 1px dotted black; + margin: 0.5em 2em 0.5em 2em; + padding: 0.5em; +} + +.dyn-source .cmt { + color: #00F; + font-style: italic; +} + +.dyn-source .kw { + color: #070; + font-weight: bold; +} + +.method { + margin-left: 1em; + margin-right: 1em; + margin-bottom: 1em; +} + +.description pre { + padding: 0.5em; + border: 1px dotted black; + background: #FFE; +} + +.method .title { + font-family: monospace; + font-size: large; + border-bottom: 1px dashed black; + margin-bottom: 0.3em; + padding-bottom: 0.1em; +} + +.method .description, .method .sourcecode { + margin-left: 1em; +} + +.description p, .sourcecode p { + margin-bottom: 0.5em; +} + +.method .sourcecode p.source-link { + text-indent: 0em; + margin-top: 0.5em; +} + +.method .aka { + margin-top: 0.3em; + margin-left: 1em; + font-style: italic; + text-indent: 2em; +} + +h1 { + padding: 1em; + border: 1px solid black; + font-size: x-large; + font-weight: bold; + color: #FFF; + background: #007; +} + +h2 { + padding: 0.5em 1em 0.5em 1em; + border: 1px solid black; + font-size: large; + font-weight: bold; + color: #FFF; + background: #009; +} + +h3, h4, h5, h6 { + padding: 0.2em 1em 0.2em 1em; + border: 1px dashed black; + color: #000; + background: #AAF; +} + +.sourcecode > pre { + padding: 0.5em; + border: 1px dotted black; + background: #FFE; +} + +CSS + +XHTML_PREAMBLE = %{<?xml version="1.0" encoding="%charset%"?> +<!DOCTYPE html + PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +} + +HEADER = XHTML_PREAMBLE + <<ENDHEADER +<html> + <head> + <title>%title%</title> + <meta http-equiv="Content-Type" content="text/html; charset=%charset%" /> + <link rel="stylesheet" href="%style_url%" type="text/css" media="screen" /> + + <script language="JavaScript" type="text/javascript"> + // <![CDATA[ + + function toggleSource( id ) + { + var elem + var link + + if( document.getElementById ) + { + elem = document.getElementById( id ) + link = document.getElementById( "l_" + id ) + } + else if ( document.all ) + { + elem = eval( "document.all." + id ) + link = eval( "document.all.l_" + id ) + } + else + return false; + + if( elem.style.display == "block" ) + { + elem.style.display = "none" + link.innerHTML = "show source" + } + else + { + elem.style.display = "block" + link.innerHTML = "hide source" + } + } + + function openCode( url ) + { + window.open( url, "SOURCE_CODE", "width=400,height=400,scrollbars=yes" ) + } + // ]]> + </script> + </head> + + <body> +ENDHEADER + +FILE_PAGE = <<HTML +<table border='0' cellpadding='0' cellspacing='0' width="100%" class='banner'> + <tr><td> + <table width="100%" border='0' cellpadding='0' cellspacing='0'><tr> + <td class="file-title" colspan="2"><span class="file-title-prefix">File</span><br />%short_name%</td> + <td align="right"> + <table border='0' cellspacing="0" cellpadding="2"> + <tr> + <td>Path:</td> + <td>%full_path% +IF:cvsurl + (<a href="%cvsurl%">CVS</a>) +ENDIF:cvsurl + </td> + </tr> + <tr> + <td>Modified:</td> + <td>%dtm_modified%</td> + </tr> + </table> + </td></tr> + </table> + </td></tr> +</table><br> +HTML + +################################################################### + +CLASS_PAGE = <<HTML +<table width="100%" border='0' cellpadding='0' cellspacing='0' class='banner'><tr> + <td class="file-title"><span class="file-title-prefix">%classmod%</span><br />%full_name%</td> + <td align="right"> + <table cellspacing=0 cellpadding=2> + <tr valign="top"> + <td>In:</td> + <td> +START:infiles +HREF:full_path_url:full_path: +IF:cvsurl + (<a href="%cvsurl%">CVS</a>) +ENDIF:cvsurl +END:infiles + </td> + </tr> +IF:parent + <tr> + <td>Parent:</td> + <td> +IF:par_url + <a href="%par_url%"> +ENDIF:par_url +%parent% +IF:par_url + </a> +ENDIF:par_url + </td> + </tr> +ENDIF:parent + </table> + </td> + </tr> + </table> +HTML + +################################################################### + +METHOD_LIST = <<HTML + <div id="content"> +IF:diagram + <table cellpadding='0' cellspacing='0' border='0' width="100%"><tr><td align="center"> + %diagram% + </td></tr></table> +ENDIF:diagram + +IF:description + <div class="description">%description%</div> +ENDIF:description + +IF:requires + <div class="sectiontitle">Required Files</div> + <ul> +START:requires + <li>HREF:aref:name:</li> +END:requires + </ul> +ENDIF:requires + +IF:toc + <div class="sectiontitle">Contents</div> + <ul> +START:toc + <li><a href="#%href%">%secname%</a></li> +END:toc + </ul> +ENDIF:toc + +IF:methods + <div class="sectiontitle">Methods</div> + <ul> +START:methods + <li>HREF:aref:name:</li> +END:methods + </ul> +ENDIF:methods + +IF:includes +<div class="sectiontitle">Included Modules</div> +<ul> +START:includes + <li>HREF:aref:name:</li> +END:includes +</ul> +ENDIF:includes + +START:sections +IF:sectitle +<div class="sectiontitle"><a nem="%secsequence%">%sectitle%</a></div> +IF:seccomment +<div class="description"> +%seccomment% +</div> +ENDIF:seccomment +ENDIF:sectitle + +IF:classlist + <div class="sectiontitle">Classes and Modules</div> + %classlist% +ENDIF:classlist + +IF:constants + <div class="sectiontitle">Constants</div> + <table border='0' cellpadding='5'> +START:constants + <tr valign='top'> + <td class="attr-name">%name%</td> + <td>=</td> + <td class="attr-value">%value%</td> + </tr> +IF:desc + <tr valign='top'> + <td> </td> + <td colspan="2" class="attr-desc">%desc%</td> + </tr> +ENDIF:desc +END:constants + </table> +ENDIF:constants + +IF:attributes + <div class="sectiontitle">Attributes</div> + <table border='0' cellpadding='5'> +START:attributes + <tr valign='top'> + <td class='attr-rw'> +IF:rw +[%rw%] +ENDIF:rw + </td> + <td class='attr-name'>%name%</td> + <td class='attr-desc'>%a_desc%</td> + </tr> +END:attributes + </table> +ENDIF:attributes + +IF:method_list +START:method_list +IF:methods +<div class="sectiontitle">%type% %category% methods</div> +START:methods +<div class="method"> + <div class="title"> +IF:callseq + <a name="%aref%"></a><b>%callseq%</b> +ENDIF:callseq +IFNOT:callseq + <a name="%aref%"></a><b>%name%</b>%params% +ENDIF:callseq +IF:codeurl +[ <a href="javascript:openCode('%codeurl%')">source</a> ] +ENDIF:codeurl + </div> +IF:m_desc + <div class="description"> + %m_desc% + </div> +ENDIF:m_desc +IF:aka +<div class="aka"> + This method is also aliased as +START:aka + <a href="%aref%">%name%</a> +END:aka +</div> +ENDIF:aka +IF:sourcecode +<div class="sourcecode"> + <p class="source-link">[ <a href="javascript:toggleSource('%aref%_source')" id="l_%aref%_source">show source</a> ]</p> + <div id="%aref%_source" class="dyn-source"> +<pre> +%sourcecode% +</pre> + </div> +</div> +ENDIF:sourcecode +</div> +END:methods +ENDIF:methods +END:method_list +ENDIF:method_list +END:sections +</div> +HTML + +FOOTER = <<ENDFOOTER + </body> +</html> +ENDFOOTER + +BODY = HEADER + <<ENDBODY + !INCLUDE! <!-- banner header --> + + <div id="bodyContent"> + #{METHOD_LIST} + </div> + + #{FOOTER} +ENDBODY + +########################## Source code ########################## + +SRC_PAGE = XHTML_PREAMBLE + <<HTML +<html> +<head><title>%title%</title> +<meta http-equiv="Content-Type" content="text/html; charset=%charset%"> +<style> +.ruby-comment { color: green; font-style: italic } +.ruby-constant { color: #4433aa; font-weight: bold; } +.ruby-identifier { color: #222222; } +.ruby-ivar { color: #2233dd; } +.ruby-keyword { color: #3333FF; font-weight: bold } +.ruby-node { color: #777777; } +.ruby-operator { color: #111111; } +.ruby-regexp { color: #662222; } +.ruby-value { color: #662222; font-style: italic } + .kw { color: #3333FF; font-weight: bold } + .cmt { color: green; font-style: italic } + .str { color: #662222; font-style: italic } + .re { color: #662222; } +</style> +</head> +<body bgcolor="white"> +<pre>%code%</pre> +</body> +</html> +HTML + +########################## Index ################################ + +FR_INDEX_BODY = <<HTML +!INCLUDE! +HTML + +FILE_INDEX = XHTML_PREAMBLE + <<HTML +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=%charset%"> +<style> +<!-- + body { + background-color: #EEE; + font-family: #{FONTS}; + color: #000; + margin: 0px; + } + .banner { + background: #005; + color: #FFF; + padding: 0.2em; + font-size: small; + font-weight: bold; + text-align: center; + } + .entries { + margin: 0.25em 1em 0 1em; + font-size: x-small; + } + a { + color: #00F; + text-decoration: none; + white-space: nowrap; + } + a:hover { + color: #77F; + text-decoration: underline; + } +--> +</style> +<base target="docwin"> +</head> +<body> +<div class="banner">%list_title%</div> +<div class="entries"> +START:entries +<a href="%href%">%name%</a><br> +END:entries +</div> +</body></html> +HTML + +CLASS_INDEX = FILE_INDEX +METHOD_INDEX = FILE_INDEX + +INDEX = XHTML_PREAMBLE + <<HTML +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> + <title>%title%</title> + <meta http-equiv="Content-Type" content="text/html; charset=%charset%"> +</head> + +<frameset cols="20%,*"> + <frameset rows="15%,35%,50%"> + <frame src="fr_file_index.html" title="Files" name="Files" /> + <frame src="fr_class_index.html" name="Classes" /> + <frame src="fr_method_index.html" name="Methods" /> + </frameset> +IF:inline_source + <frame src="%initial_page%" name="docwin"> +ENDIF:inline_source +IFNOT:inline_source + <frameset rows="80%,20%"> + <frame src="%initial_page%" name="docwin"> + <frame src="blank.html" name="source"> + </frameset> +ENDIF:inline_source + <noframes> + <body bgcolor="white"> + Click <a href="html/index.html">here</a> for a non-frames + version of this page. + </body> + </noframes> +</frameset> + +</html> +HTML + +end +end + + diff --git a/doc/rake/proto_rake.rdoc b/doc/rake/proto_rake.rdoc new file mode 100644 index 0000000000..39b9b88c1f --- /dev/null +++ b/doc/rake/proto_rake.rdoc @@ -0,0 +1,127 @@ += Original Prototype Rake + +This is the original 100 line prototype rake program. + +--- + #!/usr/bin/env ruby + + require 'ftools' + + class Task + TASKS = Hash.new + + attr_reader :prerequisites + + def initialize(task_name) + @name = task_name + @prerequisites = [] + @actions = [] + end + + def enhance(deps=nil, &block) + @prerequisites |= deps if deps + @actions << block if block_given? + self + end + + def name + @name.to_s + end + + def invoke + @prerequisites.each { |n| Task[n].invoke } + execute if needed? + end + + def execute + return if @triggered + @triggered = true + @actions.collect { |act| result = act.call(self) }.last + end + + def needed? + true + end + + def timestamp + Time.now + end + + class << self + def [](task_name) + TASKS[intern(task_name)] or fail "Don't know how to rake #{task_name}" + end + + def define_task(args, &block) + case args + when Hash + fail "Too Many Target Names: #{args.keys.join(' ')}" if args.size > 1 + fail "No Task Name Given" if args.size < 1 + task_name = args.keys[0] + deps = args[task_name] + else + task_name = args + deps = [] + end + deps = deps.collect {|d| intern(d) } + get(task_name).enhance(deps, &block) + end + + def get(task_name) + name = intern(task_name) + TASKS[name] ||= self.new(name) + end + + def intern(task_name) + (Symbol === task_name) ? task_name : task_name.intern + end + end + end + + class FileTask < Task + def needed? + return true unless File.exist?(name) + latest_prereq = @prerequisites.collect{|n| Task[n].timestamp}.max + return false if latest_prereq.nil? + timestamp < latest_prereq + end + + def timestamp + File.new(name.to_s).mtime + end + end + + def task(args, &block) + Task.define_task(args, &block) + end + + def file(args, &block) + FileTask.define_task(args, &block) + end + + def sys(cmd) + puts cmd + system(cmd) or fail "Command Failed: [#{cmd}]" + end + + def rake + begin + here = Dir.pwd + while ! File.exist?("Rakefile") + Dir.chdir("..") + fail "No Rakefile found" if Dir.pwd == here + here = Dir.pwd + end + puts "(in #{Dir.pwd})" + load "./Rakefile" + ARGV.push("default") if ARGV.size == 0 + ARGV.each { |task_name| Task[task_name].invoke } + rescue Exception => ex + puts "rake aborted ... #{ex.message}" + puts ex.backtrace.find {|str| str =~ /Rakefile/ } || "" + end + end + + if __FILE__ == $0 then + rake + end diff --git a/doc/rake/rakefile.rdoc b/doc/rake/rakefile.rdoc new file mode 100644 index 0000000000..f8ae72c32a --- /dev/null +++ b/doc/rake/rakefile.rdoc @@ -0,0 +1,534 @@ += Rakefile Format (as of version 0.8.3) + +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 (inclosed 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 paramter.. + + 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 whereever 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 +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 :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 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 to argumements 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 +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 +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. + +== Accessing Task Programatically + +Sometimes it is useful to manipulate tasks programatically in a +Rakefile. To find a task object, use the <tt>:[]</tt> operator on the +<tt>Rake::Task</tt>. + +=== 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 + +<b>NOTE:</b> 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 + +<b>NOTE:</b> +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 +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. + +=== Example: + + require 'rake/loaders/makefile' + + file ".depends.mf" => [SRC_LIST] do |t| + sh "makedepend -f- -- #{CFLAGS} -- #{t.prerequisites} > #{t.name}" + end + + 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 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. + + 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 interfer with +each other. + +For example: + + namespace "main" + 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 verses { } + +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 parenthesis 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 +prerequistes 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 -- Main documentation for Rake. diff --git a/doc/rake/rational.rdoc b/doc/rake/rational.rdoc new file mode 100644 index 0000000000..f741e65bf8 --- /dev/null +++ b/doc/rake/rational.rdoc @@ -0,0 +1,151 @@ += 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 truely 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 dependecies 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 excerise 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. diff --git a/doc/rake/release_notes/rake-0.8.7.rdoc b/doc/rake/release_notes/rake-0.8.7.rdoc new file mode 100644 index 0000000000..fb0c5d4e36 --- /dev/null +++ b/doc/rake/release_notes/rake-0.8.7.rdoc @@ -0,0 +1,55 @@ += Rake 0.8.7 Released + +Rake version 0.8.5 introduced greatly improved support for executing +commands on Windows. The "sh" command now has the same semantics on +Windows that it has on Unix based platforms. + +Rake version 0.8.6 includes minor fixes the the RDoc generation. +Rake version 0.8.7 includes a minor fix for JRuby running on windows. + +== Changes + +=== New Features / Enhancements in Version 0.8.5 + +* Improved implementation of the Rake system command for Windows. + (patch from James M. Lawrence/quix) + +* Support for Ruby 1.9's improved system command. (patch from James + M. Lawrence/quix) + +* Rake now includes the configured extension when invoking an + executable (Config::CONFIG['EXEEXT]) + +=== Bug Fixes in Version 0.8.5 + +* Environment variable keys are now correctly cased (it matters in + some implementations). + +== What is Rake + +Rake is a build tool similar to the make program in many ways. But +instead of cryptic make recipes, Rake uses standard Ruby code to +declare tasks and dependencies. You have the full power of a modern +scripting language built right into your build tool. + +== Availability + +The easiest way to get and install rake is via RubyGems ... + + gem install rake (you may need root/admin privileges) + +Otherwise, you can get it from the more traditional places: + +Home Page:: http://rake.rubyforge.org/ +Download:: http://rubyforge.org/project/showfiles.php?group_id=50 +GitHub:: git://github.com/jimweirich/rake.git + +== Thanks + +As usual, it was input from users that drove a alot of these changes. The +following people either contributed patches, made suggestions or made +otherwise helpful comments. Thanks to ... + +* Charles Nutter + +-- Jim Weirich |