rscons 0.0.14 → 0.1.0

data/.gitignore

@@ -15,4 +15,4 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
-build_tests_run
+build_test_run

data/README.md

@@ -2,11 +2,13 @@
 
 Software construction library inspired by SCons and implemented in Ruby
 
+[![Gem Version](https://badge.fury.io/rb/rscons.png)](http://badge.fury.io/rb/rscons)
+
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'rscons'
+    gem "rscons"
 
 And then execute:
 
@@ -18,20 +20,135 @@ Or install it yourself as:
 
 ## Usage
 
-    RScons::Environment.new do |env|
-      env.Program('program', Dir['*.c'])
-    end
+Rscons is a Ruby library.
+It can be called from a standalone Ruby script or it can be used with rake and
+called from your Rakefile.
+
+### Example: Building a C Program
+
+```ruby
+RScons::Environment.new do |env|
+  env["CFLAGS"] << "-Wall"
+  env.Program("program", Dir["**/*.c"])
+end
+```
+
+### Example: Building a D Program
+
+```ruby
+RScons::Environment.new do |env|
+  env["DFLAGS"] << "-Wall"
+  env.Program("program", Dir["**/*.d"])
+end
+```
+
+### Example: Cloning an Environment
 
-    main_env = RScons::Environment.new do |env|
-      env.build_dir('src', 'build/main')
-      env.Program('program', Dir['src/**/*.cc'])
+```ruby
+main_env = RScons::Environment.new do |env|
+  # Store object files from sources under "src" in "build/main"
+  env.build_dir("src", "build/main")
+  env["CFLAGS"] = ["-DSOME_DEFINE", "-O3"]
+  env["LIBS"] = ["SDL"]
+  env.Program("program", Dir["src/**/*.cc"])
+end
+
+debug_env = main_env.clone do |env|
+  # Store object files from sources under "src" in "build/debug"
+  env.build_dir("src", "build/debug")
+  env["CFLAGS"] -= ["-O3"]
+  env["CFLAGS"] += ["-g", "-O0"]
+  env.Program("program-debug", Dir["src/**/*.cc"])
+end
+```
+
+### Example: Custom Builder
+
+```ruby
+class GenerateFoo < Rscons::Builder
+  def run(target, sources, cache, env, vars)
+    File.open(target, "w") do |fh|
+      fh.puts <<EOF
+#define GENERATED 42
+EOF
     end
+  end
+end
+
+Rscons::Environment.new do |env|
+  env.GenerateFoo("foo.h", [])
+  env.Program("a.out", Dir["*.c"])
+end
+```
 
-    debug_env = main_env.clone do |env|
-      env.build_dir('src', 'build/debug')
-      env['CFLAGS'] = ['-g', '-O0']
-      env.Program('program-debug', Dir['src/**/*.cc'])
+### Example: Using different compilation flags for some sources
+
+```ruby
+Rscons::Environment.new do |env|
+  env["CFLAGS"] = ["-O3", "-Wall", "-DDEFINE"]
+  env.add_build_hook do |build_op|
+    if build_op[:target] =~ %r{build/third-party}
+      build_op[:vars]["CFLAGS"] -= ["-Wall"]
     end
+  end
+  env.build_dir("src", "build")
+  env.Program("program", Dir["**/*.cc"])
+end
+```
+
+### Example: Creating a static library
+
+```ruby
+Rscons::Environment.new do |env|
+  env.Library("mylib.a", Dir["src/**/*.c"])
+end
+```
+
+## Details
+
+### Default Builders
+
+Rscons ships with a number of default builders:
+
+* Library, which collects object files into a static library archive file
+* Object, which compiles source files to produce an object file
+* Program, which links object files to produce an executable
+
+If you want to create an Environment that does not contain any (or select)
+builders, you can use the `exclude_builders` key to the Environment constructor.
+
+### Managing Environments
+
+An Rscons::Environment consists of:
+
+* a collection of construction variables
+* a collection of builders
+* a mapping of build directories
+* a collection of targets to build
+* a collection of build hooks
+
+When cloning an environment, the construction variables, builders, and build
+directories are cloned, but the new environment does not inherit any of the
+targets or build hooks from the source environment.
+
+Cloned environments contain "deep copies" of construction variables.
+For example, in:
+
+```ruby
+base_env = Rscons::Environment.new
+base_env["CPPPATH"] = ["one", "two"]
+cloned_env = base_env.clone
+cloned_env["CPPPATH"] << "three"
+```
+
+`base_env["CPPPATH"]` will not include "three".
+
+### Construction Variables
+
+The default construction variables that Rscons uses are named using uppercase
+strings.
+Rscons options are lowercase symbols.
+Lowercase strings are reserved as user-defined construction variables.
 
 ## Contributing
 

data/{Rakefile → Rakefile.rb}

@@ -7,11 +7,8 @@ end
 
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
-require "rake/clean"
 require "yard"
 
-CLEAN.include 'build_tests_run'
-
 RSpec::Core::RakeTask.new(:spec)
 
 YARD::Rake::YardocTask.new do |yard|
@@ -19,3 +16,11 @@ YARD::Rake::YardocTask.new do |yard|
 end
 
 task :default => :spec
+
+task :clean do
+  FileUtils.rm_rf(["build_test_run", "doc", "coverage"])
+end
+
+task :clobber => :clean do
+  FileUtils.rm_rf(["pkg"])
+end

data/build_tests/d/main.d

@@ -0,0 +1,6 @@
+import std.stdio;
+
+void main()
+{
+    writeln("Hello from D!");
+}

data/lib/rscons/builders/library.rb

@@ -8,7 +8,7 @@ module Rscons
         'AR' => 'ar',
         'LIBSUFFIX' => '.a',
         'ARFLAGS' => [],
-        'ARCOM' => ['$AR', 'rcs', '$ARFLAGS', '$_TARGET', '$_SOURCES']
+        'ARCMD' => ['${AR}', 'rcs', '${ARFLAGS}', '${_TARGET}', '${_SOURCES}']
       }
     end
 
@@ -20,7 +20,7 @@ module Rscons
           '_TARGET' => target,
           '_SOURCES' => objects,
         })
