This guide covers everything you need to install and set up WsForge for your WebSocket projects.

• Prerequisites
• Installing Rust
• Adding WsForge to Your Project
• Features
• Platform-Specific Instructions
• Development Tools
• Verification
• IDE Setup
• Troubleshooting

Before installing WsForge, ensure you have:

• Rust: Version 1.70 or later (recommended: latest stable)
• Operating System: Windows, Linux, or macOS
• Internet Connection: For downloading dependencies

If you don't have Rust installed, use rustup (the official Rust installer):

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

Follow the on-screen instructions. After installation, reload your shell:

source $HOME/.cargo/env

Download and run rustup-init.exe from the official website.

rustc --version
cargo --version

You should see version information for both commands.

Keep Rust up to date:

rustup update

cargo new my-websocket-app
cd my-websocket-app

Add WsForge to your Cargo.toml:

[dependencies]
wsforge = "0.1.0"
tokio = { version = "1.40", features = ["full"] }

For JSON message handling:

[dependencies]
wsforge = "0.1.0"
tokio = { version = "1.40", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

Recommended full setup with logging:

[dependencies]
wsforge = "0.1.0"
tokio = { version = "1.40", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
tracing = "0.1"
tracing-subscriber = "0.3"

WsForge supports optional features for flexibility:

[dependencies]
wsforge = "0.1.0"

[dependencies]
wsforge = { version = "0.1.0", features = ["full"] }

[dependencies]
wsforge = { version = "0.1.0", default-features = false }

[dependencies]
wsforge = { version = "0.1.0", features = ["macros"] }

Install OpenSSL development libraries:

sudo apt-get update
sudo apt-get install -y libssl-dev pkg-config build-essential

sudo dnf install -y openssl-devel gcc

sudo pacman -S openssl pkg-config

No additional system dependencies required. However, you may need:

1. Visual Studio Build Tools: Download from Microsoft

   • Select "Desktop development with C++"

2. Alternative: Install MSYS2 for MinGW toolchain

No additional dependencies required. Xcode Command Line Tools should be sufficient:

xcode-select --install

Install helpful development tools:

# Code formatting
rustup component add rustfmt

# Linting
rustup component add clippy

# Watch for file changes and auto-rebuild
cargo install cargo-watch

# View expanded macros
cargo install cargo-expand

# Code coverage
cargo install cargo-tarpaulin

# Better error messages
cargo install cargo-nextest

# Dependency graph visualization
cargo install cargo-deps

# Audit dependencies for security issues
cargo install cargo-audit

Create a minimal test file src/main.rs:

use wsforge::prelude::*;

async fn echo(msg: Message) -> Result<Message> {
    Ok(msg)
}

#[tokio::main]
async fn main() -> Result<()> {
    println!("✅ WsForge installed successfully!");

    let router = Router::new()
        .default_handler(handler(echo));

    println!("🚀 Server ready on ws://127.0.0.1:8080");
    router.listen("127.0.0.1:8080").await?;
    Ok(())
}

cargo build

If successful, you should see:

Compiling wsforge v0.1.0
Compiling my-websocket-app v0.1.0
Finished dev [unoptimized + debuginfo] target(s) in X.XXs

cargo run

You should see:

✅ WsForge installed successfully!
🚀 Server ready on ws://127.0.0.1:8080

Recommended extensions:

1. rust-analyzer (rust-lang.rust-analyzer)

   • Install: code --install-extension rust-lang.rust-analyzer
   • Provides code completion, go-to-definition, and more

2. CodeLLDB (vadimcn.vscode-lldb)

   • Install: code --install-extension vadimcn.vscode-lldb
   • Debugging support

3. crates (serayuzgur.crates)

   • Install: code --install-extension serayuzgur.crates
   • Manage dependencies

4. Even Better TOML (tamasfe.even-better-toml)

   • Install: code --install-extension tamasfe.even-better-toml
   • TOML syntax support

Create .vscode/settings.json:

{
  "rust-analyzer.cargo.features": "all",
  "rust-analyzer.checkOnSave.command": "clippy",
  "editor.formatOnSave": true,
  "[rust]": {
    "editor.defaultFormatter": "rust-lang.rust-analyzer"
  }
}

Install the Rust plugin:

1. Go to Settings → Plugins
2. Search for "Rust"
3. Install and restart

Use rust.vim and coc.nvim with coc-rust-analyzer:

Plug 'rust-lang/rust.vim'
Plug 'neoclide/coc.nvim', {'branch': 'release'}

Use rust-mode and lsp-mode:

(use-package rust-mode
  :ensure t
  :hook (rust-mode . lsp))

Solution: Install a C compiler:

• Linux: sudo apt-get install build-essential
• macOS: xcode-select --install
• Windows: Install Visual Studio Build Tools

Solution: Make sure you're in the project directory:

cd my-websocket-app
cargo build

Solution: Install OpenSSL development libraries:

sudo apt-get install libssl-dev pkg-config

Solution: Use a faster linker:

1. Install lld or mold:

   sudo apt-get install lld  # or mold
   

2. Create .cargo/config.toml:

   [target.x86_64-unknown-linux-gnu]
   linker = "clang"
   rustflags = ["-C", "link-arg=-fuse-ld=lld"]
   

Solution: Ensure your Cargo.toml includes:

[dependencies]
wsforge = { version = "0.1.0", features = ["macros"] }

If you encounter issues:

1. Check documentation: docs/
2. Search issues: GitHub Issues
3. Ask for help: Open a new issue with:
   • Your OS and Rust version (rustc --version)
   • Error messages (full output)
   • Steps to reproduce

Now that WsForge is installed:

1. ✅ Quick Start Guide - Build your first server
2. ✅ Handlers Documentation - Learn about handler functions
3. ✅ Examples - Explore working examples

• Current Version: 0.1.0
• Minimum Rust: 1.70
• Recommended Rust: Latest stable
• License: MIT

Need help? Open an issue on GitHub or check the FAQ.