Install H3 via native extension if it isn't present. (#45)

Author: seanhandley

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "ext/h3/src"]
+	path = ext/h3/src
+	url = https://github.com/uber/h3.git

.travis.yml

@@ -1,12 +1,3 @@
-install:
-  - git clone https://github.com/uber/h3.git h3_build
-  - pushd h3_build
-  - git checkout v3.3.0
-  - cmake . -DBUILD_SHARED_LIBS=true
-  - make
-  - sudo make install
-  - popd
-  - bundle install
 language: ruby
 cache: bundler
 rvm:

README.md

@@ -24,23 +24,13 @@ We have also suffixed predicate methods with a question mark, as per the Ruby co
 
 This gem uses FFI to link directly into the H3 library (written in C).
 
-Before using the gem, you will need to install the C lib at https://github.com/uber/h3.
+The H3 library is packaged with the gem and is built as a native extension. H3 is not installed system-wide, so it will not interfere with any other versions you may have installed previously.
 
-Install the build dependencies as instructed here: https://github.com/uber/h3#install-build-time-dependencies
-
-Do *not* follow the Compilation Steps. Instead, use the following:
-
-    git clone git@github.com:uber/h3.git h3_build
-    cd h3_build
-    cmake . -DBUILD_SHARED_LIBS=true
-    make
-    sudo make install
-
-The key difference is the `BUILD_SHARED_LIBS` option.
+Before installing the gem, please install the build dependencies for your system as instructed here: https://github.com/uber/h3#install-build-time-dependencies
 
 ## Installing
 
-You can install the gem directly using
+You can install the gem directly from RubyGems.org using
 
     gem install h3
 
@@ -74,11 +64,27 @@ H3.h3_to_geo_boundary("8819429a9dfffff".to_i(16))
 
 ## Documentation
 
-There is a full reference available here: https://www.rubydoc.info/github/StuartApp/h3_ruby/H3
+Please read [the Gem Documentation](https://www.rubydoc.info/github/StuartApp/h3_ruby/H3) for a full reference of available methods.
+
+## Development
+
+The development environment requires the H3 library to be compiled from source before tests can be executed.
+
+This is done automatically by the test suite. However, Rake tasks are provided to handle building H3 in a more fine-grained manner.
+
+### Building H3
+
+    rake build
+
+You can remove the compiled H3 library with `rake clean`, or rebuild it with `rake rebuild`.
+
+### Running Tests
+
+The test suite exercises all the H3 functions.
 
-## Running Specs
+    rake spec
 
-    rake
+Be aware that errors may be encountered if you have a locally cached H3 binary that's older than the version targeted. Try `rake rebuild` and re-run `rake spec` if this occurs.
 
 ## Contributing
 

Rakefile

@@ -1,3 +1,27 @@
 require "rspec/core/rake_task"
 RSpec::Core::RakeTask.new(:spec)
+
+desc "Build H3 C library"
+task :build do
+  unless File.exists?("ext/h3/src/Makefile")
+    `git submodule update --init --recursive`
+    print "Building h3..."
+    `cd ext/h3; make > /dev/null 2>&1`
+    puts " done."
+  end
+end
+
+desc "Remove compiled H3 library"
+task :clean do
+  File.delete("ext/h3/src/Makefile") if File.exists?("ext/h3/src/Makefile")
+  FileUtils.remove_dir("ext/h3/src/bin") if Dir.exists?("ext/h3/src/bin")
+  FileUtils.remove_dir("ext/h3/src/generated") if Dir.exists?("ext/h3/src/generated")
+  FileUtils.remove_dir("ext/h3/src/lib") if Dir.exists?("ext/h3/src/lib")
+end
+
+task spec: :build
+
+desc "Recompile the H3 C library"
+task rebuild: [:clean, :build]
+
 task default: :spec

ext/h3/Makefile

@@ -0,0 +1,6 @@
+make:
+	cd src; cmake . -DBUILD_SHARED_LIBS=true; make
+install:
+	: # do nothing, we'll load the lib directly
+clean:
+	: # do nothing, cleanup happens when gem uninstalled

ext/h3/extconf.rb

@@ -0,0 +1,2 @@
+# Do nothing, Makefile is already made.
+# This file keeps `gem install` happy.

ext/h3/src

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   spec.email    = "l.laycock@stuart.com"
 
   spec.required_ruby_version = "> 2.3"
-  spec.files = `git ls-files`.split("\n")
+  spec.files = `git ls-files --recurse-submodules`.split("\n")
 
   spec.add_runtime_dependency "ffi", "~> 1.9"
   spec.add_runtime_dependency "rgeo-geojson", "~> 2.1"
@@ -19,4 +19,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rspec", "~> 3.8"
   spec.add_development_dependency "yard", "~> 0.9"
   spec.add_development_dependency "coveralls", "~> 0.8"
+
+  spec.extensions << "ext/h3/extconf.rb"
 end

h3.gemspec

@@ -8,7 +8,7 @@ def self.extended(base)
         base.extend FFI::Library
         base.include Structs
         base.include Types
-        base.ffi_lib ["libh3", "libh3.1"]
+        base.ffi_lib ["ext/h3/src/lib/libh3.dylib", "ext/h3/src/lib/libh3.so"]
         base.typedef :ulong_long, :h3_index
         base.typedef :int, :size
         base.typedef :int, :k_distance

lib/h3/bindings/base.rb

@@ -1,7 +1,11 @@
 require "coveralls"
 Coveralls.wear!
 
-require "h3"
+begin
+  require "h3"
+rescue LoadError
+  raise "Could not load h3. Run `rake rebuild` to recompile."
+end
 
 # This file was generated by the `rspec --init` command. Conventionally, all
 # specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.