Lib.rs

Rusty Road

^{In loving memory of Rusty, Rusty was my dog who passed away in September 2023. He was a wonderful loving pup. I am forever grateful for the time I had with him. He was my best friend and I will miss him dearly. I love you Rusty. 2014 - 2023}

Note: Rusty Road is still in development. Please use the release candidate or the cargo crate. Do not use master for production purposes. It is still under heavy development and is not ready for production use.

Rusty Road is a powerful and reliable web framework for the Rust programming language, inspired by Ruby on Rails. Combining the familiar conventions and ease of use of Rails with the performance and efficiency of Rust, Rusty Road empowers developers to build cutting-edge web applications with confidence.
The name "Rusty Road" not only reflects the language that the framework is built on, but also the journey that developers will take as they build their applications.

Born from a passion for Rust and a desire to make it more accessible to developers of all skill levels, Rusty Road was created to bridge the gap between Rust's low-level control and high-level web framework capabilities. With its lightning-fast performance and powerful features, Rusty Road is well-equipped to handle the demands of modern web development.

As Rusty Road continues to evolve, it will break new ground in Rust and web development, enabling developers to create increasingly advanced and sophisticated web applications. By providing a solid foundation for web development, Rusty Road will empower developers to achieve their greatest goals and make the world a better place through the power of software.

If you're tired of slow and unreliable web frameworks, and you're ready to take your web development to the next level with Rust, Rusty Road is your answer. Experience the perfect blend of Ruby on Rails' ease of use with the performance and efficiency of Rust, and unlock the full potential of your web development.
Don't let your web development be held back any longer. With Rusty Road, you can build fast and reliable applications that will delight your users and set you apart from the competition. Embrace the power of Rusty Road and elevate your web development today!

🆕 What's New in Rusty Road 0.1.8

• Rusty Road now includes GrapeJS, a drag and drop website builder. You can add it to your project by running rustyroad feature add grapesjs.
  1. You can read more about GrapeJS here.
  2. Find the example project here.
• Stable release of PostgreSQL support.
• Beta release of MySQL support.
• Beta release of SQLite support.

📝 Table of Contents

• Problem Statement
• Idea / Solution
• What is Rusty Road
• Current Features
• Dependencies / Limitations
• Future Scope
• Setting up a local environment
• Usage
• Technology Stack
• Contributing
• Authors
• Acknowledgments

🧐 Problem Statement

Rust Needs a Rails

I outlined this in a blog post here: https://rileyseaburg.com/posts/rust-needs-a-rails

• IDEAL: In a perfect world, Rust would have a framework that is as easy to use as Ruby on Rails. It would be easy to learn, easy to use, and easy to maintain. It would be fast, secure, and reliable. It would be extensible and customizable. It would be a joy to use.
• REALITY: Rust is a powerful language, but it is not easy to use. It is not easy to learn, and it is not easy to maintain. It is not fast to build with, even though it is secure, there is no framework that is as easy to use as Ruby on Rails. Rust is still the most loved programming language.

💡 Idea / Solution

Rusty Road is a framework written in Rust that is based on Ruby on Rails. It is designed to provide the familiar conventions and ease of use of Ruby on Rails, while also taking advantage of the performance and efficiency of Rust.

🐶 What is Rusty Road

Rusty Road is a framework written in Rust that is based on Ruby on Rails. It is designed to provide the familiar conventions and ease of use of Ruby on Rails, while also taking advantage of the performance and efficiency of Rust.

Rusty Road is intended to offer developers a powerful and reliable platform for building web applications using Rust, and its name incorporates a rust-themed crab pun in a playful and memorable way.

Understanding Rusty Road

Rusty Road currently works with the actix web framework, Sqlx, the Tera template engine, MySQL, PostgreSQL, and SQLite. It also has an additional optional feature that allows yout to add the GrapesJs editor with tailwind css support to your project.

🎈 Current Features

• Database migrations
• Support for PostgreSQL
• Support for MySQL
• Support for SQLite
• Routing (actix)
• Templating (Tera)
• CSS Framework (Tailwind CSS)
• Optional support for GrapesJs editor with tailwind css support

