rcee_packaged_source 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 686b2f51bd7132f8cab034537021eff6d0d7a8f55dcba6a0debbd215013dd52e
-  data.tar.gz: fe02154ea87d2120a53e9300be68e17d31d6ae164cdaeb714d354aa27bfbb621
+  metadata.gz: e0df51eb6ab06d9d2ba927b2fdd31012f176f52eaa9564c2f4f5727726ad5d28
+  data.tar.gz: 93967b78bc17354ca1375fd0375c541aab6b1317f9b677ecee3cefc7ab4a6ebb
 SHA512:
-  metadata.gz: 40b4a7914ed11fca26e482b684722695fab407bbdc21917381734faeae25830db33f14624ce511b21225fbcc15ea6874421fb69ca7c7189e56ee21e3d9cf8090
-  data.tar.gz: db3681fa1fb201f4c879ba2e298a8073cab624facbf5b0e08f71ff8a564eb0a9afa85e047808940532fdc854b9ac83c4770681a0f1952ad52ab858feb4a3da2e
+  metadata.gz: ccccd66db676cfbab807fede1d48e1fcf13ea988af7aada56f68160590e05b34949fb5fb6dd260c5ea4897b89e664bb207e885d50379bd651dbc995caf74cb15
+  data.tar.gz: 6490bb71e469eef7be4c8418b52b82397d84fcc85a62ea3ae3dc6bb388c41ac47be3d788f7767df757f65250d81b5c15c6baafe41a7b3545f0243e23a5a4cbff

data/README.md

@@ -1,2 +1,84 @@
+# RCEE::PackagedSource
 
 This gem is part of the Ruby C Extensions Explained project at https://github.com/flavorjones/ruby-c-extensions-explained
+
+## Summary
+
+Some gems, like nokogumbo and psych, include the third-party library's C files.
+
+This means the gem is *redistributing* the library -- so be careful with licensing implications if you do this. Packaging third-party libraries is a little more work for gem maintainers to set up, but may simplify your codebase and make installation more reliable.
+
+
+## Details
+
+This gem has simply copied the source files from `libyaml`, along with that library's LICENSE file, into the extensions directory:
+
+``` text
+ext/
+└── packaged_source
+    ├── extconf.rb
+    ├── packaged_source.c
+    ├── packaged_source.h
+    └── yaml
+        ├── LICENSE
+        ├── api.c
+        ├── config.h
+        ├── dumper.c
+        ├── emitter.c
+        ├── loader.c
+        ├── parser.c
+        ├── reader.c
+        ├── scanner.c
+        ├── writer.c
+        ├── yaml.h
+        └── yaml_private.h
+```
+
+The `extconf.rb` contains some new code:
+
+``` ruby
+$VPATH << "$(srcdir)/yaml"
+$srcs = Dir.glob("#{$srcdir}/{,yaml/}*.c").map { |n| File.basename(n) }.sort
+append_cppflags("-I$(srcdir)/yaml")
+
+find_header("yaml.h")
+have_header("config.h")
+```
+
+It first configures `MakeMakefile` to pay attention to the `./yaml` directory as well as the C and header files. It then verifies that `yaml.h` can be found (we could skip this since we're packing it and setting the include path manually). Finally, a libyaml-specific action is taken which is to make sure `config.h` can be found and that the `HAVE_CONFIG_H` macro is set so that `yaml.h` is compiled properly.
+
+The `Makefile` recipe looks something like:
+
+``` sh
+# `create_makefile` recipe is something like this
+
+# compile phase:
+gcc -c -I/path/to/ruby/include -I/path/to/libyaml/include packaged_source.c -o packaged_source.o
+gcc -c -I/path/to/ruby/include -I/path/to/libyaml/include yaml/api.c -o api.o
+gcc -c -I/path/to/ruby/include -I/path/to/libyaml/include yaml/dumper.c -o dumper.o
+gcc -c -I/path/to/ruby/include -I/path/to/libyaml/include yaml/emitter.c -o emitter.o
+gcc -c -I/path/to/ruby/include -I/path/to/libyaml/include yaml/loader.c -o loader.o
+gcc -c -I/path/to/ruby/include -I/path/to/libyaml/include yaml/parser.c -o parser.o
+gcc -c -I/path/to/ruby/include -I/path/to/libyaml/include yaml/reader.c -o reader.o
+gcc -c -I/path/to/ruby/include -I/path/to/libyaml/include yaml/scanner.c -o scanner.o
+gcc -c -I/path/to/ruby/include -I/path/to/libyaml/include yaml/writer.c -o writer.o
+
+# link phase:
+gcc -shared \
+  -L/path/to/ruby/lib -lruby \
+  -lyaml \
+  -lc -lm \
+  packaged_source.o api.o dumper.o emitter.o loader.o parser.o reader.o scanner.o writer.o \
+  -o packaged_source.so
+```
+
+Now we're able to rely on a specific version of the library existing with known configuration, allowing us to avoid much real-world complexity in our `extconf.rb`, and our code.
+
+
+## What Can Go Wrong
+
+In addition to what's enumerated in `isolated`'s README ...
+
+This strategy works pretty well for simple cases, but looking at the recipe, we can see that the libyaml code is being treated as if it were part of the Ruby C extension that we wrote. That's limiting, because the same compilation step must be shared across the extension code and the third-party library, and we need to be careful about filename collisions between the two filesets.
+
+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_source_spec = Bundler.load_gemspec("rcee_packaged_source.gemspec")
 Gem::PackageTask.new(rcee_packaged_source_spec).define
@@ -13,14 +14,10 @@ Rake::TestTask.new(:test) do |t|
   t.test_files = FileList["test/**/*_test.rb"]
 end
 
-require "rake/extensiontask"
-
-task build: :compile
-
 Rake::ExtensionTask.new("packaged_source") do |ext|
   ext.lib_dir = "lib/rcee/packaged_source"
 end
 
-task default: %i[clobber compile test]
+task default: [:clobber, :compile, :test]
 
-CLEAN.add("{ext,lib}/**/*.{o,so}")
+CLEAN.add("{ext,lib}/**/*.{o,so}", "pkg")

data/lib/rcee/packaged_source/version.rb

@@ -2,6 +2,6 @@
 
 module RCEE
   module PackagedSource
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rcee_packaged_source
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Mike Dalessio
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-09-02 00:00:00.000000000 Z
+date: 2021-09-10 00:00:00.000000000 Z
 dependencies: []
 description: Part of a project to explain how Ruby C extensions work.
 email:
@@ -59,7 +59,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.15
+rubygems_version: 3.2.22
 signing_key: 
 specification_version: 4
 summary: Example gem demonstrating a basic C extension.