# far

**Repository Path**: grateful/far

## Basic Information

- **Project Name**: far
- **Description**: far文档和下载
- **Primary Language**: Java
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-11-02
- **Last Updated**: 2026-10-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Far 语言

> Far —— 一款 AOT 编译到原生代码的编程语言，面向 MUD / 文字游戏 / 服务端 / 并发业务场景，风格接近 LPC + Java。
>
> farcc 一条命令把 far 应用编译成**单个自包含可执行文件**（运行时 + 标准库 + 你的代码全编译进去，目标机器零依赖）。

## 快速开始

```bash
farcc new myapp     # 生成项目骨架（myapp/app.far，含 main 方法）
cd myapp
farcc run           # 编译并立即运行 —— 输出 hello far
farcc build         # 只编译，产出 myapp.exe（Windows）/ myapp（Linux）
```

`farcc new` / `run` / `build` 是三段式项目管理命令；旧形式 `farcc myapp`（等价 `farcc build myapp`）仍兼容。

farcc 发布包自包含（包内 JDK + clang + 标准库，解压即用，目标机器无需安装任何东西）。安装步骤见 [INSTALL.md](INSTALL.md)，命令行参考见 [doc/farcc.md](doc/farcc.md)。

```far
// 一段 far 代码
class App {
    static long main(string args[]) {
        println("hello far");
        return 0;
    }
}
```

## 文档

| 文档 | 内容 |
|---|---|
| [doc/index.md](doc/index.md) | 文档总入口 |
| [doc/syntax.md](doc/syntax.md) | 语法速览（一页读懂 far） |
| [doc/types.md](doc/types.md) | 变量与数据类型 |
| [doc/array.md](doc/array.md) | 数组 |
| [doc/map.md](doc/map.md) | 字典 map |
| [doc/function.md](doc/function.md) | 方法与匿名函数 |
| [doc/control-flow.md](doc/control-flow.md) | 流程控制 |
| [doc/concurrency.md](doc/concurrency.md) | 并发：虚拟线程 + Channel |
| [doc/string.md](doc/string.md) | 字符串与模板 |
| [doc/list.md](doc/list.md) | 集合 List\<T\> |
| [doc/interface-generic.md](doc/interface-generic.md) | 接口与泛型 |
| [doc/inherit.md](doc/inherit.md) | 继承与接口实现 |
| [doc/annotation.md](doc/annotation.md) | 注解系统 |
| [doc/native-memory.md](doc/native-memory.md) | 原生内存 |
| [doc/exception.md](doc/exception.md) | 异常处理 |
| [doc/farcc.md](doc/farcc.md) | farcc 命令行打包 |
| [INSTALL.md](INSTALL.md) | 安装、验证与常见问题 |
| [stdlib.md](stdlib.md) | 标准库 API 速查 |
| [CHANGELOG.md](CHANGELOG.md) | 版本变更记录 |

## 目录结构

```
├── README.md / LICENSE / INSTALL.md / CHANGELOG.md / stdlib.md
├── doc/               # 语言文档
├── tools/
│   ├── dist/          # farcc 发布（make-release.sh 构建；release/ 产物不入库）
│   └── vscode-far/    # VSCode 插件
```

## 特性

- **AOT 原生编译**：far 源码 → LLVM IR → 原生机器码（clang），产物零依赖
- **自包含运行时**：GC、虚拟线程/协程、动态库 FFI 全部编译进产物
- **并发优先**：虚拟线程 + Channel（对标 Java 虚拟线程 / Go goroutine）
- **类型系统**：静态类型 + 泛型 + 接口 + 注解；单继承 + 多接口
- **字符串按码点**：`len` / `runeAt` / `substring` 以 Unicode 码点为单位，字节长度走 `byteLen()`；另有独立值类型 `rune`
- **可恢复错误**：`Result<T,E>` + `???` 传播，未处理由 lint 在编译期报错
- **模块化**：`import { Box } from "model.far"`（相对 src 根或标准库）

## 构建 farcc

```bash
cd tools/dist
bash make-release.sh        # → release/farcc/ 自包含发布包（含预编译 far_rt 归档）
cd release && tar -czf farcc-win.tar.gz farcc/   # 分发
```

构建说明见 `tools/dist/make-release.sh`。

## 许可

木兰宽松许可证，第 2 版（Mulan PSL v2）—— 全文见 [LICENSE](LICENSE)。

```
Copyright (c) 2024 Mike
Far is licensed under Mulan PSL v2.
You can use this software according to the terms and conditions of the Mulan PSL v2.
You may obtain a copy of Mulan PSL v2 at:
         http://license.coscl.org.cn/MulanPSL2
THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND,
EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT,
MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE.
See the Mulan PSL v2 for more details.
```

> 注：本仓库早期文档曾误写为 Apache-2.0，实际许可自始为木兰 PSL v2，以 [LICENSE](LICENSE) 为准。

## 开源范围

- 本仓库：语言文档、farcc 构建工具、运行时（C 静态库）、VSCode 插件
- far 编译器核心（闭源发行，随 farcc 发布包分发）

## 已知问题

v0.1.0 的已知问题与限制（含多调度线程下的并发竞态、通配导入裸调等）统一记录在
[CHANGELOG.md](CHANGELOG.md) 的「已知问题」小节。