rake 0.9.2.2 → 13.0.6

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2003, 2004 Jim Weirich
+Copyright (c) Jim Weirich
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.rdoc

@@ -1,7 +1,13 @@
 = RAKE -- Ruby Make
 
-This package contains Rake, a simple ruby build program with capabilities
-similar to make.
+home :: https://github.com/ruby/rake
+bugs :: https://github.com/ruby/rake/issues
+docs :: https://ruby.github.io/rake
+
+== Description
+
+Rake is a Make-like program implemented in Ruby. Tasks and dependencies are
+specified in standard Ruby syntax.
 
 Rake has the following features:
 
@@ -17,9 +23,9 @@ Rake has the following features:
   file names and paths.
 
 * A library of prepackaged tasks to make building rakefiles easier. For example,
-  tasks for building tarballs and publishing to FTP or SSH sites.  (Formerly
-  tasks for building RDoc and Gems were included in rake but they're now
-  available in RDoc and RubyGems respectively.)
+  tasks for building tarballs. (Formerly
+  tasks for building RDoc, Gems, and publishing to FTP were included in rake but they're now
+  available in RDoc, RubyGems, and rake-contrib respectively.)
 
 * Supports parallel execution of tasks.
 
@@ -29,19 +35,7 @@ Rake has the following features:
 
 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.
+  gem install rake
 
 == Usage
 
@@ -50,7 +44,7 @@ from its distribution directory.
 First, you must write a "Rakefile" file which contains the build rules. Here's
 a simple example:
 
-  task :default => [:test]
+  task default: %w[test]
 
   task :test do
     ruby "test/unittest.rb"
@@ -58,8 +52,8 @@ a simple example:
 
 This Rakefile has two tasks:
 
-* A task named "test", which - upon invocation - will run a unit test file in
-  Ruby.
+* 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.
@@ -76,122 +70,86 @@ Running the "rake" command without any options will cause it to run the
 
 Type "rake --help" for all available options.
 
+== Resources
 
-=== 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 'flexmock' gem
-* 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
+=== Rake Information
 
-Feature requests and bug reports can be made here
-
-* https://github.com/jimweirich/rake/issues
-
-Issues and bug reports can also be tracked here:
-
-* http://www.pivotaltracker.com/projects/28469
-
-== 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
-* Rake Issue Tracking: http://www.pivotaltracker.com/projects/28469
-* Rake Bug Reports: https://github.com/jimweirich/rake/issues
+* {Rake command-line}[link:doc/command_line_usage.rdoc]
+* {Writing Rakefiles}[link:doc/rakefile.rdoc]
+* The original {Rake announcement}[link:doc/rational.rdoc]
+* Rake {glossary}[link:doc/glossary.rdoc]
 
 === 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
