rcee_packaged_tarball 0.1.0 → 0.4.0

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 94aff18604fd7cea4d81c63e7a9d0e0b2033e54033eb0f31dd0e872eac402cf7
4
- data.tar.gz: 575d01f6a28b27dc8aed8ea3d2e72407b84c0157ec5045c41ec3d4de56c8a739
3
+ metadata.gz: 77ace21c823e931cb6e7d7feeed01351e8f8c67240c362868d948bb2933afff6
4
+ data.tar.gz: 16ca21fe014c181139dd5a0af35ee0720544c6e50c44238985ccd9e782ef2473
5
5
  SHA512:
6
- metadata.gz: cbe2df47548769b59d5ae37783285d842e3c5cca5a8dfd1a34c5e0bc3a150d1f98792acec9603da482e99674f76888242d89d4882329c2d7dc030a676fc122dc
7
- data.tar.gz: 51a64ecd816d0efd538ff654961a67af87cc6703c347a2bae8fe0080bf980abb9006cc4f1ddfa1b61c0b8b0c6a2e789ad5f9cbc8d3260fce21deff8901c19820
6
+ metadata.gz: 817725162179cd2ec67413d5eebae0bc5281113fce750d5bf0c1a635f71a87d79d3d9fec9c26f735f90a4febd2b2bd03621b906f65c51439279c842db29d5257
7
+ data.tar.gz: 9a778aba66c002986cea504b81621f1ba727be16f8a4ee8b729f72fc1018403479b2a44162a1e014b46c0af38f9f0d04ed053249333eba0528f8e8c19ce68ce4
data/README.md CHANGED
@@ -1,2 +1,73 @@
1
+ # RCEE::PackagedTarball
1
2
 
2
3
  This gem is part of the Ruby C Extensions Explained project at https://github.com/flavorjones/ruby-c-extensions-explained
4
+
5
+ ## Summary
6
+
7
+ 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.
8
+
9
+
10
+ ## Details
11
+
12
+ 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.
13
+
14
+ We add the tarball to the gemspec so that it's packaged with the rest of the gem:
15
+
16
+ ``` ruby
17
+ Gem::Specification.new do |spec|
18
+ # ...
19
+ spec.files << "ports/archives/yaml-0.2.5.tar.gz"
20
+ # ...
21
+ end
22
+ ```
23
+
24
+ The `extconf.rb` contains a new block:
25
+
26
+ ``` ruby
27
+ MiniPortile.new("yaml", "0.2.5").tap do |recipe|
28
+ recipe.target = File.join(package_root_dir, "ports")
29
+ recipe.files = [{
30
+ url: "https://github.com/yaml/libyaml/releases/download/0.2.5/yaml-0.2.5.tar.gz",
31
+ sha256: "c642ae9b75fee120b2d96c712538bd2cf283228d2337df2cf2988e3c02678ef4",
32
+ }]
33
+
34
+ unless File.exist?(File.join(recipe.target, recipe.host, recipe.name, recipe.version))
35
+ recipe.cook
36
+ end
37
+
38
+ recipe.activate
39
+ pkg_config(File.join(recipe.path, "lib", "pkgconfig", "yaml-0.1.pc"))
40
+ end
41
+ ```
42
+
43
+ This block:
44
+
45
+ - 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`)
46
+ - verifies the checksum of the tarball
47
+ - extracts the tarball
48
+ - configures the build system (for libyaml, this is "autoconf")
49
+ - compile libyaml's source code into object files
50
+ - link the object files together into a library we can use
51
+ - configure `MakeMakefile` to find the headers and the library
52
+
53
+ (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.)
54
+
55
+ 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.
56
+
57
+
58
+ ## Testing
59
+
60
+ See [.github/workflows/packaged_source.yml](../.github/workflows/packaged_source.yml)
61
+
62
+ Key things to note:
63
+
64
+ - matrix across all supported Rubies and platforms
65
+ - caching the compiled library speeds up builds as well as avoids re-downloading the tarball over and over
66
+ - note that the cache key includes the platform and the hash of extconf.rb
67
+
68
+
69
+ ## What Can Go Wrong
70
+
71
+ 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.
72
+
73
+ Maintainers now have an additional responsibility to keep that library up-to-date and secure for your users.
data/Rakefile CHANGED
@@ -1,8 +1,9 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  require "bundler/gem_tasks"
4
- require "rake/testtask"
5
4
  require "rubygems/package_task"
5
+ require "rake/testtask"
6
+ require "rake/extensiontask"
6
7
 
7
8
  rcee_packaged_tarball_spec = Bundler.load_gemspec("rcee_packaged_tarball.gemspec")
8
9
  Gem::PackageTask.new(rcee_packaged_tarball_spec).define
@@ -13,15 +14,17 @@ Rake::TestTask.new(:test) do |t|
13
14
  t.test_files = FileList["test/**/*_test.rb"]
14
15
  end
15
16
 
16
- require "rake/extensiontask"
17
-
18
- task build: :compile
19
-
20
17
  Rake::ExtensionTask.new("packaged_tarball") do |ext|
21
18
  ext.lib_dir = "lib/rcee/packaged_tarball"
22
19
  end
23
20
 
24
- task default: %i[clobber compile test]
21
+ task default: [:clobber, :compile, :test]
25
22
 
23
+ CLEAN.add("{ext,lib}/**/*.{o,so}", "pkg")
26
24
  CLOBBER.add("ports")
27
- CLEAN.add("{ext,lib}/**/*.{o,so}")
25
+
26
+ # when packaging the gem, if the tarball isn't cached, we need to fetch it. the easiest thing to do
27
+ # is to run the compile phase to invoke the extconf and have mini_portile download the file for us.
28
+ # this is wasteful and in the future I would prefer to separate mini_portile from the extconf to
29
+ # allow us to download without compiling.
30
+ Rake::Task["package"].prerequisites.prepend("compile")
@@ -2,6 +2,6 @@
2
2
 
3
3
  module RCEE
4
4
  module PackagedTarball
5
- VERSION = "0.1.0"
5
+ VERSION = "0.4.0"
6
6
  end
7
7
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: rcee_packaged_tarball
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.0
4
+ version: 0.4.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Mike Dalessio
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2021-09-02 00:00:00.000000000 Z
11
+ date: 2022-05-19 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: mini_portile2
@@ -62,7 +62,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
62
62
  - !ruby/object:Gem::Version
63
63
  version: '0'
64
64
  requirements: []
65
- rubygems_version: 3.2.15
65
+ rubygems_version: 3.3.5
66
66
  signing_key:
67
67
  specification_version: 4
68
68
  summary: Example gem demonstrating a basic C extension.