crystalruby 0.1.5 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e8dc48667be65ee6e6d36ba7efcfc87dfefb133a06cb375a22297db9643221e3
-  data.tar.gz: 40753b3741ae9fb5dec86019d35968027517280a08ae6bffbcf8f2e207fe96b3
+  metadata.gz: fe68e58781b8314afb53b268ba9314472ee93c611565f7398d0ff29b445f8ece
+  data.tar.gz: acd5e80d5709cc6f831daa39f58f74fe95642e16a4c44d25c8fab24106b47bcd
 SHA512:
-  metadata.gz: 1682a4405fd2baf66a93fc913af2146fa11e9806b90c8d6ac6d0eebc496b30415204474bd841377e3ea409401608f2907f58d7b717b21520cd4b1fe04d825d86
-  data.tar.gz: 8682ebdcdd83bda6ab29261cdfc627afe1bd211343bc4caa95c9f08cbb30fba663f1aebcf4df1535e27d7a84377449d5028afcce145cc0a91c153721e2d261f1
+  metadata.gz: 85516d1372b2467147cb5c61e6d33dc27e6e2c0d11876b32dbee1007152096fd54551926177b56e066fa9bc8e4329b8ef13d133280305018428775267eb4a24e
+  data.tar.gz: 207284740bef726d1a8c5df35b21ebe33b8611725363acac451bbadc3b7c714585513027be2398dd4cdd6ff94761c00585c94546fb198a4b90047d91edbef2ce

data/README.md

@@ -25,7 +25,7 @@ require 'crystalruby'
 module MyTestModule
   # The below method will be replaced by a compiled Crystal version
   # linked using FFI.
-  crystalize [:int, :int] => :int
+  crystalize [a: :int, b: :int] => :int
   def add(a, b)
     a + b
   end
@@ -133,6 +133,31 @@ def add(a, b)
 end
 ```
 
+## Getting Started
+
+The below is a stand-alone one-file script that allows you to quickly see crystalruby in action.
+
+```ruby
+# crystalrubytest.rb
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+  gem 'crystalruby', path: '../crystalruby'
+end
+
+require 'crystalruby'
+
+module Adder
+  crystalize [a: :int, b: :int] => :int
+  def add(a, b)
+    a + b
+  end
+end
+
+puts Adder.add(1, 2)
+```
+
 ## Types
 
 Currently primitive types are supported.
@@ -249,7 +274,7 @@ Remember to require these installed shards after installing them. E.g. inside `.
 
 You can edit the default paths for crystal source and library files from within the `./crystalruby.yaml` config file.
 
-### Wrapping Crystal code in Ruby
+## Wrapping Crystal code in Ruby
 
 Sometimes you may want to wrap a Crystal method in Ruby, so that you can use Ruby before the Crystal code to prepare arguments, or after the Crystal code, to apply transformations to the result. A real-life example of this might be an ActionController method, where you might want to use Ruby to parse the request, perform auth etc., and then use Crystal to perform some heavy computation, before returning the result from Ruby.
 To do this, you simply pass a block to the `crystalize` method, which will serve as the Ruby entry point to the function. From within this block, you can invoke `super` to call the Crystal method, and then apply any Ruby transformations to the result.
