/tools/Ruby/lib/ruby/gems/1.8/gems/rake-0.9.2/README.rdoc

  1= RAKE -- Ruby Make
  2
  3Supporting Rake version: 0.8.7.
  4
  5This package contains Rake, a simple ruby build program with
  6capabilities similar to make.
  7
  8Rake has the following features:
  9
 10* Rakefiles (rake's version of Makefiles) are completely defined in
 11  standard Ruby syntax.  No XML files to edit.  No quirky Makefile
 12  syntax to worry about (is that a tab or a space?)
 13
 14* Users can specify tasks with prerequisites.
 15
 16* Rake supports rule patterns to synthesize implicit tasks.
 17
 18* Flexible FileLists that act like arrays but know about manipulating
 19  file names and paths.
 20
 21* A library of prepackaged tasks to make building rakefiles easier. For example,
 22  tasks for building tarballs, gems and RDoc output are provided.
 23
 24* Supports parallel execution of tasks.
 25
 26
 27== Installation
 28
 29=== Gem Installation
 30
 31Download and install  rake with the following.
 32
 33   gem install rake
 34
 35=== Normal Installation
 36
 37You can download the source tarball of the latest version of Rake from
 38
 39* http://rubyforge.org/project/showfiles.php?group_id=50
 40
 41Extract the tarball and run
 42
 43  % ruby install.rb
 44
 45from its distribution directory.
 46
 47== Usage
 48
 49=== Simple Example
 50
 51First, you must write a "Rakefile" file which contains the build rules. Here's
 52a simple example:
 53
 54  task :default => [:test]
 55
 56  task :test do
 57    ruby "test/unittest.rb"
 58  end
 59
 60This Rakefile has two tasks:
 61
 62* A task named "test", which - upon invocation - will run a unit test file in
 63  Ruby.
 64* A task named "default". This task does nothing by itself, but it has exactly
 65  one dependency, namely the "test" task. Invoking the "default" task will
 66  cause Rake to invoke the "test" task as well.
 67
 68Running the "rake" command without any options will cause it to run the
 69"default" task in the Rakefile:
 70
 71  % ls
 72  Rakefile     test/
 73  % rake
 74  (in /home/some_user/Projects/rake)
 75  ruby test/unittest.rb
 76  ....unit test output here...
 77
 78Type "rake --help" for all available options.
 79
 80
 81=== More Information
 82
 83* For details on Rake's command-line invocation, read
 84  doc/command_line_usage.rdoc[http://rake.rubyforge.org/files/doc/command_line_usage_rdoc.html]
 85* For details on writing Rakefiles, see
 86  doc/rakefile.rdoc[http://rake.rubyforge.org/files/doc/rakefile_rdoc.html].
 87* For the original announcement of Rake, see
 88  doc/rational.rdoc[http://rake.rubyforge.org/files/doc/rational_rdoc.html].
 89* For a glossary of terms, see
 90  doc/glossary.rdoc[http://rake.rubyforge.org/files/doc/glossary_rdoc.html].
 91
 92== Development
 93
 94=== Source Repository
 95
 96Rake is currently hosted at github. The github web page is
 97http://github.com/jimweirich/rake. The public git clone URL is
 98
 99* git://github.com/jimweirich/rake.git
100
101=== Running the Rake Test Suite
102
103If you wish to run the unit and functional tests that come with Rake:
104
105* Install the 'flexmock' gem
106* Install the 'session' gem in order to run the functional tests.
107* CD into the top project directory of rake.
108* Type one of the following:
109
110     rake                  # If you have a version of rake installed
111     ruby -Ilib bin/rake   # If you do not have a version of rake installed.
112
113=== Issues and Bug Reports
114
115Feature requests and bug reports can be made here
116
117* http://onestepback.org/cgi-bin/bugs.cgi?project=rake
118
119No account is needed for posting requests.  Or you can send me an
120email (at jim dot weirich at gmail dot com)
121
122Issues and bug reports can be tracked here:
123
124* http://www.pivotaltracker.com/projects/28469
125
126== Online Resources
127
128=== Rake References
129
130* Rake Documentation Home: http://docs.rubyrake.org
131* Rake Project Page: http://rubyforge.org/projects/rake
132* Rake API Documents: http://rake.rubyforge.org
133* Rake Source Code Repo:  http://github.com/jimweirich/rake
134* Rake Git Repo Clone URL: git://github.com/jimweirich/rake.git
135* Rake Issue Tracking: http://www.pivotaltracker.com/projects/28469
136* Rake Bug Reports: http://onestepback.org/cgi-bin/bugs.cgi?project=rake
137
138=== Presentations and Articles about Rake
139
140* Jim Weirich's 2003 RubyConf presentation: http://onestepback.org/articles/buildingwithrake/
141* Martin Fowler's article on Rake: http://martinfowler.com/articles/rake.html
142
143== Other Make Reinvisionings ...
144
145Rake is a late entry in the make replacement field.  Here are links to
146other projects with similar (and not so similar) goals.
147
148* http://directory.fsf.org/bras.html -- Bras, one of earliest
149  implementations of "make in a scripting language".
150* http://www.a-a-p.org -- Make in Python
151* http://www.aromatic.com/tools/jam.txt -- JAM, Java Automated Make
152* http://ant.apache.org -- The Ant project
153* http://ppt.perl.org/commands/make/index.html -- Make from the Perl
154  Power Tools implementation.
155* http://search.cpan.org/search?query=PerlBuildSystem -- The Perl Build System
156* http://make.rubyforge.org -- Rant, another Ruby make tool.
157
158== Credits
159
160[<b>Ryan Dlugosz</b>] For the initial conversation that sparked Rake.
161
162[<b>nobu.nokada@softhome.net</b>] For the initial patch for rule support.
163
164[<b>Tilman Sauerbeck <tilman@code-monkey.de></b>] For the recursive rule patch.
165
166== License
167
168Rake is available under an MIT-style license.
169
170:include: MIT-LICENSE
171
172== Support
173
174The Rake homepage is http://rake.rubyforge.org.  You can find the Rake
175RubyForge page at http://rubyforge.org/projects/rake.
176
177Feel free to submit commits or feature requests.  If you send a patch,
178remember to update the corresponding unit tests.  In fact, I prefer
179new feature to be submitted in the form of new unit tests.
180
181For other information, feel free to ask on the ruby-talk mailing list
182(which is mirrored to comp.lang.ruby) or contact
183jim dot weirich at gmail.com.
184
185---
186
187= Other stuff
188
189Author::   Jim Weirich <jim.weirich@gmail.com>
190Requires:: Ruby 1.8.0 or later
191License::  Copyright 2003-2008 by Jim Weirich.
192           Released under an MIT-style license.  See the LICENSE file
193           included in the distribution.
194
195== Warranty
196
197This software is provided "as is" and without any express or
198implied warranties, including, without limitation, the implied
199warranties of merchantibility and fitness for a particular
200purpose.