rb_sys 0.9.62 → 0.9.64

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb45d1f47ed05580f9d5e9d1799b17c9f29dc503846a70b579db5817c65efb25
-  data.tar.gz: 758e642b26c85bd37cb1787131a223958cd93d7358c44ccc99a9dc889f089b29
+  metadata.gz: da8a462e7210f1746cca7dd9935d243b179176318aa766474fc33dd2de71227c
+  data.tar.gz: 7cd4a0126f7240b2b58ee3338dceec912d1cd9de211adc55a6f4da320fa982cc
 SHA512:
-  metadata.gz: 728591453d68f544915dfaaf0fbf2d66a55f72879542853f8c7dab8a1313a23bd85c78cd7befa1ffc3dbecccbef5f565ae0a5998a0801cf0798d9a0315360fc5
-  data.tar.gz: d9c3344159a08fe66f227adb5bf65b1c2fe7307ded78536da7760ea0cdf6c4806e9e955a1edd70b2b6efb99202d40903390657cc2ebeadde8918533a189c0b90
+  metadata.gz: be81aba075a717c61a156cfcfafba1b9e7b36a33a045a2f04372b1c8244dd4280c0ebcc113fdc5c468bf72e49b6aaa8eff8d20784706ac779bab80e64d09ae04
+  data.tar.gz: 3fa8cb0393b6cbbd53cba685b8616e5b747556ea583b8e943ec54b93a938b6b0f6610768c545e28076eb9806afb92108e1bdf6e0e2f9d78b6cdaf05666fa6bd9

data/.yardopts

@@ -0,0 +1,3 @@
+--no-private
+--list-undoc
+'lib/**/*.rb'

data/README.md