-        command = env.build_command(env['ARCOM'], vars)
+        command = env.build_command(env['ARCMD'], vars)
         standard_build("AR #{target}", target, command, objects, env, cache)
       end
     end

data/lib/rscons/builders/object.rb

@@ -2,17 +2,24 @@ module Rscons
   # A default RScons builder which knows how to produce an object file from
   # various types of source files.
   class Object < Builder
+    KNOWN_SUFFIXES = {
+      "AS" => "ASSUFFIX",
+      "CC" => "CSUFFIX",
+      "CXX" => "CXXSUFFIX",
+      "DC" => "DSUFFIX",
+    }
+
     def default_variables(env)
       {
         'OBJSUFFIX' => '.o',
 
-        'AS' => '$CC',
+        'AS' => '${CC}',
         'ASFLAGS' => [],
         'ASSUFFIX' => '.S',
-        'ASPPPATH' => '$CPPPATH',
-        'ASPPFLAGS' => '$CPPFLAGS',
-        'ASDEPGEN' => ['-MMD', '-MF', '$_DEPFILE'],
-        'ASCOM' => ['$AS', '-c', '-o', '$_TARGET', '$ASDEPGEN', '-I$[ASPPPATH]', '$ASPPFLAGS', '$ASFLAGS', '$_SOURCES'],
+        'ASPPPATH' => '${CPPPATH}',
+        'ASPPFLAGS' => '${CPPFLAGS}',
+        'ASDEPGEN' => ['-MMD', '-MF', '${_DEPFILE}'],
+        'ASCMD' => ['${AS}', '-c', '-o', '${_TARGET}', '${ASDEPGEN}', '-I${ASPPPATH}', '${ASPPFLAGS}', '${ASFLAGS}', '${_SOURCES}'],
 
         'CPPFLAGS' => [],
         'CPPPATH' => [],
@@ -20,29 +27,27 @@ module Rscons
         'CC' => 'gcc',
         'CFLAGS' => [],
         'CSUFFIX' => '.c',
-        'CCDEPGEN' => ['-MMD', '-MF', '$_DEPFILE'],
-        'CCCOM' => ['$CC', '-c', '-o', '$_TARGET', '$CCDEPGEN', '-I$[CPPPATH]', '$CPPFLAGS', '$CFLAGS', '$_SOURCES'],
+        'CCDEPGEN' => ['-MMD', '-MF', '${_DEPFILE}'],
+        'CCCMD' => ['${CC}', '-c', '-o', '${_TARGET}', '${CCDEPGEN}', '-I${CPPPATH}', '${CPPFLAGS}', '${CFLAGS}', '${_SOURCES}'],
 
         'CXX' => 'g++',
         'CXXFLAGS' => [],
         'CXXSUFFIX' => '.cc',
-        'CXXDEPGEN' => ['-MMD', '-MF', '$_DEPFILE'],
-        'CXXCOM' =>['$CXX', '-c', '-o', '$_TARGET', '$CXXDEPGEN', '-I$[CPPPATH]', '$CPPFLAGS', '$CXXFLAGS', '$_SOURCES'],
+        'CXXDEPGEN' => ['-MMD', '-MF', '${_DEPFILE}'],
+        'CXXCMD' =>['${CXX}', '-c', '-o', '${_TARGET}', '${CXXDEPGEN}', '-I${CPPPATH}', '${CPPFLAGS}', '${CXXFLAGS}', '${_SOURCES}'],
 
         'DC' => 'gdc',
         'DFLAGS' => [],
         'DSUFFIX' => '.d',
         'D_IMPORT_PATH' => [],
-        'DCCOM' => ['$DC', '-c', '-o', '$_TARGET', '-I$[D_IMPORT_PATH]', '$DFLAGS', '$_SOURCES'],
+        'DCCMD' => ['${DC}', '-c', '-o', '${_TARGET}', '-I${D_IMPORT_PATH}', '${DFLAGS}', '${_SOURCES}'],
       }
     end
 
     def produces?(target, source, env)
