rscons 1.4.3 → 1.5.0

data/lib/rscons/cache.rb

@@ -84,7 +84,8 @@ module Rscons
       @dirty = false
     end
 
-    # Check if target(s) are up to date
+    # Check if target(s) are up to date.
+    #
     # @param targets [String, Array] The name(s) of the target file(s).
     # @param command [String, Array] The command used to build the target.
     # @param deps [Array] List of the target's dependency files.
@@ -93,6 +94,7 @@ module Rscons
     # @option options [Boolean] :strict_deps
     #   Only consider a target up to date if its list of dependencies is
     #   exactly equal (including order) to the cached list of dependencies
+    #
     # @return [Boolean]
     #   True value if the targets are all up to date, meaning that,
     #   for each target:
@@ -144,11 +146,14 @@ module Rscons
       true
     end
 
-    # Store cache information about target(s) built by a builder
+    # Store cache information about target(s) built by a builder.
+    #
     # @param targets [String, Array] The name of the target(s) built.
     # @param command [String, Array] The command used to build the target.
     # @param deps [Array] List of dependencies for the target.
     # @param env [Environment] The {Rscons::Environment}.
+    #
+    # @return [void]
     def register_build(targets, command, deps, env)
       Array(targets).each do |target|
         @cache["targets"][target] = {
@@ -171,13 +176,19 @@ module Rscons
       end
     end
 
-    # Return a list of targets that have been built
+    # Return a list of targets that have been built.
+    #
+    # @return [Array<String>] List of targets that have been built.
     def targets
       @cache["targets"].keys
     end
 
     # Make any needed directories and record the ones that are created for
     # removal upon a "clean" operation.
+    #
+    # @param path [String] Directory to create.
+    #
+    # @return [void]
     def mkdir_p(path)
       parts = path.split(/[\\\/]/)
       parts.each_index do |i|
@@ -191,7 +202,10 @@ module Rscons
       end
     end
 
-    # Return a list of directories which were created as a part of the build
+    # Return a list of directories which were created as a part of the build.
+    #
+    # @return [Array<String>]
+    #   List of directories which were created as a part of the build.
     def directories
       @cache["directories"].keys
     end
@@ -213,14 +227,20 @@ module Rscons
     end
 
     # Return a file's checksum, or the previously calculated checksum for
-    # the same file
+    # the same file.
+    #
     # @param file [String] The file name.
+    #
+    # @return [String] The file's checksum.
     def lookup_checksum(file)
       @lookup_checksums[file] || calculate_checksum(file)
     end
 
-    # Calculate and return a file's checksum
+    # Calculate and return a file's checksum.
+    #
     # @param file [String] The file name.
+    #
+    # @return [String] The file's checksum.
     def calculate_checksum(file)
       @lookup_checksums[file] = Digest::MD5.hexdigest(File.read(file, mode: "rb")) rescue ""
     end

data/lib/rscons/environment.rb

@@ -1,30 +1,39 @@
-require 'set'
-require 'fileutils'
+require "fileutils"
+require "set"
+require "shellwords"
 
 module Rscons
   # The Environment class is the main programmatic interface to Rscons. It
   # contains a collection of construction variables, options, builders, and
   # rules for building targets.
   class Environment
-    # Hash of +{"builder_name" => builder_object}+ pairs.
+    # @return [Hash] Set of \{"builder_name" => builder_object} pairs.
     attr_reader :builders
 
     # :command, :short, or :off
     attr_accessor :echo
 
-    # String or +nil+
+    # @return [String, nil] The build root.
     attr_reader :build_root
+
+    # Set the build root.
+    #
+    # @param build_root [String] The build root.
     def build_root=(build_root)
       @build_root = build_root
       @build_root.gsub!('\\', '/') if @build_root
     end
 
     # Create an Environment object.
+    #
     # @param options [Hash]
-    # Possible options keys:
-    #   :echo => :command, :short, or :off (default :short)
-    #   :build_root => String specifying build root directory (default nil)
-    #   :exclude_builders => true to omit adding default builders (default false)
+    # @option options [Symbol] :echo
+    #   :command, :short, or :off (default :short)
+    # @option options [String] :build_root
+    #   Build root directory (default nil)
+    # @option options [Boolean] :exclude_builders
+    #   Whether to omit adding default builders (default false)
+    #
     # 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 initialize(options = {})
@@ -107,6 +116,10 @@ module Rscons
     end
 
     # Add a {Builder} object to the Environment.
+    #
+    # @param builder [Builder] The {Builder} object to add.
+    #
+    # @return [void]
     def add_builder(builder)
       @builders[builder.name] = builder
       var_defs = builder.default_variables(self)
@@ -118,19 +131,45 @@ module Rscons
     end
 
     # Add a build hook to the Environment.
+    #
+    # @yield [build_op]
+    #   Invoke the given block with the current build operation.
+    # @yieldparam build_op [Hash]
+    #   Hash with keys:
+    #   - :builder - The builder object in use.
+    #   - :target - Target file name.
+    #   - :sources - List of source file(s).
+    #   - :vars - Set of construction variable values in use.
+    #   - :env - The Environment invoking the builder.
+    #
+    # @return [void]
     def add_build_hook(&block)
       @build_hooks << block
     end
 
     # Specify a build directory for this Environment.
+    #
     # Source files from src_dir will produce object files under obj_dir.
+    #
+    # @param src_dir [String] Path to the source directory.
+    # @param obj_dir [String] Path to the object directory.
+    #
+    # @return [void]
     def build_dir(src_dir, obj_dir)
       src_dir = src_dir.gsub('\\', '/') if src_dir.is_a?(String)
       @build_dirs << [src_dir, obj_dir]
     end
 
-    # Return the file name to be built from source_fname with suffix suffix.
+    # Return the file name to be built from +source_fname+ with suffix
+    # +suffix+.
+    #
     # This method takes into account the Environment's build directories.
+    #
+    # @param source_fname [String] Source file name.
+    # @param suffix [String] Suffix, including "." if desired.
+    #
+    # @return [String]
+    #   The file name to be built from +source_fname+ with suffix +suffix+.
     def get_build_fname(source_fname, suffix)
       build_fname = Rscons.set_suffix(source_fname, suffix).gsub('\\', '/')
       found_match = @build_dirs.find do |src_dir, obj_dir|
@@ -150,26 +189,32 @@ module Rscons
     end
 
     # Access a construction variable or environment option.
+    #
     # @see VarSet#[]
     def [](*args)
       @varset.send(:[], *args)
     end
 
     # Set a construction variable or environment option.
+    #
     # @see VarSet#[]=
     def []=(*args)
       @varset.send(:[]=, *args)
     end
 
     # Add a set of construction variables or environment options.
+    #
     # @see VarSet#append
     def append(*args)
       @varset.append(*args)
     end
 
-    # Build all target specified in the Environment.
+    # Build all build targets specified in the Environment.
+    #
     # When a block is passed to Environment.new, this method is automatically
     # called after the block returns.
+    #
+    # @return [void]
     def process
       unless @targets.empty?
         expand_paths!
@@ -226,13 +271,16 @@ module Rscons
     end
     alias_method :build_command, :expand_varref
 
-    # Execute a builder command
+    # Execute a builder command.
+    #
     # @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, possible keys:
     #   - :env - environment Hash to pass to Kernel#system.
     #   - :options - options Hash to pass to Kernel#system.
+    #
+    # @return [true,false,nil] Return value from Kernel.system().
     def execute(short_desc, command, options = {})
       print_command = proc do
         puts command.map { |c| c =~ /\s/ ? "'#{c}'" : c }.join(' ')
@@ -244,7 +292,7 @@ module Rscons
       end
       env_args = options[:env] ? [options[:env]] : []
       options_args = options[:options] ? [options[:options]] : []
-      system(*env_args, *command, *options_args).tap do |result|
+      system(*env_args, *Rscons.command_executer, *command, *options_args).tap do |result|
         unless result or @echo == :command
           $stdout.write "Failed command was: "
           print_command.call
@@ -252,6 +300,14 @@ module Rscons
       end
     end
 
+    # Define a build target.
+    #
+    # @param method [Symbol] Method name.
+    # @param args [Array] Method arguments.
+    #
+    # @return [BuildTarget]
+    #   The {BuildTarget} object registered, if the method called is a
+    #   {Builder}.
     def method_missing(method, *args)
       if @builders.has_key?(method.to_s)
         target, sources, vars, *rest = args
@@ -259,12 +315,24 @@ module Rscons
           raise "Unexpected construction variable set: #{vars.inspect}"
         end
         sources = Array(sources)
-        add_target(target, @builders[method.to_s], sources, vars, rest)
+        builder = @builders[method.to_s]
+        build_target = builder.create_build_target(env: self, target: target, sources: sources)
+        add_target(build_target.to_s, builder, sources, vars, rest)
+        build_target
       else
         super
       end
     end
 
+    # Add a build target.
+    #
+    # @param target [String] Build target file name.
+    # @param builder [Builder] The {Builder} to use to build the target.
+    # @param sources [Array<String>] Source file name(s).
+    # @param vars [Hash] Construction variable overrides.
+    # @param args [Object] Any extra arguments passed to the {Builder}.
+    #
+    # @return [void]
     def add_target(target, builder, sources, vars, args)
       @targets[target] = {
         builder: builder,
@@ -274,27 +342,40 @@ module Rscons
       }
     end
 
-    # Manually record a given target as depending on the specified
-    # dependency files.
+    # Manually record a given target as depending on the specified files.
+    #
+    # @param target [String,BuildTarget] Target file.
+    # @param user_deps [Array<String>] Dependency files.
+    #
+    # @return [void]
     def depends(target, *user_deps)
+      target = target.to_s
       @user_deps[target] ||= []
       @user_deps[target] = (@user_deps[target] + user_deps).uniq
     end
 
-    # Return the list of user dependencies for a given target, or +nil+ for
-    # none.
+    # Return the list of user dependencies for a given target.
+    #
+    # @param target [String] Target file name.
+    #
+    # @return [Array<String>,nil]
+    #   List of user-specified dependencies for the target, or nil if none were
+    #   specified.
     def get_user_deps(target)
       @user_deps[target]
     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.
+    #
     # @param sources [Array] List of source files to build.
     # @param suffixes [Array] List of suffixes to try to convert source files into.
     # @param cache [Cache] The Cache.
     # @param vars [Hash] Extra variables to pass to the builder.
-    # Return a list of the converted file names.
+    #
+    # @return [Array<String>] List of the converted file name(s).
     def build_sources(sources, suffixes, cache, vars)
       sources.map do |source|
         if source.end_with?(*suffixes)
@@ -316,12 +397,14 @@ module Rscons
     end
 
     # Invoke a builder to build the given target based on the given sources.
+    #
     # @param builder [Builder] The Builder to use.
     # @param target [String] The target output file.
     # @param sources [Array] List of source files.
     # @param cache [Cache] The Cache.
     # @param vars [Hash] Extra variables to pass to the builder.
-    # Return the result of the builder's run() method.
+    #
+    # @return [String,false] Return value from the {Builder}'s +run+ method.
     def run_builder(builder, target, sources, cache, vars)
       vars = @varset.merge(vars)
       @build_hooks.each do |build_hook_block|
@@ -349,6 +432,157 @@ module Rscons
       path.sub(%r{^\^(?=[\\/])}, @build_root)
     end
 
+    # Execute a command using the system shell.
+    #
+    # The shell is automatically determined but can be overridden by the SHELL
+    # construction variable. If the SHELL construction variable is specified,
+    # the flag to pass to the shell is automatically dtermined but can be
+    # overridden by the SHELLFLAG construction variable.
+    #
+    # @param command [String] Command to execute.
+    #
+    # @return [String] The command's standard output.
+    def shell(command)
+      shell_cmd =
+        if self["SHELL"]
+          flag = self["SHELLFLAG"] || (self["SHELL"] == "cmd" ? "/c" : "-c")
+          [self["SHELL"], flag]
+        else
+          Rscons.get_system_shell
+        end
+      IO.popen([*shell_cmd, command]) do |io|
+        io.read
+      end
+    end
+
+    # @!method parse_flags(flags)
+    # @!method parse_flags!(flags)
+    #
+    # Parse command-line flags for compilation/linking options into separate
+    # construction variables.
+    #
+    # The parsed construction variables are returned in a Hash instead of
+    # merging them directly to the Environment. They can be merged with
+    # {#merge_flags}. The {#parse_flags!} version immediately merges the parsed
+    # flags as well.
+    #
+    # Example:
+    #   # Import FreeType build options
+    #   env.parse_flags!("!freetype-config --cflags --libs")
+    #
+    # @param flags [String]
+    #   String containing the flags to parse, or if the flags string begins
+    #   with "!", a shell command to execute using {#shell} to obtain the
+    #   flags to parse.
+    #
+    # @return [Hash] Set of construction variables to append.
+    def parse_flags(flags)
+      if flags =~ /^!(.*)$/
+        flags = shell($1)
+      end
+      rv = {}
+      words = Shellwords.split(flags)
+      skip = false
+      words.each_with_index do |word, i|
+        if skip
+          skip = false
+          next
+        end
+        append = lambda do |var, val|
+          rv[var] ||= []
+          rv[var] += val
+        end
+        handle = lambda do |var, val|
+          if val.nil? or val.empty?
+            val = words[i + 1]
+            skip = true
+          end
+          if val and not val.empty?
+            append[var, [val]]
+          end
+        end
+        if word == "-arch"
+          if val = words[i + 1]
+            append["CCFLAGS", ["-arch", val]]
+            append["LDFLAGS", ["-arch", val]]
+          end
+          skip = true
+        elsif word =~ /^#{self["CPPDEFPREFIX"]}(.*)$/
+          handle["CPPDEFINES", $1]
+        elsif word == "-include"
+          if val = words[i + 1]
+            append["CCFLAGS", ["-include", val]]
+          end
+          skip = true
+        elsif word == "-isysroot"
+          if val = words[i + 1]
+            append["CCFLAGS", ["-isysroot", val]]
+            append["LDFLAGS", ["-isysroot", val]]
+          end
+          skip = true
+        elsif word =~ /^#{self["INCPREFIX"]}(.*)$/
+          handle["CPPPATH", $1]
+        elsif word =~ /^#{self["LIBLINKPREFIX"]}(.*)$/
+          handle["LIBS", $1]
+        elsif word =~ /^#{self["LIBDIRPREFIX"]}(.*)$/
+          handle["LIBPATH", $1]
+        elsif word == "-mno-cygwin"
+          append["CCFLAGS", [word]]
+          append["LDFLAGS", [word]]
+        elsif word == "-mwindows"
+          append["LDFLAGS", [word]]
+        elsif word == "-pthread"
+          append["CCFLAGS", [word]]
+          append["LDFLAGS", [word]]
+        elsif word =~ /^-std=/
+          append["CFLAGS", [word]]
+        elsif word =~ /^-Wa,(.*)$/
+          append["ASFLAGS", $1.split(",")]
+        elsif word =~ /^-Wl,(.*)$/
+          append["LDFLAGS", $1.split(",")]
+        elsif word =~ /^-Wp,(.*)$/
+          append["CPPFLAGS", $1.split(",")]
+        elsif word.start_with?("-")
+          append["CCFLAGS", [word]]
+        elsif word.start_with?("+")
+          append["CCFLAGS", [word]]
+          append["LDFLAGS", [word]]
+        else
+          append["LIBS", [word]]
+        end
+      end
+      rv
+    end
+
+    def parse_flags!(flags)
+      flags = parse_flags(flags)
+      merge_flags(flags)
+      flags
+    end
+
+    # Merge construction variable flags into this Environment's construction
+    # variables.
+    #
+    # This method does the same thing as {#append}, except that Array values in
+    # +flags+ are appended to the end of Array construction variables instead
+    # of replacing their contents.
+    #
+    # @param flags [Hash]
+    #   Set of construction variables to merge into the current Environment.
+    #   This can be the value (or a modified version) returned by
+    #   {#parse_flags}.
+    #
+    # @return [void]
+    def merge_flags(flags)
+      flags.each_pair do |key, val|
+        if self[key].is_a?(Array) and val.is_a?(Array)
+          self[key] += val
+        else
+          self[key] = val
+        end
+      end
+    end
+
     private
 
     # Expand target and source paths before invoking builders.
@@ -356,6 +590,8 @@ module Rscons
     # This method expand construction variable references in the target and
     # source file names before passing them to the builder. It also expands
     # "^/" prefixes to the Environment's build root if a build root is defined.
+    #
+    # @return [void]
     def expand_paths!
       @targets = @targets.reduce({}) do |result, (target, target_params)|
         sources = target_params[:sources].map do |source|
@@ -370,9 +606,13 @@ module Rscons
     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.
+    #
+    # @return [Array<String>] Paths of dependency files.
     def self.parse_makefile_deps(mf_fname, target)
       deps = []
       buildup = ''