rcee_system 0.1.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7c664ec9bf7164bf409808c01388459d95b09eb9612b71c68297d930ea9d350
-  data.tar.gz: 3a8f12c1501e564f82d9c263cf4945c8bb689c8955b09b5dd9b1ead95358cf45
+  metadata.gz: 3d9c342d9489450f8b80b156619a98decb058a71acf2e6a2c36ec4cde5dda441
+  data.tar.gz: ac9f4c41b3acf1d0a1aec013f91b6ed08ca8ef43874103d72cca93cbf60214e9
 SHA512:
-  metadata.gz: a68f4616208fb9d39417fc8bca4568fd15b39e6b809756c21be58dc127e4109b48a7377b9f64b8a5e149fdc47df0712f4b03ab508c3d4f8e0fa94f0c33ac08b2
-  data.tar.gz: 38b2296af87d4182f66a2926191c1858fcb5c0c95cb9521f15f7845c69b2a2c3fc79fe8356e8e399e6ce7be23aa88fc8e226a0a72d1b089a58f0354681c6f3fa
+  metadata.gz: b83a0f8d28252951cd5dfc5b799210791667edaf57e1452cda34d09cb2f5e1b73333152e409492ae8c3f2b2b1b213f83873c97519b30d10392a8b1d1c1ce2c30
+  data.tar.gz: 2f7a57d86c58a7d8e3500f757d73c7115acb764ea417406b100fe5a8d9992d88a3e9846772a9dd65accbbfa1fb445b2027ba2b5509aae322a7d89511a9426c95

data/README.md

@@ -1,2 +1,102 @@
+# RCEE::System
 
 This gem is part of the Ruby C Extensions Explained project at https://github.com/flavorjones/ruby-c-extensions-explained
+
+## Context
+
+In the `isolated` gem, I mentioned that one goal of a C extension might be to optimize performance. This is the case for BCrypt.
+
+But there's another, more common, reason to write a C extension, which is to talk to a third-party library. Many Ruby gems use C extensions solely to integrate with a third-party library. Some examples:
+
+- nokogiri → libxml2, libxslt, libgumbo
+- psych → libyaml
+- sqlite3 → libsqlite3
+- rmagick → libMagick
+- grpc → libgrpc
+
+These gems have a thin-ish wrapper of Ruby and C that work together to make the library's features available as idiomatic Ruby.
+
+
+## Summary
+
+This gem, as well as all the following gems, will call `libyaml` as an example third-party integration, and will require that `libyaml` be installed ahead of time on the target system.
+
+Some real-world gems that use this "system" strategy are ruby-sqlite3 and rmagick.
+
+
+## Details
+
+This gem's C code is located in `ext/system/system.c`:
+
+``` C
+static VALUE
+rb_system_extension_class_do_something(VALUE self)
+{
+  int major, minor, patch;
+
+  yaml_get_version(&major, &minor, &patch);
+
+  return rb_sprintf("libyaml version %d.%d.%d", major, minor, patch);
+}
+```
+
+That's pretty simple, but is enough to demonstrate the integration with `libyaml` works.
+
+The `extconf.rb` is still simple (and similar to `isolated/ext/isolated/extconf.rb` but contains this additional block:
+
+``` ruby
+unless find_header("yaml.h") && find_library("yaml", "yaml_get_version")
+  abort("\nERROR: *** could not find libyaml development environment ***\n\n")
+end
+```
+
+`find_header` and `find_library` are `MakeMakefile` helper methods which will search your system's standard directories looking for files. If it finds them, it makes sure the compile step will be able to find `yaml.h`, and the link step will be able to find the `libyaml` library file.
+
+We ask `find_header` to look for the `yaml.h` header file because that's what our C code needs (see `ext/system/system.h`). We ask `find_library` to look for a library named `libyaml` and check that it has the function `yaml_get_version()` defined in it.
+
+(We don't need to call `find_library` for every function we intend to use; we just need to provide one function from the library so that `MakeMakefile` can verify that linking will succeed.)
+
+If these methods succeed, the `Makefile` recipe looks something like this. Note the include directory is added for the compile step, and the library directory and name are added to the link step.
+
+``` sh
+# `create_makefile` recipe is something like this
+
+# compile phase:
+gcc -c -I/path/to/ruby/include -I/path/to/libyaml/include system.c -o system.o
+
+# link phase:
+gcc -shared \
+  -L/path/to/ruby/lib -lruby \
+  -L/path/to/libyaml/lib -lyaml \
+  -lc -lm \
+  system.o -o system.so
+```
+
+If you run `ldd` on the generated `system.so` you should see `libyaml` listed, something like:
+
+``` text
+	libyaml-0.so.2 => /usr/lib/x86_64-linux-gnu/libyaml-0.so.2 (0x00007f345a3dc000)
+```
+
+
+## Testing
+
+See [.github/workflows/system.yml](../.github/workflows/system.yml)
+
+Key things to note:
+
+- matrix across all supported Rubies and platforms
+- use the github action `MSP-Greg/setup-ruby-pkgs@v1` to install system libraries on each platform
+
+
+## What Can Go Wrong
+
+In addition to what's enumerated in `isolated`'s README ...
+
+If `MakeMakefile` methods fail to find the third-party library (or fail to compile and link against it), then the user will see an error message, and have to go figure out how to install `libyaml` on their system.
+
+If the third-party library is installed into non-standard directories by the package manager, your `extconf.rb` may need special logic. `rmagick` needs to do a lot of this.
+
+If the third-party library has compile-time flags to control whether features are turned on or off, then your `extconf.rb` may need to test for that with `have_func` and your C code will need to handle the case where those methods aren't implemented.
+
+The version of the third-party library may be older or newer than you expected, and either contain bugs or be missing new features, which also require additional code complexity.

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_system_spec = Bundler.load_gemspec("rcee_system.gemspec")
 Gem::PackageTask.new(rcee_system_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("system") do |ext|
   ext.lib_dir = "lib/rcee/system"
 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/system/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rcee_system
 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: []
 description: Part of a project to explain how Ruby C extensions work.
 email:
@@ -47,7 +47,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.