Deprecated top level import in favor of Rake.import

Also added generic deprecation warnings for other deprecated features.

doc/rakefile.rdoc

@@ -358,12 +358,17 @@ invoked.  This make generated dependency files difficult to use.  By
 the time rake gets around to updating the dependencies file, it is too
 late to load it.
 
-The +import+ command addresses this by specifying a file to be loaded
-_after_ the main rakefile is loaded, but _before_ any targets on the
-command line are specified.  In addition, if the file name matches an
-explicit task, that task is invoked before loading the file.  This
-allows dependency files to be generated and used in a single rake
-command invocation.
+The +Rake.import+ command addresses this by specifying a file to be
+loaded _after_ the main rakefile is loaded, but _before_ any targets
+on the command line are invoked.  In addition, if the file name
+matches an explicit task, that task is invoked before loading the
+file.  This allows dependency files to be generated and used in a
+single rake command invocation.
+
+<b>NOTE:</b> Starting in Rake version 0.9.0, the top level +import+
+command is deprecated and we recommend using the scoped
+"+Rake.import+" command mentioned above.  Future versions of Rake will
+drop support for the top level +import+ command.
 
 === Example:
 
@@ -373,7 +378,7 @@ command invocation.
     sh "makedepend -f- -- #{CFLAGS} -- #{t.prerequisites} > #{t.name}"
   end
 
-  import ".depends.mf"
+  Rake.import ".depends.mf"
 
 If ".depends" does not exist, or is out of date w.r.t. the source
 files, a new ".depends" file is generated using +makedepend+ before

lib/rake/application.rb

@@ -153,6 +153,18 @@ def display_error_message(ex)
       $stderr.puts "(See full trace by running task with --trace)" unless options.trace
     end
 
+    # Warn about deprecated usage.
+    #
+    # Example:
+    #    Rake.application.deprecate("import", "Rake.import", caller.first)
+    #
+    def deprecate(old_usage, new_usage, call_site)
+      return if options.ignore_deprecate
+      $stderr.puts "WARNING: '#{old_usage}' is deprecated.  " +
+        "Please use '#{new_usage}' instead.\n" +
+        "    at #{call_site}"
+    end
+
     # Does the exception have a task invocation chain?
     def has_chain?(exception)
       exception.respond_to?(:chain) && exception.chain
@@ -392,6 +404,11 @@ def standard_rake_options
             Rake::TaskManager.record_task_metadata = true
           }
         ],
+        ['--no-deprecation-warnings', '-X', "Disable the deprecation warnings.",
+          lambda { |value|
+            options.ignore_deprecate = true
+          }
+        ],
       ]
     end
 

lib/rake/dsl_definition.rb

@@ -116,24 +116,31 @@ def desc(description)
       Rake.application.last_description = description
     end
 
-    # Import the partial Rakefiles +fn+.  Imported files are loaded
-    # _after_ the current file is completely loaded.  This allows the
-    # import statement to appear anywhere in the importing file, and yet
-    # allowing the imported files to depend on objects defined in the
-    # importing file.
-    #
-    # A common use of the import statement is to include files
-    # containing dependency declarations.
-    #
-    # See also the --rakelibdir command line option.
-    #
-    # Example:
-    #   import ".depend", "my_rules"
-    #
-    def import(*fns)
-      fns.each do |fn|
-        Rake.application.add_import(fn)
-      end
+    # The DSL level import command is now deprecated and moved the
+    # Rake.import.
+    def import(*fn)
+      Rake.application.deprecate("import", "Rake.import", caller.first)
+      Rake.import(*fn)
+    end
+  end
+
+  # Import the partial Rakefiles +fn+.  Imported files are loaded
+  # _after_ the current file is completely loaded.  This allows the
+  # import statement to appear anywhere in the importing file, and yet
+  # allowing the imported files to depend on objects defined in the
+  # importing file.
+  #
+  # A common use of the import statement is to include files
+  # containing dependency declarations.
+  #
+  # See also the --rakelibdir command line option.
+  #
+  # Example:
+  #   import ".depend", "my_rules"
+  #
+  def Rake.import(*fns)
+    fns.each do |fn|
+      Rake.application.add_import(fn)
     end
   end
 

lib/rake/task_manager.rb

@@ -103,6 +103,10 @@ def resolve_args_with_dependencies(args, hash) # :nodoc:
         arg_names = []
         deps = value
       elsif key == :needs
+        Rake.application.deprecate(
+          "task :t, arg, :needs => [deps]",
+          "task :t, [args] => [deps]",
+          caller.detect { |c| c !~ /\blib\/rake\b/ })
         task_name = args.shift
         arg_names = args
         deps = value

test/data/deprecated_import/Rakefile

@@ -0,0 +1 @@
+import "a"

test/data/deprecated_import/a

@@ -0,0 +1,4 @@
+#!/usr/bin/ruby -wKU
+task :imported do
+  puts "imported!"
+end

test/functional/session_based_tests.rb

@@ -254,6 +254,22 @@ def test_trace_bug
     assert_status
   end
 
