RGC 标准库提供了同步的网络能力：TCP / UDP / HTTP / HTTPS，全部以源码模块形式放在 lib/ 下，用 RGC 自身封装：

底层通过 extern def 直接调用 libc socket / OpenSSL / zlib，链接参数由编译器按符号引用自动追加（TLS 追加 -lssl -lcrypto，压缩追加 -lz），不需要手动配置链接器。

一个贯穿全篇的设计：网络操作的结果用 ok: bool + error: str 的包装类返回，失败不 panic、不抛异常。连接被拒绝、解析失败、端口越界都会得到一个 ok=False 的结果，你负责检查并处理。

1. 准备

编译器会自动在标准库目录（lib/）查找模块，直接编译运行即可：

rgc main.rg -o prog
./prog

本篇所有示例都在本仓库用 src/build/rgc3 编译运行验证过，可直接复制。

2. TCP：连接与监听

2.1 一个完整的 TCP 回环示例

下面这个程序单进程内完成「监听 → 连接 → 接受 → 双向收发 → 关闭」全流程。listen_on 使用端口 0 时，内核会分配一个临时端口：

import net

def main() -> int {
    # 1) 监听：端口 0 让内核分配临时端口
    l = net.listen_on("127.0.0.1", 0)
    if not l.ok {
        print("listen failed:", l.error)
        return 1
    }
    listener = l.listener
    port = listener.local_port()
    print("listening on port", port)

    # 2) 客户端连接（backlog 让连接先排队）
    c = net.connect_to("127.0.0.1", port)
    if not c.ok {
        print("connect failed:", c.error)
        listener.close()
        return 1
    }
    client = c.stream

    # 3) 服务器接受连接
    a = listener.accept()
    if not a.ok {
        print("accept failed:", a.error)
        client.close()
        listener.close()
        return 1
    }
    server = a.stream

    # 4) 双向收发
    client.send("ping")
    r1 = server.recv(64)
    print("server got:", r1.value)     # ping

    server.send("pong")
    r2 = client.recv(64)
    print("client got:", r2.value)     # pong

    # 5) 关闭：对端会读到 EOF（ok=True, value=""）
    client.close()
    eof = server.recv(16)
    print("eof:", eof.ok, eof.value.len())   # True 0

    server.close()
    listener.close()
    return 0
}

运行输出：

listening on port 43727
server got: ping
client got: pong
eof: True 0

几个要点：

• send 阻塞直到全部字节写出，返回实际发送字节数；
• recv(max) 最多读取 max 字节；对端关闭（EOF）时返回 ok=True, value=""；
• 真实错误（连接拒绝、解析失败、超时）返回 ok=False + error 文本；
• close() 重复调用安全，不会崩溃。

2.2 TCP API 一览

结果包装类：TcpConnect / TcpListen / TcpAccept / TcpRecv，都带 ok: bool 与 error: str 字段（失败时 stream.fd == -1）。

3. UDP：数据报

UDP 是无连接的，udp.open 绑定一个本地端口，send_to / recv_from 每次收发一个数据报：

import bytes
import udp

def main() -> int {
    a = udp.open("127.0.0.1:0")
    b = udp.open("127.0.0.1:0")
    if not a.ok or not b.ok {
        print("bind failed")
        return 1
    }
    s1 = a.sock
    s2 = b.sock
    port2 = s2.local_port()

    # 发送数据报
    r = s1.send_to("ping", "127.0.0.1", port2)
    print("sent:", r.ok, r.sent)                     # True 4
    r2 = s2.recv_from(64)
    print("got:", r2.data, r2.host, r2.port == s1.local_port())

    # 数据报边界：两次发送 -> 两次接收
    s1.send_to("one", "127.0.0.1", port2)
    s1.send_to("two", "127.0.0.1", port2)
    print("dgram:", s2.recv_from(64).data, s2.recv_from(64).data)   # one two

    # 二进制安全：data_bytes 保留全部字节
    payload = bytes.bytes_new(2)
    payload.push(0)
    payload.push(255)
    s1.send_bytes(payload, "127.0.0.1", port2)
    r3 = s2.recv_from(16)
    print("binary:", r3.data_bytes.len, r3.data_bytes.get(0), r3.data_bytes.get(1))

    # 读超时
    s2.set_timeout(100)
    r4 = s2.recv_from(16)
    print("timeout:", r4.ok, r4.error)              # False timeout

    s1.close()
    s2.close()
    return 0
}

运行输出：

sent: True 4
got: ping 127.0.0.1 True
dgram: one two
binary: 2 0 255
timeout: False timeout

要点：

• 一次 recv_from 对应一个数据报，不会与相邻数据报拼接；
• data 按 C 字符串处理（遇 NUL 截断）；需要二进制数据用 data_bytes 和 send_bytes；
• set_timeout(ms) 后超时返回 ok=False, error="timeout"，0 恢复阻塞；
• IPv6 直接 udp.open_on("::1", 0)；主机名自动解析（localhost 等）。

4. HTTP 客户端

4.1 一次性请求

import http 提供模块级函数，一次调用完成请求：

import http

