= rake-builder - Rake for C, C++, Objective-C and Objective-C++ Projects

rake-builder builds C, C++, Objective-C and Objective-C++
projects.

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-nnn
 $ cd examples

== Project Configuration

In order to build on a specific computer, you will need
to indicate information like non-standard
include paths.

Rake::Builder collects all such information in one file:
'.rake-builder'

This file should be created in the same
directory as the Rakefile.

The file should be a YAML structure, and must include a version.

Currently, the following can be configured:
* extra include paths: :include_paths

=== Example '.rake-builder'

 ---
 :rake_builder:
   :config_file:
     :version: "1.0"
 :include_paths:
 - /opt/local/include
 - /usr/include/c++/4.2.1

= Default Tasks

* compile
* build
* run - executables only
* install
* clean

= Installing Headers

If you install a static library, your headers will also be installed.
Ensure that you use file globs, e.g. './include/**/*.h',
as these will ensure that your headers are installed in the correct subdirectories.

= Online

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

= Dependencies

Task dependencies must ensure that out of date files are recreated as needed.

http://github.com/downloads/joeyates/rake-builder/RakeBuilderDependencyStructure.png

= 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> returns *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, C++ and Objective-C projects using GCC[http://gcc.gnu.org/].

= Alternatives

* GNU build system, a.k.a. Autotools: autoconf, configure, make, etc.
* Boost.Build
* CMake
* rakepp - another customisation of Rake for C++ projects
* Scons
* waf[http://code.google.com/p/waf/]