= README

release:: $Release: 0.2.1 $
copyright:: copyright(c) 2006 kuwata-lab.com all rights reserved.



== Introduction

Rook is a tool for SCM such as Make, Rake, Ant, and so on.
Rook has inspired by Cook which is made by Peter Miller.
http://www.canb.auug.org.au/~millerp/cook/cook.html

Features:
* Liken software build process to cooking.
* Two-style approach support: YAML-style and Ruby-style.
* Natural notation for production rule and optional ingredients.
* 'tar.gz', 'tar.bz2', and '.zip' support
(requires 'minitar', 'bz2', and 'rubyzip' libraries.)
* Able to invoke build command forcedly

Attention! Rook is under alpha version and specification
may change frequently.



== Installation

If you have installed RubyGems, just stype 'gem install -r rook'.
$ sudo gem install -r rook

Otherwise download ruby_X.X.X.tar.bz2 and install with setup.rb.
$ tar xjf rook_X.X.X.tar.bz2
$ cd rook_X.X.X/
$ sudo setup.rb

(Must) If you have installed rook without RubyGems, the following
libraries must be installed.
* abstract.rb (>= 1.0.0) (http://www.rubyforge.org/projects/abstract)
* kwalify (>= 0.6.0) (http://www.rubyforge.org/projects/kwalify)

(Optional) If you want to handle *.tar.gz, *.tar.bz2, or *.zip
files, you must install the following libraries.
* minitar - http://raa.ruby-lang.org/project/minitar/
* bz2 - http://raa.ruby-lang.org/project/bz2/
* rubyzip - http://raa.ruby-lang.org/project/rubyzip/

(Optional) Helper script 'ruby_X.X.X/contrib/inline_require.rb'
merges 'bin/rook' and rook libraries into a file.
$ cd rook_X.X.X/
$ unset RUBYLIB
$ ruby contrib/inline_require.rb -I lib bin/rook > contrib/rook



== Examples

The following is an example of Rookbook.yaml to cook *.c files.
(Rookbook is the equivarent to Makefile in Make or Rakefile in Rake.)

properties:
- project: hello
- c_flags: '-g -Wall -O2'

variables:
- command: $(project)
- objfiles*: Dir.glob('*.c').collect{|f| f.sub(/\.c$/, '.o')}

recipes:
- product: $(command)
ingreds: [ $(objfiles) ]
desc: create '$(command)' command
method: |
sys "gcc #@c_flags -o #@product #')"

- product: *.o
ingreds: [ $(1).c ]
options: [ $(1).h ]
method: |
sys "gcc #@c_flags -c #@ingred"

- product: :clean
method: |
rm_f Dir.glob("*.o")


Rook supports two style of Rookbook: YAML-style and Ruby-style.
The following ('Rookbook.rb') is the Ruby-style example of Rookbook
which is equivarent to the above YAML-style example.

property :project, 'hello'
property :c_flags, '-g -Wall -O2'

command = @project
objfiles = Dir.glob('*.c').collect{|f| f.sub(/\.c$/, '.o')}

desc "create '#command' command"
recipe command, objfiles do |r|
sys "gcc #@c_flags -o #@product #')"
end

recipe "*.o", '$(1).c', :options=>['$(1).h'] do |r|
sys "gcc #@c_flags -c #@ingred"
end

recipe :clean do |r|
rm_f Dir.glob("*.o")
end


See 'examples/' directory for more examples.



== Documents

See 'doc/users-guide.html' for details.



== Terms

[ Product ]
Output of cooking.

[ Ingredient ]
Materials needed for cooking.

[ Byproduct ]
Garbages produced in cooking.

[ Recipe ]
Method how to cook product.

[ Generic recipe ]
Recipe which product is specified by pattern.
This is equivarent to 'rule' in Rake.

[ Specific recipe ]
Recipe which product is specified by name.
This is equivarent to 'file' in Rake.

[ Symbolic recipe ]
Recipe which product is specified by Symbol.
This is equivarent to 'task' in Rake.



== To Do

* [_] Include external cookbook
* [_] Fingerprints support
* [_] Dependency Tree
* [_] Plugin architecture
* [_] Auto-detection of product and by-product, and delete them automatically
* [_] Multi-products
* [V] (DONE) Reporting Line number when schema error is found in cookbook
* [_] Convertion cookbook into ruby code


== License

LGPL ver2.1



== Author

makoto kuwata <kwa(at)kuwata-lab.com>