Square.rb - Unofficial Ruby Runtime for SquareCloud

Square.rb is a Python-based Ruby script executor that allows you to run Ruby code without installing Ruby on your system. It's designed to be portable and self-contained, perfect for SquareCloud environments.

Features

• No Ruby Installation Required - Runs Ruby scripts using portable runtime
• Automatic Gem Management - Installs gems from Gemfile automatically
• Interactive Mode - Run Ruby code interactively like IRB
• Cross-Platform - Works on Windows, macOS, and Linux
• Error Handling - Graceful error handling with detailed output
• Self-Contained - Everything stays in the project directory

Quick Start

Basic Usage

# Run default script (automatically finds start.rb, main.rb, app.rb, or index.rb)
python main.py

# Run a specific Ruby script
python main.py hello.rb

# Run with arguments
python main.py app.rb --port 3000 --host 0.0.0.0

# Interactive mode
python main.py --interactive

# Install gems from Gemfile
python main.py --install-gems

First Time Setup

1. Place Ruby Binary (Optional): Square.rb will try to download Ruby automatically, but you can also place a Ruby binary in the ruby_runtime/ directory.

2. Create Your Ruby Script: Write your Ruby code in any .rb file. Create a start.rb file to run automatically when no script is specified.

3. Add Dependencies (Optional): Create a Gemfile with your required gems. Gems are installed automatically when scripts run.

4. Environment Variables (Optional): Create a .env file to set environment variables that will be loaded automatically.

5. Run: Use python main.py to run the default script, or python main.py your_script.rb to execute a specific Ruby script.

Examples

Default Script (start.rb)

# start.rb - Runs automatically when no script specified
puts "Welcome to Square.rb!"
puts "Environment: #{ENV['SQUARE_ENVIRONMENT']}"

Simple Script

# hello.rb
puts "Hello from Square.rb!"
puts "Ruby version: #{RUBY_VERSION}"

With Gems

# app.rb
require 'json'

data = { name: "Square.rb", version: "1.0" }
puts JSON.pretty_generate(data)

Interactive Mode

$ python main.py --interactive
Square.rb Interactive Ruby Mode
Type 'exit' or 'quit' to exit
----------------------------------------
ruby> puts "Hello World!"
Hello World!
ruby> 2 + 2
4
ruby> exit

Project Structure

squarerb/
├── main.py              # Main Python script
├── start.rb             # Default script (auto-runs when no args)
├── hello.rb             # Sample Ruby script
├── Gemfile              # Sample Gemfile
├── .env                   # Environment variables (optional)
├── ruby_runtime/        # Ruby runtime directory (auto-created)
│   ├── bin/            # Ruby binaries
│   ├── gems/           # Installed gems
│   └── bundle/         # Bundle cache
└── README.md

Command Line Options

• python main.py - Run default script (start.rb, main.rb, app.rb, or index.rb)
• python main.py script.rb [args...] - Execute a Ruby script with optional arguments
• python main.py --interactive - Start interactive Ruby mode
• python main.py --install-gems - Install gems from Gemfile
• python main.py --help - Show help information

How It Works

1. Runtime Detection: Square.rb detects your platform and architecture
2. Ruby Acquisition: Downloads appropriate Ruby runtime if not present
3. Environment Setup: Configures Ruby environment variables and loads .env file
4. Gem Installation: Automatically installs gems from Gemfile (no manual intervention needed)
5. Script Execution: Runs your Ruby script with proper error handling
6. Default Script: Automatically finds and runs start.rb when no script is specified

Supported Platforms

• Windows (x64, x86)
• macOS (Intel, Apple Silicon)
• Linux (x64, x86)

Error Handling

Square.rb provides comprehensive error handling:

• Missing Scripts: Clear error messages for missing Ruby files
• Runtime Errors: Captures and displays Ruby errors with stack traces
• Timeout Protection: Scripts timeout after 5 minutes to prevent hanging
• Graceful Degradation: Falls back to manual Ruby installation if automatic download fails

Tips

1. Default Script: Create a start.rb file to run automatically when no arguments are provided
2. Environment Variables: Use .env file to set environment variables automatically
3. Gems: Gems are installed automatically from Gemfile - no manual bundle install needed
4. Performance: First run may be slower due to Ruby runtime download
5. Debugging: Use --interactive mode for testing small code snippets
6. Portability: Keep everything in the project directory for easy deployment

Troubleshooting

Ruby Not Found

• Square.rb will attempt to download Ruby automatically
• You can manually place Ruby binary in ruby_runtime/ directory

Gem Installation Fails

• Check your internet connection
• Verify Gemfile syntax
• Try running python main.py --install-gems separately

Script Execution Fails

• Check Ruby script syntax
• Verify required gems are in Gemfile
• Use --interactive mode for debugging

License

This project is open source and available under the MIT License.

---

Square.rb - Making Ruby accessible everywhere, no installation required!