rant 0.3.2 → 0.3.4

data/NEWS

@@ -1,6 +1,27 @@
 
 = Rant NEWS
 
+== Rant 0.3.4
+
+Incompatible changes:
+* Arguments of the form VAR=VAL to rant no longer set environment
+  variables directly, they are available through +var+ now. Read
+  doc/advanced.rdoc[link:files/doc/advanced_rdoc.html] for more info.
+* Replace any
+    include Sys
+  with
+    include Rant::Sys
+  in Rantfiles. Or even better: don't include the +Sys+ module.
+
+New features:
+* Installation with install.rb installs .cmd files on Windows.
+  Read README[link:files/README.html]
+* Sharing variables between Rantfiles. Read 
+  doc/advanced.rdoc[link:files/doc/advanced_rdoc.html] for more info.
+* Selecting files with the +sys+ command.
+* Rules
+Read doc/rantfile.rdoc[link:files/doc/rantfile_rdoc.html] for docu.
+
 == Rant 0.3.2
 
 This version should be fully backwards compatible to 0.3.0.
@@ -9,7 +30,7 @@ New features:
 * Support splitting your buildfiles up and placing them into multiple
   directories with the +subdirs+ command. Please read
   doc/rantfile.rdoc[link:files/doc/rantfile_rdoc.html] for usage.
-  This is especially usefull for bigger projects.
+  This is especially useful for bigger projects.
 
 == Rant 0.3.0
 

data/README

@@ -36,10 +36,10 @@ Running rant in the directory of this file:
 will ensure that the "data" file in the "backup" directory is up to
 date.
 
-This document was written for version 0.3.2 of Rant. Most things
+This document was written for version 0.3.4 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 for your Rant version.
+documentation of your Rant version.
 
 == Support
 
@@ -103,18 +103,14 @@ is done, you have successfully installed Rant. Congratulations!
 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:
+the archive, cd to the new directory and run the install.rb script.
+This could look like:
     % tar -xzf rant-<version>.tar.gz
     % cd rant-<version>
-    % ruby setup.rb
+    % ruby install.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
+privileges for the last command.
+Finally try to run
     % rant --version
 to verify Rant was installed correctly.
 
@@ -202,7 +198,8 @@ Rant was tested on:
     Linux		1.8.2
 			1.9
     MacOS X		1.8.2
-    WindowsXP		1.8.2 (OneClick Installer)
+    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...

data/Rantfile

@@ -5,9 +5,10 @@ import %w(rubytest rubydoc rubypackage)
 
 task :default => :test
 
-lib_files = FileList["lib/**/*.rb"]
-dist_files = FileList["{bin,lib,test,doc}/**/*"].shun("html", "coverage") +
-	FileList["*"].no_dir.exclude("InstalledFiles", "Session.vim")
+lib_files = sys["lib/**/*.rb"]
+dist_files = sys["{bin,lib,test,doc}/**/*"].shun("html", "coverage") +
+	sys["*"].no_dir.exclude("InstalledFiles", "Session.vim")
+bin_files = sys["bin/*"]
 
 gen RubyPackage, "rant" do |t|
     t.version = `#{Env::RUBY} run_rant --version`.split[1]
@@ -18,7 +19,7 @@ gen RubyPackage, "rant" do |t|
     t.author = "Stefan Lang"
     t.email = "langstefan@gmx.at"
     t.rubyforge_project = "make"
-    t.gem_extra_rdoc_files = FileList["**/README", "NEWS"].no_dir("pkg").no_dir("test") + FileList["doc/**/*.rdoc"]
+    t.gem_extra_rdoc_files = sys["**/README", "NEWS"].no_dir("pkg").no_dir("test") + sys["doc/**/*.rdoc"]
     t.homepage = "http://make.rubyforge.org"
     desc "Create packages for distribution."
     t.package_task
@@ -59,7 +60,7 @@ end
 desc "Test plugins."
 gen RubyTest, :testplugins do |g|
     g.libs << "test"
-    g.test_files = FileList["test/plugin/**/test_*"]
+    g.test_files = sys["test/plugin/**/test_*"]
 end
 
 desc "Run all tests and generate coverage with rcov."
@@ -73,13 +74,13 @@ end
 desc "Test project with subdirs."
 gen RubyTest, :tsubdirs do |t|
     t.libs << "test"
-    t.test_files = FileList["test/subdirs/test_*.rb"]
+    t.test_files = sys["test/subdirs/test_*.rb"]
 end
 
 desc "Run all tests."
 gen RubyTest, :tall do |g|
     g.libs << "test"
-    g.test_files = FileList["test/**/test_*.rb"]
+    g.test_files = sys["test/**/test_*.rb"]
 end
 task :testall => %w(test testp1 testp2 testrb1 testplugins)
 
