+~^~+ Ruby2Make +~^~+
=====================

* Goal: Ruby DSL to generate Makefiles

* Simple example: to make this Makefile,

    CC = gcc
    FLAGS = -g

    hello: hello.c
        $(CC) $(FLAGS) hello.c -o hello

    clean:
        -rm hello 
        -rm *.o

use this Ruby:

    vars :FLAGS => "-g"

    rule "hello", :depends => "hello.c" do
        compile :output => "hello"
    end

    clean "hello", "*.o"
 
It's more readable, and it doesn't insanely require tabs and not spaces.


-=- Usage -=-
-------------

* To install in /usr/bin, do `ruby setup.rb` as root.

* To use, `rbmake` looks for a Makefile.rb and generates a Makefile.

* To specify a Makefile.rb, use `rbmake other_file.rb`.


-=- Examples -=-
----------------

* A number of usage examples are included, they would be the best way to
  learn the syntax.


-=- Syntax -=-
--------------

vars [hash] 
    => Set Makefile macros (includes {:CC => "gcc", :FLAGS => ""})

suffix [out extension] [in extension] [command]
    => Add a rule to compile files from the inextension to the out extension,
       currently using a literal compilation command. See example5.rb.

rule [name] [optional depends hash] [block] 
    => Add a rule/target called name. If a hash like ':depends => "hello.o"'
       or ':depend => ["hello.o", "hello.h"]' is present, then those items
       are added as dependencies to the rule.

depends [args]
    => Add dependencies to a rule (must occure in rule declaration's block)

compile [args]
    => Without any args, uses '$(CC) $(FLAGS)' to compile the dependencies.

       Parameters accepted:
         :input, :i         => Specify input file(s)
         :output, :o        => Specify output file
         :compiler, :c      => Specify a compiler other than $(CC)
         :to_obj, :obj      => Add a "-c" flag
         :to_asm, :asm      => Add a "-S" flag
         :debug             => Add a "-g" flag
         :$@                => Sets the output file to "$@" (name of the rule)

       Literal arguments are also accepted.  Strings are directly inserted, and
       symbols are converted to macros. :LIBS becomes $(LIBS).

shell [args]
    => Add a custom line/command to a rule.
       Modifiers allowed:
        :silent     => Add a '@' to command (Make won't echo it when it executes)
        :suppress   => Add a '-' to command (Make won't worry about errors)

echo [message]
    => Shortcut for an often used command: `shell "@echo #{message}"`

clean [files]
    => Shortcut to create a clean rule, with a '-rm -rf' command for all file
       arguments given.

comment [comments]
    => When used outside a rule, adds the comment at the beginning of the 
       Makefile.  When used inside a rule, adds the comments directly above
       the rule (see example 1).