Merge pull request #9 from malept/optional-rust-extension

Add optional_rust_extension option

Author: malept

NEWS.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+### Added
+
+* `optional_rust_extension` option - prints a warning to STDERR instead of raising an exception, if
+  Cargo is unavailable and `github_releases` is either disabled or unavailable. Useful for projects
+  where either fallback code exists, or a native extension is desirable but not required. (#4, #6)
+
 ## [0.5.0] - 2016-07-18
 
 ### Added

README.md

@@ -60,6 +60,10 @@ Possible options:
   precompiled Rust tarballs. One group must be specified that indicates the version number to be
   used in the tarball filename. Defaults to `vN.N.N`, where `N` is any n-digit number. In this case,
   the group is around the entire expression.
+* `optional_rust_extension` - prints a warning to STDERR instead of raising an exception, if Cargo
+  is unavailable and `github_releases` is either disabled or unavailable. Useful for projects where
+  either fallback code exists, or a native extension is desirable but not required. Defaults
+  to `false`.
 * `ruby_project_path` - the top-level directory of the Ruby gem's project. Defaults to the
   current working directory.
 

lib/thermite/cargo.rb

@@ -58,18 +58,43 @@ def run_cargo_build(target)
       run_cargo(*cargo_args)
     end
 
-    # :nocov:
+    #
+    # Inform the user about cargo if it doesn't exist.
+    #
+    # If `optional_rust_extension` is true, print message to STDERR. Otherwise, raise an exception.
+    #
+    def inform_user_about_cargo
+      raise cargo_required_msg unless options[:optional_rust_extension]
+
+      $stderr.write(cargo_recommended_msg)
+    end
 
     #
-    # Message used when cargo is required but not found.
+    # Message used when cargo is not found.
     #
-    def cargo_required_msg
+    # `require_severity` is the verb that indicates how important Rust is to the library.
+    #
+    def cargo_msg(require_severity)
       <<EOM
 ****
-Rust's Cargo is required to build this extension. Please install Rust and put
-it in the PATH, or set the CARGO environment variable appropriately.
+Rust's Cargo is #{require_severity} to build this extension. Please install
+Rust and put it in the PATH, or set the CARGO environment variable appropriately.
 ****
 EOM
     end
+
+    #
+    # Message used when cargo is required but not found.
+    #
+    def cargo_required_msg
+      cargo_msg('required')
+    end
+
+    #
+    # Message used when cargo is recommended but not found.
+    #
+    def cargo_recommended_msg
+      cargo_msg('recommended (but not required)')
+    end
   end
 end

lib/thermite/tasks.rb

@@ -70,6 +70,10 @@ class Tasks < Rake::TaskLib
     #   releases to look for precompiled Rust tarballs. One group must be specified that indicates
     #   the version number to be used in the tarball filename. Defaults to `vN.N.N`, where `N` is
     #   any n-digit number. In this case, the group is around the entire expression.
+    # * `optional_rust_extension` - prints a warning to STDERR instead of raising an exception, if
+    #   Cargo is unavailable and `github_releases` is either disabled or unavailable. Useful for
+    #   projects where either fallback code exists, or a native extension is desirable but not
+    #   required. Defaults to `false`.
     # * `ruby_project_path` - the toplevel directory of the Ruby gem's project. Defaults to the
     #   current working directory.
     #
@@ -109,7 +113,7 @@ def define_build_task
           FileUtils.cp(config.rust_path('target', target, config.shared_library),
                        config.ruby_path('lib'))
         elsif !download_binary
-          raise cargo_required_msg
+          inform_user_about_cargo
         end
       end
     end

test/lib/thermite/cargo_test.rb

@@ -32,6 +32,24 @@ def test_run_cargo_release_build
       mock_module.run_cargo_build('release')
     end
 
+    def test_inform_user_about_cargo_exception
+      _, err = capture_io do
+        assert_raises RuntimeError do
+          mock_module(optional_rust_extension: false).inform_user_about_cargo
+        end
+      end
+
+      assert_equal '', err
+    end
+
+    def test_inform_user_about_cargo_warning
+      _, err = capture_io do
+        mock_module(optional_rust_extension: true).inform_user_about_cargo
+      end
+
+      assert_equal mock_module.cargo_recommended_msg, err
+    end
+
     def described_class
       Tester
     end