def main() {
    r = http.get("http://127.0.0.1:8080/hello")
    if not r.ok {
        print("request failed:", r.error)          # 网络/证书/限额错误
        return
    }
    res = r.response
    print("status:", res.status)                   # 200
    print("type:", http.header(@res, "Content-Type"))
    print("body:", res.body)
}

• http.get(url) / http.post(url, body) / http.request(method, url, body)；
• 响应结构 HttpResponse：status、version、headers、body、body_bytes、url（重定向后的最终地址）；
• http.header(@res, "Content-Type") 大小写不敏感地查响应头，未找到返回 ""；
• body 是已解压的文本（strlen 语义），二进制内容用 body_bytes；
• 默认自动跟随 3xx 重定向，自动解压 gzip / deflate。

4.2 复用连接的客户端

需要 keep-alive、Cookie、自定义头、代理或限额时，使用 http.new_client()：

import http

def main() {
    c = http.new_client()
    c.add_header("X-Token", "secret")          # 每次请求附加
    c.timeout_ms = 5000                          # 读超时
    c.max_body = 1 << 20                        # 正文上限 1 MiB

    a = c.get("http://127.0.0.1:8080/a")       # 同一 keep-alive 连接
    b = c.post("http://127.0.0.1:8080/b", "data")
    print(a.response.status, b.response.status)
    c.close()
}

常用配置字段：

4.3 查询串编解码

pairs = List[str]()
pairs.push("q=a b")
pairs.push("x=1")
print(http.encode_query(pairs))        # q=a%20b&x=1

dq = http.decode_query("q=hello+world&x=%E4%BD%A0")
print(dq.get(0), dq.get(1))             # q=hello world x=你

4.4 异步请求

async def 函数在调用点派生线程，返回 Task[T]，配合内建 asyncio 汇合：

import asyncio
import http

def main() -> int {
    tasks = List[Task[HttpResult]]()
    tasks.push(http.get_async("http://127.0.0.1:8080/a"))
    tasks.push(http.get_async("http://127.0.0.1:8080/b"))
    rs = asyncio.run(asyncio.gather(tasks))
    print(rs.len(), rs.get(0).ok, rs.get(1).ok)
    return 0
}

5. HTTPS 与 TLS

http 模块原生支持 https://（默认校验证书链与主机名），无需额外配置。需要跳过证书校验（本地自签名服务）时用 https 兼容层：

import https

def main() {
    r = https.get("https://example.com/")
    if r.ok {
        print(r.response.status)
    } else {
        print("request failed:", r.error)      # 证书/网络错误
    }

    local = https.get_insecure("https://127.0.0.1:8443/")
    print(local.ok)                              # 跳过证书校验，仅供本地测试
}

需要低层 TLS 时用 tls.connect：

import tls

def main() {
    c = tls.connect("example.com", 443, 10000, True)   # 超时 10s，校验证书
    if c.ok {
        s = c.conn
        s.send("GET / HTTP/1.1\r\nHost: example.com\r\n\r\n")
        print(s.recv(4096).value)
        s.close()
    }
}

6. 实战：自包含的 HTTP 请求工具

现在把 net 和 http 结合起来，写一个自包含的程序：main 在后台用 --serve 参数启动自己作为最小 HTTP 服务器，然后作为客户端用 http.get / http.post 请求它。这样不需要任何外部服务，单文件即可跑通。

import http
import io
import net
import os
import time

# --serve 模式：最小 HTTP 服务器（响应 3 个连接）
def serve(port_file: str) -> int {
    l = net.listen_on("127.0.0.1", 0)
    if not l.ok {
        return 1
    }
    listener = l.listener
    port = listener.local_port()
    wr = io.write_file(port_file, to_string(port))
    if not wr.is_ok() {
        listener.close()
        return 1
    }

    served = 0
    while served < 3 {
        a = listener.accept()
        if not a.ok {
            break
        }
        s = a.stream
        buf = ""
        while not buf.contains("\r\n\r\n") {
            r = s.recv(256)
            if not r.ok or r.value.len() == 0 {
                break
            }
            buf = buf + r.value
        }
        body = "hello from RGC server"
        resp = "HTTP/1.1 200 OK\r\nContent-Type: text/plain\r\nContent-Length: " +
               to_string(body.len()) + "\r\n\r\n" + body
        s.send(resp)
        s.close()
        served = served + 1
    }
    listener.close()
    return 0
}

def main() -> int {
    argv = args()
    if argv.len() > 2 and argv.get(1) == "--serve" {
        return serve(argv.get(2))
    }

    port_file = "/tmp/rgc_http_demo.port"
    io.remove_file(port_file)
    cmd = "'" + argv.get(0) + "' --serve '" + port_file + "' >/dev/null 2>&1 &"
    os.system(cmd)

    # 等待服务器把端口写入文件
    port = 0
    tries = 0
    while tries < 200 {
        if io.exists(port_file) {
            fr = io.read_file(port_file)
            if fr.is_ok() {
                port = fr.unwrap().to_int().unwrap()
                break
            }
        }
        time.sleep(0.01)
        tries = tries + 1
    }
    if port == 0 {
        print("server did not start")
        return 1
    }
    print("server started on", port)

    base = "http://127.0.0.1:" + to_string(port)

    # GET：检查状态、头与正文
    r = http.get(base + "/hello")
    if r.ok {
        res = r.response
        print("status:", res.status)
        print("content-type:", http.header(@res, "Content-Type"))
        print("body:", res.body)
    } else {
        print("request failed:", r.error)
    }

    # POST
    p = http.post(base + "/echo", "hello")
    print("post:", p.ok, p.response.status)

    # 查询串编码
    pairs = List[str]()
    pairs.push("q=a b")
    pairs.push("x=1")
    print("encoded:", http.encode_query(pairs))

    return 0
}