@@ -0,0 +1,98 @@
+# The `rb_sys` gem
+
+![Gem](https://img.shields.io/gem/v/rb_sys)
+[![Documentation](https://img.shields.io/badge/docs-rdoc.info-blue.svg)](https://www.rubydoc.info/gems/rb_sys/frames)
+[![Join the discussion](https://img.shields.io/badge/slack-chat-blue.svg)](https://join.slack.com/t/oxidize-rb/shared_invite/zt-16zv5tqte-Vi7WfzxCesdo2TqF_RYBCw)
+
+The `rb_sys` gem is a Ruby gem makes it easy to build native Ruby extensions in Rust. It interops with the existing Ruby
+native extension toolchains (i.e. `rake-compiler`) to make testing, building, and cross compilation of gems easy.
+
+## `RbSys::ExtensionTask`
+
+This gem provides a `RbSys::ExtensionTask` class that can be used to build a Ruby extension in Rust. It's a thin wrapper
+around `Rake::ExtensionTask` that provides sane defaults for building Rust extensions.
+
+```ruby
+# Rakefile
+
+require "rb_sys/extensiontask"
+
+GEMSPEC = Gem::Specification.load("my_gem.gemspec")
+
+RbSys::ExtensionTask.new("my-crate-name", GEMSPEC) do |ext|
+  ext.lib_dir = "lib/my_gem"
+end
+```
+
+## `create_rust_makefile`
+
+This gem provides a simple helper to build a Ruby compatible Makefile for you Rust extension. For a full example, see
+the [examples](./../examples) directory.
+
+```ruby
+# ext/rust_reverse/extconf.rb
+
+# We need to require mkmf *first* this since `rake-compiler` injects code here for cross compilation
+require "mkmf"
+require "rb_sys/mkmf"
+
+create_rust_makefile("rust_reverse") do |r|
+  # Create debug builds in dev. Make sure that release gems are compiled with
+  # `RB_SYS_CARGO_PROFILE=release` (optional)
+  r.profile = ENV.fetch("RB_SYS_CARGO_PROFILE", :dev).to_sym
+
+  # Can be overridden with `RB_SYS_CARGO_FEATURES` env var (optional)
+  r.features = ["test-feature"]
+
+  # You can add whatever env vars you want to the env hash (optional)
+  r.env = {"FOO" => "BAR"}
+
+  # If your Cargo.toml is in a different directory, you can specify it here (optional)
+  r.ext_dir = "."
+
+  # Extra flags to pass to the $RUSTFLAGS environment variable (optional)
+  r.extra_rustflags = ["--cfg=some_nested_config_var_for_crate"]
+
+  # Force a rust toolchain to be installed via rustup (optional)
+  # You can also set the env var `RB_SYS_FORCE_INSTALL_RUST_TOOLCHAIN=true`
+  r.force_install_rust_toolchain = "stable"
+
+  # Clean up the target/ dir after `gem install` to reduce bloat (optional)
+  r.clean_after_install = false # default: true if invoked by rubygems
+
+  # Auto-install Rust toolchain if not present on "gem install" (optional)
+  r.auto_install_rust_toolchain = false # default: true if invoked by rubygems
+end
+```
+
+## Tips and Tricks
+
+- When using `rake-compiler` to build your gem, you can use the `RB_SYS_CARGO_PROFILE` environment variable to set the
+  Cargo profile (i.e. `release` or `dev`).
+
+- You can pass Cargo arguments to `rake-compiler` like so: `rake compile -- --verbose`
+
+- It's possible to force an installation of a Rust toolchain by setting the `RB_SYS_FORCE_INSTALL_RUST_TOOLCHAIN`
+  environment variable. This will install [rustup](https://rustup.rs/) and [cargo](https://crates.io/) in the build
+  directory, so the end user does not have to have Rust pre-installed. Ideally, this should be a last resort, as it's
+  better to already have the toolchain installed on your system.
+
+## Troubleshooting
+
+### Libclang issues
+
+If you see an error like this:
+
+```
+thread 'main' panicked at 'Unable to find libclang: "couldn't find any valid shared libraries matching: \['libclang.so', 'libclang-*.so', 'libclang.so.*', 'libclang-*.so.*'\], set the `LIBCLANG_PATH` environment variable to a path where one of these files can be found (invalid: \[\])"'
+```
+
+This means that bindgen is having issues finding a usable version of libclang. An easy way to fix this is to install the
+[`libclang` gem](https://github.com/oxidize-rb/libclang-rb), which will install a pre-built version of libclang for you.
+`rb_sys` will automatically detect this gem and use it.
+
+```ruby
+# Gemfile
+
+gem "libclang", "~> 14.0.6"
+```

data/exe/rb-sys-dock

@@ -300,8 +300,10 @@ def download_image(options)
   end
 end
 
-def log_some_useful_info(_options)
-  if ARGV.empty? && !options[:build]
+def log_some_useful_info(options)
+  return if options[:build]
+
+  if ARGV.empty?
     log(:notice, "Entering shell in Docker container #{ENV["RCD_IMAGE"].inspect}")
   else
     log(:notice, "Running command #{ARGV.inspect} in Docker container #{ENV["RCD_IMAGE"].inspect}")

data/lib/rb_sys/cargo/metadata.rb

@@ -9,35 +9,83 @@ module RbSys
     class Metadata
       attr_reader :name
 
+      # Initializes a new Cargo::Metadata instance.
+      #
+      # @param name [String] the name of the Cargo project
       def initialize(name)
         raise ArgumentError, "name must be a String" unless name.is_a?(String)
 
         @name = name
       end
 
-      # @api private
-      def self.delegates_to_cargo_metadata(*methods)
-        methods.each do |method|
-          define_method(method) { cargo_metadata.fetch(method.to_s) }
-        end
+      # Returns the path where the Cargo project's Cargo.toml is located.
+      #
+      # @return [String]
+      def manifest_directory
+        @manifest_directory ||= File.dirname(manifest_path)
       end
 
-      # @api private
-      def self.delegates_to_package_metadata(*methods)
-        methods.each do |method|
-          define_method(method) { package_metadata.fetch(method.to_s) }
-        end
+      # Returns the target directory for the Cargo project.
+      #
+      # @return [String]
+      def target_directory
+        cargo_metadata.fetch("target_directory")
       end
 
-      delegates_to_cargo_metadata :target_directory, :workspace_root, :packages
+      # Returns the workspace root for the Cargo project.
+      #
+      # @return [String]
+      def workspace_root
+        cargo_metadata.fetch("workspace_root")
+      end
 
-      delegates_to_package_metadata :manifest_path, :version, :id, :edition, :targets, :features, :metadata
+      # Returns the workspace members for the Cargo project.
+      #
+      # @return [Array<Hash>]
+      def packages
+        cargo_metadata.fetch("packages")
+      end
 
-      # Returns the path where the Cargo project's Cargo.toml is located.
+      # Returns the path to the package's Cargo.toml.
       #
       # @return [String]
-      def manifest_directory
-        @manifest_directory ||= File.dirname(manifest_path)
+      def manifest_path
+        package_metadata.fetch("manifest_path")
+      end
+
+      # Returns the package's version.
+      #
+      # @return [String]
+      def version
+        package_metadata.fetch("version")
+      end
+
+      # Returns the package's id.
+      #
+      # @return [String]
+      def id
+        package_metadata.fetch("id")
+      end
+
+      # Returns the package's Rust edition.
+      #
+      # @return [String]
+      def edition
+        package_metadata.fetch("edition")
+      end
+
+      # Returns the package's features.
+      #
+      # @return [Array<String>]
+      def features
+        package_metadata.fetch("features")
+      end
+
+      # Returns the package's custom metadata.
+      #
+      # @return [Hash]
+      def metadata
+        package_metadata.fetch("metadata")
       end
 
       private
@@ -56,10 +104,13 @@ module RbSys
         ::Gem.load_yaml
         cargo = ENV["CARGO"] || "cargo"
         args = ["metadata", "--no-deps", "--format-version", "1"]
-        out, stderr, _status = Open3.capture3(cargo, *args)
-        @cargo_metadata = Gem::SafeYAML.safe_load(out)
+        out, stderr, status = Open3.capture3(cargo, *args)
+        raise "exited with non-zero status (#{status})" unless status.success?
+        data = Gem::SafeYAML.safe_load(out)
+        raise "metadata must be a Hash" unless data.is_a?(Hash)
+        @cargo_metadata = data
       rescue => err
-        raise CargoMetadataError.new(err, stderr, manifest_path)
+        raise CargoMetadataError.new(err, stderr)
       end
     end
   end

data/lib/rb_sys/error.rb

@@ -19,18 +19,24 @@ module RbSys
 
   # Raised when Cargo metadata cannot be parsed.
   class CargoMetadataError < Error
-    def initialize(err, stderr, manifest_path)
+    def initialize(err, stderr)
       msg = <<~MSG.chomp.tr("\n", " ")
-        Could not parse Cargo metadata. Please check that your Cargo.toml
-        is valid. The error was: #{err}
+        Could not infer Rust crate information using `cargo metadata`.
 
-        Looking for this Cargo.toml: #{manifest_path.inspect}
+        Original error was:
+          #{err.class}: #{err.message}
 
-        Stderr
-        ------
-        #{stderr}
+        Things to check:
+          - Check that your ext/*/Cargo.toml at is valid
+          - If you are using a workspace, make sure you are the root Cargo.toml exists
+          - Make sure `cargo` is installed and in your PATH
       MSG
 
+      if !stderr.empty?
+        indented_stderr = stderr.lines.map { |line| "  #{line}" }.join
+        msg << "Stderr from `cargo metadata` was:\n#{indented_stderr}"
+      end
+
       super(msg)
     end
   end

data/lib/rb_sys/mkmf.rb

@@ -59,6 +59,7 @@ module RbSys
         #{conditional_assign("CARGO", "cargo")}
         #{conditional_assign("CARGO_BUILD_TARGET", builder.target)}
         #{conditional_assign("SOEXT", builder.so_ext)}
+        #{try_load_bundled_libclang(builder)}
 
         # Determine the prefix Cargo uses for the lib.
         #{if_neq_stmt("$(SOEXT)", "dll")}
@@ -317,6 +318,26 @@ module RbSys
       end
     end
 
+    def try_load_bundled_libclang(_builder)
+      require "libclang"
+      assert_libclang_version_valid!
+      export_env("LIBCLANG_PATH", Libclang.libdir)
+    rescue LoadError
+      # If we can't load the bundled libclang, just continue
+    end
+
+    def assert_libclang_version_valid!
+      libclang_version = Libclang.version
+
+      if libclang_version < Gem::Version.new("5.0.0")
+        raise "libclang version 5.0.0 or greater is required (current #{libclang_version})"
+      end
+
+      if libclang_version >= Gem::Version.new("15.0.0")
+        raise "libclang version > 14.0.0 or greater is required (current #{libclang_version})"
+      end
+    end
+
     def set_cargo_profile(builder)
       return assign_stmt("RB_SYS_CARGO_PROFILE", "release") if builder.rubygems_invoked?
 

data/lib/rb_sys/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RbSys
-  VERSION = "0.9.62"
+  VERSION = "0.9.64"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rb_sys
 version: !ruby/object:Gem::Version
-  version: 0.9.62
+  version: 0.9.64
 platform: ruby
 authors:
 - Ian Ker-Seymer
@@ -30,7 +30,7 @@ cert_chain:
   Rl+ASkq2/1i07TkBpCf+2hq66+h/hx+/Y/KrUzXfe0jtvil0WESkJT2kqRqHWNhD
   9GKBxaQlXokNDtWCm1/gl6cD8WRZ0N5S4ZGJT1FLLsA=
   -----END CERTIFICATE-----
-date: 2023-02-06 00:00:00.000000000 Z
+date: 2023-02-07 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -40,8 +40,10 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - LICENSE-APACHE
 - LICENSE-MIT
+- README.md
 - certs/ianks.pem
 - exe/rb-sys-dock
 - lib/rb_sys.rb
@@ -56,8 +58,7 @@ files:
 - lib/rb_sys/toolchain_info.rb
 - lib/rb_sys/toolchain_info/data.rb
 - lib/rb_sys/version.rb
-- sig/rb_sys.rbs
-homepage: https://github.com/oxidize-rb/rb-sys
+homepage: https://oxidize-rb.github.io/rb-sys/
 licenses:
 - MIT
 - Apache-2.0

data/sig/rb_sys.rbs

@@ -1,4 +0,0 @@
-module RbSys
-  VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
-end