🚀 Future Scope

• Add support for GraphQL.
• Add support for API based microservices.
• Add support for more asset pipelines.
• Add kubernetes support.
• Add support for more authentication frameworks.

🏁 Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

Understanding the Build Process

Before diving into the setup and resolving the known issues, it’s crucial to understand how the build process works in this project and why certain steps are essential.

Why Use build.rs?

The build.rs file in Rust is a build script, executed before the Rust compiler to perform various tasks, such as compiling linked C libraries, generating code, and more.

In this project, build.rs performs crucial tasks:

1. PostgreSQL Linkage: It handles the linkage to the PostgreSQL library. If the build script cannot find the required PostgreSQL library, it will cause a build failure, hence the need to set up environment variables correctly, as mentioned in the Solving PostgreSQL linkage issue section.

2. Node.js Integration: It ensures the correct Node.js version is used and runs the build for the Node.js part of the project, housed in the grapesjs-tailwind directory. This is vital for integrating GrapesJS, a JavaScript framework, into the Rust project.

3. JavaScript File Inclusion: To include the JavaScript file (grapesjs-tailwind.min.js) required for GrapesJS, the build script copies this file to a known location during compile time. The Rust code then includes the file content using include_bytes! from this known location. This approach is robust, portable, and does not rely on the absolute path of the file.

🛠️ Setup and Installation

1. Install Prerequisites

Before you start, make sure you have Rust installed on your machine. If not, you can install it using rustup. Also, follow the instructions in the Installing Node Version Manager (nvm) for Windows section to set up Node.js.

2. Resolve Known Issues

• Follow the steps in the Solving PostgreSQL linkage issue section to resolve any PostgreSQL linkage issues.
• Address any additional linkage issues as described in the Solving the Generated Project linkage issue on Windows section.

3. Clone and Build the Project

• Clone the project to your local machine.
• Navigate to the project directory and run cargo build to build the project.

4. Verify the Build

• Ensure that there are no errors during the build process.
• If any issues arise, refer to the Known Issues section and make sure all prerequisites are correctly installed and configured.

🚀 Running the Project

Once you have resolved the known issues and understood the build process, you can run the project locally for development and testing purposes. Use cargo run to start the project, and follow the on-screen instructions or refer to the project documentation for using and testing the implemented features.

⚠️ Note

Understanding the build process and resolving known issues are crucial steps in setting up the project. While they might seem cumbersome, they ensure that the project runs seamlessly across different environments and configurations, laying a solid foundation for development, testing, and deployment.

Known Issues

There are a couple known issues, but they are easy to fix.

Solving PostgreSQL linkage issue

If you encounter an error like this: LINK : fatal error LNK1181: cannot open input file 'libpq.lib', it means the project is not able to find the libpq library. Follow these steps to resolve the issue:

1. If you haven't already, download and install PostgreSQL binaries for Windows from the official website.

2. Make sure to install it in an easily accessible location, like C:\\Program Files\\PostgreSQL\\13\\.