-      target.has_suffix?(env['OBJSUFFIX']) and (
-        source.has_suffix?(env['ASSUFFIX']) or
-        source.has_suffix?(env['CSUFFIX']) or
-        source.has_suffix?(env['CXXSUFFIX']) or
-        source.has_suffix?(env['DSUFFIX']))
+      target.has_suffix?(env['OBJSUFFIX']) and KNOWN_SUFFIXES.find do |compiler, suffix_var|
+        source.has_suffix?(env[suffix_var])
+      end
     end
 
     def run(target, sources, cache, env, vars = {})
@@ -51,25 +56,19 @@ module Rscons
         '_SOURCES' => sources,
         '_DEPFILE' => target.set_suffix('.mf'),
       })
-      com_prefix = if sources.first.has_suffix?(env['ASSUFFIX'])
-                     'AS'
-                   elsif sources.first.has_suffix?(env['CSUFFIX'])
-                     'CC'
-                   elsif sources.first.has_suffix?(env['CXXSUFFIX'])
-                     'CXX'
-                   elsif sources.first.has_suffix?(env['DSUFFIX'])
-                     'DC'
-                   else
-                     raise "Error: unknown input file type: #{sources.first.inspect}"
-                   end
-      command = env.build_command(env["#{com_prefix}COM"], vars)
+      com_prefix = KNOWN_SUFFIXES.find do |compiler, suffix_var|
+        sources.first.has_suffix?(env[suffix_var])
+      end.tap do |v|
+        v.nil? and raise "Error: unknown input file type: #{sources.first.inspect}"
+      end.first
+      command = env.build_command(env["#{com_prefix}CMD"], vars)
       unless cache.up_to_date?(target, command, sources)
         cache.mkdir_p(File.dirname(target))
         FileUtils.rm_f(target)
         return false unless env.execute("#{com_prefix} #{target}", command)
         deps = sources
         if File.exists?(vars['_DEPFILE'])
-          deps += env.parse_makefile_deps(vars['_DEPFILE'], target)
+          deps += Environment.parse_makefile_deps(vars['_DEPFILE'], target)
           FileUtils.rm_f(vars['_DEPFILE'])
         end
         cache.register_build(target, command, deps.uniq)

data/lib/rscons/builders/program.rb

@@ -10,31 +10,29 @@ module Rscons
         'LDFLAGS' => [],
         'LIBPATH' => [],
         'LIBS' => [],
-        'LDCOM' => ['$LD', '-o', '$_TARGET', '$LDFLAGS', '$_SOURCES', '-L$[LIBPATH]', '-l$[LIBS]']
+        'LDCMD' => ['${LD}', '-o', '${_TARGET}', '${LDFLAGS}', '${_SOURCES}', '-L${LIBPATH}', '-l${LIBS}']
       }
     end
 
     def run(target, sources, cache, env, vars = {})
       # build sources to linkable objects
       objects = env.build_sources(sources, [env['OBJSUFFIX'], env['LIBSUFFIX']].flatten, cache, vars)
-      if objects
-        ld = if env["LD"]
-               env["LD"]
-             elsif sources.find {|s| s.has_suffix?(env["DSUFFIX"])}
-               env["DC"]
-             elsif sources.find {|s| s.has_suffix?(env["CXXSUFFIX"])}
-               env["CXX"]
-             else
-               env["CC"]
-             end
-        vars = vars.merge({
-          '_TARGET' => target,
-          '_SOURCES' => objects,
-          'LD' => ld,
-        })
-        command = env.build_command(env['LDCOM'], vars)
-        standard_build("LD #{target}", target, command, objects, env, cache)
-      end
+      ld = if env["LD"]
+             env["LD"]
+           elsif sources.find {|s| s.has_suffix?(env["DSUFFIX"])}
+             env["DC"]
+           elsif sources.find {|s| s.has_suffix?(env["CXXSUFFIX"])}
+             env["CXX"]
+           else
+             env["CC"]
+           end
+      vars = vars.merge({
+        '_TARGET' => target,
+        '_SOURCES' => objects,
+        'LD' => ld,
+      })
+      command = env.build_command(env['LDCMD'], vars)
+      standard_build("LD #{target}", target, command, objects, env, cache)
     end
   end
 end

