formula: add new pour_bottle DSL with reason.

This allows there to be a user-visible description of why a bottle is
not being installed.

Library/Homebrew/formula.rb

@@ -799,10 +799,16 @@ class Formula
   # Can be overridden to selectively disable bottles from formulae.
   # Defaults to true so overridden version does not have to check if bottles
   # are supported.
+  # Replaced by {.pour_bottle}'s `satisfy` method if it is specified.
   def pour_bottle?
     true
   end
 
+  # @private
+  def pour_bottle_check_unsatisfied_reason
+    self.class.pour_bottle_check_unsatisfied_reason
+  end
+
   # Can be overridden to run commands on both source and bottle installation.
   def post_install; end
 
@@ -1614,6 +1620,11 @@ class Formula
     # @private
     attr_reader :plist_manual
 
+    # If `pour_bottle?` returns `false` the user-visible reason to display for
+    # why they cannot use the bottle.
+    # @private
+    attr_accessor :pour_bottle_check_unsatisfied_reason
+
     # @!attribute [w] revision
     # Used for creating new Homebrew versions of software without new upstream
     # versions. For example, if we bump the major version of a library this
@@ -2023,11 +2034,27 @@ class Formula
     #
     # The test will fail if it returns false, or if an exception is raised.
     # Failed assertions and failed `system` commands will raise exceptions.
-
     def test(&block)
       define_method(:test, &block)
     end
 
+    # Defines whether the {Formula}'s bottle can be used on the given Homebrew
+    # installation.
+    #
+    # For example, if the bottle requires the Xcode CLT to be installed a
+    # {Formula} would declare:
+    # <pre>pour_bottle? do
+    #   reason "The bottle needs the Xcode CLT to be installed."
+    #   satisfy { MacOS::CLT.installed? }
+    # end</pre>
+    #
+    # If `satisfy` returns `false` then a bottle will not be used and instead
+    # the {Formula} will be built from source and `reason` will be printed.
+    def pour_bottle?(&block)
+      @pour_bottle_check = PourBottleCheck.new(self)
+      @pour_bottle_check.instance_eval(&block)
+    end
+
     # @private
     def link_overwrite(*paths)
       paths.flatten!

Library/Homebrew/software_spec.rb

@@ -351,7 +351,7 @@ class PourBottleCheck
   end
 
   def reason(reason)
-    @formula.pour_bottle_check_unsatisfied_reason(reason)
+    @formula.pour_bottle_check_unsatisfied_reason = reason
   end
 
   def satisfy(&block)

Library/Homebrew/test/test_formula.rb

@@ -367,4 +367,42 @@ class FormulaTests < Homebrew::TestCase
     [f1, f2, f3].each(&:clear_cache)
     f3.rack.rmtree
   end
+
+  def test_pour_bottle
+    f_false = formula("foo") do
+      url "foo-1.0"
+      def pour_bottle?
+        false
+      end
+    end
+    refute f_false.pour_bottle?
+
+    f_true = formula("foo") do
+      url "foo-1.0"
+      def pour_bottle?
+        true
+      end
+    end
+    assert f_true.pour_bottle?
+  end
+
+  def test_pour_bottle_dsl
+    f_false = formula("foo") do
+      url "foo-1.0"
+      pour_bottle? do
+        reason "false reason"
+        satisfy { var == etc }
+      end
+    end
+    refute f_false.pour_bottle?
+
+    f_true = formula("foo") do
+      url "foo-1.0"
+      pour_bottle? do
+        reason "true reason"
+        satisfy { var == var }
+      end
+    end
+    assert f_true.pour_bottle?
+  end
 end