@@ -87,6 +88,7 @@ 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)
+    sys.rm_f sys["bin/*.cmd"]
 end
 
 desc "Publish html docs on make.rubyfore.org.",
@@ -104,8 +106,29 @@ task "to-win" => :package do
     win_dir = "/mnt/data_fat/stefan/Ruby"
     Dir["pkg/*"].each { |f|
 	target = File.join(win_dir, File.basename(f))
-	sys.rm_rf target if test(?e, target)
-	sys.cp_r f, target
+	(file target => f do |t|
+	    sys.rm_rf target if test(?e, target)
+	    sys.cp_r f, t.name
+	end).invoke
+    }
+end
+
+desc "Install Rant."
+install = task :install do
+    sys.ruby "setup.rb"
+end
+
+if Env.on_windows?
+    cmd_files = bin_files.find_all { |f| f !~ /\.cmd$/}
+    cmd_files.map! { |f| "#{f}.cmd" }
+    cmd_files.zip(bin_files).each { |cmd, bin|
+	file cmd do |t|
+	    File.open(t.name, "w") { |f|
+		i_bin = File.join(Env::RUBY_BINDIR, File.basename(bin))
+		f.puts "@#{sys.sp Env::RUBY} #{sys.sp i_bin} %*"
+	    }
+	end
+	install << cmd
     }
 end
 

data/devel-notes

@@ -63,4 +63,20 @@ following:
 * Worker#needed?
 * RantApp#run before returning.
 
+== RantContext#rantapp rename
+Rename +rantapp+ to +rac+.
+Done.
+
+== Circular dependencies
+Before Rant detected circular dependencies, we silently removed a task
+dependency on itself. Should we remove this mechanism now?
+
+== Testing
+Files/directories created during tests match the glob *.t*
+so don't give names matching this pattern to regular files, as they
+would soon be deleted!
+
+== Compiling C
+make uses the env. variables CC and CFLAGS.
+
 # vim:tw=70:

data/doc/advanced.rdoc

@@ -0,0 +1,55 @@
+
+== Advanced Rantfiles
+
+=== Sharing variables
+
+The +var+ command allows you to share variables between Rantfiles and
+to set variables from the commandline. Just use +var+ like a hash to
+set/get variables:
+    var[:manifest] = %w(README Rantfile myprog.rb lib)
+In this example, :manifest is the variable name, which has to be a
+string or symbol. Symbols as variable names are converted to strings.
+Now you can access the "manifest" variable in every Rantfile of your
+project:
+    file "MANIFEST" do |t|
+	open(t.name, "w") { |f|
+	    var[:manifest].each { |str| f.puts(str) }
+	}
+    end
+
+Arguments of the form VAR=VAL to the rant command are also available
+through +var+:
+    % cat Rantfile
+    task :show_test do
+	puts var[:test]
+    end
+    % rant
+    nil
+    % rant test=hello
+    hello
+
+For some variables it is necessary to make them available for
+subprocesses, like CC or CFLAGS:
+    var.env %w(CC CFLAGS)
+The variables CC and CFLAGS are available through +var+ as always and
+are mapped to environment variables.
+
+=== The "ignore" variable
+
+The "ignore" variable is a list of files/regular expressions which are
+ignored when selecting files with the +sys+ command:
+    var[:ignore] = ["CVS", /~$/]
+If you select files with <tt>sys[]</tt> now, the lists won't contain
+any directory/file named "CVS" or ending in ~. Examples would be:
+    CVS
+    src/CVS
+    src/CVS/xy
+    xy~
+    src/util.c~
+
+== See also
+
+Rantfile basics::
+    doc/rantfile.rdoc[link:files/doc/rantfile_rdoc.html]
+Rant Overview::
+    README[link:files/README.html]

data/doc/rant.rdoc

@@ -5,13 +5,31 @@ 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 environment
-   variables. All other arguments are names of tasks to be invoked.
+   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
    names are recognized:
 	Rantfile
@@ -22,3 +40,10 @@ steps (roughly):
    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.
+
+== 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]

data/doc/rantfile.rdoc

@@ -47,7 +47,7 @@ anything. To associate an action with the task, add a block:
 Put these 3 lines of code into a file called +Rantfile+ and run rant:
     % rant mytask
     Hello, mytask running.
-Note: you could have ommited the mytask argument to rant because it is
+Note: you could have omited the mytask argument to rant because it is
 the only task in the Rantfile.
 
 You can add a block parameter which will be a reference to the created
@@ -149,36 +149,70 @@ Only the tasks which have a description are listed.
 === The +sys+ function
 
 After using the +sys+ function quite often in the examples, I should
