rant 0.3.0

data/README

@@ -0,0 +1,203 @@
+
+= 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.
+* Primitive support for compiling C# sources portably with csc, cscc
+  and mcs.
+* A _configure_ plugin for easy environment and build-parameter
+  checking (but not like autoconf!) which saves data in a yaml file.
+* The <em>rant-import</em> command creates a monolithic rant script,
+  so you don't depend on an rant installation anymore.
+
+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 "data", 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.
+
+== Support
+
+The newest version of this document can be found at
+http://make.rubyforge.org.
+
+For further information, feature requests, bugreports or comments
+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 the section _Installation_ in this document
+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]
+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]
+
+== Installation
+
+Of course you need Ruby to run rant. You can get the latest Ruby
+package from the {Ruby hompage}[http://www.ruby-lang.org/en/].
+
+There are two ways to install Rant on your system:
+
+=== Installing Rant as a RubyGem
+
+RubyGems has to be installed on your system. Check this by trying
+the _gem_ command:
+    % gem
+If this prints a help message, RubyGems should work. Otherwise
+install Rant as described in the next section.
+Now the following command:
+    % gem install --remote rant
+will download and install Rant. Depending on the RubyGems
+configuration, you will probably need superuser privileges.
+Then try to run:
+    % rant --version
+which should print name and version of the _rant_ command. If this
+is done, you have successfully installed Rant. Congratulations!
+
+=== Conventional installation
+
+First download the latest version of Rant from
+http://rubyforge.org/frs/?group_id=615. Choose the .zip or .tar.gz
+file, whatever you like, with the highest version number. Then unpack
+the archive, cd to the new directory and run the setup.rb script. This
+could look like:
+    % tar -xzf rant-<version>.tar.gz
+    % cd rant-<version>
+    % ruby setup.rb
+Depending on your Ruby installation, you'll probably need superuser
+privileges for the last command. If you wan't to install Rant in
+another location than the default, run
+    % ruby setup.rb --help
+which will show you a bunch of options for the installation.
+
+After performing the steps listed above, try to run
+    % rant --version
+to verify Rant was installed correctly.
+
+If you aren't already reading this documentation in html format, you
+can generate it with:
+    % rant doc
+The output will be in doc/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.
+
+== Other info
+
+Rant was started in February 2005. It has been written and is
+maintained by Stefan Lang (mailto:langstefan@gmx.at).
+
+=== 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.
+
+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].
+
+=== 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.2
+			1.9
+    MacOS X		1.8.2
+    WindowsXP		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.1
+or higher) please write a bugreport!

data/Rantfile

