rcee_isolated 0.1.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad8122cd8fd59ce71a825faa743476782c16b974640d27c315ee00faf744cf85
-  data.tar.gz: cd588fadacc9fed33249b6fae408ebd4fb2102e0e4a39574ae8566a3ff885096
+  metadata.gz: a461114de18644d5643fec8675602da79ed21c98eaa5cc243ec2bd9083993ac2
+  data.tar.gz: b0136c5e723c9320a8fdfb8d67cee80a23ffa9e553ac8d096fb0e66b1c0a88b9
 SHA512:
-  metadata.gz: 33ef24a02739be741e0898789a710103c0bfa5a7957302b1316b23acabf07cc2b7ec20bc93a82e26a05f89a62b8ee93e9b2660786bad1c01a8c2d50eefa8b4fc
-  data.tar.gz: 35470156add2382ee65bcf9e7ec67e2410438aa320886fad76b42350fa2cdcb1c0c161bf0e7e5a71ee0368113c38873d6a1526f87547e1655f54efb3a8e244ea
+  metadata.gz: abbe234ceba963dc030105db2d81f789b5969d52e9e84442160ff24709c672339b0a7648fbe43c367a4a6fa09489cca1edb47dab855573bfa96746703347adb1
+  data.tar.gz: 2cabbe4af51adb65e4a5a7b807daf505031e5e0ed0b9facbc3878c38a9ac928821d85b4ffb92d9e48b6dd0c2674dc14f02c7b553808e81dfeabec6ed0c9ecb0d

data/README.md

@@ -1,2 +1,78 @@
+# RCEE::Isolated
 
 This gem is part of the Ruby C Extensions Explained project at https://github.com/flavorjones/ruby-c-extensions-explained
+
+## Summary
+
+This is the simplest viable C extension gem. It's named "Isolated" it's entirely self-contained, and doesn't call any external libraries.
+
+You might choose to write a C extension like this as a performance optimization if you have some CPU-intensive work to do. The BCrypt gem is a good example of this kind of C extension -- it's iterating over cryptographic math which is simply faster in C than it would be in Ruby.
+
+## Details
+
+This gem's C code is located in `ext/isolated/isolated.c` and includes this singleton method:
+
+``` C
+static VALUE
+rb_isolated_extension_class_do_something(VALUE self)
+{
+  /* todo: perform CPU-intensive operation */
+  return rb_str_new_cstr("something has been done");
+}
+
+void
+Init_isolated(void)
+{
+  rb_mRCEE = rb_define_module("RCEE");
+  rb_mIsolated = rb_define_module_under(rb_mRCEE, "Isolated");
+  rb_cIsolatedExtension = rb_define_class_under(rb_mIsolated, "Extension", rb_cObject);
+  rb_define_singleton_method(rb_cIsolatedExtension, "do_something",
+                             rb_isolated_extension_class_do_something, 0);
+}
+```
+
+The `extconf.rb` is as simple as it gets:
+
+``` ruby
+require "mkmf"
+
+create_makefile("rcee/isolated/isolated")
+```
+
+"mkmf" is short for MakeMakefile, a Ruby module that's shipped with the standard library. It defines "create_makefile" as well as a handful of other methods for advanced configuration, some of which we'll see in later examples.
+
+The "create_makefile" method is what actually writes the recipe for _compiling_ and _linking_. Because we haven't configured anything, it's going to adopt a set of reasonable defaults.
+
+The output `Makefile` is long and complex, but the recipe it implements is relatively simple and does something like:
+
+``` sh
+# `create_makefile` recipe is something like this
+
+# compile phase:
+gcc -c -I/path/to/ruby/include isolated.c -o isolated.o
+
+# link phase:
+gcc -shared -L/path/to/ruby/lib -lruby -lc -lm isolated.o -o isolated.so
+```
+
+That final shared library, `isolated.so`, is loaded like any other Ruby file, via `require` in `lib/rcee/isolated.rb`:
+
+``` ruby
+require_relative "isolated/isolated"
+```
+
+## Testing
+
+See [.github/workflows/isolated.yml](../.github/workflows/isolated.yml)
+
+Key things to note:
+
+- matrix across all supported versions of Ruby
+- matrix across all supported platforms
+
+
+## What Can Go Wrong
+
+1. Users don't have the compiler toolchain installed (`gcc`, `ld`, `stdio.h`, `libc.so`, etc.)
+2. Users don't have the ruby development files installed (`ruby.h`, etc.)
+3. Users try to use the compiled extension on a different minor version of Ruby, a different CPU architecture, or a different operating system.

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_isolated_spec = Bundler.load_gemspec("rcee_isolated.gemspec")
 Gem::PackageTask.new(rcee_isolated_spec).define
@@ -13,12 +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("isolated") do |ext|
   ext.lib_dir = "lib/rcee/isolated"
 end
 
-task default: %i[clobber compile test]
+task default: [:clobber, :compile, :test]
+
+CLEAN.add("{ext,lib}/**/*.{o,so}", "pkg")

data/lib/rcee/isolated/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rcee_isolated
 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.