运行输出：

server started on 38819
status: 200
content-type: text/plain
body: hello from RGC server
post: True 200
encoded: q=a%20b&x=1

这个例子把本篇的知识串起来了：

• net.listen_on + TcpListener.accept 实现服务器；
• TcpStream.recv / send 读写原始字节；
• io.write_file / io.read_file / io.exists 在父子进程间传递端口；
• os.system 启动后台进程；
• http.get / http.post / http.header / http.encode_query 完成客户端请求；
• 每个可能失败的点都用 ok 判断并优雅退出，没有 panic。

7. 注意事项

• 同步模型：网络调用是阻塞的。需要并发时用 async def + asyncio（一任务一线程），或自己派生子进程。
• 二进制数据用 Bytes：str 的 len() 基于 strlen，遇 NUL 会截断；send_bytes / recv_bytes / body_bytes / data_bytes 才是二进制安全的。
• 字符串生命周期：接收缓冲与返回字符串为堆分配，当前无 GC，进程退出时由系统回收。
• 错误即值：所有网络 API 通过 ok/error 返回失败原因，不要假设某个操作一定成功。
• 外部依赖：TLS 需要 OpenSSL，gzip 需要 zlib；编译器检测到符号引用后自动追加链接参数。

8. 下一步

• 标准库规范：仓库 docs/compiler/STDLIB.md（网络章节含全部 API 细节与行为约定）
• RGC 入门教程：从 Hello World 到成绩管理器
• rack 入门：用 RGC 包管理器构建项目
• pyrig 入门：把 RGC 函数变成 Python 原生扩展

RGC 以 Apache 2.0 协议开源。欢迎在 GitHub 提 Issue、贡献代码。

rack 是 RGC 的包管理器，用 RGC 自己编写。它管理 RGC 项目的完整生命周期：新建项目、安装依赖（含传递依赖解析与完整性校验）、锁文件、构建与运行、发布与搜索。

这篇教程从一个真实的示例包出发，带你走一遍完整流程：发布 → 新建项目 → 安装依赖 → 查看依赖树 → 构建运行 → 发布自己的包。所有命令都在仓库中验证过，可以直接复制运行。

1. 准备

rack 二进制在仓库 rack/target/bin/rack（已构建）。也可以自行构建：

cd rack && ./tests/bootstrap.sh
# -> target/bin/rack

rack 构建项目时需要调用 rgc 编译器，通过 RGC 环境变量指定：

export RGC=/path/to/RGLite/build/rgc

验证：

rack --version
# rack 0.3.0 (RGC)

2. 发布示例包到本地注册表

rack 使用本地注册表（默认 $HOME/.rack/registry）。先把仓库里两个示例包发布进去：

cd rack/examples/mathx
rack publish

cd ../calcx
rack publish

输出：

Published mathx@0.2.0 -> $HOME/.rack/registry
Published calcx@0.1.0 -> $HOME/.rack/registry

• mathx 是一个数学工具模块，提供 add / mul / fib / square_sum；
• calcx 依赖 mathx@0.2.0，提供 double_add / fib_sq。

3. 新建项目

rack new demo && cd demo

生成：

demo/
├── .gitignore   # 忽略 target/ 与 a.out
├── main.rg      # 项目入口
└── rack.toml   # 清单

默认 main.rg：

# demo — rack 项目入口

def main() {
    print("hello from demo")
}

rack.toml 记录包元数据：

[package]
name = "demo"
version = "0.1.0"
entry = "main.rg"

4. 安装依赖

把 main.rg 改成使用 calcx：

import calcx

def main() -> int {
    print(double_add(2, 3))
    return 0
}

安装：

rack install calcx

输出：

  resolved calcx -> calcx@0.1.0
  + calcx@0.1.0
  + mathx@0.2.0
  Installed 2 package(s)

rack 自动完成传递依赖解析：calcx 依赖 mathx，所以 mathx 一起被安装。

5. 查看依赖树

rack tree

demo@0.1.0
└── calcx@0.1.0
    └── mathx@0.2.0

6. 构建并运行

rack run

built: ./target/bin/demo
10

此时项目布局：

demo/
  rack.toml       # 清单（rack 维护，手改亦可）
  rack.lock       # 锁文件：依赖闭包
  main.rg         # 入口
  target/
    deps/         # 已安装依赖模块 <name>.rg（缓存，可随时重建）
    build/        # 构建暂存区（入口 + 全部依赖，每次构建前清空）
    bin/demo      # 构建产物

7. 锁文件 rack.lock

install 会把解析后的完整依赖闭包写入 rack.lock（rack 维护、随项目入库，勿手改）：

# rack.lock — 依赖闭包锁文件（rack 维护，勿手改；随项目入库）

