rake 13.0.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (75) hide show
  1. checksums.yaml +7 -0
  2. data/.github/workflows/macos.yml +22 -0
  3. data/.github/workflows/ubuntu-rvm.yml +28 -0
  4. data/.github/workflows/ubuntu.yml +20 -0
  5. data/.github/workflows/windows.yml +20 -0
  6. data/CONTRIBUTING.rdoc +43 -0
  7. data/Gemfile +10 -0
  8. data/History.rdoc +2359 -0
  9. data/MIT-LICENSE +21 -0
  10. data/README.rdoc +155 -0
  11. data/Rakefile +41 -0
  12. data/bin/bundle +105 -0
  13. data/bin/console +7 -0
  14. data/bin/rake +29 -0
  15. data/bin/rdoc +29 -0
  16. data/bin/rubocop +29 -0
  17. data/bin/setup +6 -0
  18. data/doc/command_line_usage.rdoc +158 -0
  19. data/doc/example/Rakefile1 +38 -0
  20. data/doc/example/Rakefile2 +35 -0
  21. data/doc/example/a.c +6 -0
  22. data/doc/example/b.c +6 -0
  23. data/doc/example/main.c +11 -0
  24. data/doc/glossary.rdoc +42 -0
  25. data/doc/jamis.rb +592 -0
  26. data/doc/proto_rake.rdoc +127 -0
  27. data/doc/rake.1 +156 -0
  28. data/doc/rakefile.rdoc +622 -0
  29. data/doc/rational.rdoc +151 -0
  30. data/exe/rake +27 -0
  31. data/lib/rake.rb +71 -0
  32. data/lib/rake/application.rb +824 -0
  33. data/lib/rake/backtrace.rb +24 -0
  34. data/lib/rake/clean.rb +78 -0
  35. data/lib/rake/cloneable.rb +17 -0
  36. data/lib/rake/cpu_counter.rb +107 -0
  37. data/lib/rake/default_loader.rb +15 -0
  38. data/lib/rake/dsl_definition.rb +195 -0
  39. data/lib/rake/early_time.rb +22 -0
  40. data/lib/rake/ext/core.rb +26 -0
  41. data/lib/rake/ext/string.rb +176 -0
  42. data/lib/rake/file_creation_task.rb +25 -0
  43. data/lib/rake/file_list.rb +435 -0
  44. data/lib/rake/file_task.rb +54 -0
  45. data/lib/rake/file_utils.rb +134 -0
  46. data/lib/rake/file_utils_ext.rb +134 -0
  47. data/lib/rake/invocation_chain.rb +57 -0
  48. data/lib/rake/invocation_exception_mixin.rb +17 -0
  49. data/lib/rake/late_time.rb +18 -0
  50. data/lib/rake/linked_list.rb +112 -0
  51. data/lib/rake/loaders/makefile.rb +54 -0
  52. data/lib/rake/multi_task.rb +14 -0
  53. data/lib/rake/name_space.rb +38 -0
  54. data/lib/rake/packagetask.rb +222 -0
  55. data/lib/rake/phony.rb +16 -0
  56. data/lib/rake/private_reader.rb +21 -0
  57. data/lib/rake/promise.rb +100 -0
  58. data/lib/rake/pseudo_status.rb +30 -0
  59. data/lib/rake/rake_module.rb +67 -0
  60. data/lib/rake/rake_test_loader.rb +27 -0
  61. data/lib/rake/rule_recursion_overflow_error.rb +20 -0
  62. data/lib/rake/scope.rb +43 -0
  63. data/lib/rake/task.rb +433 -0
  64. data/lib/rake/task_argument_error.rb +8 -0
  65. data/lib/rake/task_arguments.rb +109 -0
  66. data/lib/rake/task_manager.rb +328 -0
  67. data/lib/rake/tasklib.rb +12 -0
  68. data/lib/rake/testtask.rb +224 -0
  69. data/lib/rake/thread_history_display.rb +49 -0
  70. data/lib/rake/thread_pool.rb +163 -0
  71. data/lib/rake/trace_output.rb +23 -0
  72. data/lib/rake/version.rb +10 -0
  73. data/lib/rake/win32.rb +51 -0
  74. data/rake.gemspec +36 -0
  75. metadata +132 -0
