= rake-builder - Rake for C/C++/Objective-C/Objective-C++ Projects

rake-builder provides a simple interface for building C, C++,
Objective-C and Objective-C++ projects.
It uses rake, which was created as a make replacement,
and specializes it for the specific purpose of compiling
single projects. 

Projects are managed and built via a 'Rakefile'.

Here is a typical example:

 require 'rubygems' if RUBY_VERSION < '1.9'
 require 'rake'
 require 'rake/builder'
 
 Rake::Builder.new do |builder|
   builder.target               = 'my_program'
   builder.source_search_paths  = [ 'src' ]
   builder.header_search_paths  = [ 'include' ]
 end

= Installation

 $ sudo gem install rake-builder

= Hello World! Example

See the 'examples' directory.

The Hello World! project should build and run:

 $ cd examples/01_hello_world_cpp
 $ rake run
 Hello World!

= Usage

See the 'examples' directory.

If you've installed the gem system-wide, type the following to go to
the correct directory:

 $ cd `gem environment gemdir`/gems/rake-builder/examples

= Tasks

You can list tasks as follows:

 $ rake -T
 rake build    # Compile and build 'hello-world'
 rake clean    # Remove temporary files
 rake compile  # Compile all sources
 rake default  # Equivalent to 'rake build'
 rake run      # Run 'hello-world'

= Online

* 'Source code'[http://github.com/joeyates/rake-builder]
* Documentation[http://rdoc.info/projects/joeyates/rake-builder]
* Gem[http://rubygems.org/gems/rake-builder]

= Limitations

== File Modification Times

Rake's FileTask decides whether a file needs rebuilding by comparing on disk file
modification times (see the private method <em>out_of_date?</em>, which returns true if the
dependency was modified *after* the dependent).
Unfortunately, most modern file systems hold modification times in whole
seconds. If a dependency and a dependent were modificed during the same second,
<b>even if the dependency were modified later</b>, <em>out_of_date?</em> gives *false*
which is not the correct answer.

This problem is mostly felt in testing, where file modification times are temporarily
modified to test dependencies. Also, tests wait for second to complete after building.

=== File Modification Time Resolutions

* Ext3[http://en.wikipedia.org/wiki/Ext3] - resolution: 1s
* Ext4[http://en.wikipedia.org/wiki/Ext4] - resolution: 1 microsecond
* Hierarchical_File_System[http://en.wikipedia.org/wiki/Hierarchical_File_System] - resolution: 1s
* HFS_Plus[http://en.wikipedia.org/wiki/HFS_Plus] - resolution: 1s

== Source Files with the Same Name

Currently, object files from all source files are placed in the same directory.
So, if there are two source files with the same name, they will overwrite each other.

= Status

* Builds C and C++ projects using gcc

= Alternatives

* make
* CMake
* Boost.Build
* rakepp - another take on using rake for c++ projects

= TODO

* Objective-C/Objective-C++ builds
* pre-compiled headers
* parallel builds