blackroad/roadc/QUICKSTART.md

🚀 BlackRoad Language - Quick Start Guide

5-Minute Setup

Step 1: Build the Compiler

cd ~/roadc
gcc -std=c99 -O2 -o roadc roadc.c

Step 2: Write Your First Program

cat > hello.road << 'EOF'
# My First BlackRoad Program
fun main():
    print("Hello, BlackRoad! 🖤🛣️")
EOF

Step 3: Run It!

./roadc hello.road

What's Next?

Try the Examples

# Simple 3D rotating cube
./roadc examples/hello_3d.road

# Full 3D space shooter game
./roadc examples/space_shooter.road

Start the REPL

./roadc
> let x = 42
> print(x)

Read the Docs

• Full Specification
• README
• Complete Guide

Syntax Cheat Sheet

Variables

let x: int = 42           # Immutable
var y = 3.14              # Mutable (type inferred)
const PI = 3.14159        # Constant

Functions

fun add(a: int, b: int) -> int:
    return a + b

fun greet(name: string):
    print("Hello, {name}!")

Control Flow

if x > 10:
    print("Large")
elif x > 5:
    print("Medium")
else:
    print("Small")

for i in 0..10:
    print(i)

while condition:
    process()

3D Objects

space MyScene:
    cube Box:
        position: vec3(0, 0, 0)
        color: #FF1D6C

    light Sun:
        type: point
        intensity: 1.0

    camera Cam:
        position: vec3(0, 0, 5)
        fov: 75

Types

type User:
    name: string
    age: int
    email: string

let user = User{
    name: "Alexa",
    age: 25,
    email: "alexa@blackroad.io"
}

Common Tasks

Create a 3D Scene

space Game:
    cube Player:
        position: vec3(0, 0, 0)
        color: #FF1D6C

fun main():
    render(Game)

Async/Await

async fun fetchData(url: string) -> string:
    let response = await http.get(url)
    return response.text()

fun main():
    let data = await fetchData("https://api.example.com")
    print(data)

Lists & Loops

let numbers = [1, 2, 3, 4, 5]

for num in numbers:
    print(num * 2)

Pattern Matching

match status:
    200 -> print("OK")
    404 -> print("Not Found")
    500..599 -> print("Server Error")
    _ -> print("Unknown")

Testing Your Code

Python Parser (for validation)

python3 parser.py

C Compiler (native)

./roadc your_file.road

Deploy to Raspberry Pi

# On your Mac
scp roadc.c pi@192.168.4.38:~

# On the Pi
ssh pi@192.168.4.38
gcc -std=c99 -O2 -o roadc roadc.c
./roadc

Troubleshooting

"Command not found: roadc"

# Make sure you compiled it
gcc -std=c99 -O2 -o roadc roadc.c

# Or use full path
./roadc test.road

"Syntax Error"

Check the syntax matches the specification:

# Correct
let x: int = 42

# Wrong
int x = 42  # This is C, not BlackRoad!

"Unexpected token"

Make sure indentation is consistent (spaces or tabs, not mixed).

Learning Resources

1. Read the Spec - ~/BLACKROAD_LANGUAGE_SPECIFICATION.md
2. Study Examples - ~/roadc/examples/*.road
3. Experiment in REPL - ./roadc (no arguments)
4. Check the Source - Lexer and parser are well-documented

Community

• Issues: blackroad.systems@gmail.com
• Ideas: amundsonalexa@gmail.com
• GitHub: Coming soon!

---

Happy coding in BlackRoad! 🖤🛣️