3. Set the POSTGRES_LIB_PATH environment variable pointing to your PostgreSQL lib directory where libpq.lib resides:

   • Press Windows key -> Type 'Environment Variables' -> Click on 'Edit the system environment variables' -> Click the 'Environment Variables...' button -> Under the 'System Variables' section, click the 'New...' button -> For 'Variable name', enter 'POSTGRES_LIB_PATH'. For 'Variable value', enter the path to the directory containing libpq.lib` -> Confirm and apply the changes. Remember, you might need to open a new command prompt or PowerShell window for the changes to take effect.

4. After you generate a website using rustyRoad, if you are on windows.

   • Create or edit the config.toml file inside the .cargo directory in your rustyroad project's root directory (create the .cargo directory if it doesn't exist). Add the following lines, replacing C:\\Program Files\\PostgreSQL\\13\\lib with your actual path where your libpq.lib is located. Remember to use double backslashes \\ for cross-platform compatibility.

   [target.'cfg(windows)']
   rustflags = ["-C", "link-arg=/LIBPATH:C:\\Program Files\\PostgreSQL\\13\\lib"]
   

Note: Replace C:\\Program Files\\PostgreSQL\\13\\lib with your exact path where PostgreSQL is installed.

Note: The Rust build script uses this POSTGRES_LIB_PATH environment variable.

Solving the Generated Project linkage issue on Windows

1. Navigate to your rustyroad project's root directory (where your Cargo.toml file is located).

   cd to/your/project/directory
   

2. Inside this directory, find the .cargo directory, or create it if it doesn't exist.

mkdir .cargo    # if .cargo directory doesn't exist

3. Inside the .cargo directory, create or edit the config.toml file.

cd .cargo
touch config.toml  # if config.toml doesn't exist

4. Open the config.toml file in your preferred text editor. Add the following lines to the config.toml file, replacing C:\\ProgramData\\PostgreSQL\\16rc1\\lib with the actual path (use double backslashes) where your libpq.lib file is located.

[target.'cfg(windows)']
rustflags = ["-C", "link-arg=/LIBPATH:C:\\ProgramData\\PostgreSQL\\16rc1\\lib"]

5. Save and close the file.
6. Now when you build your project again with cargo build or cargo run, the build should find the libpq.lib file correctly.

Installing Node Version Manager (nvm) for Windows

The Rusty Road project uses Node.js, which we'll manage versions with by using Node Version Manager (nvm). To install nvm for Windows:

1. Visit the latest release page for nvm for Windows at https://github.com/coreybutler/nvm-windows/releases
2. Download the nvm-setup.zip file.
3. Extract the zip file and run the installer (nvm-setup.exe).
4. Follow the instructions provided by the installer.
5. Once nvm is installed, close your terminal or command prompt and open a new one for the changes to take effect.
6. Verify that nvm is installed correctly by typing nvm version into your new terminal. If a version number is displayed, nvm has been installed successfully.

Prerequisites

Rust is required to build and run Rusty Road. You can install Rust using rustup. rustup is a tool that helps manage Rust installations, it allows for installing multiple versions of Rust and switching between them easily.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Installing

Crates.io

Rusty Road is available on crates.io. You can install it using cargo:

cargo install rustyroad

Bonus Step #1 (optional): Add the following to your .bashrc or .zshrc file to make the rustyroad command available in your terminal:

export PATH="$HOME/.cargo/bin:$PATH"

Bonus Step #2 (optional): Create a symbolic link to the rustyroad command in your ~/.cargo/bin directory. This will create a symlink from rustyroad to rr inside ~/.cargo/bin/ directory. Now you can invoke rr command which is just a symlink to rustyroad.

sudo ln -s ~/.cargo/bin/rustyroad /usr/local/bin/rr

(Windows users can download the executable from the releases page and add it to their PATH.)

Installing from source

Clone the repository and run the setup script.

git clone --recurse-submodules https://github.com/RustyRoad/RustyRoad

cd RustyRoad

cargo run

🎈 Usage

The cli will prompt you to create a new project. Enter the name of your project and the cli will create a new project in the current directory.

$ rustyroad
CLI for Rusty Road

Usage: rustyroad.exe <COMMAND>

Commands:
  new         Creates a new project
  generate    Generates a new route, model, or controller
  migration   Runs migrations
  feature     Adds a new feature to your project
  help        Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

Follow the command flow to create a new project

rustyroad new my_project

Generate a new route

rustyroad generate route users

Note: If you want to run an example project, be sure to run the migrations first.

cd example

rustyroad migration run

⛏️ Built With

• Rust - Programming Language
• actix - Web Framework
• Sqlx - SQLx
• Tera - Template Engine
• PostgreSQL - Database
• Cucumber Rust - Testing

✍️ Authors

• @rileyseaburg - Idea & Initial work

See also the list of contributors who participated in this project.

🎉 Acknowledgments

• Creator of Ruby on Rails, David Heinemeier Hansson (DHH)
• Creator of Rust, Graydon Hoare