
== How to write an *Rantfile*

As already mentioned, an Rantfile is a Ruby script. Additionally, Rant
provides methods and classes which aid you in automating your work.

Centric to the processing done by Rant is the *task*. The Rantfile
defines tasks and their dependencies, Rant invokes the required tasks.

Also important is the <b>Rant application</b>. When the rant command
starts, it instantiates one Rant application which will read one or
more Rantfiles. The Rantfile communicates with the following list of
methods with the Rant application:

+task+::        Defines a task with prerequisites and an action.
+file+::        A special form of task which creates one file.
+desc+::        Describes the next defined task. A task with
                description is considered a "public" task.
+gen+::         Takes a _generator_ object as first argument which
                usually creates one or more tasks. An example would be
                the +RubyPackage+ generator which produces tasks for
                packaging.
+import+::      Imports additional code which usually provides
                additional generators. Example: to use the
                +RubyPackage+ generator you have to <tt>import
                "rubypackage"</tt> first.
+sys+::         Run external commands or do usual file system
                operations (copy files, unlink files, install, ...).
+source+::      Takes a filename as argument and causes Rant to read
                it in as Rantfile.
+subdirs+::     Takes a list of subdirectories in which Rant should
                look for Rantfiles.
+var+::         Provides access to variables accessible in Rantfiles
                and from the commandline.
+make+::        Immediately build a target.

=== Defining a task

Just call the +task+ function and give it a task name as argument. The
task name may be a string or symbol:
    task :taskname
That's it, your first task. Not very useful, because it doesn't do
anything. To associate an action with the task, add a block:
    task :mytask do
        puts "Hello, mytask running."
    end
Put these 3 lines of code into a file called +Rantfile+ and run rant:
    % rant mytask
    Hello, mytask running.
Note: you could have omited the mytask argument to rant because it is
the only task in the Rantfile.

You can add a block parameter which will be a reference to the created
task:
    task :mytask do |t|
        puts t.name
    end
Running rant now:
    % rant
    mytask

Add prerequisites to create relations between tasks:
    task :first => [:t1, :t2] do |t|
        puts t.name
    end
    task :t1 do |t|
        puts t.name
    end
    task :t2 do |t|
        puts t.name
    end
In the definition of the "first" task we told Rant that it _depends_
on task "t1" and task "t2". "t1" and "t2" are called prerequisites for
"first". Try it out:
    % rant first
    t1
    t2
    first
    % rant t1
    t1
    % rant t2
    t2

=== Defining a file task

You will notice that rant will run the actions for a normal task
always its name is given on the commandline or it is required by
another task. Often you want to create a file, e.g. a program by
invoking a compiler. In this case, the action needs only to be run if
the source files (prerequisites) have changed. Use a file task instead
of a normal task.

In this example we use the <tt>sys.touch</tt> method to test our file
task. (This method works the same as the Unix touch command: Update
the modification time of a file or create an empty file):
    file "testfile" do |t|
        sys.touch t.name
    end
Now run rant:
    % rant
    touch testfile
This would have been the same with a normal task. But now run rant a
second time:
    % rant
This time rant doesn't run the action, because "testfile" is up to
date. Of course you can add prerequisites the same way as for a normal
task. Additionally you can add filenames as prerequisites. Assuming
the files "a.o" and "b.o" are in the same directory as the Rantfile:
    file "myprog" => %w(a.o b.o) do |t|
        sys %w(cc -o), t.name, t.prerequisites
    end
Running rant:
    % rant
    cc -o myprog a.o b.o
Running a second time:
    % rant
Does nothing, myprog is up to date.
Don't be irritated by the <tt>%w()</tt> syntax. It creates a list of
strings. The following expressions are equivalent:
    ["a", "b", "c"]
    %w(a b c)

=== Adding task descriptions

The +desc+ function lets you describe your tasks. A small example
Rantfile:
    # Generate C source file ls.c with the xgen command.
    file "ls.c" => %w(ls1.x ls2.x) do |t|
        sys %w(xgen -o), t.name, t.prerequisites
    end

    desc "Build ls program."
    file "ls" => "ls.c" do
        sys "cc -o ls ls.c"
    end

    desc "Remove autogenerated files."
    task :clean do
        sys.rm_f %w(ls.c ls)
    end
(Note that xgen is a hypothetical command ;)
The <tt>--tasks</tt> (or the short form, <tt>-T</tt>) option of rant
shows this descriptions:
    % rant -T
    rant ls     # Build ls program.
    rant clean  # Remove autogenerated files.
Only the tasks which have a description are listed.

=== The +sys+ method

After using the +sys+ method quite often in the examples, I should
explain it a little bit. It can be used in three ways:

1. <b>File system operations</b>

   The first form is with no arguments. It returns an object on which
   you can invoke methods for common file system operations:

   Examples are:

        sys.rm ["file1", "file2"]       # remove files
        sys.cp "src", "dest"            # copy from "src" do "dest"
        sys.mkdir "dir"                 # create directory "dir"

   For a list of all available methods read
   doc/sys.rdoc[link:files/doc/sys_rdoc.html].

2. <b>Running external commands</b>

   Invoke the +sys+ method with a string as argument to run a shell:

        sys "echo *.c"

   will print a list of C files to stdout.

   When given multiple arguments, +sys+ invokes the program named with
   the first argument giving it the remaining arguments as arguments:

        sys "echo", "*.c"

   will print "*.c" to stdout.

   When the external program returns with an exit code other than 0,
   Rant will abort with an error message. Sometimes this is not
   desirable. E.g. the +diff+ program, which compares two files,
   returns 0 if the files are equal, 1 if they have differences and
   something else if an error occurs. Rant allows you to handle/ignore
   the exit code of a program yourself. Example:

        task :diff do |t|
            sys "diff -u a/util.c b/util.c > util.diff" do |ps|
                # ps is an instance of Process::Status
                case ps.exitstatus
                when 0:
                    puts "a/util.c and b/util.c are equal"
                when 1:
                    puts "a/util.c and b/util.c are not equal"
                else
                    t.fail "diff error"
                end
            end
        end


3. <b>Selecting files</b>

   To select files with the help of glob patterns use +sys+ with the
   <tt>[]</tt> operator:

        file "program" => sys["*.o"]

   The task "program" depends on all files ending in ".o".
    
   For extensive documentation read 
   doc/sys_filelist.rdoc[link:files/doc/sys_filelist_rdoc.html].
   
=== Generators

The *gen* function takes a generator which usually creates one or more
tasks for you. The following list of generators is immediately
available:

+Directory+::   Create directories.
+Task+::        Define custom task.
+Rule+::        Define a rule (a rule produces tasks on the fly).
+Action+::      Run a block of code immediately.
                The Action generator is discussed in
                doc/advanced.rdoc[link:files/doc/advanced_rdoc.html].

=== The +Directory+ generator

An example usage of the +Directory+ generator would be the backup
example shown in the README file:

    file "misc/backup/data" => %w(misc/backup data) do |t|
        sys.cp "data", t.name
    end
    
    gen Directory, "misc/backup"

Now rant will create the directories "misc" and "backup" on demand.
Assuming "misc/backup" doesn't exist:

    % rant
    mkdir misc
    mkdir misc/backup
    cp data misc/backup/data

=== The +Task+ generator

The +Task+ generator allows you to determine by hand when your task
action needs to be run:

    desc "Install with setup.rb"
    gen Task, :install do |t|
        t.needed { !File.exist? "InstalledFiles" }
        t.act do
            sys.ruby "setup.rb"
        end
    end

The +act+ block of the "install" task will only be run if
"InstalledFiles" doesn't exist. Of course you can add prerequisites
like with any other task.

=== Rules

A Rule allows you to tell Rant how it should build files matching a
common pattern, e.g. how to build files ending in ".o". A standard
rule usage is to create C object files:

    gen Rule, '.o' => '.c' do |t|
        sys "cc -c -o #{t.name} #{t.source}"
    end

Assuming that we have the C source file util.c in the current
directory:

    % rant util.o
    cc -c -o util.o util.c

Because Rant didn't find a task for util.o, it looked for a matching
rule and created a task for util.o.

The first line above could also be written as:

    gen Rule, :o => :c do |t|

The +source+ method of the task object gives us the first dependency.
So the following line has the same effect:

        sys "cc -c -o #{t.name} #{t.prerequisites.first}"

You can also refine the rule pattern by using a regular expression. To
refine dependency selection give a block as source argument:

    src = lambda { |target| [target.sub_ext("c"), target.sub_ext("h")] }
    gen Rule, /^my_[^.]+\.o$/ => src do |t|
        sys "cc -c -o #{t.name} #{t.source}"
    end

This rule generates a task for files beginning with "my_" and ending
in ".o" (like "my_program.o"). The task has a file ending in ".c" and
one ending in ".h" as dependencies (like "my_program.c" and
"my_program.h") . Since <tt>t.source</tt> gives us the *first*
dependency, the ".c" file will appear as argument to cc, but not the
".h" file.

The +sub_ext+ method of the +String+ class replaces anything after the
last dot with the given string.

=== Importing additional generators

The +import+ function lets you import additional generators.
Currently the following come with Rant:

Clean::         Remove selected files.
AutoClean::     Remove all files generated by any file task (including
                those generated by rules).
