rb_sys 0.9.63 → 0.9.64

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52407f94f77dfbef05d18940ac493f58192b704c64bfa30a023498e2a78c42d6
-  data.tar.gz: 25d5c1894e187b3208933d3c7874923c44f77fb0fbdbc68e63800430dfba3378
+  metadata.gz: da8a462e7210f1746cca7dd9935d243b179176318aa766474fc33dd2de71227c
+  data.tar.gz: 7cd4a0126f7240b2b58ee3338dceec912d1cd9de211adc55a6f4da320fa982cc
 SHA512:
-  metadata.gz: 4df8ead8517d700e6690fd52e74ccf67c7b8fcd74fbbacf4a7fb9dca6bffc2da8ef8f6803c55159011030f0cf3b703d8015d29ab71ea078ef3d9649f2653247e
-  data.tar.gz: c87238853cb91b0e9bbd5deb0b1eba7ce0463812da6a9aac7c3d6695ba9102c411b0c41724c5a6fcbad2c19885447d184b7836c93240ae4d43712caf16b8c2e6
+  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/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.63"
+  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.63
+  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