rake 10.1.1 → 10.2.0

data/lib/rake/backtrace.rb

@@ -1,5 +1,5 @@
 module Rake
-  module Backtrace
+  module Backtrace # :nodoc: all
     SYS_KEYS  = RbConfig::CONFIG.keys.grep(/(prefix|libdir)/)
     SYS_PATHS = RbConfig::CONFIG.values_at(*SYS_KEYS).uniq +
       [ File.join(File.dirname(__FILE__), "..") ]

data/lib/rake/cloneable.rb

@@ -1,8 +1,8 @@
 module Rake
-  # ##########################################################################
+  ##
   # Mixin for creating easily cloned objects.
-  #
-  module Cloneable
+
+  module Cloneable # :nodoc:
     # The hook that invoked by 'clone' and 'dup' methods.
     def initialize_copy(source)
       super

data/lib/rake/contrib/ftptools.rb

@@ -9,9 +9,7 @@ require 'rake/file_list'
 
 module Rake # :nodoc:
 
-  ####################################################################
-  # <b>Note:</b> <em> Not released for general use.</em>
-  class FtpFile
+  class FtpFile # :nodoc: all
     attr_reader :name, :size, :owner, :group, :time
 
     def self.date
@@ -68,9 +66,9 @@ module Rake # :nodoc:
     end
   end
 
-  ####################################################################
+  ##
   # Manage the uploading of files to an FTP account.
-  class FtpUploader
+  class FtpUploader # :nodoc:
 
     # Log uploads to standard output when true.
     attr_accessor :verbose

data/lib/rake/contrib/publisher.rb

@@ -14,8 +14,10 @@ HostInfo = Struct.new(:name, :webdir, :pkgdir)
 
 # :startdoc:
 
+# TODO: Move to contrib/sshpublisher
+#--
 # Manage several publishers as a single entity.
-class CompositePublisher
+class CompositePublisher # :nodoc:
   def initialize
     @publishers = []
   end
@@ -31,9 +33,11 @@ class CompositePublisher
   end
 end
 
+# TODO: Remove in Rake 11, duplicated
+#--
 # Publish an entire directory to an existing remote directory using
 # SSH.
-class SshDirPublisher
+class SshDirPublisher # :nodoc: all
   def initialize(host, remote_dir, local_dir)
     @host = host
     @remote_dir = remote_dir
@@ -45,8 +49,10 @@ class SshDirPublisher
   end
 end
 
+# TODO: Remove in Rake 11, duplicated
+#--
 # Publish an entire directory to a fresh remote directory using SSH.