-explain it a little bit. The +sys+ function can be used in two ways:
-
-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:
-    % ri FileUtils
-which will also show documentation for them.
-Additionally you have the following methos which are not in the
-FileUtils module:
-    sys.ruby "arg1", "arg2", ... # invoke the ruby interpreter
-    sys.safe_ln "src", "dest"	 # create a hardlink or fall back to
-				 # copying
-If you're tired of typing <tt>sys.</tt> all the time, you can include
-the +Sys+ module in your Rantfile (though it is not recommended to do
-this):
-    include Sys
-    task :clean do
-	rm_f "myprog"
-    end
+explain it a little bit. The +sys+ function 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.
+   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:
+	% ri FileUtils
+   which will also show documentation for them.
+   Additionally you have the following methos which are not in the
+   FileUtils module:
+	sys.ruby "arg1", "arg2", ... # invoke the ruby interpreter
+	sys.safe_ln "src", "dest"    # create a hardlink or fall back to
+				     # copying
+   If you're tired of typing <tt>sys.</tt> all the time, you can include
+   the Rant::Sys module in your Rantfile (though it is not recommended
+   to do this):
+	include Rant::Sys
+	task :clean do
+	    rm_f "myprog"
+	end
 Then you can invoke these methods without the <tt>sys</tt> function.
-Note::	You are highly encouraged to not <tt>include Sys</tt> into
-	your Rantfile as this introduces many methods in the global
-	namespace, which can cause name clashes with other libraries.
-	Of course if you have just some tasks to remove backup files
-	in your home directory and do not use other Ruby libraries in
-	your Rantfile, it is no problem.
+Note::	You are highly encouraged to not <tt>include Rant::Sys</tt>
+	into your Rantfile as this introduces many methods in the
+	global namespace, which can cause name clashes with other
+	libraries.  Of course if you have just some tasks to remove
+	backup files in your home directory and do not use other Ruby
+	libraries in your Rantfile, it is no problem.
+
+2. <b>Running external commands</b>
+
+   Invoke the +sys+ function 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.
+
+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"]
+   The task "program" depends on all files ending in ".o". Rant uses
+   the Dir::glob method internally to resolve patterns, so you can
+   read the ri docs to get an overview:
+	ri Dir::glob
+
+   You can give more patterns:
+	c_files = sys["**/*.h", "**/*.c"]
+   gives a list of all files ending in ".h" or ".c" in the current
+   directory and all subdirectories.
+
+   The object returned by sys#[] _behaves_ like a list of string, so
+   it is possible to pass it to methods expecting an array. If you're
+   getting errors or experience strange behaviour convert the list
+   explicetely to an array:
+	sys.touch c_files.to_a
 
 === Generators
 
@@ -218,6 +252,44 @@ The +act+ block of the "install" task will only be run if
 "InstalledFiles" doesn't exist. Of course you can add prerequisites
 like with any other task.
 
+=== Rules
+
+A Rule allows you to tell Rant how it should build files matching a
+common pattern, e.g. how to build files ending in ".o". A standard
+rule usage is to create C object files:
+    gen Rule, '.o' => '.c' do |t|
+	sys "cc -c -o #{t.name} #{t.source}"
+    end
+Assuming that we have the C source file util.c in the current
+directory:
+    % rant util.o
+    cc -c -o util.o util.c
+Because Rant didn't find a task for util.o, it looked for a matching
+rule and created a task for util.o.
+
+The first line above could also be written as:
+    gen Rule, :o => :c do |t|
+
+The +source+ method of the task object gives us the first dependency.
+So the following line has the same effect:
+	sys "cc -c -o #{t.name} #{t.prerequisites.first}"
+
+You can also refine the rule pattern by using a regular expression. To
+refine dependency selection give a block as source argument:
+    src = lambda { |target| [target.sub_ext("c"), target.sub_ext("h")] }
+    gen Rule, /^my_[^.]+\.o$/ => src do |t|
+	sys "cc -c -o #{t.name} #{t.source}"
+    end
+This rule generates a task for files beginning with "my_" and ending
+in ".o" (like "my_program.o"). The task has a file ending in ".c" and
+one ending in ".h" as dependencies (like "my_program.c" and
+"my_program.h") . Since <tt>t.source</tt> gives us the *first*
+dependency, the ".c" file will appear as argument to cc, but not the
+".h" file.
+
+The +sub_ext+ method of the +String+ class replaces anything after the
+last dot with the given string.
+
 === Importing additional generators
 
 The +import+ function lets you import additional generators.
@@ -326,6 +398,8 @@ because it refers to a main Rantfile.
 
 == See also
 
+Advanced Rantfiles::
+    doc/advanced.rdoc[link:files/doc/advanced_rdoc.html]
 Rant Overview::
     README[link:files/README.html]
 Ruby project howto::