【far 语言】farcc 构建工具

本文是「far 语言」系列文档之一，总目录见《【far 语言】语言文档目录》。

farcc：一键打包 far 应用

farcc 是 far 的编译器命令行工具，对标 Go 的 go build——一条命令把 far 应用编译成单个自包含可执行文件（运行时 + 标准库 + 你的代码全编译进去，目标机器零依赖）。

安装与依赖

farcc 是 Java 程序（编译器前端），需要 Java 21+。编译时自动定位 clang：

平台	clang 定位顺序
Windows	FAR_CLANG 环境变量 → farcc 安装目录旁的 llvm-mingw/ → PATH
Linux	FAR_CLANG 环境变量 → PATH 的 clang（如 sudo apt install clang）

标准库目录自动定位：FAR_STD → farcc 安装目录旁的 farlang/src/std → 上级目录查找。

基本用法

farcc <src目录>                  # 编译 <src>/app.far → <src>/<目录名>.exe
farcc <src目录> -o myapp.exe     # 指定输出名
farcc <src目录> -O0              # 关闭优化（默认 -O2）
farcc <src目录> -strip           # 剥离符号表减小体积
farcc <src目录> -verbose         # 打印编译过程

输出与目录结构

myapp/
├── app.far          # 你的源码（任意命名，main 在入口文件）
├── model.far
└── build/           # 中间产物（app.ll / app.o）——自动生成，可删除
└── myapp.exe        # 最终可执行文件（Linux 下为 myapp，无后缀）

• 产物完全自包含：拷贝到任意机器即可运行，无需安装 Java/clang/far 运行时
• Windows 产物 .exe；Linux 产物为无后缀 ELF
• 中间产物隔离在 build/，不污染源码目录（运行时以预编译 far_rt-win.a 归档链接，build 不再出现 .c 源码）

与模块 import 配合

farcc 自动处理 import 的路径定位：

// myapp/ 下有 model.far，或使用标准库 List/File
import { Box } from "model.far";     // 相对 src 根
import List from "List.far";          // 相对标准库目录

跨平台

• Windows：farcc 在 Windows 上编译出 Windows 可执行文件
• Linux：farcc 在 Linux（或 WSL）上编译出 Linux ELF
• 在哪台机器跑 farcc，就产出那个平台的程序（宿主工具链模型）

交叉编译（在 Windows 上产出 Linux/arm64 程序）规划中。

示例

# 编译 myapp 目录
farcc myapp
# 输出 myapp/myapp.exe，直接运行
./myapp/myapp.exe

常见问题

• 找不到 clang：设置 FAR_CLANG 指向 clang 完整路径，或安装 clang 并加入 PATH
• import 报找不到文件：确认 from 路径相对 src 根；标准库类（List/File）用相对 stdDir 的路径
• 编译失败：用 -verbose 查看详细过程，中间产物在 <src>/build/

安装目录结构（发布包）

解压 farcc 发布包后（放任意目录，如 C:\farcc 或 ~/farcc）：

farcc/
├── farcc.sh / farcc.bat     # 入口脚本（farcc <src> [-flags]，自动定位 jar/java/clang）
├── farcc.jar                # 编译器核心（Java 21 运行）
├── lib/
│   ├── far_rt-win.a         # 预编译运行时归档（带调试信息；farcc 链接用，编译不再现编 .c）
│   └── hutool-all-5.7.6.jar # 编译器依赖
├── llvm-mingw/              # 捆绑工具链（Windows 版 clang，Windows 免装直接用）
└── std/                     # 标准库（List.far / File.far ...）

• Windows：farcc.bat <src>；clang 用捆绑的 llvm-mingw/（也可用 FAR_CLANG/PATH 覆盖）
• Linux：farcc.sh <src>；clang 用系统安装的（apt install clang），java 用 PATH 的 Java 21
• 标准库：std/ 目录自动被 import 定位；可用 FAR_STD 指向自定义位置
• 移动整个 farcc/ 目录即可迁移安装（无注册表/系统级依赖，除 Java 21）

注：farcc 本身是 Java 程序（编译器），编译产物 exe 是自包含原生程序，运行不需要 Java。