-class SshFreshDirPublisher < SshDirPublisher
+class SshFreshDirPublisher < SshDirPublisher # :nodoc: all
   def upload
     run %{ssh #{@host} rm -rf #{@remote_dir}} rescue nil
     run %{ssh #{@host} mkdir #{@remote_dir}}
@@ -54,8 +60,10 @@ class SshFreshDirPublisher < SshDirPublisher
   end
 end
 
+# TODO: Remove in Rake 11, duplicated
+#--
 # Publish a list of files to an existing remote directory.
-class SshFilePublisher
+class SshFilePublisher # :nodoc: all
   # Create a publisher using the give host information.
   def initialize(host, remote_dir, local_dir, *files)
     @host = host

data/lib/rake/contrib/rubyforgepublisher.rb

@@ -1,8 +1,10 @@
+# TODO: Remove in Rake 11
+
 require 'rake/contrib/sshpublisher'
 
 module Rake
 
-  class RubyForgePublisher < SshDirPublisher
+  class RubyForgePublisher < SshDirPublisher # :nodoc: all
     attr_reader :project, :proj_id, :user
 
     def initialize(projname, user)

data/lib/rake/contrib/sshpublisher.rb

@@ -8,12 +8,17 @@ module Rake
   class SshDirPublisher
     include Rake::DSL
 
+    # Creates an SSH publisher which will scp all files in +local_dir+ to
+    # +remote_dir+ on +host+
+
     def initialize(host, remote_dir, local_dir)
       @host = host
       @remote_dir = remote_dir
       @local_dir = local_dir
     end
 
+    # Uploads the files
+
     def upload
       sh %{scp -rq #{@local_dir}/* #{@host}:#{@remote_dir}}
     end
@@ -21,6 +26,9 @@ module Rake
 
   # Publish an entire directory to a fresh remote directory using SSH.
   class SshFreshDirPublisher < SshDirPublisher
+
+    # Uploads the files after removing the existing remote directory.
+
     def upload
       sh %{ssh #{@host} rm -rf #{@remote_dir}} rescue nil
       sh %{ssh #{@host} mkdir #{@remote_dir}}
@@ -32,7 +40,9 @@ module Rake
   class SshFilePublisher
     include Rake::DSL
 
-    # Create a publisher using the give host information.
+    # Creates an SSH publisher which will scp all +files+ in +local_dir+ to
+    # +remote_dir+ on +host+.
+
     def initialize(host, remote_dir, local_dir, *files)
       @host = host
       @remote_dir = remote_dir
@@ -40,7 +50,8 @@ module Rake
       @files = files
     end
 
-    # Upload the local directory to the remote directory.
+    # Uploads the files
+
     def upload
       @files.each do |fn|
         sh %{scp -q #{@local_dir}/#{fn} #{@host}:#{@remote_dir}}

data/lib/rake/contrib/sys.rb

@@ -1,2 +1,4 @@
+# TODO: Remove in Rake 11
+
 fail "ERROR: 'rake/contrib/sys' is obsolete and no longer supported. " +
   "Use 'FileUtils' instead."

data/lib/rake/cpu_counter.rb

@@ -0,0 +1,104 @@
+require 'rbconfig'
+
+module Rake
+
+  # Based on a script at:
+  #   http://stackoverflow.com/questions/891537/ruby-detect-number-of-cpus-installed
+  class CpuCounter # :nodoc: all
+    def self.count
+      new.count_with_default
+    end
+
+    def count_with_default(default=4)
+      count || default
+    rescue StandardError
+      default
+    end
+
+    def count
+      if defined?(Java::Java)
+        count_via_java_runtime
+      else
+        case RbConfig::CONFIG['host_os']
+        when /darwin9/
+          count_via_hwprefs_cpu_count
+        when /darwin/
+          count_via_hwprefs_thread_count || count_via_sysctl
+        when /linux/
+          count_via_cpuinfo
+        when /freebsd/
+          count_via_sysctl
+        when /mswin|mingw/
+          count_via_win32
+        else
+          # Try everything
+          count_via_win32 ||
+            count_via_sysctl ||
+            count_via_hwprefs_thread_count ||
+            count_via_hwprefs_cpu_count
+        end
+      end
+    end
+
+    def count_via_java_runtime
+      Java::Java.lang.Runtime.getRuntime.availableProcessors
+    rescue StandardError
+      nil
+    end
+
+    def count_via_win32
+      require 'win32ole'
+      wmi = WIN32OLE.connect("winmgmts://")
+      cpu = wmi.ExecQuery("select NumberOfCores from Win32_Processor") # TODO count hyper-threaded in this
+      cpu.to_enum.first.NumberOfCores
+    rescue StandardError
+      nil
+    end
+
+    def count_via_cpuinfo
+      open('/proc/cpuinfo') { |f| f.readlines }.grep(/processor/).size
+    rescue StandardError
+      nil
+    end
+
+    def count_via_hwprefs_thread_count
+      run 'hwprefs', 'thread_count'
+    end
+
+    def count_via_hwprefs_cpu_count
+      run 'hwprefs', 'cpu_count'
+    end
+
+    def count_via_sysctl
+      run 'sysctl', '-n', 'hw.ncpu'
+    end
+
+    def run(command, *args)
+      cmd = resolve_command(command)
+      if cmd
+        IO.popen [cmd, *args] do |io|
+          io.read.to_i
+        end
+      else
+        nil
+      end
+    end
+
+    def resolve_command(command)
+      look_for_command("/usr/sbin", command) ||
+        look_for_command("/sbin", command) ||
+        in_path_command(command)
+    end
+
+    def look_for_command(dir, command)
+      path = File.join(dir, command)
+      File.exist?(path) ? path : nil
+    end
+
+    def in_path_command(command)
+      IO.popen ['which', command] do |io|
+        io.eof? ? nil : command
+      end
+    end
+  end
+end

data/lib/rake/default_loader.rb

@@ -2,6 +2,10 @@ module Rake
 
   # Default Rakefile loader used by +import+.
   class DefaultLoader
+
+    ##
+    # Loads a rakefile into the current application from +fn+
+
     def load(fn)
       Rake.load_rakefile(File.expand_path(fn))
     end

data/lib/rake/dsl_definition.rb

@@ -6,6 +6,9 @@ module Rake
   ##
   # DSL is a module that provides #task, #desc, #namespace, etc.  Use this
   # when you'd like to use rake outside the top level scope.
+  #
+  # For a Rakefile you run from the comamnd line this module is automatically
+  # included.
 
   module DSL
 
@@ -21,14 +24,45 @@ module Rake
 
     private
 
-    # Declare a basic task.
+    # :call-seq:
+    #   task task_name
+    #   task task_name: dependencies
+    #   task task_name, arguments => dependencies
+    #   task task_name, argument[, argument ...], :needs: dependencies
     #
-    # Example:
-    #   task :clobber => [:clean] do
+    # Declare a basic task.  The +task_name+ is always the first argument.  If
+    # the task name contains a ":" it is defined in that namespace.
+    #
+    # The +dependencies+ may be a single task name or an Array of task names.
+    # The +argument+ (a single name) or +arguments+ (an Array of names) define
+    # the arguments provided to the task.
+    #
+    # The task, argument and dependency names may be either symbols or
+    # strings.
+    #
+    # A task with a single dependency:
+    #
+    #   task clobber: %w[clean] do
     #     rm_rf "html"
     #   end
     #
-    def task(*args, &block)
+    # A task with an argument and a dependency:
+    #
+    #   task :package, [:version] => :test do |t, args|
+    #     # ...
+    #   end
+    #
+    # To invoke this task from the command line:
+    #
+    #   $ rake package[1.2.3]
+    #
+    # Alternate definition:
+    #
+    #   task :package, :version, needs: :test do |t, args|
+    #     # ...
+    #   end
+    #
+    def task(*args, &block) # :doc:
       Rake::Task.define_task(*args, &block)
     end
 
@@ -45,7 +79,7 @@ module Rake
     #     end
     #  end
     #
-    def file(*args, &block)
+    def file(*args, &block) # :doc:
       Rake::FileTask.define_task(*args, &block)
     end
 
@@ -61,7 +95,7 @@ module Rake
     # Example:
     #   directory "testdata/doc"
     #
-    def directory(*args, &block)
+    def directory(*args, &block) # :doc:
       result = file_create(*args, &block)
       dir, _ = *Rake.application.resolve_args(args)
       Rake.each_dir_parent(dir) do |d|
@@ -78,9 +112,9 @@ module Rake
     # about it)
     #
     # Example:
-    #   multitask :deploy => [:deploy_gem, :deploy_rdoc]
+    #   multitask deploy: %w[deploy_gem deploy_rdoc]
     #
-    def multitask(*args, &block)
+    def multitask(*args, &block) # :doc:
       Rake::MultiTask.define_task(*args, &block)
     end
 
@@ -88,14 +122,22 @@ module Rake
     # block.  Returns a NameSpace object that can be used to lookup
     # tasks defined in the namespace.
     #
-    # E.g.
+    # Example:
     #
     #   ns = namespace "nested" do
+    #     # the "nested:run" task
     #     task :run
     #   end
     #   task_run = ns[:run] # find :run in the given namespace.
     #
-    def namespace(name=nil, &block)
+    # Tasks can also be defined in a namespace by using a ":" in the task
+    # name:
+    #
+    #   task "nested:test" do
+    #     # ...
+    #   end
+    #
+    def namespace(name=nil, &block) # :doc:
       name = name.to_s if name.kind_of?(Symbol)
       name = name.to_str if name.respond_to?(:to_str)
       unless name.kind_of?(String) || name.nil?
@@ -111,20 +153,19 @@ module Rake
     #    sh %{cc -o #{t.name} #{t.source}}
     #  end
     #
-    def rule(*args, &block)
+    def rule(*args, &block) # :doc:
       Rake::Task.create_rule(*args, &block)
     end
 
-    # Describe the next rake task.
-    # Duplicate descriptions are discarded.
+    # Describes the next rake task.  Duplicate descriptions are discarded.
     #
     # Example:
     #   desc "Run the Unit Tests"
-    #   task :test => [:build]
-    #     runtests
+    #   task test: [:build]
+    #     # ... run tests
     #   end
     #
-    def desc(description)
+    def desc(description) # :doc:
       Rake.application.last_description = description
     end
 
@@ -142,7 +183,7 @@ module Rake
     # Example:
     #   import ".depend", "my_rules"
     #
-    def import(*fns)
+    def import(*fns) # :doc:
       fns.each do |fn|
         Rake.application.add_import(fn)
       end

data/lib/rake/early_time.rb

@@ -5,11 +5,14 @@ module Rake
     include Comparable
     include Singleton
 
+    ##
+    # The EarlyTime always comes before +other+!
+
     def <=>(other)
       -1
     end
 
-    def to_s
+    def to_s # :nodoc:
       "<EARLY TIME>"
     end
   end

data/lib/rake/ext/core.rb

@@ -1,8 +1,5 @@
-######################################################################
-# Core extension library
-#
 class Module
-  # Check for an existing method in the current class before extending.  IF
+  # Check for an existing method in the current class before extending.  If
   # the method already exists, then a warning is printed and the extension is
   # not added.  Otherwise the block is yielded and any definitions in the
   # block will take effect.
@@ -17,7 +14,7 @@ class Module
   #     end
   #   end
   #
-  def rake_extension(method)
+  def rake_extension(method) # :nodoc:
     if method_defined?(method)
       $stderr.puts "WARNING: Possible conflict with Rake extension: " +
         "#{self}##{method} already exists"