ratch 0.2.3 → 0.3.0
Sign up to get free protection for your applications and to get access to all the features.
- data/bin/ratch +60 -47
- data/bin/ratch-find +21 -0
- data/demo/{README → XR} +0 -0
- data/demo/task/stats +0 -2
- data/doc/images/clipboard.jpg +0 -0
- data/doc/images/clipboard2.png +0 -0
- data/doc/images/milles-tn.jpg +0 -0
- data/doc/images/mints.png +0 -0
- data/doc/images/ratch2.png +0 -0
- data/doc/images/ruby-sm.png +0 -0
- data/doc/images/silver.gif +0 -0
- data/doc/images/toolbox.jpg +0 -0
- data/doc/index.html +181 -0
- data/doc/notes/original.rb +308 -0
- data/doc/rdoc/classes/Array.html +194 -0
- data/doc/rdoc/classes/Dir.html +317 -0
- data/doc/rdoc/classes/Hash.html +217 -0
- data/doc/rdoc/classes/Ratch.html +201 -0
- data/doc/rdoc/classes/Ratch/ArgvUtils.html +173 -0
- data/doc/rdoc/classes/Ratch/ArgvUtils/Ext.html +285 -0
- data/doc/rdoc/classes/Ratch/BatchFile.html +207 -0
- data/doc/rdoc/classes/Ratch/BatchManager.html +250 -0
- data/doc/rdoc/classes/Ratch/BatchScript.html +127 -0
- data/doc/rdoc/classes/Ratch/Batchable.html +373 -0
- data/doc/rdoc/classes/Ratch/Build.html +321 -0
- data/doc/rdoc/classes/Ratch/BuildManager.html +319 -0
- data/doc/rdoc/classes/Ratch/Buildable.html +202 -0
- data/doc/rdoc/classes/Ratch/ConfigUtils.html +281 -0
- data/doc/rdoc/classes/Ratch/ConsoleUtils.html +189 -0
- data/doc/rdoc/classes/Ratch/EmailUtils.html +209 -0
- data/doc/rdoc/classes/Ratch/FileUtils.html +674 -0
- data/doc/rdoc/classes/Ratch/GeneralOptions.html +430 -0
- data/doc/rdoc/classes/Ratch/Task.html +201 -0
- data/doc/rdoc/classes/Ratch/TaskManager.html +330 -0
- data/doc/rdoc/classes/Ratch/Taskable.html +231 -0
- data/doc/rdoc/classes/Ratch/UploadUtils.html +566 -0
- data/doc/rdoc/created.rid +1 -0
- data/doc/rdoc/files/COPYING.html +1003 -0
- data/{demo/doc → doc}/rdoc/files/README.html +36 -5
- data/doc/rdoc/files/lib/ratch/argvutils_rb.html +131 -0
- data/doc/rdoc/files/lib/ratch/batch_rb.html +155 -0
- data/doc/rdoc/files/lib/ratch/batchable_rb.html +131 -0
- data/doc/rdoc/files/lib/ratch/batchfile_rb.html +148 -0
- data/doc/rdoc/files/lib/ratch/buildable_rb.html +131 -0
- data/doc/rdoc/files/lib/ratch/consoleutils_rb.html +131 -0
- data/{demo/doc/rdoc/files/lib/foo/foo_rb.html → doc/rdoc/files/lib/ratch/emailutils_rb.html} +35 -41
- data/doc/rdoc/files/lib/ratch/facets/multiglob_rb.html +137 -0
- data/doc/rdoc/files/lib/ratch/fileutils_rb.html +139 -0
- data/doc/rdoc/files/lib/ratch/options_rb.html +131 -0
- data/doc/rdoc/files/lib/ratch/taskable_rb.html +131 -0
- data/doc/rdoc/files/lib/ratch/uploadutils_rb.html +150 -0
- data/doc/rdoc/fr_class_index.html +48 -0
- data/doc/rdoc/fr_file_index.html +41 -0
- data/doc/rdoc/fr_method_index.html +133 -0
- data/{demo/doc → doc}/rdoc/index.html +1 -1
- data/{demo/doc → doc}/rdoc/rdoc-style.css +0 -0
- data/doc/scrap/flexihead-flip.jpg +0 -0
- data/doc/scrap/flexihead.jpg +0 -0
- data/doc/scrap/head1.jpg +0 -0
- data/doc/scrap/ratch.jpg +0 -0
- data/doc/scrap/ratch1.png +0 -0
- data/doc/scrap/ratch2.jpg +0 -0
- data/doc/scrap/ratch3.png +0 -0
- data/doc/scrap/red-ratch.jpg +0 -0
- data/doc/scrap/redratchet.jpg +0 -0
- data/doc/scrap/ruby-kit/ruby.png +0 -0
- data/doc/scrap/scrap.red +256 -0
- data/doc/sitemap.yaml +10 -0
- data/doc/siteparts/index.red +100 -0
- data/doc/siteparts/layout.rhtml +56 -0
- data/doc/siteparts/tutorial.red +578 -0
- data/doc/style.css +112 -0
- data/doc/tutorial.html +722 -0
- data/lib/ratch/batch.rb +417 -30
- data/lib/ratch/{argvutils.rb → batch/argvutils.rb} +27 -19
- data/lib/ratch/batch/build.rb +95 -0
- data/lib/ratch/{consoleutils.rb → batch/consoleutils.rb} +0 -0
- data/lib/ratch/{emailutils.rb → batch/emailutils.rb} +0 -0
- data/lib/ratch/{fileutils.rb → batch/fileutils.rb} +32 -32
- data/lib/ratch/{options.rb → batch/options.rb} +0 -0
- data/lib/ratch/batch/task.rb +43 -0
- data/lib/ratch/manager.rb +34 -0
- data/lib/ratch/project/information.rb +257 -0
- data/lib/ratch/project/package.rb +82 -0
- data/lib/ratch/project/project.rb +531 -0
- data/lib/ratch/project/release.rb +112 -0
- data/lib/ratch/support/filetest.rb +29 -0
- data/lib/ratch/support/setuputils.rb +124 -0
- data/lib/ratch/support/signiture.rb +252 -0
- data/lib/ratch/support/stage.rb +292 -0
- data/lib/ratch/toolset/ruby/pack/gem +85 -0
- data/lib/ratch/toolset/ruby/pack/tgz +85 -0
- data/lib/ratch/toolset/ruby/{crosstest → test/crosstest} +0 -0
- data/lib/ratch/toolset/ruby/{extest → test/extest} +0 -0
- data/lib/ratch/toolset/ruby/{isotest → test/isotest} +0 -0
- data/lib/ratch/toolset/ruby/{load → test/load} +0 -0
- data/lib/ratch/toolset/ruby/{loadtest → test/loadtest} +0 -0
- data/lib/ratch/toolset/ruby/{syntax → test/syntax} +0 -0
- data/lib/ratch/toolset/ruby/{test → test/test} +0 -0
- data/log/{history.rd → history} +6 -0
- data/log/{todo.rd → todo} +0 -0
- data/meta/MANIFEST +52 -36
- data/meta/ROLLRC +2 -0
- data/meta/icli.yaml +16 -0
- data/meta/{ratch-0.2.3.roll → project.yaml} +1 -7
- data/task/release +12 -0
- data/{lib/ratch → work/old}/batchfile.rb +0 -0
- data/work/project-old.rb +67 -0
- data/work/scrap/install +89 -0
- data/work/scrap/install.0 +49 -0
- data/work/scrap/install.1 +63 -0
- data/work/scrap/ludo +25 -0
- data/work/scrap/oldtaskable.rb +573 -0
- data/work/scrap/ratch.man +39 -0
- data/work/scrap/taskable-simple.rb +42 -0
- data/work/scrap/taskable.rb +120 -0
- metadata +170 -72
- data/demo/doc/rdoc/created.rid +0 -1
- data/demo/doc/rdoc/fr_class_index.html +0 -26
- data/demo/doc/rdoc/fr_file_index.html +0 -28
- data/demo/doc/rdoc/fr_method_index.html +0 -27
- data/demo/task/config.yaml +0 -2
- data/lib/ratch/batchable.rb +0 -169
- data/lib/ratch/buildable.rb +0 -182
- data/lib/ratch/configutils.rb +0 -132
- data/lib/ratch/facets/multiglob.rb +0 -160
- data/lib/ratch/taskable.rb +0 -152
- data/log/recent.rd +0 -8
- data/task/config.yaml +0 -10
data/doc/sitemap.yaml
ADDED
@@ -0,0 +1,100 @@
|
|
1
|
+
h1(top). Welcome
|
2
|
+
|
3
|
+
Ratch is a Ruby-based build tool in the linage of Rake and Reap, but distinguishes
|
4
|
+
itself in it's closer adherence to the UNIX-way in that Ratch "targets" are independent
|
5
|
+
scripts. In fact, the name "ratch" derives from the phrase
|
6
|
+
"<u>R</u>uby b<u>atch</u> file".
|
7
|
+
|
8
|
+
Ratch is part of the ProUtils collection. In particular Ratch scripts might take
|
9
|
+
advantage of the "Box":http://proutils.rubyforge.org/box system and can easily be
|
10
|
+
copied and updated via "Mint":http://proutils.rubyforge.org/mint.
|
11
|
+
|
12
|
+
h1. News
|
13
|
+
|
14
|
+
h3(date). 2007-11-11
|
15
|
+
|
16
|
+
h2. From Special to Main
|
17
|
+
|
18
|
+
Ratch is really starting to come together. And I dare say that's no small statement.
|
19
|
+
I started development many, many months ago with only a hunch that the basic
|
20
|
+
design would be effective --was it even possible to effectively bridge the gap
|
21
|
+
between the shell and script? We may never have found out. Implementation has been
|
22
|
+
challenge at times and more than once a little voice in the back of my head would
|
23
|
+
say "just use Rake". But if I am anything, it is determined. I really believe
|
24
|
+
in the underlying design of this project --as hard as it might have been get "right".
|
25
|
+
|
26
|
+
But "right" is where I may finally be. Granted I'm still worried about tricky
|
27
|
+
dependency loops, but that's a rare bird and I have yet to see it happen in practice.
|
28
|
+
And, sure there's areas of the code that could just use some general spit-and-shine.
|
29
|
+
But in practice, it's really starting to look good.
|
30
|
+
|
31
|
+
For instance, this evening I transitioned from executing all ratch files in an
|
32
|
+
instance of a special runner class (a subclass of Module), to executing
|
33
|
+
in top-level 'main' space. This simplifies the start up code a fair bit and now allows
|
34
|
+
@load()@ to work for ratch files just as it does for ruby files --where as before
|
35
|
+
I had to create a special #import method to load the ratch file into the special object.
|
36
|
+
The benefit of this change is that one no longer _has_ to copy any of the pre-made tools
|
37
|
+
distributed with ratch. Instead one can just depend on them like normal code.
|
38
|
+
For instance, my projects tool/stats file looks like this:
|
39
|
+
|
40
|
+
<pre>
|
41
|
+
#!/usr/bin/env ratch
|
42
|
+
# code stats
|
43
|
+
load('ratch/toolset/ruby/stats')
|
44
|
+
</pre>
|
45
|
+
|
46
|
+
Of course if you want to make project specific modifications you can still grab a copy
|
47
|
+
and have at it.
|
48
|
+
|
49
|
+
|
50
|
+
h1. Installation
|
51
|
+
|
52
|
+
Via RubyGems:
|
53
|
+
|
54
|
+
$ gem install ratch
|
55
|
+
|
56
|
+
With the source code:
|
57
|
+
|
58
|
+
$ tar -xzf ratch-x.y.z.tar.gz
|
59
|
+
$ cd ratch-x.y.z
|
60
|
+
$ sudo task/setup
|
61
|
+
|
62
|
+
Microsoft Windows users, you'll have to use '@ruby task/setup@' instead.
|
63
|
+
|
64
|
+
|
65
|
+
h1. Development
|
66
|
+
|
67
|
+
Ratch is part of the "ProUtils":http://protuils.rubyforge.org project.
|
68
|
+
|
69
|
+
h2. Anonymous Subversion Access
|
70
|
+
|
71
|
+
This project's SVN repository can be checked out through anonymous access with the following command(s).
|
72
|
+
|
73
|
+
svn checkout svn://rubyforge.org/var/svn/proutils/ratch
|
74
|
+
svn checkout http://proutils.rubyforge.org/svn/ratch
|
75
|
+
|
76
|
+
h2. Developer Subversion Access via SSH
|
77
|
+
|
78
|
+
Only project developers can access the SVN tree via this method. SSH must be installed on your client machine. Substitute developername with the proper values. Enter your site password when prompted.
|
79
|
+
|
80
|
+
svn checkout svn+ssh://developername@rubyforge.org/var/svn/proutils/ratch
|
81
|
+
|
82
|
+
|
83
|
+
h1. Copying
|
84
|
+
|
85
|
+
Ratch -- Ruby-based Batch Files
|
86
|
+
|
87
|
+
Copyright © 2007 Ψ Τ Corporation
|
88
|
+
|
89
|
+
This program is free software: you can redistribute it and/or modify
|
90
|
+
it under the terms of the GNU General Public License as published by
|
91
|
+
the Free Software Foundation, either version 3 of the License, or
|
92
|
+
(at your option) any later version.
|
93
|
+
|
94
|
+
This program is distributed in the hope that it will be useful,
|
95
|
+
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
96
|
+
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
97
|
+
GNU General Public License for more details.
|
98
|
+
|
99
|
+
You should have received a copy of the GNU General Public License
|
100
|
+
along with this program. If not, see <http://www.gnu.org/licenses/>.
|
@@ -0,0 +1,56 @@
|
|
1
|
+
<html>
|
2
|
+
<head>
|
3
|
+
<title>Ratch</title>
|
4
|
+
<link href="style.css" rel="stylesheet" type="text/css"/>
|
5
|
+
<LINK REL="SHORTCUT ICON" HREF="images/ratch1.png"/>
|
6
|
+
</head>
|
7
|
+
<body>
|
8
|
+
|
9
|
+
<div class="promenu">
|
10
|
+
ProUtils :: <a href="http://proutils.rubyforge.org/">Home</a> ·
|
11
|
+
<a href="http://rubyforge.org/news/?group_id=4438">News</a> ·
|
12
|
+
<a href="http://rubyforge.org/frs/?group_id=4438">Download</a> ·
|
13
|
+
<a href="http://rubyforge.org/mail/?group_id=4438">Mail</a> ·
|
14
|
+
<a href="http://rubyforge.org/forum/?group_id=4438">Forum</a> ·
|
15
|
+
<a href="http://rubyforge.org/scm/?group_id=4438">Source</a> ·
|
16
|
+
<a href="http://rubyforge.org/tracker/?group_id=4438">Ticket</a>
|
17
|
+
</div>
|
18
|
+
|
19
|
+
<div class="container">
|
20
|
+
|
21
|
+
<div class="banner">
|
22
|
+
RATCH <img src="images/ruby-sm.png"/>
|
23
|
+
</div>
|
24
|
+
|
25
|
+
<div class="menu">
|
26
|
+
<a href="index.html">Welcome</a>
|
27
|
+
<a href="tutorial.html">Tutorial</a>
|
28
|
+
<a href="rdoc/index.html">Library</a>
|
29
|
+
</div>
|
30
|
+
|
31
|
+
<div class="ad">
|
32
|
+
<script type="text/javascript"><!--
|
33
|
+
google_ad_client = "pub-1126154564663472";
|
34
|
+
//RATCH 728x90, 11/8/07
|
35
|
+
google_ad_slot = "6500283279";
|
36
|
+
google_ad_width = 728;
|
37
|
+
google_ad_height = 90;
|
38
|
+
//--></script>
|
39
|
+
<script type="text/javascript"
|
40
|
+
src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
|
41
|
+
</script>
|
42
|
+
</div>
|
43
|
+
|
44
|
+
<div class="content">
|
45
|
+
<%= part :content %>
|
46
|
+
</div>
|
47
|
+
|
48
|
+
<div class="copyright">
|
49
|
+
Ratch, Copyright © 2007 <a href="http://psytower.info">Ψ Τ Corp.</a> <br/><br/>
|
50
|
+
Website design by <a href="http://psytower.info/transcode/">TransCrankItOut</a> using <a href="">Webrite</a>!
|
51
|
+
</div>
|
52
|
+
|
53
|
+
</div>
|
54
|
+
|
55
|
+
</body>
|
56
|
+
</html>
|
@@ -0,0 +1,578 @@
|
|
1
|
+
p(rev){float: right}. rev. 9
|
2
|
+
|
3
|
+
h1(top). Ratch Tutorial
|
4
|
+
|
5
|
+
p(copy). Copyright © 2006 7rans. All Rights Reserved.
|
6
|
+
|
7
|
+
p(important). IMPORTANT
|
8
|
+
Ratch is still in it's infancy as a project. While mostly functional
|
9
|
+
in its present state, it is still under going a good bit of design
|
10
|
+
considerations, so methods and certain aspects of functionality may
|
11
|
+
change. Likewise, documentation is not 100% current.
|
12
|
+
|
13
|
+
|
14
|
+
|
15
|
+
h1. Introduction
|
16
|
+
|
17
|
+
Ratch is a Ruby-based batch file system specially designed for handling
|
18
|
+
project support and build tasks.
|
19
|
+
|
20
|
+
The creation of support and build tools for a project enatils the
|
21
|
+
question of whether to simply use shell scripts or rely on a specialized
|
22
|
+
build system. The later is almost always the prefered choice. Why?
|
23
|
+
Two reasons in particular stand out. First, and perhaps most importantly,
|
24
|
+
shell scripts are generally not cross-platform. A shell script on a Linux
|
25
|
+
machine may well fail on a Mac X system, and will certainly fail on a Windows
|
26
|
+
system. Second, shell scripting lacks dedicated support for the creation of
|
27
|
+
build tasks. This is the reason we have tools like Make --a build tool built
|
28
|
+
on top of the Unix shell commands.
|
29
|
+
|
30
|
+
Ratch solves these two issues by providing a cross-platform shell scripting
|
31
|
+
DSL based on Ruby. Ratch scripts are really just Ruby scripts. What sets them
|
32
|
+
apart from plain Ruby is the convenient Domain Specific Language (DSL) that
|
33
|
+
Ratch provides geared specifically toward the needs of project task and
|
34
|
+
build task scripting. With Ratch, scripting becomes a viable option again.
|
35
|
+
|
36
|
+
Individual task scripts have some clear advantages over monolithic build systems:
|
37
|
+
|
38
|
+
* Tasks are clearly enumerable and can be viewed like any other file-system folder.
|
39
|
+
* And like any system script, permissions can be restricted --per individual task.
|
40
|
+
* Individual tasks can be easily edited w/o sorting through large "Makefiles".
|
41
|
+
* Shell-based tools and scripts written in other languages easily coexist.
|
42
|
+
|
43
|
+
The only signifficant disadvantage to the script appraoch is the focus on _tasks_
|
44
|
+
rather than _builds_. In other words one can't ask that a particular file be built
|
45
|
+
unless some task provides an interface for doing so.
|
46
|
+
|
47
|
+
But Ratch provides some
|
48
|
+
|
49
|
+
|
50
|
+
h2. Getting Started
|
51
|
+
|
52
|
+
If you haven't already done so, you'll first need to install Ratch.
|
53
|
+
The process is straight-forward with RubyGems.
|
54
|
+
|
55
|
+
$ gem install ratch
|
56
|
+
|
57
|
+
Alternatively you can install from source. Simply, download the package file,
|
58
|
+
decompress it, 'cd' into the package directory and run @task/setup@.
|
59
|
+
|
60
|
+
$ tar -xvzf ratch-1.0.0.gzip
|
61
|
+
$ cd ratch-1.0.0
|
62
|
+
$ sudo task/setup
|
63
|
+
|
64
|
+
Once installed, you can immediately start using Ratch. However, to make life even
|
65
|
+
easier, two other tools augment Ratch very nicely. So we recommend that you also
|
66
|
+
install "Box":http://reap.rubyforge.org/box and "Mint":http://reap.rubyforge.org/mint.
|
67
|
+
Box is meta-packaging system and Mint is managed copy tool. They are optional,
|
68
|
+
but parts of this tutorial will also cover their use in relation to Ratch.
|
69
|
+
|
70
|
+
|
71
|
+
!{float: right; width: 150px;}images/toolbox.jpg!
|
72
|
+
|
73
|
+
h1. Task Creation
|
74
|
+
|
75
|
+
|
76
|
+
h2. Creating Your First Task
|
77
|
+
|
78
|
+
Let jump right in by creating a Ratch script so you can see just how easy it is.
|
79
|
+
First create a faux project dirctory in which to conduct our tutorial. We'll call it
|
80
|
+
@myproject/@.
|
81
|
+
|
82
|
+
$ mkdir myproject
|
83
|
+
|
84
|
+
Now @cd@ into it and create a directory to store your ratch scripts. The name of the directory
|
85
|
+
can be anything you like. Ratch doesn't require that it have a special name. For the purposes
|
86
|
+
of this tutorial we will call it @task/@.
|
87
|
+
|
88
|
+
$ cd myproject
|
89
|
+
$ mkdir task
|
90
|
+
|
91
|
+
Now lets create a ratch script.
|
92
|
+
|
93
|
+
$ vi task/list
|
94
|
+
|
95
|
+
This example uses @vi@. You can use your favorite editor, of course. Now, edit the file to read:
|
96
|
+
|
97
|
+
<pre class="script">
|
98
|
+
#!/usr/bin/env ratch
|
99
|
+
|
100
|
+
# List project files
|
101
|
+
|
102
|
+
puts glob('**/*')
|
103
|
+
</pre>
|
104
|
+
|
105
|
+
Save the file. If you are using a Unix-based operating system, also change the file's
|
106
|
+
mode to be user executable[2].
|
107
|
+
|
108
|
+
$ chmod u+x task/list
|
109
|
+
|
110
|
+
Now run it like you might any executable file on your system:
|
111
|
+
|
112
|
+
$ task/list
|
113
|
+
|
114
|
+
fn2. On Windows systems you do this a little differntly. Instead you need to run the task
|
115
|
+
via either of the @ruby@ command. Ie. @ruby task/list@. You'll need to keep
|
116
|
+
that in mind throughout this tutorial.
|
117
|
+
|
118
|
+
And, as you might have expected, our first task printed a listing of every file in our
|
119
|
+
project directory. Pretty simple. Yet there are a few things to notice about this example.
|
120
|
+
|
121
|
+
First, the @glob@ command. @glob@ is not a standard main method in Ruby. So this method
|
122
|
+
comes instead from the Ratch DSL. In normal Ruby you'd have to use @Dir.glob@ to do the same
|
123
|
+
thing. Wile a minor difference, this is a simple example of how Ratch makes building project
|
124
|
+
tasks easier than just using normal Ruby scripts. There are many more methods provided by
|
125
|
+
Ratch's DSL, and we will cover many of them later in this tutorial.
|
126
|
+
|
127
|
+
The other thing to notice is that we executed our script like we would any local command,
|
128
|
+
and we did so _from the project's root directory_. This is very important. <i>The task will
|
129
|
+
act on the directory from which it is called</i>. This can be useful if a task provides
|
130
|
+
behavior effective relative to the call location, but it also means we must remain aware
|
131
|
+
this versitility, and use our task accordinginly. However, often a task is designed to be
|
132
|
+
run only from the project's root directory, as we did in our example. In those cases it
|
133
|
+
is not uncommon for the task to perform _sanity_ checks to make sure that's indeed were a
|
134
|
+
task is being run. One thing you should not do though, but may at first be tempted to do,
|
135
|
+
is @cd@ down into that task directory and run the tasks from there. Do not do that.
|
136
|
+
It won't work!!!
|
137
|
+
|
138
|
+
h2. Task and System Calls
|
139
|
+
|
140
|
+
Okay, that's our first teeny tiny example. Now's its time to dig a little deeper into the
|
141
|
+
Ratch DSL.
|
142
|
+
|
143
|
+
One of more unique aspects of Ratch scripts is the way in polymophizes internal method calls,
|
144
|
+
external task calls and external command calls. To demonstrate lets define a second task
|
145
|
+
called 'list2'.
|
146
|
+
|
147
|
+
$ vi task/list2
|
148
|
+
|
149
|
+
Make it read:
|
150
|
+
|
151
|
+
<pre class="script">
|
152
|
+
#!/usr/bin/env ratch
|
153
|
+
|
154
|
+
# List project files
|
155
|
+
|
156
|
+
puts "How many lists?"
|
157
|
+
list
|
158
|
+
list
|
159
|
+
list
|
160
|
+
</pre>
|
161
|
+
|
162
|
+
Be sure to change the mode to user executable, then run it.
|
163
|
+
|
164
|
+
$ task/list2
|
165
|
+
|
166
|
+
You will notice that calling @list2@, in turn, calls our first script, @list@. But it didn't generate
|
167
|
+
a list three times, as you may have expected, but only once. That's because tasks, by definition, are
|
168
|
+
only supposed to run once in a given run session. Internally, task results are cached to facilitate this.
|
169
|
+
|
170
|
+
Now lets try another example. First, rename @last2@ to @rdoc@
|
171
|
+
|
172
|
+
$ mv task/list2 task/rdoc
|
173
|
+
|
174
|
+
Then edit it to read:
|
175
|
+
|
176
|
+
<pre class="script">
|
177
|
+
#!/usr/bin/env ratch
|
178
|
+
|
179
|
+
# Generate RDocs
|
180
|
+
|
181
|
+
rdoc "README", 'm' => true, 'op' => 'doc'
|
182
|
+
</pre>
|
183
|
+
|
184
|
+
For this example to work we'll need to create a @README@ file in project's root directory.
|
185
|
+
Anything content will do:
|
186
|
+
|
187
|
+
$ echo "= Welcome" > README
|
188
|
+
|
189
|
+
Now, rather than run the task outright, let's see what it would do without actually running the task.
|
190
|
+
Ratch provieds a --dryrun global flag that allows you to check/debug scripts easily.
|
191
|
+
|
192
|
+
$ task/rdoc --dryrun
|
193
|
+
rdoc -m --op doc lib
|
194
|
+
|
195
|
+
Ratch prints out the command that would have been run without the --dryrun flag. Notice how
|
196
|
+
Ratch interpreted the Ruby-esque method call as a commandline tool. It knew this b/c
|
197
|
+
1) there were no methods defined with then name 'rdoc', 2) there were not other local tasks
|
198
|
+
with the name rdoc (the task's own filename does not count), and 3) it looked up the
|
199
|
+
systems list of executable files and found 'rdoc' listed. It then interprets the arguments
|
200
|
+
accordingly, the main trick being that any trailing keyword arguments will be truned into
|
201
|
+
flag options of the command. However sometimes an external command will have an argument
|
202
|
+
usage that Ratch can't handle. In thos cases simple trail along argument text. For instance
|
203
|
+
the above #rdoc call could have been written in any number of ways:
|
204
|
+
|
205
|
+
<pre>
|
206
|
+
rdoc "-m --op doc "README"
|
207
|
+
rdoc "-m --op doc", "README"
|
208
|
+
rdoc "-m", "--op doc", "README"
|
209
|
+
</pre>
|
210
|
+
|
211
|
+
Occasionally, there may be a name conflict bwetween a method and an external task
|
212
|
+
or command you wish to use. In those cases you can invoke the task or command using
|
213
|
+
either the @target@ or @system@ reference object, respectively. For instance the above
|
214
|
+
could have also been written:
|
215
|
+
|
216
|
+
system.rdoc "README", 'm' => true, 'op' => 'doc'
|
217
|
+
|
218
|
+
The two forms are completely equivalent. The former is simply using @system@
|
219
|
+
behined the scenes.
|
220
|
+
|
221
|
+
h2. Integrated Build Tools
|
222
|
+
|
223
|
+
Well Ratch wouldn't be much a build tool if it didn't facilitate the defintion
|
224
|
+
of file creation tasks, beyond simply running shell commands on demand. Ratch
|
225
|
+
provides a DSL method, @file@, just for this purpose. With it we can rewrite
|
226
|
+
the above RDoc task more robustly as:
|
227
|
+
|
228
|
+
<pre class="script">
|
229
|
+
#!/usr/bin/env ratch
|
230
|
+
|
231
|
+
# Generate RDocs
|
232
|
+
|
233
|
+
file 'doc' => ['README'] do
|
234
|
+
rdoc "README", 'm' => true, 'op' => 'doc'
|
235
|
+
end
|
236
|
+
|
237
|
+
target 'doc'
|
238
|
+
</pre>
|
239
|
+
|
240
|
+
If you are familiar with Rake or Rant what this does is clear. It says that the
|
241
|
+
construction of a target file, in this case a directory called 'doc', depends on
|
242
|
+
a file 'README'. What this does in practice is compare the modification times
|
243
|
+
of the target and it's dependsencies. If _any_ of the dependencies
|
244
|
+
have a modification time _after_ the target file's, then the target clearly
|
245
|
+
needs to be regenerated and so the task will execute. But if _none_ of the
|
246
|
+
the dependecies have a last modification time _after_ the targets, the the
|
247
|
+
target is considered upto date, and will not be rebuilt.
|
248
|
+
|
249
|
+
Note the last line @target :doc@, which invokes an _internal target_,
|
250
|
+
as opposed to external target which is another task script.
|
251
|
+
|
252
|
+
|
253
|
+
h2. Task Configuration
|
254
|
+
|
255
|
+
Often a task proves useful enough to be reused in other projects, but to do this requires
|
256
|
+
some level of generalization and configurability. Ratch makes this easy to do via the
|
257
|
+
#config_load method. With it you can load a set of configuration options tied to a specific
|
258
|
+
name. The information can then be an entry in a central @config.yaml@ file in your task
|
259
|
+
directory, or it can be in a file by that name, ie. @_name_.yaml@.
|
260
|
+
|
261
|
+
For example, a @config.yaml@ file might look something like:
|
262
|
+
|
263
|
+
<pre class="script">
|
264
|
+
---
|
265
|
+
|
266
|
+
rdoc:
|
267
|
+
dir : 'doc/rdoc'
|
268
|
+
main : README
|
269
|
+
|
270
|
+
publish:
|
271
|
+
target : rubyforge
|
272
|
+
type : web
|
273
|
+
host : rubyforge.org
|
274
|
+
username : transami
|
275
|
+
dir : web
|
276
|
+
|
277
|
+
release:
|
278
|
+
host : rubyforge.org
|
279
|
+
username : transami
|
280
|
+
project : reap
|
281
|
+
groupid : 811
|
282
|
+
package : ratch
|
283
|
+
dir : pkg
|
284
|
+
</pre>
|
285
|
+
|
286
|
+
In a script one can access this information easily. With it we can define our rdoc task
|
287
|
+
like so:
|
288
|
+
|
289
|
+
<pre class="script">
|
290
|
+
#!/usr/bin/env ratch
|
291
|
+
|
292
|
+
# Generate RDocs
|
293
|
+
|
294
|
+
config = load_config('rdoc')
|
295
|
+
|
296
|
+
output = config['dir']
|
297
|
+
include = config['include'] || ['README']
|
298
|
+
|
299
|
+
file ouput => include do
|
300
|
+
rdoc include, 'm' => true, 'op' => output
|
301
|
+
end
|
302
|
+
|
303
|
+
target 'doc'
|
304
|
+
</pre>
|
305
|
+
|
306
|
+
Now our rdoc task is perfectly general (albiet a bit simplistic), we can reuse the same
|
307
|
+
task in any project. We only need to change the config.yaml settings per project instead
|
308
|
+
of having to make isolated changes to the task itself. In turn this makes it possible to
|
309
|
+
readily share task with other project developers.
|
310
|
+
|
311
|
+
|
312
|
+
h2. Project Info via Box
|
313
|
+
|
314
|
+
!{float: left; width: 100px;}images/box.jpg!
|
315
|
+
|
316
|
+
Notice the reference to 'info'. This is an OpenStruct-like interface to the project information.
|
317
|
+
|
318
|
+
It's a good idea to take some time and learn all the standard properties of a project's information file
|
319
|
+
which you can draw on for your own tools. Looking at the RDoc API documentation will elucidate most of them.
|
320
|
+
And, of course you can also invent your own if needed.
|
321
|
+
|
322
|
+
|
323
|
+
|
324
|
+
As you can see this creates a <i>project information file</i> called <code>ProjectInfo</code>.
|
325
|
+
Another, and perhaps better way to create a ProjectInfo file is to copy one from some
|
326
|
+
other project and modify it to suit your needs. That makes it easier to learn how to fill
|
327
|
+
them out. But if you don't have that option or you are already familiar with the layout,
|
328
|
+
then you can use <code>mint</code> to copy a new template.
|
329
|
+
|
330
|
+
The name of the project information file has some flexibility. Capitalization, for
|
331
|
+
instance, is insignifficant; <code>projectinfo</code> would do just as well. Also
|
332
|
+
a few alternative namings are supported, namely, <code>project.yaml</code> or just
|
333
|
+
<code>PROJECT</code> (again capitalization doesn't matter). For simplicity sake we will refer
|
334
|
+
to this file as the ProjectInfo file throughout the documentation. Just remember that you
|
335
|
+
can substitue any of these other supported names in it's place to suit your personal preference.
|
336
|
+
If you prefer one of the alternate names when creating the file, you can specify it as
|
337
|
+
a parameter of the <code>--info</code> option.
|
338
|
+
|
339
|
+
$ project new --info project.yaml
|
340
|
+
|
341
|
+
Rather then 'ProjectInfo', the file will be called 'project.yaml'. Ratchets will let you know
|
342
|
+
if you pick a name it does not recognize.
|
343
|
+
|
344
|
+
Once you have edited the ProjectInfo file (more on this in the next section), subsequnelty running
|
345
|
+
<code>project new</code> will create the same project layout as before, but it will add
|
346
|
+
enhanced details to further ease the creation of the new project. For instance, the lib
|
347
|
+
directory will already have subdirectory named appropriately and if you use the --web option,
|
348
|
+
the index.html page will be suitably labeled. And so on.
|
349
|
+
|
350
|
+
<div class="special"><b>NOTE</b> The enhanced information scaffolding is barely
|
351
|
+
implemented as of yet. But will continue to improve with future releases.</div>
|
352
|
+
|
353
|
+
Of course, if you already have a project with which you wish to use Ratchets, rather than
|
354
|
+
create a whole new project layout you will probably just want to add the <code><i>ProjectInfo</i></code>
|
355
|
+
file to it. In that case you simply run <code>project new --info</code>. The project information file
|
356
|
+
will be added and the rest of your project will be undisturbed. Running <code>project new</code> on
|
357
|
+
a pre-existing project will have no effect. It will simply report an error that your project
|
358
|
+
already has content.
|
359
|
+
|
360
|
+
The project file is of central importance to Ratchets and the <code>project</code> command.
|
361
|
+
The file is a YAML-formatted file storing shared information from which Ratchets' tools gather
|
362
|
+
default information on how to perform their actions. Most subsequent activity will largely
|
363
|
+
depend on the content of this file. So lets now turn our attention squarely to it.
|
364
|
+
|
365
|
+
The structure of the ProjectInfo file is fairly self-explanitory. The header is devoted to
|
366
|
+
common information. This is generally followed by deafult tool settings. And lastly
|
367
|
+
a <i>tasks</i> section is used to define user tasks. Each task entry is a YAML map where the
|
368
|
+
key represent the task name followed by a private type (!!) which identifies the tool
|
369
|
+
it invokes. The next line begins the indented attributes the tool needs to do the job.
|
370
|
+
To a detailed list of parameters each tool accepts have a look at the RDoc API.
|
371
|
+
|
372
|
+
Example ProjectInfo File
|
373
|
+
|
374
|
+
<pre class="script">
|
375
|
+
--- %YAML:1.0
|
376
|
+
|
377
|
+
title : Reap
|
378
|
+
name : reap
|
379
|
+
|
380
|
+
version : 6.0.0
|
381
|
+
status : 'beta'
|
382
|
+
|
383
|
+
author : Thomas Sawyer
|
384
|
+
created : '2004-04-01'
|
385
|
+
email : transfirz@zmail.com
|
386
|
+
homepage : "http://reap.rubyforge.org"
|
387
|
+
|
388
|
+
summary : A Ruby Project Management Assistant
|
389
|
+
|
390
|
+
description: >
|
391
|
+
Reap comprises a set of tasks commonly needed by
|
392
|
+
Ruby package developers/deployers, such as testing,
|
393
|
+
packaging, releasing, etc. You can also use Reap
|
394
|
+
to create your own custom tasks. Reap utilizes a
|
395
|
+
YAML configuration file to harvest common project
|
396
|
+
information, significantly simplifying these chores.
|
397
|
+
|
398
|
+
rubyforge:
|
399
|
+
project : reap
|
400
|
+
username : transami
|
401
|
+
|
402
|
+
revision:
|
403
|
+
tool: darcs
|
404
|
+
exclude:
|
405
|
+
- doc/api
|
406
|
+
|
407
|
+
executables : [ reap, rubytest ]
|
408
|
+
|
409
|
+
dependencies:
|
410
|
+
- [ facets, '> 1.5' ]
|
411
|
+
|
412
|
+
exclude:
|
413
|
+
- snip
|
414
|
+
- doc/api
|
415
|
+
</pre>
|
416
|
+
|
417
|
+
As you can the top portion is fairly self-explainitory. After that we see entries related to
|
418
|
+
specific Ratchet tools like package. This entry specifies default parameters to use for any
|
419
|
+
subsequent call of the package tool. We will cover this in more detail in the
|
420
|
+
<a href="tool.html">Tool Utilization</a> documention.
|
421
|
+
|
422
|
+
Following this is the tasks section with which we can define our own user-defined
|
423
|
+
tasks. Typically these are specializtions of the buil-in tools,
|
424
|
+
but as you can see by our "silly example" arbitary tasks can be written as well. We will
|
425
|
+
cover this in more detail in the <a href="task.html">Task Management</a> documentation.
|
426
|
+
|
427
|
+
|
428
|
+
h2. Verifying Project Information
|
429
|
+
|
430
|
+
When Ratchets searches for a ProjectInfo file it will move up the
|
431
|
+
directory hierarchy from the current working directory until it finds a ProjectInfo file
|
432
|
+
and will assume the location of that file is your project's source directory unless the file
|
433
|
+
itself specifes that another directory is the source root.
|
434
|
+
|
435
|
+
Project has one other subcommand that can be used to verify the project information: <code>info</code>.
|
436
|
+
This simply dumps the parsed contents of the ProjectInfo file to stdout.
|
437
|
+
|
438
|
+
$ box --dump
|
439
|
+
|
440
|
+
This may seem trivial, but it can be sometimes be useful to quicky insure information
|
441
|
+
is correct and that you are calling <code>project</code> from an appropriate location. [ed-
|
442
|
+
the order of information is arbitrary, so it looks a bit messy. This will be improved
|
443
|
+
in a future release.]
|
444
|
+
|
445
|
+
|
446
|
+
h2. On Your Own
|
447
|
+
|
448
|
+
The rest of building a task is just a matter of writing the code to have
|
449
|
+
it do what you want. If you develop any nice tasks, be sure to pass them along!
|
450
|
+
|
451
|
+
|
452
|
+
|
453
|
+
|
454
|
+
|
455
|
+
|
456
|
+
|
457
|
+
|
458
|
+
!{float: right; width: 128px;}images/clipboard.jpg!
|
459
|
+
|
460
|
+
h1. Task Management
|
461
|
+
|
462
|
+
|
463
|
+
h2. Listings Tasks
|
464
|
+
|
465
|
+
Of course, it's not enough to just create tasks and run them willy-nilly. A good build tool
|
466
|
+
will let us see what tasks we have available and what they do. It's eay enough to use @ls@
|
467
|
+
or @dir@ to list the targets in the task directory.
|
468
|
+
|
469
|
+
$ ls task/
|
470
|
+
list
|
471
|
+
|
472
|
+
But that only tells us the names of avaialble tasks. What about what the tasks do? Ratch
|
473
|
+
comes with a command line tool to faciltiate this called @lt@. It works much like @ls@.
|
474
|
+
Try it:
|
475
|
+
|
476
|
+
$ lt task/
|
477
|
+
[/home/me/projects/foo]
|
478
|
+
task/list # List project files
|
479
|
+
|
480
|
+
So now we know waht the task does as well. Didi you notice where lt got that information?
|
481
|
+
It's form the first comment line of the ratch script. @lt@ is enven a bit smater than
|
482
|
+
this. If you give it an actual script, it will output full help-details, if the script
|
483
|
+
provides it. In our case, the @list@ task doesn't have further details (it doesn't
|
484
|
+
really need them), but ew can add some for sample sake.
|
485
|
+
|
486
|
+
Edit the @list@ file to look like:
|
487
|
+
|
488
|
+
<pre class="script">
|
489
|
+
#!/usr/bin/env ratch
|
490
|
+
|
491
|
+
# List project files
|
492
|
+
|
493
|
+
# This task simply prints out a list
|
494
|
+
# of all the files in the project.
|
495
|
+
|
496
|
+
puts glob('**/*')
|
497
|
+
</pre>
|
498
|
+
|
499
|
+
Now try:
|
500
|
+
|
501
|
+
<pre>
|
502
|
+
$ lt task/list
|
503
|
+
|
504
|
+
List project files
|
505
|
+
|
506
|
+
This task simply prints out a list
|
507
|
+
of all the files in the project.
|
508
|
+
</pre>
|
509
|
+
|
510
|
+
As you can see, in the mode, @lt@ outputs all the comments line at the top of script.
|
511
|
+
It stops at the first non-blank, non-commnet line.
|
512
|
+
|
513
|
+
|
514
|
+
h2. Lookup and Do
|
515
|
+
|
516
|
+
What if I want to run a task script, but I'm currently way down in the
|
517
|
+
project's directory tree. I dont want to <code>cd</code> all the way up or type
|
518
|
+
<code>../</code> a bunch of times.
|
519
|
+
|
520
|
+
Sake provides a utility called <code>ludo</code> which stands for
|
521
|
+
<i>lookup and do</i>. Just prepend that command to your invocation and it
|
522
|
+
will find the executable and execute it.
|
523
|
+
|
524
|
+
% ludo task/list
|
525
|
+
|
526
|
+
By the way, the <code>ludo</code> command can be used anywhere you like, it is
|
527
|
+
not dependent on Sake to work. Albeit you should exercise some caution when doing
|
528
|
+
so since <code>ludo</code> actively searches up the directory tree for a script
|
529
|
+
to execute.
|
530
|
+
|
531
|
+
Sometimes, you may want to lookup and run a command but rather than change directories to
|
532
|
+
the where the command match was made you want the task will be run from the current
|
533
|
+
directory. You can do that with the --here switch (or -h for short).
|
534
|
+
|
535
|
+
$ ludo -h task/list
|
536
|
+
|
537
|
+
This will list all the files relative to the current directory.
|
538
|
+
|
539
|
+
|
540
|
+
!{float: right;}images/mints.png!
|
541
|
+
|
542
|
+
h2. Task Trading via Mint
|
543
|
+
|
544
|
+
Mint is another ProUtil, like Ratch, taht is extermely useful for distributing and resusing Ratch tasks.
|
545
|
+
In fact Racth comes with a dozen or so general purpose tasks that you can install to you're projects
|
546
|
+
right aay using @mint@.
|
547
|
+
|
548
|
+
$ mint -s ratch/setup
|
549
|
+
|
550
|
+
|
551
|
+
|
552
|
+
!images/appendix.png!
|
553
|
+
|
554
|
+
h1. Appendix
|
555
|
+
|
556
|
+
|
557
|
+
h2. License
|
558
|
+
|
559
|
+
<p>
|
560
|
+
Ratcehts<br/>
|
561
|
+
Copyright © 2006 Thomas Sawyer</br>
|
562
|
+
</p>
|
563
|
+
|
564
|
+
Ruby/GPL License
|
565
|
+
|
566
|
+
This program is free software; you can redistribute it and/or modify
|
567
|
+
it under the terms of the Ruby License or GNU General Public License
|
568
|
+
as published by the Free Software Foundation; either version 2 of the
|
569
|
+
License, or (at your option) any later version.
|
570
|
+
|
571
|
+
This program is distributed in the hope that it will be useful,
|
572
|
+
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
573
|
+
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
574
|
+
GNU General Public License for more details.
|
575
|
+
|
576
|
+
You should have received a copy of the GNU General Public License
|
577
|
+
along with this program; if not, write to the Free Software
|
578
|
+
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|