rant 0.3.0

data/doc/csharp.rdoc

@@ -0,0 +1,74 @@
+
+== Compiling C# sources
+
+Support for C# is currently implemented as plugin. But expect that to
+change in the near future. Also note that support for C# wasn't
+heavily tested (but it works because I'm using it).
+
+It is convinient to use the C# plugin in combination with the
+Configure plugin. I'll show a short Rantfile first and explain it
+afterwards.
+
+    conf = plugin :Configure do |conf|
+	desc "Configure build."
+	conf.task
+	desc "Interactive configure."
+	conf.task "ask-config", [:interact]
+	conf.init_modes = [:guess, :interact]
+    end
+
+    plugin :Csharp do |cs|
+	cs.config = conf
+    end
+
+    gen Assembly, "myprog.exe" do |t|
+	t.libs = %w(System.Drawing.dll System.Windows.Forms.dll)
+	t.sources = Dir["src/*.cs"]
+	t.resources = Dir["res/*.*"]
+    end
+
+First we instantiate the Configure plugin and let it define two tasks
+for us:
+<tt>conf.task</tt>::	Creates a task with the name "configure" which
+			will first guess values and ask the user as
+			fallback if it can't guess the value.
+<tt>conf.task "ask-config", [:interact]</tt>::
+    This task interactively asks the user for all values.
+Afterwards we set the +init_modes+. Those decide what will be done on
+a regular rant startup if the +config+ file doesn't exist. We tell it
+to first guess configure values and to fall back to interactive mode
+if necessary.
+
+Then we instantiate the Csharp plugin and connect it with the
+Configure plugin. As a result of this operation, the Csharp plugin
+will define three configure _checks_:
+1. The command to invoke the C# compiler.
+2. If optimization should be turned on.
+3. If debug information should be generated.
+
+And last but not least we let generate a task to compile our program
+<tt>myprog.exe</tt>. The +Assembly+ generator takes the same argument
+as a normal task, meaning you could also add prerequisites:
+    gen Assembly, "myprog.exe" => :pre do |t|
+	.
+	.
+	.
+The +libs+ attribute is a list of libraries the assembly will be
+linked against, the +sources+ attribute should be clear and the
++resources+ attribute is a list of resources to be embedded in the
+assembly.
+
+Now let's see what is actually done by rant when we feed it this
+Rantfile. Because we have only one task defined, there is no need to
+specify a task on the commandline:
+    % rant
+    cscc -o myprog.exe -Wall -O2 -l System.Drawing.dll -l System.Windows.Forms.dll -fresources=res/MyProg.legend.png src/MyProg.cs src/Util.cs
+This was on a Linux system, on Windows you'll probably see a command
+with csc.
+
+== See also
+
+Rant Overview::
+    README[link:files/README.html]
+Writing an Rantfile::
+    doc/rantfile.rdoc[link:files/doc/rantfile_rdoc.html]

data/doc/rant-import.rdoc

@@ -0,0 +1,32 @@
+
+== The rant-import command
+
+The rant-import command creates a monolithic rant script tailored to
+the needs of your project and thus removes the dependency on an Rant
+installation (but of course one person needs an Rant installation to
+run rant-import).
+
+Just run the command with the <tt>--help</tt> option to get a brief
+help message:
+    % rant-import --help
+
+Probably the easiest way to create your monolithic rant script is with
+the <tt>--auto</tt> option:
+    % rant-import --auto ant
+This will write a monolithic rant script to the file +ant+ in the
+current directory. To determine which plugins and imports your project
+is using, it performs step 2 of the rant command as described in
+doc/rant.rdoc[link:files/doc/rant_rdoc.html], which means that it
+loads the Rantfile in the current directory.
+
+That one command should be enough, try it out:
+    % ruby ant
+This script has the same behaviour as the rant command. Distribute it
+with your project and nobody else but you needs an Rant installation.
+
+== See also
+
+Rant Overview::
+    README[link:files/README.html]
+Writing an Rantfile::
+    doc/rantfile.rdoc[link:files/doc/rantfile_rdoc.html]

data/doc/rant.rdoc

@@ -0,0 +1,24 @@
+
+== The *rant* program
+
+For a short usage message and a list of options invoke rant with the
+<tt>--help</tt> option:
+    % rant --help
+
+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.
+2. Load Rantfiles in working directory. Rantfiles with the following
+   names are recognized:
+	Rantfile
+	rantfile
+	Rantfile.rb
+	rantfile.rb
+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
+   be invoked.

data/doc/rantfile.rdoc

@@ -0,0 +1,227 @@
+
+== How to write an *Rantfile*
+
+As already mentioned, an Rantfile is a Ruby script. Additionally, Rant
+provides methods and classes which aid you in automating your work.
+
+Centric to the processing done by Rant is the *task*. The Rantfile
+defines tasks and their dependencies, Rant invokes the required tasks.
+
+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+::		When given argument(s), runs an external program.
+		Otherwise you can call methods to interact with the OS
+		on it.
++source+::	Takes a filename as argument and causes Rant to read
+		it in as Rantfile.
+
+=== Defining a task
+
+Just call the +task+ function and give it a task name as argument. The
+task name may be a string or symbol:
+    task :taskname
+That's it, your first task. Not very usefull, because it doesn't do
+anything. To associate an action with the task, add a block:
+    task :mytask do
+	puts "Hello, mytask running."
+    end
+Put these 3 lines of code into an Rantfile and run rant:
+    % rant mytask
+    Hello, mytask running.
+Note: you could have ommited 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
+task:
+    task :mytask do |t|
+	puts t.name
+    end
+Running rant now:
+    % rant
+    mytask
+
+Add prerequisites to create relations between tasks:
+    task :first => [:t1, :t2] do
+	puts t.name
+    end
+    task :t1 do |t|
+	puts t.name
+    end
+    task :t2 do |t|
+	puts t.name
+    end
+In the definition of the "first" task we told Rant that it +depends+
+on task "t1" and task "t2". "t1" and "t2" are called prerequisites for
+"first". Try it out:
+    % rant first
+    t1
+    t2
+    first
+    % rant t1
+    t1
+    % rant t2
+    t2
+
+=== Defining a file task
+
+You will notice that rant will run the actions for a normal task
+always its name is given on the commandline or it is required by
+another task. Often you want to create a file, e.g. a program by
+invoking a compiler. In this case, the action needs only to be run if
+the source files (prerequisites) have changed. Use a file task instead
+of a normal task.
+
+In this example we use the <tt>sys.touch</tt> method to test our file
+task. (This method works the same as the Unix touch command: Update
+the modification time of a file or create an empty file):
+    file "testfile" do |t|
+	sys.touch t.name
+    end
+Now run rant:
+    % rant
+    touch testfile
+This would have been the same with a normal task. But now run rant a
+second time:
+    % rant
+This time rant doesn't run the action, because "testfile" is up to
+date. Of course you can add prerequisites the same way as for a normal
+task. Additionally you can add filenames as prerequisites. Assuming
+the files "a.o" and "b.o" are in the same directory as the Rantfile:
+    file "myprog" => %w(a.o b.o) do |t|
+	sys %w(cc -o), t.name, t.prerequisites
+    end
+Running rant:
+    % rant
+    cc -o myprog a.o b.o
+Running a second time:
+    % rant
+Does nothing, myprog is up to date.
+Don't be irritated by the <tt>%w()</tt> syntax. It creates a list of
+strings. The following expressions are equivalent:
+    ["a", "b", "c"]
+    %w(a b c)
+
+=== Adding task descriptions
+
+The +desc+ function lets you describe your tasks. A small example
+Rantfile:
+    # Generate C source file ls.c with the xgen command.
+    file "ls.c" => %w(ls1.x ls2.x) do |t|
+	sys %w(xgen -o), t.name, t.prerequisites
+    end
+
+    desc "Build ls program."
+    file "ls" => "ls.c" do
+	sys "cc -o ls ls.c"
+    end
+
+    desc "Remove autogenerated files."
+    task :clean do
+	sys.rm_f %w(ls.c ls)
+    end
+(Note that xgen is a hypothetical command ;)
+The <tt>--tasks</tt> (or the short form, <tt>-T</tt>) option of rant
+shows this descriptions:
+    % rant -T
+    rant ls	# Build ls program.
+    rant clean	# Remove autogenerated files.
+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:
+    include Sys
+    task :clean do
+	rm_f "myprog"
+    end
+Then you can invoke these methods without the <tt>sys</tt> function.
+
+=== Generators
+
+The *gen* function takes a generator which usually creates one or more
+tasks for you. Currently are two generators immediately available:
++Directory+::	Create directories.
++Task+::	Define custom task.
+
+=== The +Directory+ generator
+
+An example usage of the +Directory+ generator would be the backup
+example shown in the README file:
+    file "misc/backup/data" => %w(misc/backup data) do |t|
+	sys.cp "data", t.name
+    end
+    
+    gen Directory, "misc/backup"
+Now rant will create the directories "misc" and "backup" on demand.
+Assuming "misc/backup" doesn't exist:
+    % rant
+    mkdir misc
+    mkdir misc/backup
+    cp data misc/backup/data
+
+=== The +Task+ generator
+
+The +Task+ generator allows you to determine by hand when your task
+action needs to be run:
+    desc "Install with setup.rb"
+    gen Task, :install do |t|
+	t.needed { !File.exist? "InstalledFiles" }
+	t.act do
+	    sys.ruby "setup.rb"
+	end
+    end
+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.
+
+=== Importing additional generators
+
+The +import+ function lets you import additional generators.
+Currently the following are coming with Rant:
++RubyTest+::	Run Test::Unit tests for your Ruby code.
++RubyDoc+::	Run RDoc.
++RubyPackage+::	Generate tar, zip and gem packages of your Ruby
+		application/library.
+As these are all Ruby specific, please read the Ruby project howto.
+
+== See also
+
+Rant Overview::
+    README[link:files/README.html]
+Ruby project howto::
+    doc/rubyproject.rdoc[link:files/doc/rubyproject_rdoc.html]

data/doc/rubyproject.rdoc

@@ -0,0 +1,210 @@
+
+== Ruby project howto
+
+This section is a brief howto for automating some common tasks like
+running rdoc, unit tests and packaging.
+
+We are assuming a project with the following directories and files:
+    Rantfile
+    README
+    bin/
+	wgrep
+    lib/
+	wgrep.rb
+    test/
+	tc_wgrep.rb
+You can find this little project in test/project_rb1 directory of the
+Rant package. You'll probably have more files in your project, but we
+will try to write our Rantfile as generic as possible:
+
+    import %w(rubytest rubydoc rubypackage)
+
+    lib_files = Dir["lib/**/*.rb"]
+    dist_files = lib_files + %w(rantfile.rb README) + Dir["{test,bin}/*"]
+
+    desc "Run unit tests."
+    gen RubyTest do |t|
+	t.test_dir = "test"
+	t.pattern = "tc_*.rb"
+    end
+
+    desc "Generate html documentation."
+    gen RubyDoc do |t|
+	t.opts = %w(--title wgrep --main README README)
+    end
+
+    desc "Create packages."
+    gen RubyPackage, :wgrep do |t|
+	t.version = "1.0.0"
+	t.summary = "Simple grep program."
+	t.files = dist_files
+	t.bindir = "bin"
+	t.executable = "wgrep"
+	t.package_task
+    end
+
+    task :clean do
+	sys.rm_rf %w(doc pkg)
+    end
+
+To verify how our tasks are named:
+    % rant -T
+    rant test     # Run unit tests.
+    rant doc      # Generate html documentation.
+    rant package  # Create packages.
+
+Let's examine the code by running the tasks:
+    % rant test
+    cd test
+    ruby -I /home/stefan/Ruby/lib/rant/test/project_rb1/lib -S testrb tc_wgrep.rb
+    Loaded suite tc_wgrep.rb
+    Started
+    .
+    Finished in 0.004588 seconds.
+
+    1 tests, 2 assertions, 0 failures, 0 errors
+    cd -
+The +RubyTest+ generator automatically added the +lib+ directory to
+the LOAD_PATH for testing. Because we have set the +test_dir+ to
+"test", it changes to the +test+ directory, evaluates the +pattern+ to
+collect the testcases and then runs the _testrb_ command.
+
+To format the documentation:
+    % rant doc
+
+				 README:
+			       wgrep.rb: mcc....
+    Generating HTML...
+
+    Files:   2
+    Classes: 2
+    Modules: 1
+    Methods: 4
+    Elapsed: 0.335s
+All of this output originates from RDoc. The +RubyDoc+ generator gives
+the +lib+ directory and additionally the +opts+ we have set to RDoc.
+
+The most interesting task is the +package+ task:
+    % rant package
+    mkdir pkg
+    mkdir pkg/wgrep-1.0.0
+    mkdir -p pkg/wgrep-1.0.0/lib
+    mkdir -p pkg/wgrep-1.0.0/test
+    mkdir -p pkg/wgrep-1.0.0/bin
+    ln lib/wgrep.rb pkg/wgrep-1.0.0/lib/wgrep.rb
+    ln rantfile.rb pkg/wgrep-1.0.0/rantfile.rb
+    ln README pkg/wgrep-1.0.0/README
+    ln test/text pkg/wgrep-1.0.0/test/text
+    ln test/tc_wgrep.rb pkg/wgrep-1.0.0/test/tc_wgrep.rb
+    ln bin/wgrep pkg/wgrep-1.0.0/bin/wgrep
+    touch pkg/wgrep-1.0.0
+    cd pkg
+    tar zcf wgrep-1.0.0.tar.gz wgrep-1.0.0
+    cd -
+    cd pkg
+    zip -yqr wgrep-1.0.0.zip wgrep-1.0.0
+    cd -
+      Successfully built RubyGem
+      Name: wgrep
+      Version: 1.0.0
+      File: wgrep-1.0.0.gem
+    mv wgrep-1.0.0.gem pkg
+This is what it does on my machine:
+1. Link all package files to the new folder <tt>pkg/wgrep-1.0.0</tt>.
+2. Create a tar.gz file in the +pkg+ directory with the tar command.
+3. Create a .zip file in the +pkg+ directory with the zip command.
+4. Create a RubyGem in +pkg+.
+The .zip file will only be created if the +zip+ command is available.
+The .tar.gz file will only be created if the +tar+ command is
+available. And the RubyGem will only be created if RubyGems is
+available on your system.
+
+The gem specification also contains the RDoc options we have given to
+the +RubyDoc+ generator and the +has_rdoc+ attribute is set to true.
+No need to duplicate this information in our Rantfile.
+
+=== More about the RubyPackage generator
+
+The argument given to the RubyPackage generator is used as package
+name (here "wgrep") and may be a symbol or string:
+    gen RubyPackage, :wgrep do |t|
+
+The line which actually creates the package task(s) is this one:
+    t.package_task
+Optionally you may give it a task name as argument:
+    t.package_task :release
+Now you can run rant with the argument "release" for packaging:
+    % rant release
+
+If you want to change the package directory (which defaults to +pkg+)
+you can set the +pkg_dir+ attribute:
+    t.pkg_dir = "packages"
+    t.package_task
+
+Perhaps you want to specify explicetely what packages you want to
+build. To accomplish this, each of the following methods listed takes
+an optional task name as argument:
+    t.tar_task		# create tar.gz archive, task name defaults to "tar"
+    t.zip_task		# create zip archive, task name defaults to "zip"
+    t.gem_task		# create gem, task name defaults to "gem"
+An example would be:
+    desc "Create tar.gz package."
+    t.tar_task :archive
+    desc "Create RubyGem."
+    t.gem_task
+    # Not required: Creates a shortcut for the previously defined
+    # package tasks ("archive" and "gem")
+    desc "Create packages."
+    t.package_task
+
+In our example we had only a few attributes for our package. Here are
+following two lists with the available attributes.
+* Attributes that take a single argument:
+	name
+	date
+	description
+	email
+	has_rdoc
+	homepage
+	platform
+	required_ruby_version
+	rubyforge_project
+	summary
+	version
+* Attributes that take one or more values (if you give a single value
+  it will automatically be converted to a list):
+	author
+	bindir
+	executable
+	extension
+	files
+	rdoc_options
+	requires
+	test_files
+	test_suite
+The attributes can also be set without the assignment operator:
+    t.executable "mybin"
+
+Additionally to all this attributes you can explicitely set an
+attribute for the gem specification by preceding it with +gem_+:
+    t.gem_autorequire = "myproject"
+
+=== More about the RubyDoc generator
+
+If an argument is given to the RubyDoc generator, it will be used as
+task name.  The output directory for the html files defaults to +doc+.
+To change this set the +dir+ attribute:
+    desc "Generate html documentation."
+    gen RubyDoc, :html do |t|
+	t.dir = "doc/html"
+As rant invokes RDoc programmatically, no command is printed when the
+task is run. If you want to see one, set the verbose attribute to
++true+:
+	t.verbose = true
+
+== See also
+
+Rant Overview::
+    README[link:files/README.html]
+Writing an Rantfile::
+    doc/rantfile.rdoc[link:files/doc/rantfile_rdoc.html]