= Rant -- Ruby's ant

Rant is a flexible build tool written entirely in Ruby.

The equivalent to a _Makefile_ for _make_ is the _Rantfile_. An
_Rantfile_ is actually a valid Ruby script that is read in by the
_rant_ command.

Rant currently features:
* Rantfiles are written in Ruby.
* Defining custom tasks
* Automated packaging, testing and RDoc generation for Ruby
  applications and libraries.
* The <em>rant-import</em> command creates a monolithic rant script,
  so you don't depend on an rant installation anymore.
* Creating gzipped tar and zip archives -- without installing
  additional software.
* Optional recognition of file changes based on MD5 checksums instead
  of file modification times.
* Tasks with command change recognition.
* Primitive support for compiling C# sources portably with csc, cscc
  and mcs.
* Dependency checking for C/C++ source files.
* A _configure_ plugin for easy environment and build-parameter
  checking (but not like autoconf!) which saves data in a yaml file.

As programmers usually want to see code, here is a short and very
basic example of rant usage:

A file called +Rantfile+ contains the code:

    file "backup/data" => "data" do |t|
	sys.cp t.source, t.name
    end

Running rant in the directory of this file:

    % rant
    cp data backup/data

will ensure that the "data" file in the "backup" directory is up to
date.

This document was written for version 0.5.2 of Rant. Most things
described here will work for older/newer versions of Rant, but look at
the README file in the Rant distribution you've installed for exact
documentation of your Rant version.

== Support

The newest version of this document can be found at
http://make.rubyforge.org.

For further information, feature requests, bugreports or comments join
the mailing list
{make-cafe}[http://rubyforge.org/mailman/listinfo/make-cafe] or visit
the {RubyForge site for Rant}[http://rubyforge.org/projects/make/].

Also feel free to contact the author directly by sending an email to
mailto:langstefan@gmx.at.

== Roadmap

Installing Rant::
    read INSTALL[link:files/INSTALL.html]
License::
    read the section _Copying_ in this document
Invoking *rant*::
    read doc/rant.rdoc[link:files/doc/rant_rdoc.html]
Writing an *Rantfile*::
    read doc/rantfile.rdoc[link:files/doc/rantfile_rdoc.html]
Automation for your Ruby library/application::
    read doc/rubyproject.rdoc[link:files/doc/rubyproject_rdoc.html]
Independent from Rant? The <tt>rant-import</tt> command::
    read doc/rant-import.rdoc[link:files/doc/rant-import_rdoc.html]
Advanced Rantfiles::
    read doc/advanced.rdoc[link:files/doc/advanced_rdoc.html]
Packaging (creating zip/tgz archives)::
    read doc/package.rdoc[link:files/doc/package_rdoc.html]
Using MD5 checksums instead of file modification times::
    read doc/md5.rdoc[link:files/doc/md5_rdoc.html]
Compiling C/C++::
    read doc/c.rdoc[link:files/doc/c_rdoc.html]
Buildfiles in subdirectories::
    read doc/subdirs.rdoc[link:files/doc/subdirs_rdoc.html]
Tasks with command change recognition::
    read doc/command.rdoc[link:files/doc/command_rdoc.html]
Using the Configure plugin::
    read doc/configure.rdoc[link:files/doc/configure_rdoc.html]
Compiling C#::
    read doc/csharp.rdoc[link:files/doc/csharp_rdoc.html]
Common file system operations::
    read doc/sys.rdoc[link:files/doc/sys_rdoc.html]
Upgrading::
    read the NEWS[link:files/NEWS.html] for new features, not
    backwards compatible changes and other issues.

Using Rant libraries::
    read doc/rubylib.rdoc[link:files/doc/rubylib_rdoc.html]

== Copying

Copyright (C) 2005  Stefan Lang

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

---

The file COPYING[link:../../COPYING] in the Rant package contains a
copy of the LGPL. Of course your Rantfiles don't need to be licenced
under the terms of the LGPL.

---

The file <tt>lib/rant/archive/minitar.rb</tt> is Copyright  2004
Mauricio Julio Fernandez Pradier and Austin Ziegler. It is licensed
under the GNU General Public Licence or Ruby's licence.

The file <tt>lib/rant/archive/rubyzip.rb</tt> and the files in the
<tt>lib/rant/archive/rubyzip</tt> directory were written by Thomas
Sondergaard. They are distributed under the same license as ruby. See
http://www.ruby-lang.org/en/LICENSE.txt.

== Other info

Rant was started in February 2005. It has been written and is
maintained by Stefan Lang (mailto:langstefan@gmx.at).

=== Credits

Rant has taken the basic syntax of a _task_ and some other concepts
from Rake.
So thanks to Jim Weirich, the author of
Rake[http://rubyforge.org/projects/rake].

Rant comes with parts of archive-tar-minitar to create (gzipped) tar
archives on platforms where no +tar+ command is available.
archive-tar-minitar is developed by Mauricio Julio Fernandez Pradier
and Austin Ziegler.

Rant comes with parts of rubyzip to create zip archives on platforms
where no +zip+ command is available. rubyzip is developed by Thomas
Sondergaard.

=== Goals of Rant

* Most important is to be a very *flexible* build tool. This currently
  means that you can run/use Rant in many different ways. E.g. you can
  invoke it the conventional way like _make_, define tasks and run
  Rant from _irb_ (the interactive Ruby shell), create an independent
  script with <em>rant-import</em>, or simply use Rant as a library to
  automate tasks for your application.
* *Extensible*: currently through _plugins_ and _generators_. (Think
  of the +plugin+ and +import+ functions.)
* Portability: see _Platforms_ below for details
* Well scaling: Rant should work acceptable for bigger projects (from
  a performance POV and for the writer of the Rantfiles).

=== Platforms

Rant was tested on:

    System		Ruby version
    =======================================================
    Linux		1.8.0
                        1.8.1
                        1.8.2
			1.8.3
			1.8.4
			1.9
    MacOS X		1.8.2
    Windows XP		1.8.2 (OneClick Installer)
    Windows 2000	1.8.2 (OneClick Installer)

It *should* run on most platforms where Ruby runs, but you never
know...

If you encounter problems with Rant on any platform (with Ruby 1.8.0
or higher) please write a bugreport!

=== Why did you write another build tool?

Because I wasn't satisfied by any other build tool. Before I started
Rant, I had to write a program in C#. The program had to run under
Windows, but I wanted to develop under Linux. Also I decided to write
the documentation in Docbook.

So there where quite a few problems arising:
* I had to compile with cscc on Linux.
* compile with csc on Windows.
* automate PDF and HTML generation from Docbook

_Nant_ would have been ok to compile the C# sources. But it isn't
suited for more general tasks as clueing togheter other programs
(needed for Docbook processing).

Then I tried to use _Rake_ and it was the other way round. I liked the
basic concept and syntax of Rake and of course I could have written
code for Rake (e.g. with a so called _Tasklib_) to support portable C#
compilation. But it was a bit quirky and because I like to work with
Ruby, I decided to write my own build tool.