[lock.calcx]
version = "0.1.0"
checksum = "130f4c9b…"
dependencies = ["mathx"]

[lock.mathx]
version = "0.2.0"
checksum = "b1dfcea6…"
dependencies = []

• version：解析后的精确版本；
• checksum：publish 时记录的模块文件 sha256，install 时先校验再拷贝，build 前也会校验 target/deps 缓存是否被篡改；
• dependencies：该包的直接依赖（用于依赖剪枝与完整性校验）。

8. 常用命令

运行参数透传

rack run -- <参数> 会把参数原样交给程序，程序用内建 args() 读取（含程序名，行为同 Python 的 sys.argv）：

rack run -- hello world

def main() -> int {
    argv = args()
    print("argc =", argv.len())
    for a in argv {
        print("arg:", a)
    }
    return 0
}

9. 依赖解析：版本冲突与环检测

rack 对依赖闭包做完整性保证：

• 版本冲突：同一包被两个依赖 pin 到不同精确版本时，直接报错拒装：

error: version conflict on `common`: pinned 1.0.0, but `beta` requires 2.0.0

• 依赖环：A -> B -> A 这样的循环依赖会被检测并拒绝：

error: dependency cycle: cycleA -> cycleB -> cycleA

这两种情况都发生在 install 的解析阶段，不会把半成品写进清单或锁文件。

10. 发布自己的包

发布一个包只需要两个文件：模块代码 <name>.rg 和清单 rack.toml。

mypkg.rg：

public def add(a: int, b: int) -> int {
    return a + b
}

rack.toml：

[package]
name = "mypkg"
version = "0.1.0"
entry = "mypkg.rg"

发布并搜索验证：

cd mypkg
rack publish
rack search mypkg

在另一个项目里安装使用：

rack new usemypkg && cd usemypkg
# 修改 main.rg：import mypkg ...
rack install mypkg
rack run

11. 构建钩子与链接参数

有些项目需要在编译前做原生预处理，或链接额外的库。rack.toml 支持 [build] 段：

[build]
prebuild = "bash tools/llvm-shim.sh"        # 编译前执行（cwd = 项目根目录）
link-args-file = "target/build/link-args"    # 文件内容作为 rgc --link-args

RGC 编译器项目本身就是一个 rack 项目（src/rack.toml）：prebuild 负责编译内嵌 LLVM 的后端 shim，link-args-file 把 shim 与 LLVM 静态库的链接参数传给 rgc。

12. 下一步

• RGC 入门教程：从 Hello World 到成绩管理器
• pyrig 入门：把 RGC 函数变成 Python 原生扩展
• 语言文档：语法基础、模块系统、标准库

rack 以 Apache 2.0 协议开源。欢迎在 GitHub 提 Issue、贡献代码。

Python 生态强大，但解释器执行热循环确实慢。常见的解法是把热点用 C/C++ 或 Rust 重写。

RGC 也提供了原生扩展能力：pyrig——RGC 官方 Python 绑定框架。把 RGC 函数导出为 CPython 扩展模块，Python 侧直接 import，性能却是原生机器码。

这篇教程从安装开始，走一遍完整流程：脚手架 → 构建 → import 调用 → 类型映射 → 实战性能对比，最后说明当前限制。所有命令都在本仓库验证过，可以直接复制运行。

1. pyrig 是什么

pyrig 把 RGC 函数变成 Python 可以直接导入的扩展模块，实现直接走 CPython C API：

• 为每个导出函数生成 C 胶水：PyArg_ParseTuple 参数解析、RGC ↔ Python 类型转换、PyMethodDef 方法表、PyInit_<module> 模块入口；
• 用 rgc --emit-object 把 RGC 源码编译成 PIC 目标文件；
• 链接为 .so 共享库（不依赖 libpython，符号由解释器在 import 时解析，与官方扩展构建方式一致）。

2. 安装与准备

先构建编译器（参见 RGC 入门教程）：

cd RGLite
cd src
./build.sh        # 产物：src/build/rgc3
cd ..

项目根目录的 build/rgc 可以直接使用。然后安装 pyrig：

pip install -e pyrig/

或者不安装，直接用模块入口：

PYTHONPATH=pyrig python3 -m pyrig --version
# pyrig 0.2.0

3. 快速开始

3.1 生成项目骨架

python3 -m pyrig new string_sum     # 若已 pip install：pyrig new string_sum
cd string_sum

生成三个文件：

string_sum/
├── README.md
├── pyproject.toml
└── string_sum.rg

3.2 RGC 侧代码

打开 string_sum.rg：

import pyrig

# Computes the sum of two integers.
public def add(a: int, b: int) -> int {
    return a + b
}

# Greets someone by name.
public def greet(name: str) -> str {
    return "hello, " + name + "!"
}

# 标记要导出的函数：pyrig.export("python 侧名字")
pyrig.export("add")
pyrig.export("greet")

核心就三件事：

• import pyrig 引入绑定运行时模块；
• 想导出的函数必须是 public，并且带显式类型注解（胶水需要 C 签名）；
• pyrig.export("add") 是编译期标记，告诉构建器生成胶水；运行时是空操作，不会出现在生成的机器码里。

