You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The `rb-sys` crate provides battle-tested Rust bindings for the Ruby C API. It uses the [`rust-bindgen`](https://github.com/rust-lang/rust-bindgen) crate to generate bindings from the `ruby.h` header.
3
+
The `rb-sys` crate provides battle-tested Rust bindings for the Ruby C API. It uses the
4
+
[`rust-bindgen`](https://github.com/rust-lang/rust-bindgen) crate to generate bindings from the `ruby.h` header.
4
5
5
6
## Usage Notice
6
7
7
-
This is a very low-level library. If you are looking to write a gem in Rust, you should probably use the [Magnus](https://github.com/matsadler/magnus) crate with the `rb-sys-interop` feature, which provides a higher-level, more ergonomic API.
8
+
This is a very low-level library. If you are looking to write a gem in Rust, you should probably use the
9
+
[Magnus](https://github.com/matsadler/magnus) crate with the `rb-sys-interop` feature, which provides a higher-level,
10
+
more ergonomic API.
8
11
9
12
If you need raw/unsafe bindings to libruby, then this crate is for you!
10
13
11
14
## Writing a Ruby Gem
12
15
13
-
Ruby gems require boilerplate to be defined to be usable from Ruby. `rb-sys` makes this process painless by doing the work for you. Simply enable the `gem` feature:
16
+
Ruby gems require boilerplate to be defined to be usable from Ruby. `rb-sys` makes this process painless by doing the
17
+
work for you. Simply enable the `gem` feature:
14
18
15
19
```toml
16
20
[dependencies]
17
21
rb-sys = "0.9"
18
22
```
19
23
20
-
Under the hood, this ensures the crate does not link libruby (unless on Windows) and defines a `ruby_abi_version` function for Ruby 3.2+.
24
+
Under the hood, this ensures the crate does not link libruby (unless on Windows) and defines a `ruby_abi_version`
25
+
function for Ruby 3.2+.
21
26
22
27
## Embedding libruby in Your Rust App
23
28
24
29
**IMPORTANT**: If you are authoring a Ruby gem, you do not need to enable this feature.
25
30
26
-
If you need to link libruby (i.e., you are initializing a Ruby VM in your Rust code), you can enable the `link-ruby` feature:
31
+
If you need to link libruby (i.e., you are initializing a Ruby VM in your Rust code), you can enable the `link-ruby`
32
+
feature:
27
33
28
34
```toml
29
35
[dependencies]
@@ -45,15 +51,15 @@ Alternatively, you can set the `RUBY_STATIC=true` environment variable.
45
51
46
52
The `rb-sys` crate provides several features that can be enabled in your `Cargo.toml`:
47
53
48
-
| Feature | Description |
49
-
|---------|-------------|
50
-
|`global-allocator`| Report Rust memory allocations to the Ruby GC (_recommended_) |
51
-
|`ruby-static`| Link the static version of libruby |
52
-
|`link-ruby`| Link libruby (typically used for embedding, not for extensions) |
53
-
|`bindgen-rbimpls`| Include the Ruby impl types in bindings |
54
-
|`bindgen-deprecated-types`| Include deprecated Ruby methods in bindings |
55
-
|`gem`| Set up the crate for use in a Ruby gem (default feature) |
56
-
|`stable-api`| Use the stable API (C level) if available for your Ruby version |
|`global-allocator`| Report Rust memory allocations to the Ruby GC (_recommended_)|
57
+
|`ruby-static`| Link the static version of libruby|
58
+
|`link-ruby`| Link libruby (typically used for embedding, not for extensions) |
59
+
|`bindgen-rbimpls`| Include the Ruby impl types in bindings|
60
+
|`bindgen-deprecated-types`| Include deprecated Ruby methods in bindings |
61
+
|`gem`| Set up the crate for use in a Ruby gem (default feature)|
62
+
|`stable-api`| Use the stable API (C level) if available for your Ruby version |
57
63
58
64
## Example Cargo.toml
59
65
@@ -64,16 +70,18 @@ rb-sys = { version = "0.9", features = ["global-allocator", "stable-api"] }
64
70
65
71
## Ruby Version Compatibility
66
72
67
-
`rb-sys` is compatible with Ruby 2.6 and later. The crate detects the Ruby version at compile time and adapts the bindings accordingly.
73
+
`rb-sys` is compatible with Ruby 2.6 and later. The crate detects the Ruby version at compile time and adapts the
74
+
bindings accordingly.
68
75
69
76
For Ruby 3.2 and later, `rb-sys` provides a `ruby_abi_version` function that is required for native extensions.
70
77
71
78
## Integration with Magnus
72
79
73
-
If you're building a Ruby extension, it's recommended to use the [Magnus](https://github.com/matsadler/magnus) crate on top of `rb-sys`. Magnus provides a high-level, safe API for interacting with Ruby:
80
+
If you're building a Ruby extension, it's recommended to use the [Magnus](https://github.com/matsadler/magnus) crate on
81
+
top of `rb-sys`. Magnus provides a high-level, safe API for interacting with Ruby:
74
82
75
83
```toml
76
84
[dependencies]
77
85
magnus = { version = "0.7", features = ["rb-sys"] }
Copy file name to clipboardExpand all lines: book/src/api-reference/rb-sys-gem-config.md
+21-13Lines changed: 21 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,10 +1,12 @@
1
1
# rb_sys Gem Configuration
2
2
3
-
The `rb_sys` gem makes it easy to build native Ruby extensions in Rust. It interoperates with existing Ruby native extension toolchains (i.e., `rake-compiler`) to make testing, building, and cross-compilation of gems easy.
3
+
The `rb_sys` gem makes it easy to build native Ruby extensions in Rust. It interoperates with existing Ruby native
4
+
extension toolchains (i.e., `rake-compiler`) to make testing, building, and cross-compilation of gems easy.
4
5
5
6
## RbSys::ExtensionTask
6
7
7
-
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.
8
+
This gem provides a `RbSys::ExtensionTask` class that can be used to build a Ruby extension in Rust. It's a thin wrapper
9
+
around `Rake::ExtensionTask` that provides sane defaults for building Rust extensions.
8
10
9
11
```ruby
10
12
# Rakefile
@@ -65,21 +67,25 @@ end
65
67
66
68
The `rb_sys` gem respects several environment variables that can modify its behavior:
67
69
68
-
| Environment Variable | Description |
69
-
|---------------------|-------------|
70
-
|`RB_SYS_CARGO_PROFILE`| Set the Cargo profile (i.e., `release` or `dev`) |
71
-
|`RB_SYS_CARGO_FEATURES`| Comma-separated list of Cargo features to enable |
72
-
|`RB_SYS_FORCE_INSTALL_RUST_TOOLCHAIN`| Force installation of a Rust toolchain |
73
-
|`RUBY_STATIC`| Force static linking of libruby if set to `true`|
74
-
|`LIBCLANG_PATH`| Path to libclang if it can't be found automatically |
|`RB_SYS_CARGO_PROFILE`| Set the Cargo profile (i.e., `release` or `dev`)|
73
+
|`RB_SYS_CARGO_FEATURES`| Comma-separated list of Cargo features to enable|
74
+
|`RB_SYS_FORCE_INSTALL_RUST_TOOLCHAIN`| Force installation of a Rust toolchain |
75
+
|`RUBY_STATIC`| Force static linking of libruby if set to `true`|
76
+
|`LIBCLANG_PATH`| Path to libclang if it can't be found automatically |
75
77
76
78
## Tips and Tricks
77
79
78
-
- 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`).
80
+
- When using `rake-compiler` to build your gem, you can use the `RB_SYS_CARGO_PROFILE` environment variable to set the
81
+
Cargo profile (i.e., `release` or `dev`).
79
82
80
83
- You can pass Cargo arguments to `rake-compiler` like so: `rake compile -- --verbose`
81
84
82
-
- 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.
85
+
- It's possible to force an installation of a Rust toolchain by setting the `RB_SYS_FORCE_INSTALL_RUST_TOOLCHAIN`
86
+
environment variable. This will install [rustup](https://rustup.rs/) and [cargo](https://crates.io/) in the build
87
+
directory, so the end user does not have to have Rust pre-installed. Ideally, this should be a last resort, as it's
88
+
better to already have the toolchain installed on your system.
83
89
84
90
## Troubleshooting
85
91
@@ -91,9 +97,11 @@ If you see an error like this:
91
97
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: \[\])"'
92
98
```
93
99
94
-
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.
100
+
This means that bindgen is having issues finding a usable version of libclang. An easy way to fix this is to install the
101
+
[`libclang` gem](https://github.com/oxidize-rb/libclang-rb), which will install a pre-built version of libclang for you.
102
+
`rb_sys` will automatically detect this gem and use it.
0 commit comments