@@ -0,0 +1,127 @@
1
+ = Original Prototype Rake
2
+
3
+ This is the original 100 line prototype rake program.
4
+
5
+ ---
6
+ #!/usr/bin/env ruby
7
+
8
+ require 'ftools'
9
+
10
+ class Task
11
+ TASKS = Hash.new
12
+
13
+ attr_reader :prerequisites
14
+
15
+ def initialize(task_name)
16
+ @name = task_name
17
+ @prerequisites = []
18
+ @actions = []
19
+ end
20
+
21
+ def enhance(deps=nil, &block)
22
+ @prerequisites |= deps if deps
23
+ @actions << block if block_given?
24
+ self
25
+ end
26
+
27
+ def name
28
+ @name.to_s
29
+ end
30
+
31
+ def invoke
32
+ @prerequisites.each { |n| Task[n].invoke }
33
+ execute if needed?
34
+ end
35
+
36
+ def execute
37
+ return if @triggered
38
+ @triggered = true
39
+ @actions.collect { |act| result = act.call(self) }.last
40
+ end
41
+
42
+ def needed?
43
+ true
44
+ end
45
+
46
+ def timestamp
47
+ Time.now
48
+ end
49
+
50
+ class << self
51
+ def [](task_name)
52
+ TASKS[intern(task_name)] or fail "Don't know how to rake #{task_name}"
53
+ end
54
+
55
+ def define_task(args, &block)
56
+ case args
57
+ when Hash
58
+ fail "Too Many Target Names: #{args.keys.join(' ')}" if args.size > 1
59
+ fail "No Task Name Given" if args.size < 1
60
+ task_name = args.keys[0]
61
+ deps = args[task_name]
62
+ else
63
+ task_name = args
64
+ deps = []
65
+ end
66
+ deps = deps.collect {|d| intern(d) }
67
+ get(task_name).enhance(deps, &block)
68
+ end
69
+
70
+ def get(task_name)
71
+ name = intern(task_name)
72
+ TASKS[name] ||= self.new(name)
73
+ end
74
+
75
+ def intern(task_name)
76
+ (Symbol === task_name) ? task_name : task_name.intern
77
+ end
78
+ end
79
+ end
80
+
81
+ class FileTask < Task
82
+ def needed?
83
+ return true unless File.exist?(name)
84
+ latest_prereq = @prerequisites.collect{|n| Task[n].timestamp}.max
85
+ return false if latest_prereq.nil?
86
+ timestamp < latest_prereq
87
+ end
88
+
89
+ def timestamp
90
+ File.new(name.to_s).mtime
91
+ end
92
+ end
93
+
94
+ def task(args, &block)
95
+ Task.define_task(args, &block)
96
+ end
97
+
98
+ def file(args, &block)
99
+ FileTask.define_task(args, &block)
100
+ end
101
+
102
+ def sys(cmd)
103
+ puts cmd
104
+ system(cmd) or fail "Command Failed: [#{cmd}]"
105
+ end
106
+
107
+ def rake
108
+ begin
109
+ here = Dir.pwd
110
+ while ! File.exist?("Rakefile")
111
+ Dir.chdir("..")
112
+ fail "No Rakefile found" if Dir.pwd == here
113
+ here = Dir.pwd
114
+ end
115
+ puts "(in #{Dir.pwd})"
116
+ load "./Rakefile"
117
+ ARGV.push("default") if ARGV.size == 0
118
+ ARGV.each { |task_name| Task[task_name].invoke }
119
+ rescue Exception => ex
120
+ puts "rake aborted ... #{ex.message}"
121
+ puts ex.backtrace.find {|str| str =~ /Rakefile/ } || ""
122
+ end
123
+ end
124
+
125
+ if __FILE__ == $0 then
126
+ rake
127
+ end
@@ -0,0 +1,156 @@
1
+ .Dd June 12, 2016
2
+ .Dt RAKE 1
3
+ .Os rake 11.2.2
4
+ .Sh NAME
5
+ .Nm rake
6
+ .Nd make-like build utility for Ruby
7
+ .Sh SYNOPSIS
8
+ .Nm
9
+ .Op Fl f Ar rakefile
10
+ .Op Ar options
11
+ .Ar targets ...
12
+ .Sh DESCRIPTION
13
+ .Nm
14
+ is a
15
+ .Xr make 1 Ns -like
16
+ build utility for Ruby.
17
+ Tasks and dependencies are specified in standard Ruby syntax.
18
+ .Sh OPTIONS
19
+ .Bl -tag -width Ds
20
+ .It Fl m , Fl -multitask
21
+ Treat all tasks as multitasks.
22
+ .It Fl B , Fl -build-all
23
+ Build all prerequisites, including those which are up\-to\-date.
24
+ .It Fl j , Fl -jobs Ar num_jobs
25
+ Specifies the maximum number of tasks to execute in parallel (default is number of CPU cores + 4).
26
+ .El
27
+ .Ss Modules
28
+ .Bl -tag -width Ds
29
+ .It Fl I , Fl -libdir Ar libdir
30
+ Include
31
+ .Ar libdir
32
+ in the search path for required modules.
33
+ .It Fl r , Fl -require Ar module
34
+ Require
35
+ .Ar module
36
+ before executing
37
+ .Pa rakefile .
38
+ .El
39
+ .Ss Rakefile location
40
+ .Bl -tag -width Ds
41
+ .It Fl f , Fl -rakefile Ar filename
42
+ Use
43
+ .Ar filename
44
+ as the rakefile to search for.
45
+ .It Fl N , Fl -no-search , Fl -nosearch
46
+ Do not search parent directories for the Rakefile.
47
+ .It Fl G , Fl -no-system , Fl -nosystem
48
+ Use standard project Rakefile search paths, ignore system wide rakefiles.
49
+ .It Fl R , Fl -rakelib Ar rakelibdir , Fl -rakelibdir Ar rakelibdir
50
+ Auto-import any .rake files in
51
+ .Ar rakelibdir
52
+ (default is
53
+ .Sq rakelib )
54
+ .It Fl g , Fl -system
55
+ Use system-wide (global) rakefiles (usually
56
+ .Pa ~/.rake/*.rake ) .
57
+ .El
58
+ .Ss Debugging
59
+ .Bl -tag -width Ds
60
+ .It Fl -backtrace Ns = Ns Ar out
61
+ Enable full backtrace.
62
+ .Ar out
63
+ can be
64
+ .Dv stderr
65
+ (default) or
66
+ .Dv stdout .
67
+ .It Fl t , Fl -trace Ns = Ns Ar out
68
+ Turn on invoke/execute tracing, enable full backtrace.
69
+ .Ar out
70
+ can be
71
+ .Dv stderr
72
+ (default) or
73
+ .Dv stdout .
74
+ .It Fl -suppress-backtrace Ar pattern
75
+ Suppress backtrace lines matching regexp
76
+ .Ar pattern .
77
+ Ignored if
78
+ .Fl -trace
79
+ is on.
80
+ .It Fl -rules
81
+ Trace the rules resolution.
82
+ .It Fl n , Fl -dry-run
83
+ Do a dry run without executing actions.
84
+ .It Fl T , Fl -tasks Op Ar pattern
85
+ Display the tasks (matching optional
86
+ .Ar pattern )
87
+ with descriptions, then exit.
88
+ .It Fl D , Fl -describe Op Ar pattern
89
+ Describe the tasks (matching optional
90
+ .Ar pattern ) ,
91
+ then exit.
92
+ .It Fl W , Fl -where Op Ar pattern
93
+ Describe the tasks (matching optional
94
+ .Ar pattern ) ,
95
+ then exit.
96
+ .It Fl P , Fl -prereqs
97
+ Display the tasks and dependencies, then exit.
98
+ .It Fl e , Fl -execute Ar code
99
+ Execute some Ruby code and exit.
100
+ .It Fl p , Fl -execute-print Ar code
101
+ Execute some Ruby code, print the result, then exit.
102
+ .It Fl E , Fl -execute-continue Ar code
103
+ Execute some Ruby code, then continue with normal task processing.
104
+ .El
105
+ .Ss Information
106
+ .Bl -tag -width Ds
107
+ .It Fl v , Fl -verbose
108
+ Log message to standard output.
109
+ .It Fl q , Fl -quiet
110
+ Do not log messages to standard output.
111
+ .It Fl s , Fl -silent
112
+ Like
113
+ .Fl -quiet ,
114
+ but also suppresses the
115
+ .Sq in directory
116
+ announcement.
117
+ .It Fl X , Fl -no-deprecation-warnings
118
+ Disable the deprecation warnings.
119
+ .It Fl -comments
120
+ Show commented tasks only
121
+ .It Fl A , Fl -all
122
+ Show all tasks, even uncommented ones (in combination with
123
+ .Fl T
124
+ or
125
+ .Fl D )
126
+ .It Fl -job-stats Op Ar level
127
+ Display job statistics.
128
+ If
129
+ .Ar level
130
+ is
131
+ .Sq history ,
132
+ displays a complete job list.
133
+ .It Fl V , Fl -version
134
+ Display the program version.
135
+ .It Fl h , Fl H , Fl -help
136
+ Display a help message.
137
+ .El
138
+ .Sh SEE ALSO
139
+ The complete documentation for
140
+ .Nm rake
141
+ has been installed at
142
+ .Pa /usr/share/doc/rake-doc/html/index.html .
143
+ It is also available online at
144
+ .Lk https://ruby.github.io/rake .
145
+ .Sh AUTHORS
146
+ .An -nosplit
147
+ .Nm
148
+ was written by
149
+ .An Jim Weirich Aq Mt jim@weirichhouse.org .
150
+ .Pp
151
+ This manual was created by
152
+ .An Caitlin Matos Aq Mt caitlin.matos@zoho.com
153
+ for the Debian project (but may be used by others).
154
+ It was inspired by the manual by
155
+ .An Jani Monoses Aq Mt jani@iv.ro
156
+ for the Ubuntu project.
@@ -0,0 +1,622 @@
1
+ = Rakefile Format
2
+
3
+ First of all, there is no special format for a Rakefile. A Rakefile
4
+ contains executable Ruby code. Anything legal in a ruby script is
5
+ allowed in a Rakefile.
6
+
7
+ Now that we understand there is no special syntax in a Rakefile, there
8
+ are some conventions that are used in a Rakefile that are a little
9
+ unusual in a typical Ruby program. Since a Rakefile is tailored to
10
+ specifying tasks and actions, the idioms used in a Rakefile are
11
+ designed to support that.
12
+
13
+ So, what goes into a Rakefile?
14
+
15
+ == Tasks
16
+
17
+ Tasks are the main unit of work in a Rakefile. Tasks have a name
18
+ (usually given as a symbol or a string), a list of prerequisites (more
19
+ symbols or strings) and a list of actions (given as a block).
20
+
21
+ === Simple Tasks
22
+
23
+ A task is declared by using the +task+ method. +task+ takes a single
24
+ parameter that is the name of the task.
25
+
26
+ task :name
27
+
28
+ === Tasks with Prerequisites
29
+
30
+ Any prerequisites are given as a list (enclosed in square brackets)
31
+ following the name and an arrow (=>).
32
+
33
+ task name: [:prereq1, :prereq2]
34
+
35
+ *NOTE:* Although this syntax looks a little funky, it is legal
36
+ Ruby. We are constructing a hash where the key is :name and the value
37
+ for that key is the list of prerequisites. It is equivalent to the
38
+ following ...
39
+
40
+ hash = Hash.new
41
+ hash[:name] = [:prereq1, :prereq2]
42
+ task(hash)
43
+
44
+ You can also use strings for task names and prerequisites, rake doesn't care.
45
+ This is the same task definition:
46
+
47
+ task 'name' => %w[prereq1 prereq2]
48
+
49
+ As is this:
50
+
51
+ task name: %w[prereq1 prereq2]
52
+
53
+ We'll prefer this style for regular tasks with prerequisites throughout the
54
+ rest of the document. Using an array of strings for the prerequisites means
55
+ you will need to make fewer changes if you need to move tasks into namespaces
56
+ or perform other refactorings.
57
+
58
+ === Tasks with Actions
59
+
60
+ Actions are defined by passing a block to the +task+ method. Any Ruby
61
+ code can be placed in the block. The block may reference the task
62
+ object via the block parameter.
63
+
64
+ task name: [:prereq1, :prereq2] do |t|
65
+ # actions (may reference t)
66
+ end
67
+
68
+ === Multiple Definitions
69
+
70
+ A task may be specified more than once. Each specification adds its
71
+ prerequisites and actions to the existing definition. This allows one
72
+ part of a rakefile to specify the actions and a different rakefile
73
+ (perhaps separately generated) to specify the dependencies.
74
+
75
+ For example, the following is equivalent to the single task
76
+ specification given above.
77
+
78
+ task :name
79
+ task name: :prereq1
80
+ task name: %w[prereq2]
81
+ task :name do |t|
82
+ # actions
83
+ end
84
+
85
+ == File Tasks
86
+
87
+ Some tasks are designed to create a file from one or more other files.
88
+ Tasks that generate these files may be skipped if the file already
89
+ exists. File tasks are used to specify file creation tasks.
90
+
91
+ File tasks are declared using the +file+ method (instead of the +task+
92
+ method). In addition, file tasks are usually named with a string
93
+ rather than a symbol.
94
+
95
+ The following file task creates a executable program (named +prog+)
96
+ given two object files named +a.o+ and +b.o+. The tasks
97
+ for creating +a.o+ and +b.o+ are not shown.
98
+
99
+ file "prog" => ["a.o", "b.o"] do |t|
100
+ sh "cc -o #{t.name} #{t.prerequisites.join(' ')}"
101
+ end
102
+
103
+ == Directory Tasks
104
+
105
+ It is common to need to create directories upon demand. The
106
+ +directory+ convenience method is a short-hand for creating a FileTask
107
+ that creates the directory. For example, the following declaration
108
+ ...
109
+
110
+ directory "testdata/examples/doc"
111
+
112
+ is equivalent to ...
113
+
114
+ file "testdata" do |t| mkdir t.name end
115
+ file "testdata/examples" => ["testdata"] do |t| mkdir t.name end
116
+ file "testdata/examples/doc" => ["testdata/examples"] do |t| mkdir t.name end
117
+
118
+ The +directory+ method does not accept prerequisites or actions, but
119
+ both prerequisites and actions can be added later. For example ...
120
+
121
+ directory "testdata"
122
+ file "testdata" => ["otherdata"]
123
+ file "testdata" do
124
+ cp Dir["standard_data/*.data"], "testdata"
125
+ end
126
+
127
+ == Tasks with Parallel Prerequisites
128
+
129
+ Rake allows parallel execution of prerequisites using the following syntax:
130
+
131
+ multitask copy_files: %w[copy_src copy_doc copy_bin] do
132
+ puts "All Copies Complete"
133
+ end
134
+
135
+ In this example, +copy_files+ is a normal rake task. Its actions are
136
+ executed whenever all of its prerequisites are done. The big
137
+ difference is that the prerequisites (+copy_src+, +copy_bin+ and
138
+ +copy_doc+) are executed in parallel. Each of the prerequisites are
139
+ run in their own Ruby thread, possibly allowing faster overall runtime.
140
+
141
+ === Secondary Prerequisites
142
+
143
+ If any of the primary prerequisites of a multitask have common secondary
144
+ prerequisites, all of the primary/parallel prerequisites will wait
145
+ until the common prerequisites have been run.
146
+
147
+ For example, if the <tt>copy_<em>xxx</em></tt> tasks have the
148
+ following prerequisites:
149
+
150
+ task copy_src: :prep_for_copy
151
+ task copy_bin: :prep_for_copy
152
+ task copy_doc: :prep_for_copy
153
+
154
+ Then the +prep_for_copy+ task is run before starting all the copies in
155
+ parallel. Once +prep_for_copy+ is complete, +copy_src+, +copy_bin+,
156
+ and +copy_doc+ are all run in parallel. Note that +prep_for_copy+ is
157
+ run only once, even though it is referenced in multiple threads.
158
+
159
+ === Thread Safety
160
+
161
+ The Rake internal data structures are thread-safe with respect
162
+ to the multitask parallel execution, so there is no need for the user
163
+ to do extra synchronization for Rake's benefit. However, if there are
164
+ user data structures shared between the parallel prerequisites, the
165
+ user must do whatever is necessary to prevent race conditions.
166
+
167
+ == Tasks with Arguments
168
+
169
+ Prior to version 0.8.0, rake was only able to handle command line
170
+ arguments of the form NAME=VALUE that were passed into Rake via the
171
+ ENV hash. Many folks had asked for some kind of simple command line
172
+ arguments, perhaps using "--" to separate regular task names from
173
+ argument values on the command line. The problem is that there was no
174
+ easy way to associate positional arguments on the command line with
175
+ different tasks. Suppose both tasks :a and :b expect a command line
176
+ argument: does the first value go with :a? What if :b is run first?
177
+ Should it then get the first command line argument.
178
+
179
+ Rake 0.8.0 solves this problem by explicitly passing values directly
180
+ to the tasks that need them. For example, if I had a release task
181
+ that required a version number, I could say:
182
+
183
+ rake release[0.8.2]
184
+
185
+ And the string "0.8.2" will be passed to the :release task. Multiple
186
+ arguments can be passed by separating them with a comma, for example:
187
+
188
+ rake name[john,doe]
189
+
190
+ Just a few words of caution. The rake task name and its arguments
191
+ need to be a single command line argument to rake. This generally
192
+ means no spaces. If spaces are needed, then the entire name +
193
+ argument string should be quoted. Something like this:
194
+
195
+ rake "name[billy bob, smith]"
196
+
197
+ (Quoting rules vary between operating systems and shells, so make sure
198
+ you consult the proper docs for your OS/shell).
199
+
200
+ === Tasks that Expect Parameters
201
+
202
+ Parameters are only given to tasks that are setup to expect them. In
203
+ order to handle named parameters, the task declaration syntax for
204
+ tasks has been extended slightly.
205
+
206
+ For example, a task that needs a first name and last name might be
207
+ declared as:
208
+
209
+ task :name, [:first_name, :last_name]
210
+
211
+ The first argument is still the name of the task (:name in this case).
212
+ The next two arguments are the names of the parameters expected by
213
+ :name in an array (:first_name and :last_name in the example).
214
+
215
+ To access the values of the parameters, the block defining the task
216
+ behaviour can now accept a second parameter:
217
+
218
+ task :name, [:first_name, :last_name] do |t, args|
219
+ puts "First name is #{args.first_name}"
220
+ puts "Last name is #{args.last_name}"
221
+ end
222
+
223
+ The first argument of the block "t" is always bound to the current
224
+ task object. The second argument "args" is an open-struct like object
225
+ that allows access to the task arguments. Extra command line
226
+ arguments to a task are ignored.
227
+
228
+ If you wish to specify default values for the arguments, you can use
229
+ the with_defaults method in the task body. Here is the above example
230
+ where we specify default values for the first and last names:
231
+
232
+ task :name, [:first_name, :last_name] do |t, args|
233
+ args.with_defaults(:first_name => "John", :last_name => "Dough")
234
+ puts "First name is #{args.first_name}"
235
+ puts "Last name is #{args.last_name}"
236
+ end
237
+
238
+ === Tasks that Expect Parameters and Have Prerequisites
239
+
240
+ Tasks that use parameters have a slightly different format for
241
+ prerequisites. Use the arrow notation to indicate the prerequisites
242
+ for tasks with arguments. For example:
243
+
244
+ task :name, [:first_name, :last_name] => [:pre_name] do |t, args|
245
+ args.with_defaults(:first_name => "John", :last_name => "Dough")
246
+ puts "First name is #{args.first_name}"
247
+ puts "Last name is #{args.last_name}"
248
+ end
249
+
250
+ === Tasks that take Variable-length Parameters
251
+
252
+ Tasks that need to handle a list of values as a parameter can use the
253
+ extras method of the args variable. This allows for tasks that can
254
+ loop over a variable number of values, and its compatible with named
255
+ parameters as well:
256
+
257
+ task :email, [:message] do |t, args|
258
+ mail = Mail.new(args.message)
259
+ recipients = args.extras
260
+ recipients.each do |target|
261
+ mail.send_to(target)
262
+ end
263
+ end
264
+
265
+ There is also the convenience method to_a that returns all parameters
266
+ in the sequential order they were given, including those associated
267
+ with named parameters.
268
+
269
+ === Deprecated Task Parameters Format
270
+
271
+ There is an older format for declaring task parameters that omitted
272
+ the task argument array and used the :needs keyword to introduce the
273
+ dependencies. That format is still supported for compatibility, but
274
+ is not recommended for use. The older format may be dropped in future
275
+ versions of rake.
276
+
277
+ == Accessing Task Programmatically
278
+
279
+ Sometimes it is useful to manipulate tasks programmatically in a
280
+ Rakefile. To find a task object use Rake::Task.[].
281
+
282
+ === Programmatic Task Example
283
+
284
+ For example, the following Rakefile defines two tasks. The :doit task
285
+ simply prints a simple "DONE" message. The :dont class will lookup
286
+ the doit class and remove (clear) all of its prerequisites and
287
+ actions.
288
+
289
+ task :doit do
290
+ puts "DONE"
291
+ end
292
+
293
+ task :dont do
294
+ Rake::Task[:doit].clear
295
+ end
296
+
297
+ Running this example:
298
+
299
+ $ rake doit
300
+ (in /Users/jim/working/git/rake/x)
301
+ DONE
302
+ $ rake dont doit
303
+ (in /Users/jim/working/git/rake/x)
304
+ $
305
+
306
+ The ability to programmatically manipulate tasks gives rake very
307
+ powerful meta-programming capabilities w.r.t. task execution, but
308
+ should be used with caution.
309
+
310
+ == Rules
311
+
312
+ When a file is named as a prerequisite, but does not have a file task
313
+ defined for it, Rake will attempt to synthesize a task by looking at a
314
+ list of rules supplied in the Rakefile.
315
+
316
+ Suppose we were trying to invoke task "mycode.o", but no task is
317
+ defined for it. But the rakefile has a rule that look like this ...
318
+
319
+ rule '.o' => ['.c'] do |t|
320
+ sh "cc #{t.source} -c -o #{t.name}"
321
+ end
322
+
323
+ This rule will synthesize any task that ends in ".o". It has a
324
+ prerequisite a source file with an extension of ".c" must exist. If
325
+ Rake is able to find a file named "mycode.c", it will automatically
326
+ create a task that builds "mycode.o" from "mycode.c".
327
+
328
+ If the file "mycode.c" does not exist, rake will attempt
329
+ to recursively synthesize a rule for it.
330
+
331
+ When a task is synthesized from a rule, the +source+ attribute of the
332
+ task is set to the matching source file. This allows us to write
333
+ rules with actions that reference the source file.
334
+
335
+ === Advanced Rules
336
+
337
+ Any regular expression may be used as the rule pattern. Additionally,
338
+ a proc may be used to calculate the name of the source file. This
339
+ allows for complex patterns and sources.
340
+
341
+ The following rule is equivalent to the example above.
342
+
343
+ rule( /\.o$/ => [
344
+ proc {|task_name| task_name.sub(/\.[^.]+$/, '.c') }
345
+ ]) do |t|
346
+ sh "cc #{t.source} -c -o #{t.name}"
347
+ end
348
+
349
+ *NOTE:* Because of a _quirk_ in Ruby syntax, parenthesis are
350
+ required on *rule* when the first argument is a regular expression.
351
+
352
+ The following rule might be used for Java files ...
353
+
354
+ rule '.class' => [
355
+ proc { |tn| tn.sub(/\.class$/, '.java').sub(/^classes\//, 'src/') }
356
+ ] do |t|
357
+ java_compile(t.source, t.name)
358
+ end
359
+
360
+ *NOTE:* +java_compile+ is a hypothetical method that invokes the
361
+ java compiler.
362
+
363
+ == Importing Dependencies
364
+
365
+ Any ruby file (including other rakefiles) can be included with a
366
+ standard Ruby +require+ command. The rules and declarations in the
367
+ required file are just added to the definitions already accumulated.
368
+
369
+ Because the files are loaded _before_ the rake targets are evaluated,
370
+ the loaded files must be "ready to go" when the rake command is
371
+ invoked. This makes generated dependency files difficult to use. By
372
+ the time rake gets around to updating the dependencies file, it is too
373
+ late to load it.
374
+
375
+ The +import+ command addresses this by specifying a file to be loaded
376
+ _after_ the main rakefile is loaded, but _before_ any targets on the
377
+ command line are invoked. In addition, if the file name matches an
378
+ explicit task, that task is invoked before loading the file. This
379
+ allows dependency files to be generated and used in a single rake
380
+ command invocation.
381
+
382
+ Example:
383
+
384
+ require 'rake/loaders/makefile'
385
+
386
+ file ".depends.mf" => [SRC_LIST] do |t|
387
+ sh "makedepend -f- -- #{CFLAGS} -- #{t.prerequisites} > #{t.name}"
388
+ end
389
+
390
+ import ".depends.mf"
391
+
392
+ If ".depends" does not exist, or is out of date w.r.t. the source
393
+ files, a new ".depends" file is generated using +makedepend+ before
394
+ loading.
395
+
396
+ == Comments
397
+
398
+ Standard Ruby comments (beginning with "#") can be used anywhere it is
399
+ legal in Ruby source code, including comments for tasks and rules.
400
+ However, if you wish a task to be described using the "-T" switch,
401
+ then you need to use the +desc+ command to describe the task.
402
+
403
+ Example:
404
+
405
+ desc "Create a distribution package"
406
+ task package: %w[ ... ] do ... end
407
+
408
+ The "-T" switch (or "--tasks" if you like to spell things out) will
409
+ display a list of tasks that have a description. If you use +desc+ to
410
+ describe your major tasks, you have a semi-automatic way of generating
411
+ a summary of your Rake file.
412
+
413
+ $ rake -T
414
+ (in /home/.../rake)
415
+ rake clean # Remove any temporary products.
416
+ rake clobber # Remove any generated file.
417
+ rake clobber_rdoc # Remove rdoc products
418
+ rake contrib_test # Run tests for contrib_test
419
+ rake default # Default Task
420
+ rake install # Install the application
421
+ rake lines # Count lines in the main rake file
422
+ rake rdoc # Build the rdoc HTML Files
423
+ rake rerdoc # Force a rebuild of the RDOC files
424
+ rake test # Run tests
425
+ rake testall # Run all test targets
426
+
427
+ Only tasks with descriptions will be displayed with the "-T" switch.
428
+ Use "-P" (or "--prereqs") to get a list of all tasks and their
429
+ prerequisites.
430
+
431
+ == Namespaces
432
+
433
+ As projects grow (and along with it, the number of tasks), it is
434
+ common for task names to begin to clash. For example, if you might
435
+ have a main program and a set of sample programs built by a single
436
+ Rakefile. By placing the tasks related to the main program in one
437
+ namespace, and the tasks for building the sample programs in a
438
+ different namespace, the task names will not interfere with each other.
439
+
440
+ For example:
441
+
442
+ namespace "main" do
443
+ task :build do
444
+ # Build the main program
445
+ end
446
+ end
447
+
448
+ namespace "samples" do
449
+ task :build do
450
+ # Build the sample programs
451
+ end
452
+ end
453
+
454
+ task build: %w[main:build samples:build]
455
+
456
+ Referencing a task in a separate namespace can be achieved by
457
+ prefixing the task name with the namespace and a colon
458
+ (e.g. "main:build" refers to the :build task in the +main+ namespace).
459
+ Nested namespaces are supported.
460
+
461
+ Note that the name given in the +task+ command is always the unadorned
462
+ task name without any namespace prefixes. The +task+ command always
463
+ defines a task in the current namespace.
464
+
465
+ === FileTasks
466
+
467
+ File task names are not scoped by the namespace command. Since the
468
+ name of a file task is the name of an actual file in the file system,
469
+ it makes little sense to include file task names in name space.
470
+ Directory tasks (created by the +directory+ command) are a type of
471
+ file task and are also not affected by namespaces.
472
+
473
+ === Name Resolution
474
+
475
+ When looking up a task name, rake will start with the current
476
+ namespace and attempt to find the name there. If it fails to find a
477
+ name in the current namespace, it will search the parent namespaces
478
+ until a match is found (or an error occurs if there is no match).
479
+
480
+ The "rake" namespace is a special implicit namespace that refers to
481
+ the toplevel names.
482
+
483
+ If a task name begins with a "^" character, the name resolution will
484
+ start in the parent namespace. Multiple "^" characters are allowed.
485
+
486
+ Here is an example file with multiple :run tasks and how various names
487
+ resolve in different locations.
488
+
489
+ task :run
490
+
491
+ namespace "one" do
492
+ task :run
493
+
494
+ namespace "two" do
495
+ task :run
496
+
497
+ # :run => "one:two:run"
498
+ # "two:run" => "one:two:run"
499
+ # "one:two:run" => "one:two:run"
500
+ # "one:run" => "one:run"
501
+ # "^run" => "one:run"
502
+ # "^^run" => "rake:run" (the top level task)
503
+ # "rake:run" => "rake:run" (the top level task)
504
+ end
505
+
506
+ # :run => "one:run"
507
+ # "two:run" => "one:two:run"
508
+ # "^run" => "rake:run"
509
+ end
510
+
511
+ # :run => "rake:run"
512
+ # "one:run" => "one:run"
513
+ # "one:two:run" => "one:two:run"
514
+
515
+ == FileLists
516
+
517
+ FileLists are the way Rake manages lists of files. You can treat a
518
+ FileList as an array of strings for the most part, but FileLists
519
+ support some additional operations.
520
+
521
+ === Creating a FileList
522
+
523
+ Creating a file list is easy. Just give it the list of file names:
524
+
525
+ fl = FileList['file1.rb', file2.rb']
526
+
527
+ Or give it a glob pattern:
528
+
529
+ fl = FileList['*.rb']
530
+
531
+ == Odds and Ends
532
+
533
+ === do/end versus { }
534
+
535
+ Blocks may be specified with either a +do+/+end+ pair, or with curly
536
+ braces in Ruby. We _strongly_ recommend using +do+/+end+ to specify the
537
+ actions for tasks and rules. Because the rakefile idiom tends to
538
+ leave off parentheses on the task/file/rule methods, unusual
539
+ ambiguities can arise when using curly braces.
540
+
541
+ For example, suppose that the method +object_files+ returns a list of
542
+ object files in a project. Now we use +object_files+ as the
543
+ prerequisites in a rule specified with actions in curly braces.
544
+
545
+ # DON'T DO THIS!
546
+ file "prog" => object_files {
547
+ # Actions are expected here (but it doesn't work)!
548
+ }
549
+
550
+ Because curly braces have a higher precedence than +do+/+end+, the
551
+ block is associated with the +object_files+ method rather than the
552
+ +file+ method.
553
+
554
+ This is the proper way to specify the task ...
555
+
556
+ # THIS IS FINE
557
+ file "prog" => object_files do
558
+ # Actions go here
559
+ end
560
+
561
+ == Rakefile Path
562
+
563
+ When issuing the +rake+ command in a terminal, Rake will look
564
+ for a Rakefile in the current directory. If a Rakefile is not found,
565
+ it will search parent directories until one is found.
566
+
567
+ For example, if a Rakefile resides in the +project/+ directory,
568
+ moving deeper into the project's directory tree will not have an adverse
569
+ effect on rake tasks:
570
+
571
+ $ pwd
572
+ /home/user/project
573
+
574
+ $ cd lib/foo/bar
575
+ $ pwd
576
+ /home/user/project/lib/foo/bar
577
+
578
+ $ rake run_pwd
579
+ /home/user/project
580
+
581
+ As far as rake is concerned, all tasks are run from the directory in
582
+ which the Rakefile resides.
583
+
584
+ === Multiple Rake Files
585
+
586
+ Not all tasks need to be included in a single Rakefile. Additional
587
+ rake files (with the file extension "+.rake+") may be placed in
588
+ +rakelib+ directory located at the top level of a project (i.e.
589
+ the same directory that contains the main +Rakefile+).
590
+
591
+ Also, rails projects may include additional rake files in the
592
+ +lib/tasks+ directory.
593
+
594
+ === Clean and Clobber Tasks
595
+
596
+ Through <tt>require 'rake/clean'</tt> Rake provides +clean+ and +clobber+
597
+ tasks:
598
+
599
+ +clean+ ::
600
+ Clean up the project by deleting scratch files and backup files. Add files
601
+ to the +CLEAN+ FileList to have the +clean+ target handle them.
602
+
603
+ +clobber+ ::
604
+ Clobber all generated and non-source files in a project. The task depends
605
+ on +clean+, so all the +CLEAN+ files will be deleted as well as files in the
606
+ +CLOBBER+ FileList. The intent of this task is to return a project to its
607
+ pristine, just unpacked state.
608
+
609
+ You can add file names or glob patterns to both the +CLEAN+ and +CLOBBER+
610
+ lists.
611
+
612
+ === Phony Task
613
+
614
+ The phony task can be used as a dependency to allow file-based tasks to use
615
+ non-file-based-tasks as prerequisites without forcing them to rebuild. You
616
+ can <tt>require 'rake/phony'</tt> to add the +phony+ task.
617
+
618
+ ----
619
+
620
+ == See
621
+
622
+ * README.rdoc -- Main documentation for Rake.