函数上方的 # 注释会变成 Python 侧的 __doc__，在 Python 里用 help() 或 .__doc__ 就能看到。

3.3 构建

python3 -m pyrig build
# built: dist/string_sum.cpython-313-x86_64-linux-gnu.so

构建器自动向上发现 pyproject.toml 里的 [tool.pyrig] 段，产物在 dist/ 下：

dist/
├── string_sum.cpython-313-x86_64-linux-gnu.so
└── pyrig_shim_string_sum.c   # 生成的 C 胶水（可阅读）

3.4 导入使用

PYTHONPATH=dist python3 -c "import string_sum; print(string_sum.add(3, 4))"
# 7

Python 侧零配置，就是一个普通的扩展模块：

import string_sum

print(string_sum.add(3, 4))            # 7
print(string_sum.greet("rgc"))            # hello, rgc!
print(string_sum.add.__doc__)
# Computes the sum of two integers.

4. 直接构建已有的 .rg 文件

不想建项目时，可以直接用 pyrig build <文件> 指定模块名和输出目录。仓库的 examples/pyrig_demo.rg 是一个完整的示例：

import pyrig

public def add(a: int, b: int) -> int {
    return a + b
}

public def greet(name: str) -> str {
    return "hello, " + name + "!"
}

public def is_even(n: int) -> bool {
    return n % 2 == 0
}

public def dist(ax: float, ay: float, bx: float, by: float) -> float {
    dx = ax - bx
    dy = ay - by
    return sqrt(dx * dx + dy * dy)
}

public def say_hi() -> None {
    puts("hi from RGC")
}

pyrig.export("add")
pyrig.export("greet")
pyrig.export("is_even")
pyrig.export("dist")
pyrig.export("say_hi")

# extern def 与 pyrig 可混用：puts 来自 libc
extern def puts(s: str) -> int

构建并验证：

python3 -m pyrig build examples/pyrig_demo.rg -n pyrig_demo -o build/pyrig
PYTHONPATH=build/pyrig python3 -c "import pyrig_demo; print(pyrig_demo.add(3, 4))"

输出：

7

这个示例同时展示了两个点：

• dist 用了标准库的 sqrt，返回 float；
• say_hi 通过 extern def puts 直接调 libc，说明 extern def（FFI）和 pyrig 可以混用。

5. 类型映射（RGC ↔ Python）

pyrig 当前支持五种标量类型的双向转换：

参数个数或类型不匹配时，CPython 会抛出标准 TypeError，和调用普通 C 扩展的体验一致。

6. 导出规则与项目配置

6.1 导出规则

• 导出函数必须写在入口文件，且带显式类型注解。
• 支持的类型：int / float / bool / str / None。
• pyrig.export("python 名") 默认用 RGC 函数名；改名导出用 pyrig.export("py 名", "rgc 函数名")（两函数需 ABI 兼容）。

6.2 pyproject.toml

在项目内 pyrig build 会自动向上发现 [tool.pyrig] 段：

[tool.pyrig]
name = "string_sum"     # 扩展模块名（默认项目目录名）
source = "string_sum.rg"
out-dir = "dist"
# rgc = "build/rgc"     # 编译器路径（默认 RGC env / PATH / 仓库 build/rgc）
# cc = "cc"
# release = true        # false -> rgc -O0
# link-args = ""

build 命令的常用选项：

pyrig develop 会把构建好的扩展安装到当前激活的 virtualenv，开发时直接 import 即可。

7. 实战：Fibonacci 性能对比

下面用 pyrig 导出一个递归 fib，看看"用 RGC 写热点"到底能快多少。

新建项目并把 fib_demo.rg 改成：

import pyrig

# Computes the n-th Fibonacci number (recursive).
public def fib(n: int) -> int {
    if n <= 1 {
        return n
    }
    return fib(n - 1) + fib(n - 2)
}

pyrig.export("fib")

构建并测试：

python3 -m pyrig build
PYTHONPATH=dist python3 - <<'EOF'
import fib_demo, time

print("fib(10) =", fib_demo.fib(10))
print("fib(20) =", fib_demo.fib(20))

t0 = time.perf_counter()
print("fib(30) =", fib_demo.fib(30))
t1 = time.perf_counter()
print(f"RGC 用时: {(t1 - t0) * 1000:.1f} ms")

def pyfib(n):
    return n if n <= 1 else pyfib(n - 1) + pyfib(n - 2)

t0 = time.perf_counter()
pyfib(30)
t1 = time.perf_counter()
print(f"Python 用时: {(t1 - t0) * 1000:.1f} ms")
EOF

本机实测（Python 3.13 / RGC v0.2）：

fib(10) = 55
fib(20) = 6765
fib(30) = 832040
RGC 用时: 1.7 ms
Python 用时: 50.4 ms

同一个递归算法，RGC 快约 30 倍。这就是"语法像 Python、性能像 C"的直观体现——你不需要改算法，只需要把热点函数用 RGC 重写一遍，然后从 Python 正常调用。

8. 当前限制（v0.2）

pyrig 还很年轻，以下限制在后续版本会逐步放开：

