rutie: A Rust repository from kphelps

Rutie

Rutie — /ro͞oˈˌtī/rOOˈˌtI/rüˈˌtaI/

Integrate Ruby with your Rust application. Or integrate Rust with your Ruby application. This project allows you to do either with relative ease.

You are highly encouraged to read the source code for this project. Every method that has been mapped from Ruby for public use in src/class/* is very well documented with example code. This is the best way to take off running with Rutie. There are also integration examples in the examples directory which are based off of this README.

This project is a continuation of:

ruru (licensed MIT)
ruby-sys (licensed MIT)

Index

Using Ruby in Rust

First add the dependency to your Cargo.toml file.

[dependencies]
rutie = "0.5.3"

Then in your Rust program add VM::init() to the beginning of its code execution path and begin to use Rutie.

extern crate rutie;

use rutie::{Object, RString, VM};

fn try_it(s: &str) -> String {
    let a = RString::new_utf8(s);

    // The `send` method returns an AnyObject type.
    let b = a.send("reverse", None);

    // We must try to convert the AnyObject
    // type back to our usable type.
    match b.try_convert_to::<RString>() {
        Ok(ruby_string) => ruby_string.to_string(),
        Err(_) => "Fail!".to_string(),
    }
}

#[test]
fn it_works() {

    // Rust projects must start the Ruby VM
    VM::init();

    assert_eq!("selppa", try_it("apples"));
}

fn main() {}

Running cargo test should have this test pass.

Using Rust in Ruby

You can start a Ruby project with bundle gem rutie_ruby_example and then once you change into that directory run cargo init. Remove the TODOs from the gemspec file. Add Rutie to the Cargo.toml file and define the lib type.

[dependencies]
rutie = "0.5.3"

[lib]
name = "rutie_ruby_example"
crate-type = ["dylib"]

Then edit your src/lib.rs file for your Rutie code.

#[macro_use]
extern crate rutie;

use rutie::{Class, Object, RString, VM};

class!(RutieExample);

methods!(
    RutieExample,
    _itself,

    fn pub_reverse(input: RString) -> RString {
        let ruby_string = input.
          map_err(|e| VM::raise_ex(e) ).
          unwrap();

        RString::new_utf8(
          &ruby_string.
          to_string().
          chars().
          rev().
          collect::<String>()
        )
    }
);

#[allow(non_snake_case)]
#[no_mangle]
pub extern "C" fn Init_rutie_ruby_example() {
    Class::new("RutieExample", None).define(|itself| {
        itself.def_self("reverse", pub_reverse);
    });
}

And that's it for the Rust side. When using the methods! macro or extern functions make sure the method name won't clash with any others. This is why this example is prefixed with pub_.

Now you just need to load the library in Ruby. Add the rutie gem to your gemspec or Gemfile.

# gemspec
spec.add_dependency 'rutie', '~> 0.0.3'

# Gemfile
gem 'rutie', '~> 0.0.3'

And then load the library in your main project file lib/rutie_ruby_example.rb.

require 'rutie_ruby_example/version'
require 'rutie'

module RutieRubyExample
  Rutie.new(:rutie_ruby_example).init 'Init_rutie_ruby_example', __dir__
end

That's all you need to load your Ruby things from Rust. Now to write the test in test/rutie_ruby_example_test.rb:

require "test_helper"

class RutieRubyExampleTest < Minitest::Test
  def test_it_reverses
    assert_equal "selppa", RutieExample.reverse("apples")
  end
end

And to properly test it you will always need to run cargo build --release whenever you make any changes to the Rust code. Run the test with:

cargo build --release; rake test

Or better yet change your Rakefile to always run the cargo build --release before every test suite run. Feel free to change the test input to prove it fails because the above test works as is.

Custom Ruby Objects in Rust

To create a Ruby object in Rust that can be returned directly to Ruby it needs just a few simple things.

Here's an example excerpt of code from FasterPath.

use rutie::types::{ Value, ValueType };
use rutie::{ RString, AnyObject, Object, Class, VerifiedObject };

pub struct Pathname {
    value: Value
}

impl Pathname {
    pub fn new(path: &str) -> Pathname {
        let arguments = [RString::new_utf8(path).to_any_object()];
        let instance = Class::from_existing("Pathname").new_instance(Some(&arguments));

        Pathname { value: instance.value() }
    }

    pub fn to_any_object(&self) -> AnyObject {
        AnyObject::from(self.value())
    }
}

impl From<Value> for Pathname {
    fn from(value: Value) -> Self {
        Pathname { value }
    }
}

impl Object for Pathname {
    #[inline]
    fn value(&self) -> Value {
        self.value
    }
}

impl VerifiedObject for Pathname {
    fn is_correct_type<T: Object>(object: &T) -> bool {
        Class::from_existing("Pathname").case_equals(object)
    }

    fn error_message() -> &'static str {
        "Error converting to Pathname"
    }
}

If the class does not yet exist in Ruby you'll need to account for creating it before generating a new instance of it. This object is now compatible to be returned into Ruby directly from Rust/Rutie. Note that this definition is merely a Rust compatible representation of the Ruby object and doesn't define any Ruby methods which can be used from Ruby.

Variadic Functions / Splat Operator

A preferred way to integrate a dynamic amount of parameters has not yet been implemented in Rutie, but you can still manage to get it done in the following way.

use rutie::{AnyObject, Array};
use rutie::types::{Argc, Value};
use rutie::util::str_to_cstring;
use rutie::rubysys::class;
use std::mem;

pub extern fn example_method(argc: Argc, argv: *const AnyObject, _: AnyObject) -> AnyObject {
    let args = Value::from(0);

    unsafe {
        let p_argv: *const Value = mem::transmute(argv);

        class::rb_scan_args(
            argc,
            p_argv,
            str_to_cstring("*").as_ptr(),
            &args
        )
    };

    let arguments = Array::from(args);

    let output = // YOUR CODE HERE.  Use arguments as you see fit.

    output.to_any_object()
}

This style of code is meant to be used outside of the methods! macro for now. You may place this method on a class or module as you normally would from a methods! macro definition.

#[macro_use]
extern crate rutie;

use rutie::{Class, Object, VM};

class!(Example);

// Code from above

fn main() {
    # VM::init();
    Class::new("Example", None).define(|itself| {
        itself.def("example_method", example_method);
    });
}

The Rutie project has in its plans to remove the need for anyone to write unsafe code for variadic support and will likely be updating the methods! macro to support this natively.

Migrating from Ruru to Rutie

<0.1

For using Rutie versions less than 0.1 the change is simple. Replace all occurrences of the string ruru with rutie in your program. And if you would like to use ruby-sys code from Rutie rather than requiring ruby-sys you can change all existing references to ruby_sys to rutie::rubysys.

0.1

You will have additional considerations to change like Error being removed. For that; change instances of type ruru::result::Error to rutie::AnyException.

0.2

Migrated parse_arguments from VM to util.

0.3

Internal changes util from binding and rubysys have been replaced to reduce confusion and reduce duplication.

Troubleshooting

It panics for some Rubies on CI server tests

Sometimes the Ruby binary built isn't the best for the system. Be sure to compile Ruby for that system if this is the issue. With RVM do rvm reinstall --disable-binary with your choice of Ruby version.

Rust signal: 11, SIGSEGV: invalid memory reference

This is an indication that you haven't started a Ruby VM in Rust yet with VM::init();. Do this once before using Ruby code from Rust.

Error while loading shared libraries: libruby.so.#.#: cannot open shared object file: No such file or directory

This may happen when a Ruby program is trying to link with libruby via Rutie. Simply disable linking by setting the environment variable NO_LINK_RUTIE before the Rust code is compiled. This is needed to be done on the service TravisCI for example.

Calling methods from other methods within the `methods!` macro doesn't work

The way the macro is designed doesn't use the same parameter signatures you've provided and therefore it is recommended to implement any methods you want to re-use in Rust with functions outside of the methods! macro. You can simply call that new external method in the methods! macro when defining methods for Ruby to use.

Handling exceptions raised from Ruby in Rust code

If you're using any method that doesn't return a Result<AnyObject, AnyException> then any exception raised from the Ruby side will interfere with that Ruby thread and cause Rust to panic and stop. Ruby internally uses exceptions to effect the entire thread through an internal thread global value. To handle places where Ruby may raise an exception during Rust code execution you should use methods that are designed to handle that.

VM::eval
Object.protect_send
Object.protect_public_send

If you are writing lower level code and want to work more directly with the internal Ruby exception you may use VM::protect and read the source code for Object.protect_send to see how it's done.

Segfault during GC when using a Ruby method written in C

One possible issue that may cause this is when you store an item in Rust in heap memory rather than the stack.

An example case that caused this issue is the following:

Class::from_existing("Pathname").new_instance(Some(&vec![RString::new_utf8(path).to_any_object()]))

Ruby's GC traces objects from the stack. Rust's Vec, on the other hand, stores elements in the heap. So Ruby's GC may not be able to find the string you created and may release it. — @irxground

To rememdy the issue it required not using Vec but rather Rust's array type to store the argument on the stack rather than the heap.

let arguments = [RString::new_utf8(path).to_any_object()];
Class::from_existing("Pathname").new_instance(Some(&arguments))

Operating System Requirements

Everything is tested against 64 bit operating systems with 64 bit Ruby & Rust builds. 32 bit isn't currently supported.

Linux & Mac

Rust 1.26 or later
Ruby (64 bit) 2.4 or later

Windows

Rust 1.26 or later
Ruby 2.5+ built with MingW (64 bit)
MS Visual Studio (Build Tools)

Dynamic vs Static Builds

Ruby needs to be compiled with the --enable shared option. Dynamic linking to the Ruby library provides the best performance and best support. Static build support is incomplete for now.

If using RBENV then the following is recommended:

CONFIGURE_OPTS=--enable-shared rbenv install 2.5.3

You can check if your Ruby is compiled to be dynamically linked to by running the following and getting a "yes" response.

ruby -e "pp RbConfig::CONFIG['ENABLE_SHARED']"

If you'd like to make a pull request for adding static build support there are currently 3 methods not working with it and linking to the proper name of the ruby static lib file & path needs to be updated.

Contributing

Contributors are welcome!

The code is organized in 3 main layers. The rubysys folder is the raw mapping to Ruby C code and all the methods from there are unsafe. The binding folder is where we wrap those methods to abstract away all the unsafe methods to safe methods. The class folder is where the public API is implemented for using Ruby with Rust code. These methods in the class folder must all be documented and tested within the documentation. There is a subfolder under class for traits called traits.

Macros for abstracting away complexity are in src/dsl.rs.

Ruby's helper gem is in the submodule folder gem.

Additional Project History

If you need some more examples of usage or the git blame history please look at the Ruru project as Rutie has had the README completely rewritten and this first git commit is from Ruru. Note that there are some fundamental changes which that README won't account for. This project also had ruby-sys merged in which may have some additional beneficial git history.

LICENSE

Both projects that were merged into this project contained identifiers under the MIT license. This project follows with the same licensing. ruby-sys marked MIT as the license in the Cargo.toml file whereas ruru had that and included a LICENSE file. This projects LICENSE has credited the original author by preserving the MIT license author line and appending new author(s) which is permitted by the MIT LICENSE.

MIT LICENSE — see LICENSE

kphelps/rutie