data/lib/rscons/cache.rb

@@ -67,12 +67,12 @@ module Rscons
       end
       @cache[:targets] ||= {}
       @cache[:directories] ||= {}
-      @cache[:version] ||= VERSION
       @lookup_checksums = {}
     end
 
     # Write the cache to disk to be loaded next time.
     def write
+      @cache[:version] = VERSION
       File.open(CACHE_FILE, 'w') do |fh|
         fh.puts(YAML.dump(@cache))
       end
@@ -119,9 +119,11 @@ module Rscons
       end
 
       # all cached dependencies must have their checksums match
-      @cache[:targets][target][:deps].map do |dep_cache|
-        dep_cache[:checksum] == lookup_checksum(dep_cache[:fname])
-      end.all?
+      @cache[:targets][target][:deps].each do |dep_cache|
+        return false unless dep_cache[:checksum] == lookup_checksum(dep_cache[:fname])
+      end
+
+      true
     end
 
     # Store cache information about a target built by a builder
@@ -150,13 +152,11 @@ module Rscons
     # removal upon a "clean" operation.
     def mkdir_p(path)
       parts = path.split(/[\\\/]/)
-      (0..parts.size).each do |i|
+      (0..parts.size-1).each do |i|
         subpath = File.join(*parts[0, i + 1]).encode(__ENCODING__)
         unless File.exists?(subpath)
           FileUtils.mkdir(subpath)
-          unless @cache[:directories].include?(subpath)
-            @cache[:directories][subpath] = true
-          end
+          @cache[:directories][subpath] = true
         end
       end
     end
@@ -179,7 +179,7 @@ module Rscons
     # Calculate and return a file's checksum
     # @param file [String] The file name.
     def calculate_checksum(file)
-      @lookup_checksums[file] = Digest::MD5.hexdigest(File.read(file, {mode: 'rb'})).encode(__ENCODING__) rescue ''
+      @lookup_checksums[file] = Digest::MD5.hexdigest(File.read(file, mode: 'rb')).encode(__ENCODING__) rescue ''
     end
   end
 end

data/lib/rscons/environment.rb

@@ -6,7 +6,7 @@ module Rscons
   # contains a collection of construction variables, options, builders, and
   # rules for building targets.
   class Environment
-    # [Hash] of {"builder_name" => builder_object} pairs.
+    # Hash of +{"builder_name" => builder_object}+ pairs.
     attr_reader :builders
 
     # Create an Environment object.
@@ -22,7 +22,7 @@ module Rscons
       @targets = {}
       @builders = {}
       @build_dirs = []
-      @tweakers = []
+      @build_hooks = []
       @varset[:exclude_builders] ||= []
       unless @varset[:exclude_builders] == :all
         exclude_builders = Set.new(@varset[:exclude_builders] || [])
@@ -32,10 +32,7 @@ module Rscons
           end
         end
       end
-      (@varset[:builders] || []).each do |builder|
-        add_builder(builder)
-      end
-      @varset[:echo] ||= :command
+      @varset[:echo] ||= :short
 
       if block_given?
         yield self
@@ -46,7 +43,7 @@ module Rscons
     # Make a copy of the Environment object.
     # The cloned environment will contain a copy of all environment options,
     # construction variables, builders, and build directories. It will not
-    # contain a copy of the targets or tweakers.
+    # contain a copy of the targets or build hooks.
     # If a block is given, the Environment object is yielded to the block and
     # when the block returns, the {#process} method is automatically called.
     def clone(variables = {})
@@ -75,9 +72,9 @@ module Rscons
       end
     end
 
-    # Add a tweaker block to the Environment.
-    def add_tweaker(&block)
-      @tweakers << block
+    # Add a build hook to the Environment.
+    def add_build_hook(&block)
+      @build_hooks << block
     end
 
     # Specify a build directory for this Environment.
@@ -89,8 +86,6 @@ module Rscons
 
     # Return the file name to be built from source_fname with suffix suffix.
     # This method takes into account the Environment's build directories.
