Skip to content

Getting Started with USL

Welcome to USL! This guide will help you get up and running quickly.

Quick Installation

Choose your platform:

curl -fsSL https://raw.githubusercontent.com/shaifulshabuj/USL/main/scripts/install.sh | sh

irm https://raw.githubusercontent.com/shaifulshabuj/USL/main/scripts/install.ps1 | iex

git clone https://github.com/shaifulshabuj/USL.git
cd USL/compiler
cargo install --path .

docker pull ghcr.io/shaifulshabuj/usl:latest
docker run -it ghcr.io/shaifulshabuj/usl:latest usl --version

Verify Installation

usl --version
# Expected: usl 1.0.0

System Requirements

  • Operating System: macOS 10.15+, Linux (Ubuntu 20.04+), Windows 10+
  • Memory: 2GB RAM minimum (4GB recommended)
  • Disk Space: 500MB for compiler + generated code
  • Dependencies:
  • Rust 1.75+ (for compilation from source)
  • Node.js 18+ (for TypeScript code generation)
  • Python 3.9+ (for Python code generation)

Editor Support

Extension: Coming soon! 🚧

Planned features: - Syntax highlighting - IntelliSense and autocomplete - Error checking - Format on save - Go to definition - Refactoring support

Other Editors

Plugins: Coming soon! 🚧

  • Vim/Neovim: In development
  • Emacs: Planned
  • IntelliJ IDEA: Planned
  • Sublime Text: Planned

Create Your First Project

mkdir my-app
cd my-app
usl init

This creates:

my-app/
├── my-app.usl      # Main specification
├── usl.toml        # Project configuration
├── .gitignore      # Git ignore rules
└── README.md       # Project documentation

Hello World

Edit my-app.usl:

domain HelloWorld {
  entity Greeting {
    id: GreetingId @primary
    message: String
  }
}

service GreetingService {
  action sayHello(name: String) -> Greeting
    effects { Write(Greeting) }
    implementation {
      let greeting = Greeting {
        id: generateId(),
        message: "Hello, " + name + "!"
      }
      store(greeting)
      return greeting
    }
}

Compile

usl compile my-app.usl

Expected output: 

Compiling my-app.usl...
✓ Lexical analysis complete
✓ Parsing complete
✓ Semantic analysis complete
✓ Type checking complete
✓ Verification complete

Compilation successful!

Generate Code

usl generate --target typescript --output ./backend
cd backend
npm install
npm run dev

usl generate --target rust --output ./api
cd api
cargo build --release
./target/release/api

usl generate --target python --output ./server
cd server
pip install -r requirements.txt
python main.py

Test Your API

curl -X POST http://localhost:3000/api/sayHello \
  -H "Content-Type: application/json" \
  -d '{"name": "World"}'

Response: 

{
  "id": "greeting_abc123",
  "message": "Hello, World!"
}

What's Next?

You've successfully: - ✅ Installed USL - ✅ Created your first project - ✅ Written USL code - ✅ Compiled and generated code - ✅ Tested your API

Continue learning:

  1. Tutorial 1: Getting Started - Build a complete task manager
  2. Language Overview - Learn USL syntax and semantics
  3. Example Projects - Explore real-world applications

Troubleshooting

Installation Issues

Problem: usl: command not found

Solution: 

# Add to PATH
export PATH="$HOME/.usl/bin:$PATH"
# Add to shell profile
echo 'export PATH="$HOME/.usl/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Problem: Permission denied

Solution: 

chmod +x ~/.usl/bin/usl

Compilation Errors

See Error Reference for detailed error explanations.

Getting Help

Configuration

Edit usl.toml to customize your project:

[package]
name = "my-app"
version = "0.1.0"
authors = ["Your Name <you@example.com>"]

[compiler]
# Verification level: none, basic, full
verification = "full"
# Enable experimental features
experimental = false

[generate]
# Default code generation target
default_target = "typescript"

[generate.typescript]
# Output directory
output = "./backend"
# Package manager: npm, yarn, pnpm
package_manager = "npm"
# Framework: express, fastify, nestjs
framework = "express"

[generate.rust]
output = "./api"
# Web framework: actix, axum, rocket
framework = "axum"

[generate.python]
output = "./server"
# Framework: flask, fastapi, django
framework = "fastapi"

Update USL

Check for updates:

usl update

Or reinstall:

curl -fsSL https://usl-lang.dev/install.sh | sh

Uninstall

rm -rf ~/.usl
# Remove from PATH in shell profile

Learn More