rcee_isolated 0.1.0 → 0.2.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: ad8122cd8fd59ce71a825faa743476782c16b974640d27c315ee00faf744cf85
4
- data.tar.gz: cd588fadacc9fed33249b6fae408ebd4fb2102e0e4a39574ae8566a3ff885096
3
+ metadata.gz: 42393b90ddea6af44b1f2b15f2229d8150f89765c78d5525ecc0440fceae9fd6
4
+ data.tar.gz: 0dcf55216f2f664b52fe758c53e3913ed216286a70249ac3ee29fe94e537ecc2
5
5
  SHA512:
6
- metadata.gz: 33ef24a02739be741e0898789a710103c0bfa5a7957302b1316b23acabf07cc2b7ec20bc93a82e26a05f89a62b8ee93e9b2660786bad1c01a8c2d50eefa8b4fc
7
- data.tar.gz: 35470156add2382ee65bcf9e7ec67e2410438aa320886fad76b42350fa2cdcb1c0c161bf0e7e5a71ee0368113c38873d6a1526f87547e1655f54efb3a8e244ea
6
+ metadata.gz: a942c785098df4d6759c448b9339c4f79506db9d8edafa9b3fad2e621fc744982e86b69e5e3b7d958a4305691fb75fa64f475814479a20399c1d3434c10897f9
7
+ data.tar.gz: 3a7bbe5ac6df9f8db7efce664951720831783a0a2e67c3196d6546b20f7816e82cbb4e1bff8352c5ce71799020dae0c9a6d73d7fce1321b6360618a3c6038ae9
data/README.md CHANGED
@@ -1,2 +1,68 @@
1
+ # RCEE::Isolated
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
+ This is the simplest viable C extension gem. It's named "Isolated" it's entirely self-contained, and doesn't call any external libraries.
8
+
9
+ 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.
10
+
11
+ ## Details
12
+
13
+ This gem's C code is located in `ext/isolated/isolated.c` and includes this singleton method:
14
+
15
+ ``` C
16
+ static VALUE
17
+ rb_isolated_extension_class_do_something(VALUE self)
18
+ {
19
+ /* todo: perform CPU-intensive operation */
20
+ return rb_str_new_cstr("something has been done");
21
+ }
22
+
23
+ void
24
+ Init_isolated(void)
25
+ {
26
+ rb_mRCEE = rb_define_module("RCEE");
27
+ rb_mIsolated = rb_define_module_under(rb_mRCEE, "Isolated");
28
+ rb_cIsolatedExtension = rb_define_class_under(rb_mIsolated, "Extension", rb_cObject);
29
+ rb_define_singleton_method(rb_cIsolatedExtension, "do_something",
30
+ rb_isolated_extension_class_do_something, 0);
31
+ }
32
+ ```
33
+
34
+ The `extconf.rb` is as simple as it gets:
35
+
36
+ ``` ruby
37
+ require "mkmf"
38
+
39
+ create_makefile("rcee/isolated/isolated")
40
+ ```
41
+
42
+ "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.
43
+
44
+ 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.
45
+
46
+ The output `Makefile` is long and complex, but the recipe it implements is relatively simple and does something like:
47
+
48
+ ``` sh
49
+ # `create_makefile` recipe is something like this
50
+
51
+ # compile phase:
52
+ gcc -c -I/path/to/ruby/include isolated.c -o isolated.o
53
+
54
+ # link phase:
55
+ gcc -shared -L/path/to/ruby/lib -lruby -lc -lm isolated.o -o isolated.so
56
+ ```
57
+
58
+ That final shared library, `isolated.so`, is loaded like any other Ruby file, via `require` in `lib/rcee/isolated.rb`:
59
+
60
+ ``` ruby
61
+ require_relative "isolated/isolated"
62
+ ```
63
+
64
+ ## What Can Go Wrong
65
+
66
+ 1. Users don't have the compiler toolchain installed (`gcc`, `ld`, `stdio.h`, `libc.so`, etc.)
67
+ 2. Users don't have the ruby development files installed (`ruby.h`, etc.)
68
+ 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 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_isolated_spec = Bundler.load_gemspec("rcee_isolated.gemspec")
8
9
  Gem::PackageTask.new(rcee_isolated_spec).define
@@ -13,12 +14,10 @@ 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("isolated") do |ext|
21
18
  ext.lib_dir = "lib/rcee/isolated"
22
19
  end
23
20
 
24
- task default: %i[clobber compile test]
21
+ task default: [:clobber, :compile, :test]
22
+
23
+ CLEAN.add("{ext,lib}/**/*.{o,so}", "pkg")
@@ -2,6 +2,6 @@
2
2
 
3
3
  module RCEE
4
4
  module Isolated
5
- VERSION = "0.1.0"
5
+ VERSION = "0.2.0"
6
6
  end
7
7
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: rcee_isolated
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.0
4
+ version: 0.2.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: 2021-09-10 00:00:00.000000000 Z
12
12
  dependencies: []
13
13
  description: Part of a project to explain how Ruby C extensions work.
14
14
  email:
@@ -47,7 +47,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
47
47
  - !ruby/object:Gem::Version
48
48
  version: '0'
49
49
  requirements: []
50
- rubygems_version: 3.2.15
50
+ rubygems_version: 3.2.22
51
51
  signing_key:
52
52
  specification_version: 4
53
53
  summary: Example gem demonstrating a basic C extension.