@@ -270,7 +295,7 @@ end
 MyModule.add("1", "2")
 ```
 
-### Release Builds
+## Release Builds
 
 You can control whether CrystalRuby builds in debug or release mode by setting following config option
 
@@ -303,7 +328,7 @@ CrystalRuby.compile!
 
 Then you can run this file as part of your build step, to ensure all Crystal code is compiled ahead of time.
 
-### Troubleshooting
+## Troubleshooting
 
 The logic to detect when to JIT recompile is not robust and can end up in an inconsistent state. To remedy this it is useful to clear out all generated assets and build from scratch.
 
@@ -324,7 +349,6 @@ It should support escape hatches to allow it to coexist with code that performs
 
 The library is currently in its infancy. Planned additions are:
 
-- Replace existing checksum process, with one that combines results of inline and external crystal to more accurately detect when recompilation is necessary.
 - Simple mixin/concern that utilises `FFI::Struct` for bi-directional passing of Ruby objects and Crystal objects (by value).
 - Install command to generate a sample build script, and supports build command (which simply verifies then invokes this script)
 - Call Ruby from Crystal using FFI callbacks (implement `.expose_to_crystal`)

data/lib/crystalruby/templates/function.cr

@@ -1,9 +1,18 @@
+# This is the template used for all CrystalRuby functions
+# Calls to this method *from ruby* are first transformed through the lib function.
+# Crystal code can simply call this method directly, enabling generated crystal code
+# to call other generated crystal code without overhead.
+
 module %{module_name}
   def self.%{fn_name}(%{fn_args}) : %{fn_ret_type}
     %{fn_body}
   end
 end
 
+# This function is the entry point for the CrystalRuby code, exposed through FFI.
+# We apply some basic error handling here, and convert the arguments and return values
+# to ensure that we are using Crystal native types.
+
 fun %{lib_fn_name}(%{lib_fn_args}): %{lib_fn_ret_type}
   begin
     %{convert_lib_args}

data/lib/crystalruby/templates/index.cr

@@ -1,38 +1,46 @@
 FAKE_ARG = "crystal"
-alias Callback = (Pointer(UInt8), Pointer(UInt8) -> Void)
+
+alias ErrorCallback = (Pointer(UInt8), Pointer(UInt8) -> Void)
 
 module CrystalRuby
+  # Initializing Crystal Ruby invokes init on the Crystal garbage collector.
+  # We need to be sure to only do this once.
   @@initialized = false
-  def self.init
-    if @@initialized
-      return
-    end
-    @@initialized = true
+
+  # We won't natively handle Crystal Exceptions in Ruby
+  # Instead, we'll catch them in Crystal, and explicitly expose them to Ruby via
+  # the error_callback.
+  @@error_callback
+
+  # This is the entry point for instantiating CrystalRuby
+  # We:
+  # 1. Initialize the Crystal garbage collector
+  # 2. Set the error callback
+  # 3. Call the Crystal main function
+  def self.init(error_callback : ErrorCallback)
+    return if @@initialized
     GC.init
+    @@initialized    = true
+    @@error_callback = error_callback
     ptr = FAKE_ARG.to_unsafe
     LibCrystalMain.__crystal_main(1, pointerof(ptr))
   end
 
-  def self.attach_rb_error_handler(cb : Callback)
-    @@rb_error_handler = cb
-  end
-
+  # Explicit error handling (triggers exception within Ruby on the same thread)
   def self.report_error(error_type : String, str : String)
-    handler = @@rb_error_handler
-    if handler
+    if handler = @@error_callback
       handler.call(error_type.to_unsafe, str.to_unsafe)
     end
   end
 end
 
-
-fun init(): Void
-  CrystalRuby.init
-end
-
-fun attach_rb_error_handler(cb : Callback) : Void
-  CrystalRuby.attach_rb_error_handler(cb)
+fun init(cb : ErrorCallback): Void
+  CrystalRuby.init(cb)
 end
 
+# This is where we define all our Crystal modules and types
+# derived from their Ruby counterparts.
 %{type_modules}
+
+# Require all generated crystal files
 %{requires}

data/lib/crystalruby/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Crystalruby
-  VERSION = "0.1.5"
+  VERSION = "0.1.7"
 end

data/lib/crystalruby.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "ffi"
 require "digest"
 require "fileutils"
@@ -10,6 +12,7 @@ require_relative "crystalruby/typebuilder"
 require_relative "crystalruby/template"
 
 module CrystalRuby
+  CR_SRC_FILES_PATTERN = "./**/*.cr"
   # Define a method to set the @crystalize proc if it doesn't already exist
   def crystalize(type = :src, **options, &block)
     (args,), returns = options.first
@@ -29,14 +32,6 @@ module CrystalRuby
     crtype(&block).serialize_as(:json)
   end
 
-  def with_temporary_constant(constant_name, new_value)
-    old_value = const_get(constant_name)
-    const_set(constant_name, new_value)
-    yield
-  ensure
-    const_set(constant_name, old_value)
-  end
-
   def method_added(method_name)
     if @crystalize_next
       attach_crystalized_method(method_name)
@@ -64,8 +59,7 @@ module CrystalRuby
     CrystalRuby.write_function(self, name: function[:name], body: function[:body]) do
       extend FFI::Library
       ffi_lib "#{config.crystal_lib_dir}/#{config.crystal_lib_name}"
-      attach_function "#{method_name}", fname, function[:ffi_types], function[:return_ffi_type]
-      attach_function "init!", "init", [], :void
+      attach_function method_name, fname, function[:ffi_types], function[:return_ffi_type]
       if block
         [singleton_class, self].each do |receiver|
           receiver.prepend(Module.new do
@@ -73,8 +67,6 @@ module CrystalRuby
           end)
         end
       end
-
-      init!
     end
 
     [singleton_class, self].each do |receiver|
@@ -219,6 +211,9 @@ module CrystalRuby
         "require \"./#{config.crystal_codegen_dir}/index\"\n"
       )
     end
+
+    attach_crystal_ruby_lib! if compiled?
+
     return if File.exist?("#{config.crystal_src_dir}/shard.yml")
 
     IO.write("#{config.crystal_src_dir}/shard.yml", <<~CRYSTAL)
@@ -227,11 +222,25 @@ module CrystalRuby
     CRYSTAL
   end
 
+  def attach_crystal_ruby_lib!
+    extend FFI::Library
+    ffi_lib "#{config.crystal_lib_dir}/#{config.crystal_lib_name}"
+    attach_function "init!", :init, [:pointer], :void
+    const_set(:ErrorCallback, FFI::Function.new(:void, %i[string string]) do |error_type, message|
+      error_type = error_type.to_sym
+      is_exception_type = Object.const_defined?(error_type) && Object.const_get(error_type).ancestors.include?(Exception)
+      error_type = is_exception_type ? Object.const_get(error_type) : RuntimeError
+      raise error_type.new(message)
+    end)
+    init!(ErrorCallback)
+  end
+
   def self.instantiated?
     @instantiated
   end
 
   def self.compiled?
+    @compiled = get_current_crystal_lib_digest == get_cr_src_files_digest unless defined?(@compiled)
     @compiled
   end
 
@@ -292,21 +301,15 @@ module CrystalRuby
               "crystal build --release --no-debug -o #{lib_target} #{config.crystal_main_file}"
             end
 
-      raise "Error compiling crystal code" unless result = system(cmd)
-
-      @compiled = true
-      File.delete("#{config.crystal_codegen_dir}/index.cr") if File.exist?("#{config.crystal_codegen_dir}/index.cr")
+      unless result = system(cmd)
+        File.delete(digest_file_name) if File.exist?(digest_file_name)
+        raise "Error compiling crystal code"
+      end
     end
-    extend FFI::Library
-    ffi_lib "#{config.crystal_lib_dir}/#{config.crystal_lib_name}"
-    attach_function :attach_rb_error_handler, [:pointer], :int
-    const_set(:ErrorCallback, FFI::Function.new(:void, %i[string string]) do |error_type, message|
-      error_type = error_type.to_sym
-      is_exception_type = Object.const_defined?(error_type) && Object.const_get(error_type).ancestors.include?(Exception)
-      error_type = is_exception_type ?  Object.const_get(error_type) : RuntimeError
-      raise error_type.new(message)
-    end)
-    attach_rb_error_handler(ErrorCallback)
+
+    IO.write(digest_file_name, get_cr_src_files_digest)
+    @compiled = true
+    attach_crystal_ruby_lib!
   end
 
   def self.attach!
@@ -316,10 +319,23 @@ module CrystalRuby
     @attached = true
   end
 
+  def self.get_cr_src_files_digest
+    file_digests = Dir.glob(CR_SRC_FILES_PATTERN).sort.map do |file_path|
+      content = File.read(file_path)
+      Digest::MD5.hexdigest(content)
+    end.join
+    Digest::MD5.hexdigest(file_digests)
+  end
+
+  def self.digest_file_name
+    @digest_file_name ||= "#{config.crystal_lib_dir}/#{config.crystal_lib_name}.digest"
+  end
+
+  def self.get_current_crystal_lib_digest
+    File.read(digest_file_name) if File.exist?(digest_file_name)
+  end
+
   def self.write_function(owner, name:, body:, &compile_callback)
-    unless defined?(@compiled)
-      @compiled = File.exist?("#{config.crystal_src_dir}/#{config.crystal_codegen_dir}/index.cr")
-    end
     @block_store ||= []
     @block_store << { owner: owner, name: name, body: body, compile_callback: compile_callback }
     FileUtils.mkdir_p("#{config.crystal_src_dir}/#{config.crystal_codegen_dir}")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: crystalruby
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.7
 platform: ruby
 authors:
 - Wouter Coppieters