hare-lang

Hare

用途

引导 Agent 使用 Hare 编程语言：了解其设计理念（简单、稳定、编译型）、hare build/test/run 工作流、标准库概览、使用 @extern 进行 C FFI、类型系统（标记联合、切片）、使用 (T | error!) 处理错误，以及将 Hare 与 C 和 Zig 进行比较，以便编写系统工具。

适用场景

• 编写兼具类 C 控制能力和现代安全性的轻量级系统工具
• 构建依赖极少的 CLI 工具或守护进程
• 从 Hare 调用 C 库，或将 Hare 函数导出给 C
• 倾向于显式错误处理，而非异常
• 为新项目评估 Hare、C 或 Zig
• 需要稳定、易审计且没有沉重运行时的代码库

工作流

1. 安装 Hare

# Linux/macOS — build from source
git clone https://git.sr.ht/~sircmpwn/hare
cd hare
make check   # builds and runs tests
sudo make install

hare version

# Create project (Hare has no project generator — lay out manually)
mkdir -p mytool && cd mytool
cat > hare.mod << 'EOF'
module mytool
EOF

2. Hello world 和构建

// main.ha
use fmt;

export fn main() void = {
	fmt::println("Hello, Hare!")!;
};

hare build -o mytool
./mytool

hare run .        # build and run
hare test         # run tests

3. 标准库概览

模块	用途
fmt	格式化 I/O（printf、println）
io	读取器/写入器接口
os	文件、环境、参数
strings	字符串操作
bufio	缓冲 I/O
encoding	JSON、十六进制等
net	TCP/UDP 网络
time	日期和时长
mem	内存辅助工具
types	平台整数类型

use os;
use fmt;
use strings;

export fn main() void = {
	const args = os::args;
	for (let i = 0z; i < len(args); i += 1) {
		fmt::println(args[i])!;
	};
};

4. 错误处理

// Errors are tagged union values — explicit propagation with !
fn read_file(path: str) (str | os::error) = {
	const file = os::open(path)?;
	defer os::close(file);
	let buf: []u8 = [];
	io::readall(file, &buf)?;
	return strings::fromutf8(buf)!;
};

export fn main() void = {
	match (read_file("config.txt")) {
	case let s: str =>
		fmt::println(s)!;
	case let err: os::error =>
		fmt::fatalf("error: {}", err)!;
	};
};

? 用于传播错误；! 用于在不可失败的上下文中断言成功；使用 match 进行处理。

5. 类型系统

// Tagged union
type color = (u8 | u16 | void);

fn get_color(c: color) u16 = {
	match (c) {
	case let v: u8 => return v: u16;
	case let v: u16 => return v;
	case => abort();
	};
};

// Slices — pointer + length
fn sum(nums: []i32) i32 = {
	let total = 0i32;
	for (let i = 0z; i < len(nums); i += 1) {
		total += nums[i];
	};
	return total;
};

不支持隐式转换——必须显式转换。

6. C FFI — @extern

// Link against C library
use c;

@extern("c") fn strlen(s: *const u8) size;

export fn main() void = {
	const s = "hello";
	fmt::println(len(s))!;  // Hare strlen via strings module
};

将 Hare 导出给 C：

// Exported C ABI function
export fn my_add(a: i32, b: i32) i32 = {
	return a + b;
};

hare build -o libmytool.a
# Link from C with generated headers or manual declarations

// cgo-style module linking in hare.mod
module mytool
require (
    libc
)

7. 测试

@test fn test_add() void = {
	assert(sum(&[1i32, 2, 3]) == 6);
};

@test fn test_error() void = {
	match (read_file("/nonexistent")) {
	case => abort("expected error");
	case let err: os::error => void;
	};
};

hare test -v

8. Hare、C 与 Zig 对比

方面	Hare	C	Zig
内存安全	部分支持（无 null、标记错误）	手动管理	手动管理 + 可选安全机制
编译时间	快	快	Comptime 开销大
标准库	精简、稳定	libc	丰富
C 互操作	@extern	原生支持	@cImport
泛型	不支持（comptime 支持有限）	不支持	Comptime 泛型
最适合	工具、实用程序	所有场景	需要元编程的系统开发

9. 使用场景

Good Hare fits
├── CLI utilities (grep-like, init tools)
├── Build tools and scripts replacing shell
├── Network daemons with simple protocol
└── Auditable security-sensitive code

Consider C/Zig instead when
├── Heavy generic metaprogramming needed (Zig)
├── Existing massive C ecosystem glue
└── GPU/kernel domains with immature Hare support

常见问题

症状	原因	解决方法
unknown type	缺少导入	添加 use module;
FFI 链接错误	库未列入 hare.mod	添加 require；修正 -l 标志
未处理错误	缺少 ? 或 match	传播错误或处理所有情况
UTF-8 错误	字符串中包含无效字节	使用 strings::fromutf8 验证
未找到测试	缺少 @test	为函数名添加 @test 属性
缺少平台系统调用	Hare 标准库不支持	使用 @extern 调用 libc

相关技能

• skills/zig/zig-compiler — 将 Zig 作为替代系统语言
• skills/zig/zig-cinterop — Zig 的 C 互操作对比
• skills/compilers/gcc — 与 Hare 搭配使用的 C 工具链
• skills/languages/carbon-lang — 其他新兴系统语言
• skills/build-systems/make — 将 Hare 集成到 Makefile 中
• skills/runtime-safety/sanitizers — C 互操作安全测试