rantfile.rdoc in rant-0.4.6

- old
+ new

@@ -10,34 +10,30 @@
 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.
-+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
 
 Just call the +task+ function and give it a task name as argument. The
@@ -148,19 +144,20 @@
     % rant -T
     rant ls	# Build ls program.
     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"
 	sys.mkdir "dir"		 	# create directory "dir"
    For a list of all available methods invoke ri:
@@ -172,19 +169,41 @@
 	sys.safe_ln "src", "dest"    # create a hardlink or fall back to
 				     # copying
 
 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.
 
    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+, 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
    <tt>[]</tt> operator:
 	file "program" => sys["*.o"]
@@ -399,13 +418,17 @@
 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 # 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::
     doc/advanced.rdoc[link:files/doc/advanced_rdoc.html]