rcee_system 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7c664ec9bf7164bf409808c01388459d95b09eb9612b71c68297d930ea9d350
-  data.tar.gz: 3a8f12c1501e564f82d9c263cf4945c8bb689c8955b09b5dd9b1ead95358cf45
+  metadata.gz: ff7148e3553b2213be8a833e3beeae61df65c8f8a11be133b30377d1152d8c17
+  data.tar.gz: c9247be0c803ca52871abec835d0a13bcdb8ff46bc8fc9656dfcae948bc210a6
 SHA512:
-  metadata.gz: a68f4616208fb9d39417fc8bca4568fd15b39e6b809756c21be58dc127e4109b48a7377b9f64b8a5e149fdc47df0712f4b03ab508c3d4f8e0fa94f0c33ac08b2
-  data.tar.gz: 38b2296af87d4182f66a2926191c1858fcb5c0c95cb9521f15f7845c69b2a2c3fc79fe8356e8e399e6ce7be23aa88fc8e226a0a72d1b089a58f0354681c6f3fa
+  metadata.gz: a5346e5943f665665b4837a0602e55064e21fcb0d21bc47f808e9b5099cb94f1549e9a81ba8434242486b0666287f1f3da73dd94458e7708e37a94e2fb2788a9
+  data.tar.gz: 119bc1e5b65c1d07296e386ece1e3361f5b25827adb14d43ac693e23f319293191d0b7ce1ed567fdab5215c288af2c50e97dc6c5c5af7651df1f1ed2270d59ab

data/README.md

@@ -1,2 +1,91 @@
+# 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)
+```
+
+## 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.2.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.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:
@@ -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.2.22
 signing_key: 
 specification_version: 4
 summary: Example gem demonstrating a basic C extension.