Aller au contenu
Français

命令行工具

Cette page n’est pas disponible dans la langue choisie. La documentation anglaise de la même version est affichée.

Instantané 0.0.19 Documentation

Ce contenu n’est pas encore disponible dans votre langue.

先用 ku -v 查看版本,ku --help 查看当前安装的总帮助。

终端窗口
ku -v
ku create hello
cd hello
ku check
ku run

项目入口由有效的 ku.mod 配置指定;省略路径不是在任意目录猜测 hello.ku。单文件也可直接运行:

终端窗口
ku ./hello.ku
命令 用途
ku check main.ku 检查源码,不执行
ku check --json main.ku 输出 JSON Lines 诊断,成功时静默
ku run main.ku 解释执行
ku build main.ku 默认 Debug / Runner 构建
ku build --backend c --release main.ku -o app 编译并链接 native C 程序
ku ir main.ku 查看优化后的 Ku IR
ku llvm empty.ku 输出实验性 LLVM 文本 IR,不生成可执行文件
ku template list 列出 basic、cli、http、json、fs、lib 模板
ku package resolve --locked 按项目 lock 固定依赖
ku package pack 创建源码与依赖分发包,不是可执行程序
ku package gc 清理未使用的包缓存

别名只在相应命令的参数位置生效。

功能 完整形式 简写或等价形式
版本 ku --version ku -v、ku -V、ku version
总帮助 ku --help ku -h、ku -help、ku help
运行单文件 ku run ./hello.ku ku ./hello.ku
创建模板 ku create hello --template http ku create hello -t http
初始化模板 ku init --template cli ku init -t cli
模板列表 ku template list ku create --list
输出路径 ku build --output PATH FILE ku build -o PATH FILE
Release --profile release --release
Debug --profile debug --debug
Small --profile small --small
Fast --profile fast --fast
LLVM 文本附加输出 --emit-llvm --emit-ll
构建详细日志 ku build --verbose FILE ku build -v FILE
Runner 后端 --backend runner --backend interp、--backend interpreter
C 后端 --backend c --backend native-c
LLVM 后端 --backend llvm --backend ll

ku -v 输出 Ku 版本;ku build -v ./hello.ku 显示构建日志,并不查看版本。profile 简写和 --backend 别名属于 build 选项,不是全局开关。

ku run、ku check、ku build、ku build . 可使用有效项目配置中的入口;ku package 对应子命令省略路径时使用当前目录项目上下文。ku build --target host 与默认的宿主目标选择等价。

单独执行 ku 不会默认运行项目;ku run . 也不是项目目录简写。隐式 ku ./hello.ku 只接受这一个路径,不接程序参数、--offline 或 --locked。需要依赖模式时使用 ku run --offline ./hello.ku 或 ku run --locked ./hello.ku,两种模式不能同时指定。

以 - 开头的文件使用显式相对路径,例如 ku ./-hello.ku。Windows 使用 ku .\-hello.ku;含空格或中文的路径用引号包住。当前不支持 ku r、ku b、ku c、ku --v 或程序 argv 透传。

调用 产物和所需工具
ku build hello.ku 默认 Debug / Runner:生成 Rust wrapper,打包解释执行路径;需要与随包运行时匹配的 Rust 及系统链接器
ku build --backend c --release hello.ku -o app native C 可执行程序;需要受支持的 C 编译器、链接器及程序使用的原生库
ku build --emit-c hello.ku 默认仍走 Runner,额外输出 C;不是 C-only 构建,也不能绕过 Runner 工具链不匹配
ku build --backend llvm empty.ku 当前为 LLVM 文本 IR,不是完整可执行链接路径
ku package pack 源码分发包,与上面两种程序产物不同

check、run 与隐式运行不要求 Rust/C 编译器。Runner 只嵌入入口文件;含本地导入的程序运行时仍需原模块源码。native C 构建展开导入图,产物不依赖原 Ku 源码。默认输出在 .ku/build/<profile>/,请使用 CLI 报出的实际路径;Windows 输出名使用 .exe。

LLVM 示例中的 empty.ku 内容为 fn main() {}。该原型只支持部分语法和内建调用;--backend llvm 写出文本 IR 后返回非零,因为尚不支持可执行链接。

保留旧调用,但推荐在新代码中明确使用 --backend c:

终端窗口
ku build --native ./hello.ku
ku build --native ./hello.ku -o ./hello

第一条只生成 C 文件;第二条通过兼容分支编译和链接 C 程序。--native 必须位于 build 后的兼容解析位置,不能移到任意选项位置并当作无条件别名。

当前没有 ku fmt、ku test 或 ku doc 命令;VS Code 格式化属于插件功能。

ku supervise 是显式的完整程序 worker 管理模式,不会自动应用到普通 run 或 HTTP 请求。Linux 需要已委托的 cgroup v2,Windows 使用提交内存限制;macOS 原生不支持该隔离模式。配置、失败语义与未覆盖范围见平台与进程限制。

常驻 native HTTP 服务

“常驻 native HTTP 服务”章节

ku service --help 说明独立的常驻服务监督器。先构建 native HTTP 示例。目标程序必须支持 native 认证健康/排空协议;probe 与 control 地址须为不同、非零且端口空闲的 loopback 地址。

运行前准备私有普通文件 service.token,内容为 32–128 个 ASCII 字母或数字;Unix 下只能所有者访问(chmod 600 service.token)。使用自行生成的不可预测 token,不把 token 随源码提交,再执行:

终端窗口
ku service --probe-addr 127.0.0.1:18181 \
--control-addr 127.0.0.1:19081 --control-token-file service.token \
--startup-timeout-ms 5000 --probe-timeout-ms 250 \
--probe-interval-ms 1000 --failure-threshold 3 \
--drain-timeout-ms 10000 --restart-limit 5 --restart-window-ms 60000 \
--backoff-ms 100 --max-backoff-ms 5000 -- ./native-server

上述数值显式给出了监督器默认值。时长单位为毫秒,不能为 0。--failure-threshold 为 1–100,--restart-limit 为 1–1000;backoff 不能超过 max-backoff,probe-timeout 不能超过 startup-timeout。-- 后接可执行文件及参数,Windows 改为实际 .exe 路径。

control listener 通过 X-Ku-Control-Token 认证暴露 GET /status、GET /metrics、POST /stop。它管理单个服务实例的健康、准入/排空与有界重启,不是请求代理或数据库重试机制。此模式将被管理程序 stdout/stderr 接到 null device,不保留应用日志,应按控制指标观察状态。

不带内存选项时普通模式不强制 OS 内存上限。显式内存模式必须同时指定 --worker-memory-bytes 与 --total-memory-bytes;Linux 还需委派的 --cgroup-root,先阅读平台限制。native macOS 拒绝此硬限制模式,但支持普通监督。指标区分当前状态与失败;健康探测成功不证明业务 SLO 或已有稳定生产后端。