bake 0.1.0

data/CONCEPTS

@@ -0,0 +1,2 @@
+= Concepts
+

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2007 Dylan Trotter
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

data/README

@@ -0,0 +1,38 @@
+= Bake
+
+Bake is a build automation utility somewhat akin to the Ruby tool Rake. Like Rake[http://rake.rubyforge.org/], Bake definition files (or <i>bakefiles</i>) are written in pure Ruby. The similarities between Rake and Bake pretty much end there, however. Bake generally takes a much higher level approach. Instead of defining tasks and specifying the commands that get executed by that task, you define high level products, such as C++ libraries or Java WAR files in your bakefiles. Thus bakefiles are simple, readable definitions of the final products of your project.
+
+== Download
+
+You can download the most recent version of Bake at here[http://rubyforge.org/frs/?group_id=3477]
+
+== Installation
+
+Currently, Bake only support Gem installs. Simply run:
+
+  % gem install bake
+
+If you don't like how Gems taste, it's probably not difficult to set up Bake from source. Download one of the source distributions and let me know how it works out :)
+
+== Further Reading
+
+Tutorial Introduction:: TUTORIAL[link:files/TUTORIAL.html]
+
+Concepts:: CONCEPTS[link:files/CONCEPTS.html]
+
+Reference:: REFERENCE[link:files/REFERENCE.html]
+
+== History
+
+Bake took inspiration from the many great build tools that exist out there. In particular, the idea of using Ruby as a domain specific language for build systems was pioneered Jim Weirich in his Make-like utility, Rake. After working with Rake for some time, however, I found that it was difficult to maintain large projects effectively due to the fact that Rake is quite low-level.
+
+Soon after I abandoned Rake, I found another great Ruby-based system called Rant created by Stefan Lang. Rant was slightly better and it had many great ideas for how a Ruby-based build system should work such as improved error messages, good support for larger multi-file projects, etc. I tried for a time to write Bake as extensions to Rant since I felt it a good starting point. In the end, however, it had similar limitations to Rake and I abandoned further work on Rant.
+
+On the other end of the spectrum there's {Boost.Build}[http://www.boost.org/tools/build/jam_src/index.html] which is the build system used for the {Boost C++ Libraries}[http://boost.org/]. Boost.Build does have a reasonably good project-based approach, however, the syntax is abominable. It's based on {Perforce Jam}[http://www.perforce.com/jam/jam.html] which is quite possibly the most hideous build system ever conceived. Ugly doesn't begin to describe the syntax, nor incomprehensible the so-called Jamfiles.
+
+The panacea is Bake. I think it satisfies my rather loose requirements: pretty, simple for simple projects, powerful for large projects and fast. The items in this list are at various stages in their evolution, but I think it solves my build problems better than any of the others I listed above.
+
+== License
+
+:include: MIT-LICENSE
+

data/REFERENCE

@@ -0,0 +1,2 @@
+= Reference
+

data/TUTORIAL

@@ -0,0 +1,133 @@
+= Tutorial Introduction
+
+== A C++ Executable
+
+=== Bakefiles and Targets
+
+Once you've installed Bake, you should be able to execute it by running the <tt>bake</tt> command. This will cause Bake to load a file called <i>root.bake</i> in the current working directory or some ancestor directory of the current directory. This <b>bakefile</b> defines the contents of the project including any settings required to properly make the build targets. Let's see the contents of <i>root.bake</i> for a simple C++ project consisting of a single source file, <i>main.cpp</i>, which gets compiled into an executable called <i>test</i>:
+
+  # root.bake
+  exe 'test' do
+      src 'main.cpp'
+  end
+
+The <tt>exe</tt> command specifies that we'd like to create an executable <b>target</b>. A target is any product that gets created as a result of the build process. There are many kinds of targets, such as <tt>lib</tt>s, or C++ libraries, etc. To make this example a little more concrete, let's also create <i>main.cpp</i>:
+
+  // main.cpp
+  #include <iostream>
+  int main()
+  {
+      std::cout << "hello bake" << std::endl;
+      return 0;
+  }
+
+Both these files should be in the same directory, call it <i>test/</i>. The layout is as follows:
+
+  test/
+    root.bake
+    main.cpp
+
+If you run <tt>bake</tt> from the <i>test/</i> directory you should see output resembling "<tt>root.bake:1: undefined symbol 'exe'</tt>". The reason for this is that we have not specified what <b>tooset</b> we will be using to build C++ targets. Bake supports a number of C++ toolsets (consult the Reference for full details) and each toolset should treat our test project identically, so which toolset you use should not matter. For the purposes of this example, I'll use the <tt>gcc</tt> toolset.
+
+=== The <tt>using</tt> Directive
+
+Generally, it is a good idea to keep your project definitions separate from which toolset you're using since your choice of toolset is conceptually distinct from your project layout. This is especially true from cross-platform projects. For this reason, in this project we'll keep this information in a separate bakefile called <i>config.bake</i> which will also live in the <i>test/</i> directory:
+
+  # config.bake
+  using 'cpp.gcc'
+
+The <tt>using</tt> directive above tells Bake that when building C++ targets, it should use the <tt>gcc</tt> toolset. If you now run the <tt>bake</tt> command, and as long as your toolset is properly configured, you should get an executable file called <i>test</i> (or <i>test.exe</i> on Windows platforms) in the <i>test/</i> directory.
+
+=== Properties
+
+Unfortunately, the <i>test</i> executable will probably be accompanied by a number of by-products of the build procedure and so our <i>test/</i> directory is now getting cluttered. It is common to keep products of the build in a separate output directory so that they don't get mixed up with our source files. The output directory is just one of a number of options supported by <tt>exe</tt> targets. To specify an output directory we set the <tt>:outdir</tt> <b>property</b> on <tt>test</tt>. Properties are just key/value pairs that are used by the toolset to output the desired product. The simplest way to set a property is to use the <tt>opt</tt> command on the <tt>test</tt> target, like this:
+
+  # root.bake
+
+  exe 'test' do
+      opt :outdir => 'bin'
+
+      src 'main.cpp'
+
+  end
+
+Note that property names are <b>symbols</b> preceded by a colon (:) whereas, in this case, the property value is a <b>string</b>. Property values can be any of a number of different types such as strings, booleans, numbers, etc.
+
+Delete all the product files generated by the last build so that your directory structure looks like:
+
+  test/
+    config.bake
+
+    root.bake
+
+    main.cpp
+
+Now run Bake again. Note that a new directory called <i>bin/</i> has been created and that all the products of the build have been placed inside. C++ executable targets have a number of other properties that affect different aspects of the build. For example, to turn off multithreading for a single threaded application, you would specify "<tt>opt :multithreaded? => false</tt>". Note that we've used a boolean value type instead of a string. The type is important as a value of <tt>'false'</tt> would result in the opposite behavior we would expect (this is because strings always evaluate to true when examined in a boolean context). For a full list of target properties and their types, see the Reference.
+
+== A More Complicated Example
+
+=== Multiple Targets, One Bakefile
+
+So far we've seen Bake build a simple C++ executable, and it did the job pretty well. Bake's strengths, however, are only seen when we have more complicated projects to test it with. Bake is designed with large projects in mind and it makes managing these projects a snap.
+
+To see how Bake handles multi-directory projects, let's create a project composed of a C++ library and an executable that depends on the library. Let's try the following directory structure:
+
+  test2/
+    test_lib/
+      source1.cpp
+      source2.cpp
+    test_exe/
+      source1.cpp
+
+As a first try at managing this project, let's create a <i>root.bake</i> in the <i>test2</i> directory that contains the definitions for both <tt>test_lib</tt> and <tt>test_exe</tt>:
+
+  # root.bake
+  lib 'test_lib' do
+      src 'test_lib/source1.cpp', 'test_lib/source2.cpp'
+  end
+
+  exe 'test_exe' do
+      dep 'test_lib'
+      src 'test_exe/source1.cpp'
+  end
+
+Here we have created a <tt>lib</tt> target called <tt>test_lib</tt> containing two source files, and an executable file that depends on the library and another source file. This is pretty simple and will probably seem to work, however, there's an insidious bug waiting to cause trouble when you least expect it. Note that there are two files called <i>source1.cpp</i>. In each case, a C++ object file called <i>source1.o</i> (or <i>source1.obj</i> on Windows) will be created in the <i>test2/</i> directory, the object file from <tt>test_exe</tt> will overwrite the object file from <tt>test_lib</tt>. This will not immediately cause a problem, since the library object file was added to the library before the executable object file was created but it will almost certainly cause problems later on.
+
+=== More About Properties
+
+The easiest way to avoid conflicts like these is to set the <tt>:outdir</tt> property differently on each target so that the object files will live in different directories. To do this, however, we're going to take a shortcut and only set the output directory once:
+
+  # root.bake
+  opt :outdir => 'bin/${name}'
+
+
+  lib 'test_lib' do
+
+      src 'test_lib/source1.cpp', 'test_lib/source2.cpp'
+
+  end
+
+
+
+  exe 'test_exe' do
+
+      dep 'test_lib'
+
+      src 'test_exe/source1.cpp'
+
+  end
+
+If you run Bake now, the outputs from <tt>test_lib</tt> will end up in <i>test2/bin/test_lib/</i> and the outputs from <tt>test_exe</tt> will end up in <i>test2/bin/test_exe</i>. If you're confused, don't worry, we've taken two steps forward here. Not only is the value of the <tt>:outdir</tt> property not explicitly set on either target, but it's out in no-man's land, what gives? Furthermore, what's up with the <tt>${projname}</tt> business?
+
+The answer to the first question is related to an important fact about targets: they are tree-like. Every target (except the root target, which we'll get into later) has a single parent target, and many targets have child targets. So what target is the parent of <tt>test_lib</tt> and <tt>test_exe</tt>? An implicit <b>project</b> target that is created when <i>root.bake</i> is processed. Therefore, the <tt>opt</tt> command is being executed on the implicit project target and so <tt>:outdir</tt> is set for the project.
+
+Furthermore, properties are inherited. So if a property is explicitly defined for a parent target but is not explicitly defined for the child, then the property for the child is the same as that for the parent. Properties can be overridden by explicitly using the <tt>opt</tt> command on the child, in which case the parent's property value will be ignored.
+
+So in the example above, the <tt>:outdir</tt> property is inherited by the <tt>test_lib</tt> and <tt>test_exe</tt> targets as <tt>'bin/${projname}'</tt>.
+
+The answer to the second question is even simpler. String property values are dynamic. Any <tt>${...}</tt> tokens found in the string will be evaluated when the property is queried. In addition, it will be queried in the context of the target being queried, not the target where the property was originally defined. So when the GCC toolset builds <tt>test_lib</tt> and <tt>test_exe</tt>, it will query the <tt>:outdir</tt> property on each target and it will evaluate to <tt>'bin/test_lib'</tt> and <tt>'bin/test_exe'</tt> respectively.
+
+=== Modular Bakefiles
+
+TODO
+

data/bin/bake

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+
+begin
+  require 'rubygems'
+rescue LoadError
+  # no rubygems to load, so we fail silently
+end
+
+require 'bake'
+

data/lib/bake.rb

@@ -0,0 +1,155 @@
+require 'bake/scheme_loader'
+require 'bake/context'
+require 'bake/project_loader'
+require 'bake_version'
+require 'optparse'
+
+module Bake
+    class CommandLineParseError < RuntimeError
+    end
+
+    class ProgramInfoRequested < RuntimeError
+    end
+
+    class App
+        @@instance = nil
+
+        def self.instance
+            return @@instance
+        end
+
+        def initialize
+            raise "App instance already created" if @@instance
+            @@instance = self
+            @scheme_loader = SchemeLoader.new
+            @context = Context.new(@scheme_loader)
+        end
+
+        def run(*args)
+            options, args = parse_command_line(*args)
+            props, targets = process_excess_args(*args)
+            props[:platform] = determine_platform
+
+            @project_loader = ProjectLoader.new(@context, Dir.pwd, props)
+            targets = targets.collect do |name|
+                target = @project_loader.invok_project.find(name)
+                if !target
+                    raise CommandLineParseError,
+                        "could not find target '#{name}'"
+                end
+                target
+            end
+
+            method = options[:clean] ? :clean : :build
+            if targets.empty?
+                send(method, @project_loader.invok_project)
+            else
+                targets.each { |target| send(method, target) }
+            end
+        end
+
+    private
+        def build(target)
+            return if target[:built?]
+            target.deps.each { |dep| build(dep) }
+            target.children.each { |child| build(child) }
+            toolset = toolset(target)
+            Dir.chdir(target[:cwdir]) do
+                toolset.build(target) if toolset
+            end
+            target.opt :built? => true
+        end
+
+        def clean(target)
+            target.children.each do |child|
+                clean(child)
+            end
+            toolset = toolset(target)
+            toolset.clean(target) if toolset
+        end
+
+        def toolset(target)
+            if !target.class.const_defined?(:SCHEME)
+                raise "no toolset for target '#{target.class.name}'"
+            end
+            scheme = target.class.const_get(:SCHEME)
+            return scheme.toolset if scheme
+            return nil
+        end
+
+        def determine_platform
+            if RUBY_PLATFORM =~ /darwin/i
+                return 'osx'
+            elsif RUBY_PLATFORM =~ /linux/i
+                return 'linux'
+            elsif RUBY_PLATFORM =~ /mswin/i
+                return 'win32'
+            end
+            return 'other'
+        end
+
+        def parse_command_line(*args)
+            options = {}
+            opts = OptionParser.new do |opts|
+                opts.banner = "Usage:  bake [options] [target ...]"
+                opts.on('--clean', 'Clean the given targets') do |clean|
+                    options[:clean] = clean
+                end
+                opts.on_tail('-h', '--help', 'Show usage') do
+                    raise ProgramInfoRequested, opts
+                end
+                opts.on_tail('--version', 'Show version information') do
+                    raise ProgramInfoRequested, 'bake ' + VERSION_STRING
+                end
+            end
+
+            begin
+                opts.parse!(args)
+            rescue ProgramInfoRequested
+                raise
+            rescue Exception => e
+                raise CommandLineParseError,
+                    "#{e.message} (use --help for usage information)"
+            end
+            return options, args
+        end
+
+        def process_excess_args(*args)
+            props = {}
+            targets = []
+            args.each do |name|
+                if name.count('=') == 1
+                    key, val = name.split('=')
+                    props[key.to_sym] = val
+                else
+                    targets << name
+                end
+            end
+            return props, targets
+        end
+    end
+end
+
+def parse_backtrace(backtrace)
+    if backtrace.find { |entry| entry =~ /^.*?(config|root|sub)\.bake:\d+/ }
+        return $&
+    end
+    return 'internal error'
+end
+
+exit_code = 1
+begin
+    app = Bake::App.new
+    app.run(*ARGV)
+    exit_code = 0
+rescue Bake::ProgramInfoRequested => e
+    puts e.message
+    exit_code = 0
+rescue Bake::CommandLineParseError => e
+    puts e.message
+rescue Exception => e
+    puts parse_backtrace(e.backtrace) + ': ' + e.message
+end
+
+exit(exit_code)
+

data/lib/bake/common_scheme.rb

@@ -0,0 +1,42 @@
+require 'bake/toolset'
+require 'bake/target'
+
+module Common
+    class Default < Bake::Toolset
+        def build(target)
+            if target.is_a?(Directory)
+                make_dir(target)
+            elsif target.is_a?(FileClone)
+                copy(target)
+            else
+                raise "unrecognized target of class '#{target.class}'"
+            end
+        end
+
+        def clean(target)
+        end
+
+    private
+        def make_dir(target)
+            puts "building directory '#{target.name}'"
+        end
+
+        def copy(target)
+            puts "building copy '#{target.name}'"
+        end
+    end
+
+    class Directory < Bake::Target
+        ACCESSORS = :dir
+
+        def initialize(name, parent)
+            super(parent)
+            @name = name
+        end
+    end
+
+    class FileClone < Bake::Target
+        ACCESSORS = [ :copy, :clone ]
+    end
+end
+

data/lib/bake/configuration.rb

@@ -0,0 +1,154 @@
+module Bake
+    class PropertyNotFoundException < RuntimeError
+    end
+
+    class TemplateEvaluationException < RuntimeError
+    end
+
+    module Configuration
+        def has_prop?(key)
+            cfg = self
+            while cfg
+                return true if cfg.has_prop_impl(key)
+                cfg = cfg.parent
+            end
+            return false
+        end
+
+        def [](key)
+            return get(key)
+        end
+
+        def get(key)
+            if multival(key)
+                cfg = self
+                opts = []
+                while cfg
+                    vals = cfg.options[key]
+                    opts.concat(vals.collect { |val| value_of(val) }) if vals
+                    cfg = cfg.parent
+                end
+                return opts
+            else
+                cfg = self
+                opt = default = nil
+                found_opt = found_default = false
+                while cfg
+                    if cfg.requirements.has_key?(key)
+                        return value_of(cfg.requirements[key])
+                    end
+                    if !found_opt
+                        if cfg.options.has_key?(key)
+                            opt = cfg.options[key]
+                            found_opt = true
+                        elsif !found_default && cfg.defaults.has_key?(key)
+                            default = cfg.defaults[key]
+                            found_default = true
+                        end
+                    end
+                    cfg = cfg.parent
+                end
+                if found_opt
+                    return value_of(opt)
+                elsif found_default
+                    return value_of(default)
+                end
+                raise PropertyNotFoundException, "no such property '#{key}'"
+            end
+        end
+
+        def is?(prop)
+            key, val = key_val(prop)
+            raise 'no multivalue comparisons' if multival(key)
+            begin
+                return get(key) == val
+            rescue PropertyNotFoundException
+                return false
+            end
+        end
+
+        def opt(prop)
+            key, val = key_val(prop)
+            if multival(key)
+                vals = options[key] ||= []
+                if val.respond_to?(:to_ary)
+                    vals.concat(val)
+                else
+                    vals << val
+                end
+            else
+                options[key] = val
+            end
+        end
+
+        def req(prop)
+            key, val = key_val(prop)
+            raise 'no multivalue requirements' if multival(key)
+            cfg = self
+            while cfg
+                req = cfg.requirements[key]
+                if req
+                    raise 'conflicting requirements' if req != val
+                    break
+                end
+                cfg = cfg.parent
+            end
+            requirements[key] = val
+        end
+
+        def default(prop)
+            key, val = key_val(prop)
+            raise 'no multivalue defaults' if multival(key)
+            defaults[key] = val
+        end
+
+    protected
+        def options
+            return @options ||= {}
+        end
+
+        def requirements
+            return @requirements ||= {}
+        end
+
+        def defaults
+            return @defaults ||= {}
+        end
+
+        def has_prop_impl(key)
+            return requirements.has_key?(key) ||
+                options.has_key?(key) ||
+                defaults.has_key?(key)
+        end
+
+        def key_val(prop)
+            raise 'invalid args' if !prop.respond_to?(:to_hash)
+            prop = prop.to_hash
+            raise 'bad' if prop.size != 1
+            key = prop.keys[0]
+            return [ key, prop[key] ]
+        end
+
+        def multival(key)
+            return key.to_s[-1, 1] == 's'
+        end
+
+        def value_of(val)
+            if val.instance_of?(String)
+                return val.gsub(/\$\{(.*?)\}/) do
+                    name = $1
+                    if has_prop?(name.to_sym)
+                        get(name.to_sym)
+                    elsif ENV.has_key?(name)
+                        ENV[name]
+                    else
+                        raise TemplateEvaluationException,
+                            "no property or environment variable '#{name}'"
+                    end
+                end
+            end
+            return val
+        end
+    end
+end
+