rcee_packaged_tarball 0.1.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 94aff18604fd7cea4d81c63e7a9d0e0b2033e54033eb0f31dd0e872eac402cf7
-  data.tar.gz: 575d01f6a28b27dc8aed8ea3d2e72407b84c0157ec5045c41ec3d4de56c8a739
+  metadata.gz: 77ace21c823e931cb6e7d7feeed01351e8f8c67240c362868d948bb2933afff6
+  data.tar.gz: 16ca21fe014c181139dd5a0af35ee0720544c6e50c44238985ccd9e782ef2473
 SHA512:
-  metadata.gz: cbe2df47548769b59d5ae37783285d842e3c5cca5a8dfd1a34c5e0bc3a150d1f98792acec9603da482e99674f76888242d89d4882329c2d7dc030a676fc122dc
-  data.tar.gz: 51a64ecd816d0efd538ff654961a67af87cc6703c347a2bae8fe0080bf980abb9006cc4f1ddfa1b61c0b8b0c6a2e789ad5f9cbc8d3260fce21deff8901c19820
+  metadata.gz: 817725162179cd2ec67413d5eebae0bc5281113fce750d5bf0c1a635f71a87d79d3d9fec9c26f735f90a4febd2b2bd03621b906f65c51439279c842db29d5257
+  data.tar.gz: 9a778aba66c002986cea504b81621f1ba727be16f8a4ee8b729f72fc1018403479b2a44162a1e014b46c0af38f9f0d04ed053249333eba0528f8e8c19ce68ce4

data/README.md

@@ -1,2 +1,73 @@
+# RCEE::PackagedTarball
 
 This gem is part of the Ruby C Extensions Explained project at https://github.com/flavorjones/ruby-c-extensions-explained
+
+## Summary
+
+Many third-party libraries have their own build process based on tools like "autoconf" or "cmake". For those libraries, it might be really challenging to just copy the C files and let MakeMakefile compile them. In those situations, it's possible to package the entire upstream tarball and use that at installation time.
+
+
+## Details
+
+An important tool that we rely on for building third-party libraries is [`flavorjones/mini_portile`](https://github.com/flavorjones/mini_portile). It is able to configure a tarball distribution that relies on "autoconf" or "cmake" and compile it into a library that we can link against.
+
+We add the tarball to the gemspec so that it's packaged with the rest of the gem:
+
+``` ruby
+Gem::Specification.new do |spec|
+  # ...
+  spec.files         << "ports/archives/yaml-0.2.5.tar.gz"
+  # ...
+end
+```
+
+The `extconf.rb` contains a new block:
+
+``` ruby
+MiniPortile.new("yaml", "0.2.5").tap do |recipe|
+  recipe.target = File.join(package_root_dir, "ports")
+  recipe.files = [{
+    url: "https://github.com/yaml/libyaml/releases/download/0.2.5/yaml-0.2.5.tar.gz",
+    sha256: "c642ae9b75fee120b2d96c712538bd2cf283228d2337df2cf2988e3c02678ef4",
+  }]
+
+  unless File.exist?(File.join(recipe.target, recipe.host, recipe.name, recipe.version))
+    recipe.cook
+  end
+
+  recipe.activate
+  pkg_config(File.join(recipe.path, "lib", "pkgconfig", "yaml-0.1.pc"))
+end
+```
+
+This block:
+
+- downloads the libyaml tarball if necessary (note that the packaged gem includes the tarball and so this is skipped by end users during `gem install`)
+- verifies the checksum of the tarball
+- extracts the tarball
+- configures the build system (for libyaml, this is "autoconf")
+- compile libyaml's source code into object files
+- link the object files together into a library we can use
+- configure `MakeMakefile` to find the headers and the library
+
+(Of special note, we're able to use `pkgconfig` to do much of our extension configuration, which allows us to have a pretty clean configuration. This is one advantage to using upstream distributions.)
+
+Note that all of those steps happen *before* the Makefile is created -- it's run by `extconf.rb` so that the Makefile will know where to find our libyaml files.
+
+
+## Testing
+
+See [.github/workflows/packaged_source.yml](../.github/workflows/packaged_source.yml)
+
+Key things to note:
+
+- matrix across all supported Rubies and platforms
+- caching the compiled library speeds up builds as well as avoids re-downloading the tarball over and over
+  - note that the cache key includes the platform and the hash of extconf.rb
+
+
+## What Can Go Wrong
+
+If you run `gem install rcee_packaged_tarball` and see this in action, You'll note that PackagedTarball is significantly slower than PackagedSource, and that's because MiniPortile is running additional configuration steps to build the library.
+
+Maintainers now have an additional responsibility to keep that library up-to-date and secure for your users.

data/Rakefile

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-require "rake/testtask"
 require "rubygems/package_task"
+require "rake/testtask"
+require "rake/extensiontask"
 
 rcee_packaged_tarball_spec = Bundler.load_gemspec("rcee_packaged_tarball.gemspec")
 Gem::PackageTask.new(rcee_packaged_tarball_spec).define
@@ -13,15 +14,17 @@ Rake::TestTask.new(:test) do |t|
   t.test_files = FileList["test/**/*_test.rb"]
 end
 
-require "rake/extensiontask"
-
-task build: :compile
-
 Rake::ExtensionTask.new("packaged_tarball") do |ext|
   ext.lib_dir = "lib/rcee/packaged_tarball"
 end
 
-task default: %i[clobber compile test]
+task default: [:clobber, :compile, :test]
 
+CLEAN.add("{ext,lib}/**/*.{o,so}", "pkg")
 CLOBBER.add("ports")
-CLEAN.add("{ext,lib}/**/*.{o,so}")
+
+# when packaging the gem, if the tarball isn't cached, we need to fetch it. the easiest thing to do
+# is to run the compile phase to invoke the extconf and have mini_portile download the file for us.
+# this is wasteful and in the future I would prefer to separate mini_portile from the extconf to
+# allow us to download without compiling.
+Rake::Task["package"].prerequisites.prepend("compile")

data/lib/rcee/packaged_tarball/version.rb

@@ -2,6 +2,6 @@
 
 module RCEE
   module PackagedTarball
-    VERSION = "0.1.0"
+    VERSION = "0.4.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rcee_packaged_tarball
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Mike Dalessio
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-09-02 00:00:00.000000000 Z
+date: 2022-05-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mini_portile2
@@ -62,7 +62,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.15
+rubygems_version: 3.3.5
 signing_key: 
 specification_version: 4
 summary: Example gem demonstrating a basic C extension.