+* Avdi Grimm's rake series:
+  1. {Rake Basics}[https://avdi.codes/rake-part-1-basics/]
+  2. {Rake File Lists}[https://avdi.codes/rake-part-2-file-lists-2/]
+  3. {Rake Rules}[https://avdi.codes/rake-part-3-rules/]
+  4. {Rake Pathmap}[https://avdi.codes/rake-part-4-pathmap/]
+  5. {File Operations}[https://avdi.codes/rake-part-5-file-operations/]
+  6. {Clean and Clobber}[https://avdi.codes/rake-part-6-clean-and-clobber/]
+  7. {MultiTask}[https://avdi.codes/rake-part-7-multitask/]
+* {Jim Weirich's 2003 RubyConf presentation}[https://web.archive.org/web/20140221123354/http://onestepback.org/articles/buildingwithrake/]
+* Martin Fowler's article on Rake: https://martinfowler.com/articles/rake.html
 
-== Other Make Reinvisionings ...
+== Other Make Re-envisionings ...
 
 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
+* https://directory.fsf.org/wiki/Bras -- 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.
+* https://ant.apache.org -- The Ant project
+* https://search.cpan.org/search?query=PerlBuildSystem -- The Perl Build System
+* https://www.rubydoc.info/gems/rant/0.5.7/frames -- Rant, another Ruby make tool.
 
 == Credits
 
+[<b>Jim Weirich</b>] Who originally created Rake.
+
 [<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>Nobuyoshi Nakada <nobu@ruby-lang.org></b>] For the initial patch for rule support.
 
 [<b>Tilman Sauerbeck <tilman@code-monkey.de></b>] For the recursive rule patch.
 
+[<b>Eric Hodel</b>] For aid in maintaining rake.
+
+[<b>Hiroshi SHIBATA</b>] Maintainer of Rake 10.X and Rake 11.X
+
 == 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.  In 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.6 or later
-License::  Copyright 2003-2008 by Jim Weirich.
-           Released under an MIT-style license.  See the LICENSE file
-           included in the distribution.
+Requires:: Ruby 2.0.0 or later
+License::  Copyright Jim Weirich.
+           Released under an MIT-style license.  See the MIT-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.
+This software is provided "as is" and without any express or implied
+warranties, including, without limitation, the implied warranties of
+merchantability and fitness for a particular purpose.
+
+== Historical
+
+Rake was originally created by Jim Weirich, who unfortunately passed away in
+February 2014. This repository was originally hosted at
+{github.com/jimweirich/rake}[https://github.com/jimweirich/rake/], however
+with his passing, has been moved to {ruby/rake}[https://github.com/ruby/rake].
+
+You can view Jim's last commit here:
+https://github.com/jimweirich/rake/tree/336559f28f55bce418e2ebcc0a57548dcbac4025
+
+You can {read more about Jim}[https://en.wikipedia.org/wiki/Jim_Weirich] at Wikipedia.
+
+Thank you for this great tool, Jim. We'll remember you.

data/doc/command_line_usage.rdoc

@@ -2,7 +2,7 @@
 
 Rake is invoked from the command line using:
 
-   % rake [<em>options</em> ...]  [<em>VAR</em>=<em>VALUE</em>]  [<em>targets</em> ...]
+    % rake [options ...]  [VAR=VALUE ...]  [targets ...]
 
 Options are:
 
@@ -11,12 +11,22 @@ Options are:
     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>--all</tt> (-A)]
+    Used in combination with the -T and -D options, will force
+    those options to show all the tasks, even the ones without comments.
+
+[<tt>--backtrace</tt>{=_output_} (-n)]
+    Enable a full backtrace (i.e. like --trace, but without the task
+    tracing details). The _output_ parameter is optional, but if
+    specified it controls where the backtrace output is sent. If
+    _output_ is <tt>stdout</tt>, then backtrace output is directed to
+    standard output. If _output_ is <tt>stderr</tt>, or if it is
+    missing, then the backtrace output is sent to standard error.
+
+[<tt>--comments</tt>]
+    Used in combination with the -W options to force the output to
+    contain commented options only. This is the reverse of
+    <tt>--all</tt>.
 
 [<tt>--describe</tt> _pattern_ (-D)]
     Describe the tasks (matching optional PATTERN), then exit.
@@ -31,15 +41,46 @@ Options are:
 [<tt>--execute-print</tt> _code_ (-p)]
     Execute some Ruby code, print the result, and exit.
 
-[<tt>--execute-continue</tt> _code_ (-p)]
+[<tt>--execute-continue</tt> _code_ (-E)]
     Execute some Ruby code, then continue with normal task processing.
 
 [<tt>--help</tt>  (-H)]
     Display some help text and exit.
 
+[<tt>--jobs</tt> _number_  (-j)]
+
+    Specifies the maximum number of concurrent threads allowed. Rake
+    will allocate threads as needed up to this maximum number.
+
+    If omitted, Rake will attempt to estimate the number of CPUs on
+    the system and add 4 to that number.
+
+    The concurrent threads are used to execute the <tt>multitask</tt>
+    prerequisites. Also see the <tt>-m</tt> option which turns all
+    tasks into multitasks.
+
+    Sample values:
+       (no -j)   : Allow up to (# of CPUs + 4) number of threads
+       --jobs    : Allow unlimited number of threads
+       --jobs=1  : Allow only one thread (the main thread)
+       --jobs=16 : Allow up to 16 concurrent threads
+
+[<tt>--job-stats</tt> _level_]
+
+    Display job statistics at the completion of the run. By default,
+    this will display the requested number of active threads (from the
+    -j options) and the maximum number of threads in play at any given
+    time.
+
+    If the optional _level_ is <tt>history</tt>, then a complete trace
+    of task history will be displayed on standard output.
+
 [<tt>--libdir</tt> _directory_  (-I)]
     Add _directory_ to the list of directories searched for require.
 
+[<tt>--multitask</tt> (-m)]
+    Treat all tasks as multitasks. ('make/drake' semantics)
+
 [<tt>--nosearch</tt>  (-N)]
     Do not search for a Rakefile in parent directories.
 
@@ -69,6 +110,11 @@ Options are:
 [<tt>--silent (-s)</tt>]
     Like --quiet, but also suppresses the 'in directory' announcement.
 
+[<tt>--suppress-backtrace _pattern_ </tt>]
+    Line matching the regular expression _pattern_ will be removed
+    from the backtrace output. Note that the --backtrace option is the
+    full backtrace without these lines suppressed.
+
 [<tt>--system</tt> (-g)]
     Use the system wide (global) rakefiles. The project Rakefile is
     ignored. By default, the system wide rakefiles are used only if no
@@ -85,19 +131,13 @@ Options are:
     are defined using the "desc" command.  If a pattern is given, then
     only tasks matching the pattern are displayed.
 
-[<tt>--no-top-level-dsl</tt> (-X)]
-    Do not put the Rake DSL commands into the top level scope.
-
-[<tt>--top-level-dsl</tt>]
-    Put the Rake DSL commands into the top level scope (default).
-
-    NOTE: Although currently Rake defaults to its DSL in the top level
-    scope, the plan is to deprecate this in the future and default ot
-    having the DSL commands *not* appear in the top level scope.
-
-[<tt>--trace</tt> (-t)]
+[<tt>--trace</tt>{=_output_} (-t)]
     Turn on invoke/execute tracing. Also enable full backtrace on
-    errors.
+    errors. The _output_ parameter is optional, but if specified it
+    controls where the trace output is sent. If _output_ is
+    <tt>stdout</tt>, then trace output is directed to standard output.
+    If _output_ is <tt>stderr</tt>, or if it is missing, then trace
+    output is sent to standard error.
 
 [<tt>--verbose</tt> (-v)]
     Echo the Sys commands to standard output.
@@ -107,7 +147,11 @@ Options are:
 
 [<tt>--where</tt> <em>pattern</em> (-W)]
     Display tasks that match <em>pattern</em> and the file and line
-    number where the task is defined.
+    number where the task is defined. By default this option will
+    display all tasks, not just the tasks that have descriptions.
+
+[<tt>--no-deprecation-warnings</tt> (-X)]
+    Do not display the deprecation warnings.
 
 In addition, any command line option of the form
 <em>VAR</em>=<em>VALUE</em> will be added to the environment hash

data/doc/glossary.rdoc

@@ -1,51 +1,42 @@
 = 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 (possibly 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.
-
+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 <tt>invoke</tt>, <tt>execute</tt> always
+  executes the actions (without invoking or executing the prerequisites).
+
+file task (Rake::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 it has
+  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
+  Rake::Task#needed?.  If the task is needed, we execute its actions.
+
+  NOTE: Prerequisites are still invoked even if the task is not needed.
+
+prerequisites ::
+  Every task has a (possibly empty) set 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 (Rake::Task) ::
+  The basic unit of work in a Rakefile.  A task has a name, a set of 
+  prerequisites, and a list of actions to be performed.

data/doc/jamis.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module RDoc
 module Page
 

data/doc/rake.1

@@ -0,0 +1,156 @@
+.Dd June 12, 2016
+.Dt RAKE 1
+.Os rake 11.2.2
+.Sh NAME
+.Nm rake
+.Nd make-like build utility for Ruby
+.Sh SYNOPSIS
+.Nm
+.Op Fl f Ar rakefile
+.Op Ar options
+.Ar targets ...
+.Sh DESCRIPTION
+.Nm
+is a
+.Xr make 1 Ns -like
+build utility for Ruby.
+Tasks and dependencies are specified in standard Ruby syntax.
+.Sh OPTIONS
+.Bl -tag -width Ds
+.It Fl m , Fl -multitask
+Treat all tasks as multitasks.
+.It Fl B , Fl -build-all
+Build all prerequisites, including those which are up\-to\-date.
+.It Fl j , Fl -jobs Ar num_jobs
+Specifies the maximum number of tasks to execute in parallel (default is number of CPU cores + 4).
+.El
+.Ss Modules
+.Bl -tag -width Ds
+.It Fl I , Fl -libdir Ar libdir
+Include
+.Ar libdir
+in the search path for required modules.
+.It Fl r , Fl -require Ar module
+Require
+.Ar module
+before executing
+.Pa rakefile .
+.El
+.Ss Rakefile location
+.Bl -tag -width Ds
+.It Fl f , Fl -rakefile Ar filename
+Use
+.Ar filename
+as the rakefile to search for.
+.It Fl N , Fl -no-search , Fl -nosearch
+Do not search parent directories for the Rakefile.
+.It Fl G , Fl -no-system , Fl -nosystem
+Use standard project Rakefile search paths, ignore system wide rakefiles.
+.It Fl R , Fl -rakelib Ar rakelibdir , Fl -rakelibdir Ar rakelibdir
+Auto-import any .rake files in
+.Ar rakelibdir
+(default is
+.Sq rakelib )
+.It Fl g , Fl -system
+Use system-wide (global) rakefiles (usually
+.Pa ~/.rake/*.rake ) .
+.El
+.Ss Debugging
+.Bl -tag -width Ds
+.It Fl -backtrace Ns = Ns Ar out
+Enable full backtrace.
+.Ar out
+can be
+.Dv stderr
+(default) or
+.Dv stdout .
+.It Fl t , Fl -trace Ns = Ns Ar out
+Turn on invoke/execute tracing, enable full backtrace.
+.Ar out
+can be
+.Dv stderr
+(default) or
+.Dv stdout .
+.It Fl -suppress-backtrace Ar pattern
+Suppress backtrace lines matching regexp
+.Ar pattern .
+Ignored if
+.Fl -trace
+is on.
+.It Fl -rules
+Trace the rules resolution.
+.It Fl n , Fl -dry-run
+Do a dry run without executing actions.
+.It Fl T , Fl -tasks Op Ar pattern
+Display the tasks (matching optional
+.Ar pattern )
+with descriptions, then exit.
+.It Fl D , Fl -describe Op Ar pattern
+Describe the tasks (matching optional
+.Ar pattern ) ,
+then exit.
+.It Fl W , Fl -where Op Ar pattern
+Describe the tasks (matching optional
+.Ar pattern ) ,
+then exit.
+.It Fl P , Fl -prereqs
+Display the tasks and dependencies, then exit.
+.It Fl e , Fl -execute Ar code
+Execute some Ruby code and exit.
+.It Fl p , Fl -execute-print Ar code
+Execute some Ruby code, print the result, then exit.
+.It Fl E , Fl -execute-continue Ar code
+Execute some Ruby code, then continue with normal task processing.
+.El
+.Ss Information
+.Bl -tag -width Ds
+.It Fl v , Fl -verbose
+Log message to standard output.
+.It Fl q , Fl -quiet
+Do not log messages to standard output.
+.It Fl s , Fl -silent
+Like
+.Fl -quiet ,
+but also suppresses the
+.Sq in directory
+announcement.
+.It Fl X , Fl -no-deprecation-warnings
+Disable the deprecation warnings.
+.It Fl -comments
+Show commented tasks only
+.It Fl A , Fl -all
+Show all tasks, even uncommented ones (in combination with
+.Fl T
+or
+.Fl D )
+.It Fl -job-stats Op Ar level
+Display job statistics.
+If
+.Ar level
+is
+.Sq history ,
+displays a complete job list.
+.It Fl V , Fl -version
+Display the program version.
+.It Fl h , Fl H , Fl -help
+Display a help message.
+.El
+.Sh SEE ALSO
+The complete documentation for
+.Nm rake
+has been installed at
+.Pa /usr/share/doc/rake-doc/html/index.html .
+It is also available online at
+.Lk https://ruby.github.io/rake .
+.Sh AUTHORS
+.An -nosplit
+.Nm
+was written by
+.An Jim Weirich Aq Mt jim@weirichhouse.org .
+.Pp
+This manual was created by
+.An Caitlin Matos Aq Mt caitlin.matos@zoho.com
+for the Debian project (but may be used by others).
+It was inspired by the manual by
+.An Jani Monoses Aq Mt jani@iv.ro
+for the Ubuntu project.