• 只支持入口文件的标量函数；方法、类、容器（List/Map）导出待实现。
• str 参数指针只在调用期间有效，不要把传入的 str 长期持有；str 返回值暂不回收（RGC 无 GC）。
• 不支持关键字参数、默认值参数。
• 无 PyErr 异常传播——RGC 错误建议返回 Result 并在 RGC 层处理。

9. 下一步

• 完整文档：仓库 docs/compiler/FFI.md（extern def 调用 C 库 + pyrig 详解）
• 语言基础：RGC 入门教程
• 回归测试：tests/run_pyrig.sh（构建 + CPython 实际 import 断言）；pyrig/tests/ 有 pytest 单元测试

pyrig 以 Apache 2.0 协议开源。欢迎在 GitHub 提 Issue、贡献代码。如果你有现成的 Python 热点函数，不妨试试用 RGC 重写——也许就是几倍的性能提升。

RGC 是一门 Python 风格、编译型、内存安全 的系统编程语言。语法上你几乎不用重新学习——def、if、for、and、None 都还在；但它在编译期完成类型检查和所有权检查，由 LLVM 生成原生机器码，性能接近 C / Rust。

这篇教程面向 Python 开发者，从零开始：先跑起第一个程序，再逐个掌握语法、类型、所有权、泛型、模块与标准库，最后用一个成绩管理器小项目把全部知识串起来。所有示例都来自仓库中可编译运行的代码，你可以直接复制运行。

1. 环境准备

1.1 构建编译器

RGC 采用自举（bootstrapping）构建：stage0 是 C++ 编写的一次性种子，之后由 RGC 自身逐级编译出 stage1 → stage2 → stage3，最终编译器完全由 RGC 构建。

先安装依赖：

• LLVM 23（自包含发行包，默认路径 /home/bluemoon/llvm/LLVM-23.1.4-Linux-X64/bin）
• CMake ≥ 3.31
• GCC 13.3+ 或 Clang

克隆仓库并构建：

git clone https://github.com/lexing-2026/vscode-rgc
cd RGLite
cd src
./build.sh

首次构建会自动编译 C++ 引导种子；之后 rack 会管理 rgc1 → rgc2 → rgc3 的逐级自举，并校验 IR 不动点。构建产物在 src/build/rgc3。

1.2 编译并运行第一个程序

cd src
./build/rgc3 ../examples/hello.rg -o /tmp/hello
/tmp/hello

输出：

hello from RGC, x + y = 42
condition: ok
score 95 => excellent
score 70 => pass
score 30 => fail
flag = True
7 // 2 = 3  7 % 2 = 1  2 ** 10 = 1024

rgc3 内嵌 LLVM，运行时只需要系统链接器 gcc，不需要额外安装 llc 或 clang。

2. 第一个程序：Hello World

来看 examples/hello.rg 的完整内容：

def add(a: int, b: int) -> int {
    return a + b
}

def classify(score: int) -> str {
    if score >= 90 {
        return "excellent"
    } elif score >= 60 {
        return "pass"
    } else {
        return "fail"
    }
}

