23 releases

new 0.9.19 Jul 5, 2022
0.9.18 Jun 30, 2022
0.9.0 May 25, 2022
0.8.1 Apr 26, 2022
0.1.14 Jun 28, 2022

#78 in FFI

Download history 206/week @ 2022-04-20 132/week @ 2022-04-27 101/week @ 2022-05-04 57/week @ 2022-05-11 146/week @ 2022-05-18 103/week @ 2022-05-25 419/week @ 2022-06-01 1125/week @ 2022-06-08 484/week @ 2022-06-15 2593/week @ 2022-06-22 2049/week @ 2022-06-29

6,437 downloads per month
Used in 3 crates

MIT/Apache

33KB
672 lines

rb-sys

Join the discussion

Autogenerated Rust bindings for Ruby. Uses the rust-bindgen crate to generate bindings from the ruby.h header.https://github.com/rust-lang/rust-bindgen

⚠️ Notice

This is a very low-level library. If you are looking to write a gem in Rust, you should probably use https://github.com/matsadler/magnus crate, with the rb-sys-interop feature.

If you actually need raw/unsafe bindings to libruby, the this crate if for you!

Usage

Writing a Ruby gem

Ruby gems require a bit of boilerplate to be defined to be usable from Ruby. rb-sys makes this process painless by doing the work for you, by simply enabling the gem feature.

rb-sys = { version = "0.9",  features = ["gem"] }

Under the hood this ensures we do not link libruby (unless on Windows), and defines a ruby_abi_version function for Ruby 3.2+.

See this example of creating a Ruby gem in Rust

Embedding libruby in your Rust app

IMPORTANT: If you are authoring a Ruby gem, you do not need to enable this feature.

If you need to link libruby (i.e. you are initializing a Ruby VM in your Rust code), use can enable the link-ruby feature:

rb-sys = { version = "0.9",  features = ["link-ruby"] }

Static libruby

You can also force static linking of libruby:

rb-sys = { version = "0.9", features = ["ruby-static"] }

Alternatively, you can set the RUBY_STATIC=true environment variable.

Ruby Macros

The rb-sys crates comes with an optional ruby-macros feature. This feature compiles a small bit of C code to give access to some commonly used C macros in Ruby.

# Cargo.toml

[dependencies]
rb-sys = { version = "0.9",  features = ["ruby-macros"] }

Other features

  • gem: Setup boilerplate for a Ruby gem.
  • ruby-abi-version: Set the Ruby ABI version.
  • ruby-macros: Generate Rust functions for Ruby macros like RSTRING_PTR.
  • global-allocator: Report Rust memory allocations to the Ruby GC (recommended).
  • ruby-static: Link the static version of libruby.
  • link-ruby: Link libruby.
  • bindgen-rbimpls: Include the Ruby impl types in bindings.
  • bindgen-deprecated-types: Include deprecated Ruby methods in bindings.

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Dependencies

~0–1.4MB
~29K SLoC