-    # It also creates any parent directories needed to be able to open and
-    # write to the output file.
     def get_build_fname(source_fname, suffix)
       build_fname = source_fname.set_suffix(suffix).gsub('\\', '/')
       @build_dirs.each do |src_dir, obj_dir|
@@ -122,41 +117,33 @@ module Rscons
       @varset.send(:append, *args)
     end
 
-    # Return a list of target file names
-    def targets
-      @targets.keys
-    end
-
-    # Return a list of sources needed to build target target.
-    def target_sources(target)
-      @targets[target][:source] rescue nil
-    end
-
     # Build all target specified in the Environment.
     # When a block is passed to Environment.new, this method is automatically
     # called after the block returns.
     def process
       cache = Cache.new
-      targets_processed = Set.new
+      targets_processed = {}
       process_target = proc do |target|
-        if @targets[target][:source].map do |src|
-          targets_processed.include?(src) or not @targets.include?(src) or process_target.call(src)
-        end.all?
-          run_builder(@targets[target][:builder],
-                      target,
-                      @targets[target][:source],
-                      cache,
-                      @targets[target][:vars] || {})
-        else
-          false
+        targets_processed[target] ||= begin
+          @targets[target][:source].each do |src|
+            if @targets.include?(src) and not targets_processed.include?(src)
+              process_target.call(src)
+            end
+          end
+          result = run_builder(@targets[target][:builder],
+                               target,
+                               @targets[target][:source],
+                               cache,
+                               @targets[target][:vars] || {})
+          unless result
+            cache.write
+            raise BuildError.new("Failed to build #{target}")
+          end
+          result
         end
       end
       @targets.each do |target, info|
-        next if targets_processed.include?(target)
-        unless process_target.call(target)
-          cache.write
-          raise BuildError.new("Failed to build #{target}")
-        end
+        process_target.call(target)
       end
       cache.write
     end
@@ -177,7 +164,7 @@ module Rscons
     # @param short_desc [String] Message to print if the Environment's :echo
     #   mode is set to :short
     # @param command [Array] The command to execute.
-    # @param options [Hash] Optional options to pass to {Kernel#system}.
+    # @param options [Hash] Optional options to pass to Kernel#system.
     def execute(short_desc, command, options = {})
       print_command = proc do
         puts command.map { |c| c =~ /\s/ ? "'#{c}'" : c }.join(' ')
@@ -214,30 +201,6 @@ module Rscons
       end
     end
 
-    # Parse dependencies for a given target from a Makefile.
-    # This method is used internally by RScons builders.
-    # @param mf_fname [String] File name of the Makefile to read.
-    # @param target [String] Name of the target to gather dependencies for.
-    def parse_makefile_deps(mf_fname, target)
-      deps = []
-      buildup = ''
-      File.read(mf_fname).each_line do |line|
-        if line =~ /^(.*)\\\s*$/
-          buildup += ' ' + $1
-        else
-          buildup += ' ' + line
-          if buildup =~ /^(.*): (.*)$/
-            mf_target, mf_deps = $1.strip, $2
-            if mf_target == target
-              deps += mf_deps.split(' ').map(&:strip)
-            end
-          end
-          buildup = ''
-        end
-      end
-      deps
-    end
-
     # Build a list of source files into files containing one of the suffixes
     # given by suffixes.
     # This method is used internally by RScons builders.
@@ -275,16 +238,40 @@ module Rscons
     # Return the result of the builder's run() method.
     def run_builder(builder, target, sources, cache, vars)
       vars = @varset.merge(vars)
-      @tweakers.each do |tweaker_block|
+      @build_hooks.each do |build_hook_block|
         build_operation = {
           builder: builder,
           target: target,
           sources: sources,
           vars: vars,
         }
-        tweaker_block.call(build_operation)
+        build_hook_block.call(build_operation)
       end
       builder.run(target, sources, cache, self, vars)
     end
+
+    # Parse dependencies for a given target from a Makefile.
+    # This method is used internally by RScons builders.
+    # @param mf_fname [String] File name of the Makefile to read.
+    # @param target [String] Name of the target to gather dependencies for.
+    def self.parse_makefile_deps(mf_fname, target)
+      deps = []
+      buildup = ''
+      File.read(mf_fname).each_line do |line|
+        if line =~ /^(.*)\\\s*$/
+          buildup += ' ' + $1
+        else
+          buildup += ' ' + line
+          if buildup =~ /^(.*): (.*)$/
+            mf_target, mf_deps = $1.strip, $2
+            if mf_target == target
+              deps += mf_deps.split(' ').map(&:strip)
+            end
+          end
+          buildup = ''
+        end
+      end
+      deps
+    end
   end
 end