rant 0.4.4 → 0.4.6

data/doc/homepage/rant_home.css

@@ -0,0 +1,98 @@
+body {
+	color:#333;
+	background-color:white;
+	/* background-color:gray; */
+	margin:20px;
+	padding:0px;
+	font:12px verdana, arial, helvetica, sans-serif;
+	}
+h1 {
+	margin:0px 0px 15px 0px;
+	padding:0px;
+	font-size:28px;
+	font-weight:900;
+	color:#ccc;
+	}
+h2 {
+	font:bold 14px/15px verdana, arial, helvetica, sans-serif;
+	margin:0px 0px 5px 0px;
+	padding:0px;
+	}
+h3 {
+	font:bold 12px/14px verdana, arial, helvetica, sans-serif;
+	margin:0px 0px 5px 0px;
+	padding:0px;
+	}
+p {
+	font:12px/20px verdana, arial, helvetica, sans-serif;
+	margin:0px 0px 16px 0px;
+	padding:0px;
+	}
+.Content>p {margin:0px;}
+.Content>p+p {text-indent:30px;}
+
+a {
+	color:#09c;
+	font-size:12px;
+	font-family:verdana, arial, helvetica, sans-serif;
+	font-weight:600;
+	text-decoration:none;
+	}
+a:link {color:#09c;}
+a:visited {color:#07a;}
+a:hover {background-color:#eee;}
+  
+
+/* All the content boxes belong to the content class. */
+.content {
+	position:relative; /* Position is declared "relative" to gain control of stacking order (z-index). */
+	width:auto;
+	min-width:120px;
+	margin:0px 210px 20px 170px;
+	border:1px solid black;
+	background-color:white;
+	padding:10px;
+	z-index:3; /* This allows the content to overlap the right menu in narrow windows in good browsers. */
+	}
+
+#navAlpha {
+	position:absolute;
+	/* width:150px; */
+	top:20px;
+	left:20px;
+	border:1px dashed black;
+	background-color:#eee;
+	padding:10px;
+	z-index:2;
+
+/* Here is the ugly brilliant hack that protects IE5/Win from its own stupidity. 
+Thanks to Tantek Celik for the hack and to Eric Costello for publicizing it. 
+IE5/Win incorrectly parses the "\"}"" value, prematurely closing the style 
+declaration. The incorrect IE5/Win value is above, while the correct value is 
+below. See http://glish.com/css/hacks.asp for details. */
+	voice-family: "\"}\"";
+	voice-family:inherit;
+	/* width:128px; */
+	}
+/* I've heard this called the "be nice to Opera 5" rule. Basically, it feeds correct 
+length values to user agents that exhibit the parsing error exploited above yet get 
+the CSS box model right and understand the CSS2 parent-child selector. ALWAYS include
+a "be nice to Opera 5" rule every time you use the Tantek Celik hack (above). */
+body>#navAlpha {width:128px;}
+		
+#navBeta {
+	position:absolute;
+	width:190px;
+	top:20px;
+	right:20px;
+	border:1px dashed black;
+	background-color:#eee;
+	padding:10px;
+	z-index:1;
+/* Again, the ugly brilliant hack. */
+	voice-family: "\"}\"";
+	voice-family:inherit;
+	width:168px;
+	}
+/* Again, "be nice to Opera 5". */
+body>#navBeta {width:168px;}

data/doc/rant.1

@@ -0,0 +1,129 @@
+.\" rant.1 - rant manpage
+.\" Date of last change to this manpage.
+.TH RANT 1 "September 17, 2005"
+.SH NAME
+rant \- A flexible and portable build tool.
+.SH SYNOPSIS
+.B rant
+.RI [OPTION]\ ...\ [TARGET]\ ...
+.br
+.SH DESCRIPTION
+.B Striking features
+
+* Defining custom tasks.
+
+* Automated packaging, testing and RDoc generation for Ruby
+  applications and libraries.
+
+* Creation of a monolithic script tailored to the needs of a specific
+  project which can be used instead of an Rant installation - users
+  don't need to install Rant.
+
+* Creating gzipped tar and zip archives -- without installing
+  additional software. 
+
+* Optional recognition of file changes based on MD5 checksums instead
+  of file modification times. 
+
+* Dependency checking for C/C++ source files (integrated makedepend
+  replacement).
+
+* Primitive support for compiling C# sources with csc, cscc and mcs.
+
+.B Startup
+
+On startup, rant will look for a file called
+.IR Rantfile
+,
+.IR rantfile
+or
+.IR root.rant
+which contains the build specification (which in fact is valid Ruby
+code). After reading the Rantfile(s), rant will execute the following
+tasks:
+
+.B If at least one target was given on the commandline:
+
+rant will execute all tasks necessary to build all targets given on
+the commandline.
+
+.B else:
+
+rant tries to build the target called "default". If no task with this
+name exists, rant invokes the first defined task.
+
+If you want to know which task(s) will be invoked when no target is
+given on the commandline, run rant with the
+.IR -T
+option. Example:
+
+  $ rant -T
+.br
+  rant               # => test
+.br
+  rant package       # Create packages for distribution.
+.br
+  rant doc           # Generate documentation.
+.br
+  rant publish-docs  # Publish html docs on make.rubyfore.org.
+.br
+                     #   Note: scp will prompt for rubyforge password.
+.br
+  rant test          # Run basic tests.
+
+The
+.B first line
+always shows the target that will be built if no target argument is
+given. In this case, it would be the
+.RI test
+target.
+
+.PP
+.SH OPTIONS
+.TP
+  --help                           -h
+      Print a help message and exit.
+.TP
+  --version                        -V
+      Print version of Rant and exit.
+.TP
+  --verbose                        -v
+      Print more messages to stderr.
+.TP
+  --quiet                          -q
+      Don't print commands.
+.TP
+  --err-commands
+      Print failed commands and their exit status.
+.TP
+  --directory DIRECTORY            -C DIRECTORY
+      Run rant in DIRECTORY.
+.TP
+  --cd-parent                      -c
+      With this option, Rant starts to search for an Rantfile in the
+      current working directory as usual, but if it doesn't find one,
+      it changes to the parent directory and looks there for an
+      Rantfile. This is repeated until an Rantfile is found or the
+      working directory is the root directory of the filesystem.
+.TP
+  --look-up                        -u
+      Look in parent directories for root Rantfile.
+.TP
+  --rantfile RANTFILE              -f RANTFILE
+      Process RANTFILE instead of standard rantfiles.
+      Multiple files may be specified by repeating this option.
+.TP
+  --force-run TARGET               -a TARGET
+      Force rebuild of TARGET and all dependencies.
+.TP
+  --tasks                          -T
+      Show a list of all described tasks and exit.
+
+.SH AUTHOR
+rant was developed by Stefan Lang <langstefan@gmx.at>
+.SH COPYRIGHT
+Copyright (C) 2005  Stefan Lang <langstefan@gmx.at>
+.SH SEE ALSO
+For extensive documentation visit the Rant homepage
+.IR http://make.ruby-co.de
+.\" vim:ft=nroff

data/doc/rant.rdoc

@@ -17,7 +17,7 @@ run rant with the <tt>--tasks</tt> (short form: <tt>-T</tt>) option:
     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.
+                       #   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.
@@ -30,12 +30,11 @@ steps (roughly):
    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 Rantfiles in working directory. Rantfiles with the following
+2. Load Rantfile in working directory. Rantfiles with the following
    names are recognized:
-	Rantfile
-	rantfile
-	Rantfile.rb
-	rantfile.rb
+        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

data/doc/rantfile.rdoc

@@ -12,30 +12,26 @@ 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.
-+plugin+::	Instantiate a plugin. Example: <tt>plugin
-		:Configure</tt> instantiates the Configure plugin.
-+sys+::		Run external commands or call portable file system
-		manipulation methods (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.
-+rac+::		The "Rant compiler" which is compiling the Rantfiles.
++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
@@ -150,15 +146,16 @@ shows this descriptions:
     rant clean	# Remove autogenerated files.
 Only the tasks which have a description are listed.
 
-=== The +sys+ function
+=== The +sys+ command
 
-After using the +sys+ function quite often in the examples, I should
-explain it a little bit. The +sys+ function can be used in three ways:
+After using the +sys+ command quite often in the examples, I should
+explain it a little bit. The +sys+ command 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 the methods of the +FileUtils+ module that comes with ruby.
+   The first form is with no arguments. It returns an object on which
+   you can invoke the methods of the +FileUtils+ module that comes
+   with ruby.
    Examples are:
 	sys.rm "file1", "file2", ...	# remove files
 	sys.cp "src", "dest"	 	# copy from "src" do "dest"
@@ -174,7 +171,7 @@ explain it a little bit. The +sys+ function can be used in three ways:
 
 2. <b>Running external commands</b>
 
-   Invoke the +sys+ function with a string as argument to run a shell:
+   Invoke the +sys+ command with a string as argument to run a shell:
 	sys "echo *.c"
    will print a list of C files to stdout.
 
@@ -183,6 +180,28 @@ explain it a little bit. The +sys+ function can be used in three ways:
 	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+, which compares two files, returns 0 if
+   the files are equal, 1 if 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
@@ -401,11 +420,15 @@ 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 # in front of the task name:
-    task "a" => "#b"
+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::

data/doc/subdirs.rdoc

@@ -0,0 +1,147 @@
+
+== Buildfiles in subdirectories
+
+When a software project grows, it is often desired to split the build
+file up and create multiple buildfiles, e.g. one per directory. Rant
+has support for this case built in (unlike make). Part of this support
+is the +subdirs+ command which is described in
+doc/rantfile.rdoc[link:files/doc/rantfile_rdoc.html].  This section
+will describe one possible technique.
+
+First, a project needs to have a so called "root Rantfile". This file
+lives in the top directory of the project and is called +Rantfile+ or
+<tt>root.rant</tt>. Each subdirectory which needs specialized tasks,
+has a buildfile called <tt>sub.rant</tt>.
+
+A simple example would be a Ruby project where the test task(s) are
+defined in a seperate buildfile in the +test+ directory. The
+directory structure could look like:
+
+    rubyproject/
+        README
+        root.rant
+        bin/
+            ... some scripts
+        lib/
+            ... ruby library scripts
+        test/
+            sub.rant
+            tc_reader.rb
+            tc_writer.rb
+            tc_filter.rb
+            tc_metautils.rb
+
+The project has one <tt>root.rant</tt> file and any number of
+<tt>sub.rant</tt> files (in this case only one). In root.rant we
+define tasks for packaging, installation, cleanup, etc. and in the
+test/sub.rant file we define tasks that run unit tests.
+
+<tt>root.rant</tt> could look like:
+
+    import "md5"    # use MD5 checksums instead of timestamps, optional
+    import "rubypackage", "rubydoc", "autoclean"
+
+    # reference the "all" task defined in test/sub.rant
+    task :default => "test/all"
+
+    desc "Create package for distribution."
+    gen RubyPackage, "foo" do |t|
+        t.version = "1.0.1"
+        t.summary = "Foo is a ruby library and program for ..."
+        t.files = sys["bin/*", "lib/**/*.rb", "test/tc_*.rb", "**/*.rant"].shun("pkg")
+        t.package_task
+    end
+
+    desc "Generate HTML docs."
+    gen RubyDoc
+
+    desc "Remove generated files and directories."
+    gen AutoClean, :clobber
+
+    # read test/sub.rant
+    subdirs "test"
+
+and <tt>test/sub.rant</tt> contains:
+
+    desc "Run all unit tests."
+    task :all do
+        sys "testrb", sys["tc_*.rb"]
+    end
+
+    desc "Run IO related unit tests."
+    task :io do
+        sys "testrb tc_reader.rb tc_writer.rb"
+    end
+
+    desc "Test internals."
+    task :internals do
+        sys "testrb tc_filter.rb tc_metautils.rb"
+    end
+
+Now we run from the shell:
+
+First let rant list all public tasks:
+    
+    <rubyproject> $ rant -T
+    rant                 # => test/all
+    rant package         # Create package for distribution.
+    rant doc             # Generate HTML docs.
+    rant clobber         # Remove generated files and directories.
+    rant test/all        # Run all unit tests.
+    rant test/io         # Run IO related unit tests.
+    rant test/internals  # Test internals.
+
+We see that if we run rant without arguments, it will run the test/all
+task.
+
+Change to the test directory:
+
+    <rubyproject> $ cd test
+    <test> $ rant -T
+    (root is /home/stefan/Ruby/misc/rant/rbtest, in test)
+    rant all        # Run all unit tests.
+    rant io         # Run IO related unit tests.
+    rant internals  # Test internals.
+    rant @package   # Create package for distribution.
+    rant @doc       # Generate HTML docs.
+    rant @clobber   # Remove generated files and directories.
+
+If rant is started from a directory with a sub.rant file, it searches
+upwards in the directory tree until it finds a file called +Rantfile+
+or <tt>root.rant</tt>. This file will be read first, the directory
+which contains this file is viewed as the projects root directory.
+Then it ensures that the sub.rant file in the current directory is
+read and starts operating. Task names given on the commandline are
+interpreted relative to the current directory. Tasks defined in other
+directories can be referenced by prepending them with an <tt>@</tt>
+character.
+
+To run the IO related tests from the test directory we type:
+
+    <test> $ rant io
+    (root is /home/stefan/Ruby/misc/rant/rbtest, in test)
+    testrb tc_reader.rb tc_writer.rb
+    ... output of testrb ...
+
+To run the clobber task from the test directory:
+
+    <test> $ rant @clobber
+    (root is /home/stefan/Ruby/misc/rant/rbtest, in test)
+    (in /home/stefan/Ruby/misc/rant/rbtest)
+    rm -f ...
+    ... more output ...
+
+== See also
+
+Rantfile basics::
+    doc/rantfile.rdoc[link:files/doc/rantfile_rdoc.html]
+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]
+Rant Overview::
+    README[link:files/README.html]