mrubyedge_cli/
lib.rs

1//! # mrubyedge-cli
2//!
3//! Command-line interface for mruby/edge - a lightweight, WebAssembly-focused mruby VM implementation.
4//!
5//! ## About mruby/edge
6//!
7//! mruby/edge is an mruby-compatible virtual machine implementation written in Rust,
8//! specifically designed for WebAssembly environments. It aims to provide:
9//!
10//! - **WebAssembly-first design**: Optimized for running Ruby code in browsers and edge computing environments
11//! - **Lightweight runtime**: Minimal footprint and binary size suitable for constrained environments
12//! - **mruby compatibility**: Executes mruby bytecode (`.mrb` files) and Ruby source code
13//! - **Rust safety**: Built with Rust for memory safety and reliability
14//!
15//! ## Installation
16//!
17//! Install mrubyedge-cli using cargo:
18//!
19//! ```sh
20//! cargo install mrubyedge-cli
21//! ```
22//!
23//! Or build from source:
24//!
25//! ```sh
26//! git clone https://github.com/mrubyedge/mrubyedge.git
27//! cd mrubyedge
28//! cargo build --release -p mrubyedge-cli
29//! ```
30//!
31//! ## Getting Started
32//!
33//! Create a simple Ruby script `hello.rb`:
34//!
35//! ```ruby
36//! puts "Hello from mruby/edge!"
37//! puts RUBY_ENGINE
38//! ```
39//!
40//! Run it with mrbedge:
41//!
42//! ```sh
43//! mrbedge hello.rb
44//! # or explicitly
45//! mrbedge run hello.rb
46//! ```
47//!
48//! ## Main Features
49//!
50//! ### `run` - Execute Ruby Scripts
51//!
52//! The `run` subcommand executes Ruby source files (`.rb`) or compiled mruby bytecode (`.mrb`).
53//!
54//! **Usage:**
55//! ```sh
56//! mrbedge run <file>
57//! # or simply
58//! mrbedge <file>
59//! ```
60//!
61//! **Examples:**
62//! ```sh
63//! # Run Ruby source
64//! mrbedge run script.rb
65//!
66//! # Run compiled bytecode
67//! mrbedge run script.mrb
68//! ```
69//!
70//! ### `compile-mrb` - Compile Ruby to Bytecode
71//!
72//! Compiles Ruby source code into mruby bytecode format for faster loading and distribution.
73//!
74//! **Usage:**
75//! ```sh
76//! mrbedge compile-mrb <input.rb> -o <output.mrb>
77//! ```
78//!
79//! **Examples:**
80//! ```sh
81//! # Compile a single file
82//! mrbedge compile-mrb app.rb -o app.mrb
83//!
84//! # Run the compiled bytecode
85//! mrbedge run app.mrb
86//! ```
87//!
88//! ### `wasm` - Generate WebAssembly Modules
89//!
90//! Compiles Ruby code directly into a standalone WebAssembly module that can run in browsers
91//! or any WebAssembly runtime.
92//!
93//! **Usage:**
94//! ```sh
95//! mrbedge wasm <input.rb> -o <output.wasm>
96//! ```
97//!
98//! **Examples:**
99//! ```sh
100//! # Generate WebAssembly module
101//! mrbedge wasm app.rb -o app.wasm
102//!
103//! # Use in browser or Node.js
104//! # The generated WASM can be loaded and executed in any WASM runtime
105//! ```
106//!
107//! **Use Cases:**
108//! - Serverless edge computing
109//! - Browser-based applications
110//! - Microservices with minimal overhead
111//! - Cross-platform portable executables
112//!
113//! **WASI Support:**
114//!
115//! The `wasm` command can generate both WASI-enabled and non-WASI WebAssembly binaries.
116//! By default, it produces WASI-enabled modules. To disable WASI support, use the `--no-wasi` flag.
117//!
118//! **Import/Export Functions:**
119//!
120//! You can specify WebAssembly function imports and exports using RBS (Ruby Signature) files.
121//! Place RBS files with specific naming conventions alongside your Ruby script:
122//!
123//! For a Ruby script named `foo.rb`:
124//! - **`foo.import.rbs`**: Defines external functions to import from the WebAssembly host
125//! - **`foo.export.rbs`**: Defines Ruby functions to export as WebAssembly functions
126//!
127//! **Example:**
128//! ```ruby
129//! # app.rb
130//! def calculate(x, y)
131//!   x + y
132//! end
133//! ```
134//!
135//! ```rbs
136//! # app.export.rbs
137//! def calculate: (Integer, Integer) -> Integer
138//! ```
139//!
140//! ```rbs
141//! # app.import.rbs
142//! def external_log: (String) -> void
143//! ```
144//!
145//! The generated WebAssembly module will expose `Kernel#calculate` and can call `Kernel#external_log`
146//! from the host environment.
147//!
148//! NOTE: Inlined RBS for imports and exports annotations will be supported in future releases.
149//!
150//! ## Additional Resources
151//!
152//! - [GitHub Repository](https://github.com/mrubyedge/mrubyedge)
153//! - [API Documentation](https://docs.rs/mrubyedge-cli)
154//! - [Core VM Documentation](https://docs.rs/mrubyedge)
155
156pub mod rbs_parser;
157pub mod subcommands;
158pub mod template;
mrubyedge_cli/lib.rs

mrubyedge_cli/
lib.rs
