README.md

ferrocarril

Archived: ferrocarril has been superseded by Artichoke.

ferrocarril aims to embed a Ruby on Rails web application that talks to an external MySQL database in Rust and serve the app with Rocket.

ferrocarril means railway in Spanish and sounds like ferrous which means containing iron.

hubris

The hubris crate runs a Sinatra::Base echo server with Nemesis.

Usage

HUBRIS_LOG=info cargo run --bin hubris

Then, open http://localhost:8000 on your browser.

Features

• Utilizes a Rust implenentation of Regexp and MatchData.
• Utilizes a stack-based synchronous implementation of Thread.
• Utilizes a complete implementation of Ruby 2.6.3 String API that uses a hybrid of mruby C, Ruby, and Rust.
• Utilizes implementations of Ruby standard library packages customized for mruby, including delegate, forwardable, json, monitor, ostruct, set, strscan, and uri.
• Utilizes patched versions of Sinatra and its dependencies.

foolsgold

The foolsgold crate is an early attempt to achieve the goal of a Rust-backed Ruby web application.

Usage

FOOLSGOLD_LOG=info cargo run --bin foolsgold

Then, open http://localhost:8000 on your browser.

Features

• Embeds a safe interpreter that wraps generated C bindings for mruby.
• Implements a web application server similar to Thin that supports shared nothing and prefork execution modes.
• Loads pure Ruby sources into the interpreter's virtual filesystem such that Ruby code can require them.
• Defines classes and modules in Rust and loads them into the virtual filesystem such that Ruby code can require them.
• Shares Rust objects across mruby interpreter instances.
• Defines Ruby classes whose instances are backed by Rust structs.
• Bridges Rust and Ruby by converting a Rack-compatible response into a Rocket response.

REPL

Crate mruby-bin provides an rirb executable that is an IRB shell and REPL for the mruby interpreter in this workspace. rirb aims to load every extension to mruby made by this workspace in addition to all gems in the gems crate.

Usage

cargo run --bin rirb

Contributing

There is a lot to build! If you'd like to help out, take a look at the open issues. Tickets that are tagged with good first issue might be a good introduction to the codebase.

Setup

A ferrocarril development environment has several dependencies. Setup your development environment.

Code Overview

To familiarize yourself with the code in this workspace, consider reviewing these source files:

File	Purpose	Learning Objective
manual.rs	mruby crate integration test	Define Rust-backed Ruby sources
extn::regexp	Regexp implementation	Implement a Ruby Core class with a mix of Rust and Ruby
nemesis.rs	nemesis crate Ruby runtime	Define a Gem
ffi_tests.rs	C API test suite	Manipulate an interpreter with the C API
repl.rs	REPL loop for rirb	Eval code on an interpreter and handle errors

Known Missing Features

Core

mruby does not implement all Ruby 2.6 core classes.

Required classes include (at least):

• File
• IO
• Regexp

Standard Library

mruby does not implement any of the Ruby 2.6 standard library.

See the stdlib tracking ticket (GH-8) for more details.

Gems

Rails requires lots of gems. This workspace maintains a registry of vendored gems. To support the goal of running Rails, this crate identifies dependencies, vendors the gem sources, patches gems so they parse on mruby, reimplements C extensions in Rust, and runs the tests for each gem.