== The *rant* program

For a short usage message and a list of options invoke rant with the
<tt>--help</tt> option:
    % rant --help

Usually you'll run rant by giving it the name of the task(s) to be
invoked as argument(s).
To get an overview for the project in the current working directory,
run rant with the <tt>--tasks</tt> (short form: <tt>-T</tt>) option:
    % rant -T
    rant               # => test
    rant package       # Create packages for distribution.
    rant doc           # Generate documentation.
    rant test          # Run unit tests.
    rant cov           # Run all tests and generate coverage with rcov.
    rant clean         # Remove autogenerated files.
    rant publish-docs  # Publish html docs on RubyForge.
                       #   Note: scp will prompt for rubyforge password.
This lists the "public" tasks for the project. The first line always
tells you the task(s) that will be invoked when no argument is given
to rant, in the above example, this would be the +test+ task.

When you invoke rant on the commandline it performs the following
steps (roughly):

1. Process commandline options and arguments.
   An option starts with two dashes or one for the single letter
   equivalent. Arguments of the form <tt>VAR=VAL</tt> set variables
   available in the Rantfile(s). All other arguments are names of
   tasks to be invoked.
2. Load Rantfile in working directory. Rantfiles with the following
   names are recognized:
        Rantfile
        rantfile
        root.rant
3. Calculate task dependencies and invoke required tasks. If no task
   was given on the commandline, a task called "default" will be
   invoked. If the "default" task doesn't exist, the first task will
   be invoked.

=== Dry-Run

If you run rant in dry-run mode, it will print the actions it would
execute instead of actually executing them. This can be useful in
debugging your Rantfiles. To enable it, give the <tt>--dry-run</tt>,
option or its short form, <tt>-n</tt>, on the commandline.

Example Rantfile:

    import "command"

    task :install => "foo" do
      sys.install "foo", "/usr/local/bin", :mode => 0755
    end

    gen Command, "foo", "foo.c", "cc -o $(>) $(<)"

Running rant in dry-run mode:

    % rant -n
    Executing "foo"
    - SHELL
      cc -o foo foo.c
    Executing "install"
    - Ruby Proc at Rantfile:3

Running rant in "normal" mode:

    % rant
    cc -o foo foo.c
    install -c -m 0755 foo /usr/local/bin

Running rant in dry-run mode again:

    % rant -n
    Executing "install"
    - Ruby Proc at Rantfile:3

== See also

Rant Overview::
    README[link:files/README.html]
Independent from Rant? The <tt>rant-import</tt> command::
    doc/rant-import.rdoc[link:files/doc/rant-import_rdoc.html]