rscons 1.4.3 → 1.5.0

data/lib/rscons.rb

@@ -1,3 +1,4 @@
+require_relative "rscons/build_target"
 require_relative "rscons/builder"
 require_relative "rscons/cache"
 require_relative "rscons/environment"
@@ -14,6 +15,8 @@ require_relative "rscons/builders/program"
 
 # Namespace module for rscons classes
 module Rscons
+  # Names of the default builders which will be added to all newly created
+  # {Environment} objects.
   DEFAULT_BUILDERS = [
     :CFile,
     :Disassemble,
@@ -23,9 +26,10 @@ module Rscons
     :Program,
   ]
 
+  # Class to represent a fatal error while building a target.
   class BuildError < RuntimeError; end
 
-  # Remove all generated files
+  # Remove all generated files.
   def self.clean
     cache = Cache.instance
     # remove all built files
@@ -42,16 +46,82 @@ module Rscons
     cache.clear
   end
 
-  # Return whether the given path is an absolute filesystem path or not
-  # @param path [String] the path to examine
+  # Return whether the given path is an absolute filesystem path.
+  #
+  # @param path [String] the path to examine.
+  #
+  # @return [Boolean] Whether the given path is an absolute filesystem path.
   def self.absolute_path?(path)
     path =~ %r{^(/|\w:[\\/])}
   end
 
   # Return a new path by changing the suffix in path to suffix.
-  # @param path [String] the path to alter
-  # @param suffix [String] the new filename suffix
+  #
+  # @param path [String] The path to alter.
+  # @param suffix [String] The new filename suffix, e.g. ".exe".
+  #
+  # @return [String] New path.
   def self.set_suffix(path, suffix)
     path.sub(/\.[^.]*$/, suffix)
   end
+
+  # Return the system shell and arguments for executing a shell command.
+  #
+  # @return [Array<String>] The shell and flag.
+  def self.get_system_shell
+    @@shell ||=
+      begin
+        test_shell = lambda do |*args|
+          begin
+            "success" == IO.popen([*args, "echo success"]) do |io|
+              io.read.strip
+            end
+          rescue
+            false
+          end
+        end
+        if ENV["SHELL"] and ENV["SHELL"] != "" and test_shell[ENV["SHELL"], "-c"]
+          [ENV["SHELL"], "-c"]
+        elsif Object.const_get("RUBY_PLATFORM") =~ /mingw/
+          if test_shell["sh", "-c"]
+            # Using Rscons from MSYS should use MSYS's shell.
+            ["sh", "-c"]
+          else
+            ["cmd", "/c"]
+          end
+        else
+          ["sh", "-c"]
+        end
+      end
+  end
+
+  # Return an Array containing a command used to execute commands.
+  #
+  # This will normally be an empty Array, but on Windows if Rscons detects
+  # that it is running in MSYS then ["env"] will be returned.
+  #
+  # @return [Array<String>] Command used to execute commands.
+  def self.command_executer
+    @@command_executer ||=
+      if Object.const_get("RUBY_PLATFORM") =~ /mingw/
+        if ENV.keys.find {|key| key =~ /MSYS/}
+          begin
+            if IO.popen(["env", "echo", "success"]) {|io| io.read.strip} == "success"
+              ["env"]
+            end
+          rescue
+          end
+        end
+      end || []
+  end
+
+  # Set the command executer array.
+  #
+  # @param val [Array<String>] Command used to execute commands.
+  def self.command_executer=(val)
+    @@command_executer = val
+  end
 end
+
+# Unbuffer $stdout
+$stdout.sync = true

data/lib/rscons/build_target.rb