@@ -0,0 +1,104 @@
+#!/usr/bin/env ruby
+
+# Rantfile for Rant :)
+
+require 'rant'
+
+import %w(rubytest rubydoc rubypackage)
+
+task :default => :test
+
+lib_files = FileList["lib/**/*.rb"]
+dist_files = FileList["{bin,lib,test,doc}/**/*"].no_dir("html") +
+	FileList["*"].no_dir.no_file("InstalledFiles").no_file("Session.vim")
+
+gen RubyPackage, "rant" do |t|
+    t.version = `#{Env::RUBY} run_rant --version`.split[1]
+    t.summary = "Rant is a Ruby based build tool."
+    t.files = dist_files
+    t.bindir = "bin"
+    t.executable %w(rant rant-import)
+    t.author = "Stefan Lang"
+    t.email = "langstefan@gmx.at"
+    t.gem_rubyforge_project = "make"
+    t.gem_extra_rdoc_files = FileList["**/README"].no_dir("pkg").no_dir("test") + FileList["doc/**/*.rdoc"]
+    t.homepage = "http://make.rubyforge.org"
+    desc "Create packages for distribution."
+    t.package_task
+end
+
+desc "Generate documentation."
+gen RubyDoc do |g|
+    g.dir = "doc/html"
+    g.files.concat FileList["**/README"].no_dir("pkg").no_dir("test")
+    g.files.concat FileList["doc/**/*.rdoc"]
+    g.opts = %w(-S -c UTF-8 --title Rant --main README)
+end
+
+desc "Run basic tests."
+gen RubyTest do |g|
+    g.libs << "test"
+    g.pattern = 'test_*.rb'
+end
+
+desc "Run first test-project.",
+     "Warning: writes to disc."
+gen RubyTest, :testp1 do |g|
+    g.libs << "test"
+    g.test_files = ["test/project1/test_project.rb"]
+end
+
+desc "Run second test project.",
+     "Warning: writes to disc"
+gen RubyTest, :testp2 do |g|
+    g.libs << "test"
+    g.test_files = ["test/project2/test_project.rb"]
+end
+
+desc "Test small Ruby project."
+gen RubyTest, :testrb1 do |g|
+    g.libs << "test"
+    g.test_files = %w(test/project_rb1/test_project_rb1.rb)
+end
+
+desc "Test plugins."
+gen RubyTest, :testplugins do |g|
+    g.libs << "test"
+    g.test_files = FileList["test/plugin/**/test_*"]
+end
+
+desc "Run all tests and generate coverage with rcov."
+task :cov do
+    lp = File.expand_path "lib"
+    sys.cd "test" do
+	sys %W(rcov -xts_*,tc_*,test_* -I#{lp} ts_all.rb)
+    end
+end
+
+desc "Run all tests."
+gen RubyTest, :tall do |g|
+    g.libs << "test"
+    g.test_files = FileList["test/**/test_*.rb"]
+end
+task :testall => %w(test testp1 testp2 testrb1 testplugins)
+
+desc "Remove autogenerated files."
+task :clean do
+    sys.rm_f %w(InstalledFiles .config bench-rant bench-depsearch)
+    sys.rm_rf %w(doc/html pkg test/coverage)
+end
+
+# Just for quick visual testing of rant...
+task :please_fail do |t|
+    sys "mix_nix_gibts"
+end
+
+# for quich rant testing
+#plugin :Configure
+
+# mainly for rant testing
+source 'rantmethods.rb'
+
+if $0 == __FILE__
+    Rant.run
+end

data/TODO

@@ -0,0 +1,19 @@
+
+= TODO
+
+== C# plugin
+Define the method +assembly+ for building a file with the C# compiler?
+Done.
+
+== Predefined tasks
+
+Add a 'distclean' task that removes all files and directories
+generatet by any file task.
+
+RDoc task.
+
+Gem task (+ one that interactively creates a gemspec).
+
+== Java plugin
+
+At least for the 1.0.0 release.

data/bin/rant

@@ -0,0 +1,12 @@
+#! /usr/local/bin/ruby
+
+# rant -- Ruby's ant
+#
+# Copyright (C) 2005 Stefan Lang <langstefan@gmx.at>
+#
+# This program is free software.
+# You can distribute/modify this program under the terms of
+# the GNU LGPL, Lesser General Public License version 2.1.
+
+require 'rant/rantlib'
+exit Rant.run

data/bin/rant-import

@@ -0,0 +1,12 @@
+#! /usr/local/bin/ruby
+
+# rant-import -- Create a monolithic rant script.
+#
+# Copyright (C) 2005 Stefan Lang <langstefan@gmx.at>
+#
+# This program is free software.
+# You can distribute/modify this program under the terms of
+# the GNU LGPL, Lesser General Public License version 2.1.
+
+require 'rant/import'
+exit Rant::RantImport.run

data/devel-notes

@@ -0,0 +1,50 @@
+
+== Here docs
+Don't use here documents in the Rant sources, imports and plugins.
+They'll get messed up by the rant-import command.
+
+== Running RDoc programmatically
+require 'rdoc/rdoc'
+rdoc = RDoc::RDoc.new
+begin
+    rdoc.document(%w(like args from commandline))
+rescue RDoc::RDocError
+    $stderr.puts "Error when running rdoc: " + $!.message
+end
+
+== Changing the behaviour of Rant from Rantfiles
+Perhaps a method named like `behave' would be appropriate to to
+set options of the Rant application.
+
+== Subdirectories
+Allow the use of `#' at the start of a pathname to tell rant that
+it should be interpreted relative to the project's root directory.
+
+== Directory structure of +lib/+
++lib/+ contains only two entries:
+[rant.rb]      Used to require rantlib and include +Rant+ for small
+	       build scripts.
+[rant/]	       All files matching <tt>/^rant\w+\.rb$/</tt> are considered
+	       as Rant core. Others contain utilities, helper classes,
+	       Generators and similar.
+[rant/plugin]  Each file ending in <tt>.rb</tt> in this directory is
+               considered to load support for one Rant plugin.
+
+== Performance
+With version 0.2.6, the big performance problem with task lookup
+(caused very slow dependency resolving) is fixed.
+The next performance improvement should target Rantfile reading,
+especially task creation.
+
+== RubyPackage generator
+Currently, the package task(s) generated by RubyPackage doesn't
+recognize (and repackage) when files/directories are removed (from the
+sources).
+
+== Unit tests
+The unit tests contain many assertions of the form
+  assert_equal(Rant.run(...), 0)
+which are wrong, because the first argument should be the expected
+result!
+
+# vim:tw=70:

data/doc/configure.rdoc

@@ -0,0 +1,40 @@
+
+== The Configure plugin
+
+The Configure plugin lets you define a list of checks and generates
+tasks to run them. I'll show an Rantfile using the Configure plugin
+and explain it afterwards.
+
+    conf = plugin :Configure do |conf|
+	conf.task           # define a task named :configure
+	conf.check "a" do |c|
+	    c.default "value_a"
+	    c.guess { "value_a_guess" }
+	    c.react { |val|
+		p val
+	    }
+	end
+	conf.check "b" do |c|
+	    c.default "value_b"
+	end
+	conf.check "c" do |c|
+	end
+	conf.check "d" do |c|
+	    c.react {
+	    }
+	end
+	conf.check "e" do |c|
+	    c.guess { false }
+	end
+    end
+
+    file conf["a"] do |t|
+	sys.touch t.name
+    end
+
+== See also
+
+Rant Overview::
+    README[link:files/README.html]
+Writing an Rantfile::
+    doc/rantfile.rdoc[link:files/doc/rantfile_rdoc.html]