+  def test_deprecated_import
+    in_environment("PWD" => "test/data/deprecated_import") do
+      rake "imported"
+    end
+    assert_match(/deprecated/, @err)
+    assert_match(/imported!/, @out)
+  end
+
+  def test_suppressed_deprecated_message
+    in_environment("PWD" => "test/data/deprecated_import") do
+      rake "imported -X"
+    end
+    assert_not_match(/deprecated/, @err)
+    assert_match(/imported!/, @out)
+  end
+
   def test_imports
     open("test/data/imports/static_deps", "w") do |f|
       f.puts 'puts "STATIC"'

test/lib/task_manager_test.rb

@@ -151,6 +151,16 @@ def test_correctly_scoped_prerequisites_are_invoked
 end
 
 class TestTaskManagerArgumentResolution < Test::Unit::TestCase
+  def setup
+    super
+    Rake.application.options.ignore_deprecate = true
+  end
+
+  def teardown
+    Rake.application.options.ignore_deprecate = false
+    super
+  end
+
   def test_good_arg_patterns
     assert_equal [:t, [], []],       task(:t)
     assert_equal [:t, [], [:x]],     task(:t => :x)

test/lib/task_test.rb

@@ -37,7 +37,8 @@ def test_create
   end
 
   def test_inspect
-    t = task(:foo, :needs => [:bar, :baz])
+#    t = task(:foo, :needs => [:bar, :baz])
+    t = task(:foo => [:bar, :baz])
     assert_equal "<Rake::Task foo => [bar, baz]>", t.inspect
   end
 
@@ -308,23 +309,20 @@ def test_name_and_needs
     assert_equal ["pre"], t.prerequisites
   end
 
-  def test_name_and_explicit_needs
-    t = task(:t, :needs => [:pre])
-    assert_equal "t", t.name
-    assert_equal [], t.arg_names
-    assert_equal ["pre"], t.prerequisites
-  end
-
   def test_name_args_and_explicit_needs
-    t = task(:t, :x, :y, :needs => [:pre])
-    assert_equal "t", t.name
-    assert_equal [:x, :y], t.arg_names
-    assert_equal ["pre"], t.prerequisites
+    ignore_deprecations do
+      t = task(:t, :x, :y, :needs => [:pre])
+      assert_equal "t", t.name
+      assert_equal [:x, :y], t.arg_names
+      assert_equal ["pre"], t.prerequisites
+    end
   end
 
   def test_illegal_keys_in_task_name_hash
-    assert_exception RuntimeError do
-      t = task(:t, :x, :y => 1, :needs => [:pre])
+    ignore_deprecations do
+      assert_exception RuntimeError do
+        t = task(:t, :x, :y => 1, :needs => [:pre])
+      end
     end
   end
 
@@ -415,7 +413,7 @@ def test_name_with_args
   def test_named_args_are_passed_to_prereqs
     value = nil
     pre = task(:pre, :rev) { |t, args| value = args.rev }
-    t = task(:t, :name, :rev, :needs => [:pre])
+    t = task(:t, [:name, :rev] => [:pre])
     t.invoke("bill", "1.2")
     assert_equal "1.2", value
   end
@@ -425,15 +423,15 @@ def test_args_not_passed_if_no_prereq_names
       assert_equal({}, args.to_hash)
       assert_equal "bill", args.name
     }
-    t = task(:t, :name, :rev, :needs => [:pre])
+    t = task(:t, [:name, :rev] => [:pre])
     t.invoke("bill", "1.2")
   end
 
   def test_args_not_passed_if_no_arg_names
     pre = task(:pre, :rev) { |t, args|
       assert_equal({}, args.to_hash)
     }
-    t = task(:t, :needs => [:pre])
+    t = task(:t  => [:pre])
     t.invoke("bill", "1.2")
   end
 end

test/lib/top_level_functions_test.rb

@@ -20,6 +20,8 @@ def setup
     super
     @app = Rake.application
     Rake.application = flexmock("app")
+    Rake.application.should_receive(:deprecate).
+      and_return { |old, new, call| @app.deprecate(old, new, call) }
   end
 
   def teardown
@@ -36,7 +38,7 @@ def test_import
     Rake.application.should_receive(:add_import).with("x").once.ordered
     Rake.application.should_receive(:add_import).with("y").once.ordered
     Rake.application.should_receive(:add_import).with("z").once.ordered
-    import('x', 'y', 'z')
+    Rake.import('x', 'y', 'z')
   end
 
   def test_when_writing

test/rake_test_setup.rb

@@ -10,6 +10,7 @@
 require 'flexmock/test_unit'
 require 'test/filecreation'
 require 'test/capture_stdout'
+require 'test/test_helper'
 
 module TestMethods
   # Shim method for compatibility

test/test_helper.rb

@@ -9,4 +9,11 @@
 
 class Test::Unit::TestCase
   include Rake::DSL
+
+  def ignore_deprecations
+    Rake.application.options.ignore_deprecate = true
+    yield
+  ensure
+    Rake.application.options.ignore_deprecate = false
+  end
 end