@@ -0,0 +1,36 @@
+module Rscons
+  # The BuildTarget class represents a single build target.
+  class BuildTarget
+    # Create a BuildTarget object.
+    #
+    # @param options [Hash] Options to create the BuildTarget with.
+    # @option options [Environment] :env
+    #   The Environment.
+    # @option options [String] :target
+    #   The user-supplied target name.
+    # @option options [Array<String>] :sources
+    #   The user-supplied source file name(s).
+    def initialize(options)
+      @env = options[:env]
+      @target = options[:target]
+    end
+
+    # Manually record a given target as depending on the specified files.
+    #
+    # @param user_deps [Array<String>] Dependency files.
+    #
+    # @return [void]
+    def depends(*user_deps)
+      @env.depends(@target, *user_deps)
+    end
+
+    # Convert the BuildTarget to a String.
+    #
+    # This method always returns the target file name.
+    #
+    # @return [String] Target file name.
+    def to_s
+      @target
+    end
+  end
+end

data/lib/rscons/builder.rb

@@ -7,30 +7,68 @@ module Rscons
   # Class to hold an object that knows how to build a certain type of file.
   class Builder
     # Return the name of the builder.
+    #
     # If not overridden this defaults to the last component of the class name.
     def name
       self.class.name.split(":").last
     end
 
-    # Return a set of default variable values for the Environment to use
-    # unless the user overrides any.
+    # Return a set of default construction variables for the builder.
+    #
     # @param env [Environment] The Environment.
+    #
+    # @return [Hash] Default construction variables.
     def default_variables(env)
       {}
     end
 
+    # Create a BuildTarget object for this build target.
+    #
+    # Builder sub-classes can override this method to manipulate parameters
+    # (for example, add a suffix to the user-given target file name).
+    #
+    # @param options [Hash] Options to create the BuildTarget with.
+    # @option options [Environment] :env
+    #   The Environment.
+    # @option options [String] :target
+    #   The user-supplied target name.
+    # @option options [Array<String>] :sources
+    #   The user-supplied source file name(s).
+    #
+    # @return [BuildTarget]
+    def create_build_target(options)
+      BuildTarget.new(options)
+    end
+
     # Return whether this builder object is capable of producing a given target
     # file name from a given source file name.
+    #
     # @param target [String] The target file name.
     # @param source [String, Array] The source file name(s).
     # @param env [Environment] The Environment.
+    #
+    # @return [Boolean]
+    #   Whether this builder object is capable of producing a given target
+    #   file name from a given source file name.
     def produces?(target, source, env)
       false
     end
 
     # Check if the cache is up to date for the target and if not execute the
     # build command.
-    # Return the name of the target or false on failure.
+    #
+    # @param short_cmd_string [String]
+    #   Short description of build action to be printed when env.echo ==
+    #   :short.
+    # @param target [String] Name of the target file.
+    # @param command [Array<String>]
+    #   The command to execute to build the target.
+    # @param sources [Array<String>] Source file name(s).
+    # @param env [Environment] The Environment executing the builder.
+    # @param cache [Cache] The Cache object.
+    #
+    # @return [String,false]
+    #   The name of the target on success or false on failure.
     def standard_build(short_cmd_string, target, command, sources, env, cache)
       unless cache.up_to_date?(target, command, sources, env)
         cache.mkdir_p(File.dirname(target))

data/lib/rscons/builders/cfile.rb

@@ -7,6 +7,11 @@ module Rscons
     #   env.CFile("parser.tab.cc", "parser.yy")
     #   env.CFile("lex.yy.cc", "parser.ll")
     class CFile < Builder
+      # Return default construction variables for the builder.
+      #
+      # @param env [Environment] The Environment using the builder.
+      #
+      # @return [Hash] Default construction variables for the builder.
       def default_variables(env)
         {
           "YACC" => "bison",
@@ -18,6 +23,16 @@ module Rscons
         }
       end
 