DirectedRule::  A Rule which takes sources from one or more
                directories and puts generated files into a specified
                directory.
SubFile::       Create file task and necessary directory tasks.
Command::       Tasks with command change recognition.
RubyTest::      Run Test::Unit tests for your Ruby code.
RubyDoc::       Run RDoc.
RubyPackage::   Generate tar, zip and gem packages of your Ruby
                application/library.
Archive::Tgz::  Create gzipped tar archives.
Archive::Zip::  Create zip archives.
Package::Tgz::  Create gzipped tar packages.
Package::Zip::  Create zip packages.
C::Dependencies::   Determine dependencies between C/C++ source/header
                    files caused by #include statements.
Win32::RubyCmdWrapper:: Create .cmd wrapper scripts for installation
                        of Ruby scripts on Windows.

Read doc/advanced.rdoc[link:files/doc/advanced_rdoc.html] and
doc/rubyproject.rdoc[link:files/doc/rubyproject_rdoc.html] for
documentation.

=== The +subdirs+ command

The +subdirs+ command allows you to give Rant a list of subdirectories
(relative to the Rantfile) where it should look for additional
Rantfiles. The tasks defined in those subdirectories can be referenced
from your main Rantfile and vice versa.

A small example: We are assuming the following files:
    myprog/
        Rantfile        # the main Rantfile
        README
        src/
            Rantfile
            main.c
            lib.c
            lib.h
Then the main Rantfile could look like:
    desc "Build myprog."
    file "myprog" => "src/myprog" do
        sys.cp "src/myprog", "myprog"
    end

    desc "Remove compiler products."
    task :clean => "src/clean" do
        sys.rm_f "myprog"
    end

    # Tell Rant to look in src for an Rantfile,
    # we could list more directories here.
    subdirs "src"
And src/Rantfile:
    file "lib.o" => %w(lib.c lib.h) do
        sys "cc -c -o lib.o lib.c"
    end

    file "main.o" => "main.c" do
        sys "cc -c -o main.o main.c"
    end

    file "myprog" => %w(lib.o main.o) do
        sys "cc -o myprog main.o lib.o"
    end

    task :clean do
        sys.rm_f Dir["*.o"] + %w(myprog)
    end
Note that we refer to the task in subdirectory simply by prepending
the directory name and a slash to the task name.
    file "myprog" => "src/myprog" do
This tells Rant that the "myprog" task depends on the "myprog" task
defined in the Rantfile in the "src" directory. The same goes for the
"clean" task.

Let's examine what Rant thinks about our build specification:
    myprog % rant -T
    rant myprog   # Build myprog.
    rant clean    # Remove compiler products.
Since the "myprog" task is the first in our Rantfile, we don't need to
specify a task to build myprog:
    myprog % rant
    cc -c -o lib.o lib.c
    cc -c -o main.o main.c
    cc -o myprog main.o lib.o
    cp src/myprog myprog
And to save disk space, remove generated files:
    myprog % rant clean
    rm -f lib.o main.o myprog
    rm -f myprog
The nice thing about our buildfiles is, that we can use the
src/Rantfile independent from our main Rantfile. Consider you are
working on <tt>lib.c</tt> and only want to check that it compiles
correctly.
You can specify the task explicitely:
    myprog % rant src/lib.o
    cc -c -o lib.o lib.c
But if you are working a long time only in the src/ directory it is
convinient to do:
    myprog % cd src
    myprog/src % rant lib.o
    cc -c -o lib.o lib.c
To clean only the src directory:
    myprog/src % rant clean
    rm -f lib.o main.o myprog
You can find this example project in the doc/examples/myprog directory
of the Rant distribution.

Of course you can also have a subdirectory in src/ containing an
Rantfile. Simply put a +subdirs+ command into the src/Rantfile. Rant
integrates well into your file system :)

If you want to refer to a task in the main Rantfile from a subdir
Rantfile, put a <tt>@</tt> in front of the task name:
    task "a" => "@b"
But note that this Rantfile won't work as a standalone buildfile,
because it refers to a main Rantfile.

For further documentation about managing build files in project
subdirectories, read
doc/subdirs.rdoc[link:files/doc/subdirs_rdoc.html].

== See also

Advanced Rantfiles::
    doc/advanced.rdoc[link:files/doc/advanced_rdoc.html]
Support for C/C++::
    doc/c.rdoc[link:files/doc/c_rdoc.html]
Packaging::
    doc/package.rdoc[link:files/doc/package_rdoc.html]
Ruby project howto::
    doc/rubyproject.rdoc[link:files/doc/rubyproject_rdoc.html]
Using filelists in Rantfiles::
   doc/sys_filelist.rdoc[link:files/doc/sys_filelist_rdoc.html]
Rant Overview::
    README[link:files/README.html]