def main() {
    x = 40
    y: int = 2
    total = add(x, y)
    print("hello from RGC, x + y =", total)

    if x > 10 and y < 10 {
        print("condition: ok")
    } else {
        print("condition: no")
    }

    flag = not (x == 0)
    print("flag =", flag)
    print("7 // 2 =", 7 // 2, " 7 % 2 =", 7 % 2, " 2 ** 10 =", 2 ** 10)
}

即使没有 Python 背景，这段代码也几乎可以无障碍阅读。几个要点：

• 入口函数是 main()，和 Python 脚本一样。
• 变量 x = 40无需 mut——RGC 的变量默认可变，符合 Python 习惯。
• y: int = 2 是显式类型注解；x 则由编译器推断为 int。
• 块结构用大括号 {}，不依赖缩进，注释是 #。
• 逻辑运算符沿用 Python 风格：and、or、not。
• //（整除）、%（取模）、**（幂）都与 Python 一致。

注意一个与 Python 不同的细节：两个整数相除 / 得到整数（与 C 一致），浮点数参与才会得到浮点结果。例如 7 / 2 结果是 3，而 7.0 / 2 是 3.5。

3. 变量与类型系统

RGC 是静态类型语言：每个表达式在编译期都有确定的类型。但类型推断让你不必到处写注解。

def main() {
    count = 1          # 推断为 int
    name = "RGC"       # 推断为 str
    ratio: float = 0.5 # 显式注解为 float
    ok: bool = True
}

函数签名可以完整标注参数与返回类型，让错误尽早暴露在编译期：

def scale(x: float, factor: int) -> float {
    return x * factor
}

4. 函数与控制流

4.1 函数

def greet(name: str) {
    print("Hello,", name)
}

返回值类型可以省略；需要返回时用 return。

4.2 if / elif / else

def classify(n: int) -> str {
    if n < 0 {
        return "negative"
    } elif n == 0 {
        return "zero"
    } else {
        return "positive"
    }
}

4.3 循环：for / while / break / continue / pass

def main() {
    # for 遍历 range
    for i in range(5) {        # 0 1 2 3 4
        print(i)
    }

    # while + continue + break
    i = 0
    while i < 6 {
        i = i + 1
        if i == 2 {
            continue
        }
        if i == 5 {
            break
        }
        print("i =", i)
    }

    # pass 空语句
    n = 0
    while n < 3 {
        n = n + 1
        pass
    }
}

range、break、continue、pass 的语义与 Python 一致，只是块结构换成大括号。

5. 类、枚举与模式匹配

RGC 提供完整的代数数据类型（ADT）：class 组织数据与方法，enum 描述"要么是 A、要么是 B"的枚举，配合 match 做穷尽的模式匹配。

class Point {
    x: int
    y: int
    def sum(self) -> int {
        return self.x + self.y
    }
}

enum Shape {
    Circle(float)
    Rect { w: float, h: float }
}

def area(s: Shape) -> float {
    match s {
        case Circle(r) => 3.14159 * r * r
        case Rect { w, h } => w * h
        case _ => 0.0
    }
}

def main() {
    p = Point()
    p.x = 3
    p.y = 4
    print("p.sum() =", p.sum())   # 7

    c = Circle(2.0)
    r = Rect(3.0, 4.0)
    print("area(circle) =", area(c))
    print("area(rect)  =", area(r))
}

几个和 Python 不一样的写法：

• 枚举变体用构造函数语法创建：Circle(2.0)、Rect(3.0, 4.0)；没有参数的单位变体写成 Pass()。
• match 的 case 不需要括号：case Circle(r) 直接把负载绑定到变量 r。
• case _ 是通配分支，保证匹配一定完整。

6. 所有权与借用

这是 RGC 内存安全的核心，也是和 Python 最大的不同。每个值有唯一的拥有者，离开作用域即被释放；通过借用安全地共享访问。全程没有 GC，零运行时开销。

6.1 移动（move）

自定义类型（class / enum）默认是 move 语义。赋值后原变量不再可用：

class Point {
    x: int
    def sum(self) -> int {
        return self.x
    }
}

def main() {
    a = Point()
    a.x = 5
    b = a              # 所有权从 a 移动到 b
    print("b.x =", b.x)   # 5
    # print(a)         # 编译错误：a 已被 move
}

被移动的变量在重新赋值后可以恢复可用：

d = Point()
d.x = 7
e = d                # move d -> e
d = Point()          # 重新赋值，d 恢复可用
d.x = 8

6.2 只读借用 @ 与可变借用 @var

不想转移所有权、只想读，用 @ 借用。以自定义类型为例：

class Counter {
    value: int
}

def read(c: @Counter) -> int {
    return c.value
}

def main() {
    x = Counter()
    x.value = 10

    r1 = @x       # 只读借用
    r2 = @x       # 多个 @ 可以并存
    print("read(r1) =", read(r1))   # 10
    print("read(r2) =", read(r2))   # 10
    print("x.value =", x.value)     # x 仍然可用
}

想修改，用 @var 可变借用（独占访问）：

def push_zero(lst: @var List[int]) {
    lst.push(0)
}

多个 @ 只读借用可以并存；@var 与任何其他借用互斥——这一切都在编译期检查，保证没有 use-after-move、悬垂引用和数据竞争。

6.3 方法调用自动借用

调用 self 方法时，方法按借用语义自动处理，不需要手动写 @。可变方法自动使用可变借用：

class Counter {
    value: int
    def inc(self) {
        self.value = self.value + 1
    }
}

def main() {
    z = Counter()
    z.value = 30
    z.inc()           # self 自动可变借用
    print(z.value)    # 31，z 仍可用
}

7. 泛型与接口

7.1 泛型函数

def identity[T](x: T) -> T {
    return x
}

def pair_sum[T](a: T, b: T) -> T {
    return a + b
}

def main() {
    print(identity(42))        # 42
    print(identity(3.14))      # 3.14
    print(pair_sum(2, 3))      # 5
    print(pair_sum(1.5, 2.5))  # 4.0
}

7.2 泛型类

class Box[T] {
    value: T
    def get(self) -> T {
        return self.value
    }
}

def main() {
    b = Box[int]()
    b.value = 42
    print(b.get())        # 42

    f = Box[float]()
    f.value = 3.14
    print(f.get())        # 3.14
}

7.3 接口与边界约束

接口定义行为契约，类通过 class T : Interface 实现：

interface Show {
    def show(self) -> str
}

class Point : Show {
    x: int
    y: int
    def show(self) -> str {
        return "Point"
    }
}

class Line : Show {
    a: int
    b: int
    def show(self) -> str {
        return "Line"
    }
}

# T 受 Show 约束，函数体内可直接调用接口方法
def describe[T: Show](x: T) -> str {
    return x.show()
}

def main() {
    p = Point()
    p.x = 1
    p.y = 2
    print(describe(p))   # Point

    l = Line()
    l.a = 3
    l.b = 4
    print(describe(l))   # Line
}

泛型通过单态化编译：每个具体类型生成专用代码，没有虚表、没有装箱，性能和手写专用实现一致。

8. 模块系统

用 import 引入模块，模块内部通过 public 控制可见性。未加 public 的项只在模块内部可见。

geometry.rg：

public class Point {
    x: int
    y: int
    def sum(self) -> int {
        return self.x + self.y
    }
}

# 私有函数：仅模块内部可见
def double(v: int) -> int {
    return v * 2
}

public def make_point(x: int, y: int) -> Point {
    p = Point()
    p.x = x
    p.y = y
    return p
}

public def norm_sq(p: Point) -> int {
    return double(p.x * p.x + p.y * p.y)
}

main.rg：

import geometry

def main() {
    p = make_point(3, 4)
    print("point sum =", p.sum())   # 7
    print("norm_sq   =", norm_sq(p))  # 50
}

注意 norm_sq 内部调用了私有函数 double，但对外只暴露 public 项——内部实现细节被安全地封装在模块边界内。

9. 标准库初探

标准库目前提供内建核心类型与方法：to_string、字符串方法、List[T]、Maybe[T]、Result[T, E]。

9.1 字符串

def main() {
    msg = "Hello, " + "RGC"
    print(msg.len())                  # 10
    print(msg.contains("lo,"))        # True
    print(msg.startswith("Hello"))    # True
    print(msg.endswith("RGC"))        # True

    print("hello world".slice(0, 5))  # hello
    print("12345".to_int().unwrap())  # 12345
}

9.2 List

def main() {
    xs = List[int]()
    xs.push(1)
    xs.push(2)
    xs.push(3)
    print(xs.len())          # 3
    print(xs.get(0))         # 1
    xs.set(1, 20)
    print(xs.get(1))         # 20
    print(xs.contains(3))    # True
    print(xs.pop())          # 3

    total = 0
    for x in xs {
        total = total + x
    }
    print(total)             # 21
}

9.3 Maybe 与 Result

RGC 用 Result[T, Err] 表达可恢复错误：不抛异常、不静默失败。解析字符串可能失败时，签名里就写着"可能失败"：

def main() {
    ok = Result[int, str].Ok(7)
    err = Result[int, str].Err("boom")
    print(ok.is_ok())    # True
    print(err.is_err())  # True

    # match 推荐用法：错误分支显式处理
    match err {
        case Ok(v) => print("unexpected:", v)
        case Err(msg) => print("error is:", msg)
    }
}

配合字符串的 to_int()：

r = "12345".to_int()
match r {
    case Ok(v) => print("value =", v)     # value = 12345
    case Err(msg) => print("err:", msg)
}

bad = "abc".to_int()
match bad {
    case Ok(v) => print("unexpected:", v)
    case Err(msg) => print("to_int error:", msg)   # invalid integer literal
}

10. 实战：成绩管理器

现在把上面的知识串起来，写一个小程序：录入三名学生成绩，输出每个人的等级、及格人数和平均分。这会用到类、接口、枚举、模式匹配、List、所有权与借用、泛型边界。

interface Show {
    def show(self) -> str
}

class Student : Show {
    name: str
    score: int
    def show(self) -> str {
        return self.name + ": " + to_string(self.score)
    }
    def is_pass(self) -> bool {
        return self.score >= 60
    }
}

enum Grade {
    Excellent
    Pass
    Fail
}

def grade_of(score: int) -> Grade {
    if score >= 90 {
        return Excellent()
    } elif score >= 60 {
        return Pass()
    } else {
        return Fail()
    }
}

def grade_name(g: Grade) -> str {
    match g {
        case Excellent => "优秀"
        case Pass => "及格"
        case Fail => "不及格"
        case _ => "?"
    }
}

def total(students: @List[Student]) -> int {
    sum = 0
    for s in students {
        sum = sum + s.score
    }
    return sum
}

def count_pass(students: @List[Student]) -> int {
    n = 0
    for s in students {
        if s.is_pass() {
            n = n + 1
        }
    }
    return n
}

def main() {
    students = List[Student]()

    s = Student()
    s.name = "Alice"
    s.score = 92
    students.push(s)          # push 移动所有权，s 可重新赋值

    s = Student()
    s.name = "Bob"
    s.score = 74
    students.push(s)

    s = Student()
    s.name = "Carol"
    s.score = 55
    students.push(s)

    for st in students {
        print(st.show(), "=>", grade_name(grade_of(st.score)))
    }

    print("及格人数 =", count_pass(@students))
    print("平均分 =", total(@students) / students.len())
}

运行输出：

Alice: 92 => 优秀
Bob: 74 => 及格
Carol: 55 => 不及格
及格人数 = 2
平均分 = 73

几个值得回味的点：

• students.push(s) 把 s移动进列表；之后给 s 重新赋值一个新 Student()，符合所有权模型。
• for st in students 按借用迭代，循环结束后 students 仍然可用。
• count_pass(@students) 和 total(@students) 用 @只读借用传入列表，调用后 students 不受影响。
• grade_name 用 match 把枚举变体映射成中文标签，编译期保证分支完整。
• class Student : Show 实现了接口，show() 在 for 循环里被多态调用（单态化，无虚表开销）。

11. 下一步

至此你已经掌握了 RGC 的核心：从语法、类型，到所有权、泛型、模块和标准库。继续深入：

• 语法基础
• 类型系统
• 所有权与借用
• 泛型与接口
• 模块系统
• 标准库

RGC 以 Apache 2.0 协议开源。欢迎在 GitHub 提 Issue、贡献代码；也欢迎安装 VSCode 插件，获得语法高亮与补全支持。祝你写得开心！