+      # Run the builder to produce a build target.
+      #
+      # @param target [String] Target file name.
+      # @param sources [Array<String>] Source file name(s).
+      # @param cache [Cache] The Cache object.
+      # @param env [Environment] The Environment executing the builder.
+      # @param vars [Hash,VarSet] Extra construction variables.
+      #
+      # @return [String,false]
+      #   Name of the target file on success or false on failure.
       def run(target, sources, cache, env, vars)
         vars = vars.merge({
           "_TARGET" => target,

data/lib/rscons/builders/disassemble.rb

@@ -2,6 +2,11 @@ module Rscons
   module Builders
     # The Disassemble builder produces a disassembly listing of a source file.
     class Disassemble < Builder
+      # Return default construction variables for the builder.
+      #
+      # @param env [Environment] The Environment using the builder.
+      #
+      # @return [Hash] Default construction variables for the builder.
       def default_variables(env)
         {
           "OBJDUMP" => "objdump",
@@ -10,6 +15,16 @@ module Rscons
         }
       end
 
+      # Run the builder to produce a build target.
+      #
+      # @param target [String] Target file name.
+      # @param sources [Array<String>] Source file name(s).
+      # @param cache [Cache] The Cache object.
+      # @param env [Environment] The Environment executing the builder.
+      # @param vars [Hash,VarSet] Extra construction variables.
+      #
+      # @return [String,false]
+      #   Name of the target file on success or false on failure.
       def run(target, sources, cache, env, vars)
         vars = vars.merge("_SOURCES" => sources)
         command = env.build_command("${DISASM_CMD}", vars)

data/lib/rscons/builders/library.rb

@@ -2,15 +2,30 @@ module Rscons
   module Builders
     # A default Rscons builder that produces a static library archive.
     class Library < Builder
+      # Return default construction variables for the builder.
+      #
+      # @param env [Environment] The Environment using the builder.
+      #
+      # @return [Hash] Default construction variables for the builder.
       def default_variables(env)
         {
           'AR' => 'ar',
           'LIBSUFFIX' => '.a',
-          'ARFLAGS' => [],
-          'ARCMD' => ['${AR}', 'rcs', '${ARFLAGS}', '${_TARGET}', '${_SOURCES}']
+          'ARFLAGS' => ['rcs'],
+          'ARCMD' => ['${AR}', '${ARFLAGS}', '${_TARGET}', '${_SOURCES}']
         }
       end
 
+      # Run the builder to produce a build target.
+      #
+      # @param target [String] Target file name.
+      # @param sources [Array<String>] Source file name(s).
+      # @param cache [Cache] The Cache object.
+      # @param env [Environment] The Environment executing the builder.
+      # @param vars [Hash,VarSet] Extra construction variables.
+      #
+      # @return [String,false]
+      #   Name of the target file on success or false on failure.
       def run(target, sources, cache, env, vars)
         # build sources to linkable objects
         objects = env.build_sources(sources, env.expand_varref(["${OBJSUFFIX}", "${LIBSUFFIX}"], vars).flatten, cache, vars)

data/lib/rscons/builders/object.rb

@@ -3,6 +3,7 @@ module Rscons
     # A default Rscons builder which knows how to produce an object file from
     # various types of source files.
     class Object < Builder
+      # Mapping of known sources from which to build object files.
       KNOWN_SUFFIXES = {
         "AS" => "ASSUFFIX",
         "CC" => "CSUFFIX",
@@ -10,47 +11,78 @@ module Rscons
         "DC" => "DSUFFIX",
       }
 
+      # Return default construction variables for the builder.
+      #
+      # @param env [Environment] The Environment using the builder.
+      #
+      # @return [Hash] Default construction variables for the builder.
       def default_variables(env)
         {
           'OBJSUFFIX' => '.o',
 
+          'CPPDEFPREFIX' => '-D',
+          'INCPREFIX' => '-I',
+
           'AS' => '${CC}',
           'ASFLAGS' => [],
           'ASSUFFIX' => '.S',
           'ASPPPATH' => '${CPPPATH}',
           'ASPPFLAGS' => '${CPPFLAGS}',
           'ASDEPGEN' => ['-MMD', '-MF', '${_DEPFILE}'],
-          'ASCMD' => ['${AS}', '-c', '-o', '${_TARGET}', '${ASDEPGEN}', '-I${ASPPPATH}', '${ASPPFLAGS}', '${ASFLAGS}', '${_SOURCES}'],
+          'ASCMD' => ['${AS}', '-c', '-o', '${_TARGET}', '${ASDEPGEN}', '${INCPREFIX}${ASPPPATH}', '${ASPPFLAGS}', '${ASFLAGS}', '${_SOURCES}'],
 
-          'CPPFLAGS' => [],
+          'CPPFLAGS' => ['${CPPDEFPREFIX}${CPPDEFINES}'],
+          'CPPDEFINES' => [],
           'CPPPATH' => [],
 
+          'CCFLAGS' => [],
+
           'CC' => 'gcc',
           'CFLAGS' => [],
           'CSUFFIX' => '.c',
           'CCDEPGEN' => ['-MMD', '-MF', '${_DEPFILE}'],
-          'CCCMD' => ['${CC}', '-c', '-o', '${_TARGET}', '${CCDEPGEN}', '-I${CPPPATH}', '${CPPFLAGS}', '${CFLAGS}', '${_SOURCES}'],
+          'CCCMD' => ['${CC}', '-c', '-o', '${_TARGET}', '${CCDEPGEN}', '${INCPREFIX}${CPPPATH}', '${CPPFLAGS}', '${CFLAGS}', '${CCFLAGS}', '${_SOURCES}'],
 
           'CXX' => 'g++',
           'CXXFLAGS' => [],
           'CXXSUFFIX' => '.cc',
           'CXXDEPGEN' => ['-MMD', '-MF', '${_DEPFILE}'],
-          'CXXCMD' =>['${CXX}', '-c', '-o', '${_TARGET}', '${CXXDEPGEN}', '-I${CPPPATH}', '${CPPFLAGS}', '${CXXFLAGS}', '${_SOURCES}'],
+          'CXXCMD' =>['${CXX}', '-c', '-o', '${_TARGET}', '${CXXDEPGEN}', '${INCPREFIX}${CPPPATH}', '${CPPFLAGS}', '${CXXFLAGS}', '${CCFLAGS}', '${_SOURCES}'],
 
           'DC' => 'gdc',
           'DFLAGS' => [],
           'DSUFFIX' => '.d',
           'D_IMPORT_PATH' => [],
-          'DCCMD' => ['${DC}', '-c', '-o', '${_TARGET}', '-I${D_IMPORT_PATH}', '${DFLAGS}', '${_SOURCES}'],
+          'DCCMD' => ['${DC}', '-c', '-o', '${_TARGET}', '${INCPREFIX}${D_IMPORT_PATH}', '${DFLAGS}', '${_SOURCES}'],
         }
       end
 
+      # Return whether this builder object is capable of producing a given target
+      # file name from a given source file name.
+      #
+      # @param target [String] The target file name.
+      # @param source [String, Array] The source file name(s).
+      # @param env [Environment] The Environment.
+      #
+      # @return [Boolean]
+      #   Whether this builder object is capable of producing a given target
+      #   file name from a given source file name.
       def produces?(target, source, env)
         target.end_with?(*env['OBJSUFFIX']) and KNOWN_SUFFIXES.find do |compiler, suffix_var|
           source.end_with?(*env[suffix_var])
         end
       end
 
+      # Run the builder to produce a build target.
+      #
+      # @param target [String] Target file name.
+      # @param sources [Array<String>] Source file name(s).
+      # @param cache [Cache] The Cache object.
+      # @param env [Environment] The Environment executing the builder.
+      # @param vars [Hash,VarSet] Extra construction variables.
+      #
+      # @return [String,false]
+      #   Name of the target file on success or false on failure.
       def run(target, sources, cache, env, vars)
         vars = vars.merge({
           '_TARGET' => target,

data/lib/rscons/builders/preprocess.rb

@@ -2,12 +2,27 @@ module Rscons
   module Builders
     # The Preprocess builder invokes the C preprocessor
     class Preprocess < Builder
+      # Return default construction variables for the builder.
+      #
+      # @param env [Environment] The Environment using the builder.
+      #
+      # @return [Hash] Default construction variables for the builder.
       def default_variables(env)
         {
           "CPP_CMD" => ["${_PREPROCESS_CC}", "-E", "-o", "${_TARGET}", "-I${CPPPATH}", "${CPPFLAGS}", "${CFLAGS}", "${_SOURCES}"],
         }
       end
 
+      # Run the builder to produce a build target.
+      #
+      # @param target [String] Target file name.
+      # @param sources [Array<String>] Source file name(s).
+      # @param cache [Cache] The Cache object.
+      # @param env [Environment] The Environment executing the builder.
+      # @param vars [Hash,VarSet] Extra construction variables.
+      #
+      # @return [String,false]
+      #   Name of the target file on success or false on failure.
       def run(target, sources, cache, env, vars)
         pp_cc = if sources.find {|s| s.end_with?(*env.expand_varref("${CXXSUFFIX}", vars))}
                   "${CXX}"

data/lib/rscons/builders/program.rb

@@ -3,18 +3,58 @@ module Rscons
     # A default Rscons builder that knows how to link object files into an
     # executable program.
     class Program < Builder
+      # Return default construction variables for the builder.
+      #
+      # @param env [Environment] The Environment using the builder.
+      #
+      # @return [Hash] Default construction variables for the builder.
       def default_variables(env)
         {
-          'LD' => nil,
           'OBJSUFFIX' => '.o',
+          'PROGSUFFIX' => (Object.const_get("RUBY_PLATFORM") =~ /mingw|cygwin/ ? ".exe" : ""),
+          'LD' => nil,
           'LIBSUFFIX' => '.a',
           'LDFLAGS' => [],
           'LIBPATH' => [],
+          'LIBDIRPREFIX' => '-L',
+          'LIBLINKPREFIX' => '-l',
           'LIBS' => [],
-          'LDCMD' => ['${LD}', '-o', '${_TARGET}', '${LDFLAGS}', '${_SOURCES}', '-L${LIBPATH}', '-l${LIBS}']
+          'LDCMD' => ['${LD}', '-o', '${_TARGET}', '${LDFLAGS}', '${_SOURCES}', '${LIBDIRPREFIX}${LIBPATH}', '${LIBLINKPREFIX}${LIBS}']
         }
       end
 
+      # Create a BuildTarget object for this build target.
+      #
+      # The build target filename is given a ".exe" suffix if Rscons is
+      # executing on a Windows platform and no other suffix is given.
+      #
+      # @param options [Hash] Options to create the BuildTarget with.
+      # @option options [Environment] :env
+      #   The Environment.
+      # @option options [String] :target
+      #   The user-supplied target name.
+      # @option options [Array<String>] :sources
+      #   The user-supplied source file name(s).
+      #
+      # @return [BuildTarget]
+      def create_build_target(options)
+        my_options = options.dup
+        unless my_options[:target] =~ /\./
+          my_options[:target] += options[:env].expand_varref("${PROGSUFFIX}")
+        end
+        super(my_options)
+      end
+
+      # Run the builder to produce a build target.
+      #
+      # @param target [String] Target file name.
+      # @param sources [Array<String>] Source file name(s).
+      # @param cache [Cache] The Cache object.
+      # @param env [Environment] The Environment executing the builder.
+      # @param vars [Hash,VarSet] Extra construction variables.
+      #
+      # @return [String,false]
+      #   Name of the target file on success or false on failure.
       def run(target, sources, cache, env, vars)
         # build sources to linkable objects
         objects = env.build_sources(sources, env.expand_varref(["${OBJSUFFIX}", "${LIBSUFFIX}"], vars).flatten, cache, vars)