#命令行参考

luxc 现在以 alpha toolchain binary 分发，也可以从源码构建。release zip 自带 install-lux-path.ps1，会把同目录的 compiler 安装到用户 toolchain 布局；源码构建 可以使用同一个脚本并传入 -LuxcPath .\compiler\target\release\luxc.exe。

加入 PATH 后：

luxc <command>

如果没有加入 PATH，可以直接使用构建产物或用户入口：

.\compiler\target\release\luxc.exe <command>
%USERPROFILE%\.lux\bin\luxc.exe <command>

@lux/std 等官方 package 通过 luxc init --std 或 luxc install 按项目安装。

#命令总览

luxc lex <path>
luxc parse <path>
luxc lint <path>
luxc format <path> [--check] [--write]
luxc build <source-root> --out <path> [--map] [--source-comments [none|readable|boundary|dense]]
luxc init [path] [--name <name>] [--std] [--out <path>] [--runtime-base <path>] [--no-autorun]
luxc install <package-id> --from <github:owner/repo|url|path> [--tag <tag>|--branch <branch>|--commit <commit>]
luxc remove <package-id> [--project <project-root>]
luxc lock [project-root]
luxc list [project-root]
luxc doctor [project-root]
luxc self install [version] [--from <path|url>] [--default]
luxc self update
luxc self default <version>
luxc self list
luxc self which [--project <project-root>]
luxc self pin <version> [--project <project-root>]
luxc self unpin [--project <project-root>]
luxc lsp
luxc compile <path> [--map <path>] [--source-comments [none|readable|boundary|dense]]
luxc map-error <map.json> <generated-line>
luxc gmod build <source-root> --out <path> [--runtime-base <path>] [--no-autorun] [--dry-run]
luxc gmod build --manifest <lux.toml> [--out <path>] [--runtime-base <path>] [--no-autorun] [--dry-run]
luxc gmod package --manifest <lux.toml> --root <path> --gmad <path> --out <path> [--run] [--build-out <path>] [--runtime-base <path>] [--no-autorun]
luxc gmod api update [--out <path>] [--coverage-out <path>] [--cache-dir <path>] [--offline] [--allow-failures]

#lex

打印词法 token，主要用于调试 lexer：

luxc lex examples\features.lux

输出包含行列号和 token 类型。词法错误会返回非零退出码。

#parse

解析并打印语法树：

luxc parse examples\features.lux

这个命令适合调试语法和宏展开前后的结构，不用于日常构建。

#lint

运行语义风格检查：

luxc lint examples\features.lux

当前 lint 覆盖典型 GLua 脚枪，例如可疑的尾表调用、被分号压制的返回、无意义自赋值 和回调隐式返回。需要局部关闭时使用行内注释。

-- lux-lint: allow LINT004
drawPanel(self, w, h)

#format

检查格式：

luxc format examples\features.lux --check

写回格式化结果：

luxc format examples\features.lux --write

不加 --check 和 --write 时，格式化结果打印到标准输出：

luxc format examples\features.lux

--check 与 --write 不能同时使用。

#build

把目录下的 .lux 文件按单文件方式递归编译，并在输出目录里保留相对路径：

luxc build src --out generated/lua

这个命令用于渐进式 GLua 集成：需要语法增强，但不希望 Lux 生成 GMod loader tree。 每个输入文件都像 luxc compile 一样独立编译，因此不会按项目图解析 import、package、 export 和 realm。

调试生成 Lua 时可以同时写 source map 和 source comment：

luxc build src --out generated/lua --map --source-comments readable

#init

创建项目骨架：

luxc init my_addon

普通 init 离线执行，只写空的 [dependencies]。需要官方标准 package set 时显式加 --std：

luxc init my_addon --std

默认 init 生成 addon-friendly 的 GMod 配置：

[target.gmod]
source_root = "src"
out = "generated/lua"
runtime_base = "lux/my_addon"
autorun = true

如果入口由已有 gamemode、框架或手写 loader 接管，可以关闭 autorun：

luxc init my_addon --no-autorun --out generated

#install

添加直接 package 依赖并重写 lux.lock：

Push-Location my_addon
luxc install @lux/gmod --from github:TimeWatcher/lux-packages
Pop-Location

Lux 没有 registry。--from 直接选择 package set 来源：github:owner/repo、zip url 或本地 path。GitHub 来源可以用 --tag、--branch 或 --commit 中的一个 固定具体引用。

#remove

从 lux.toml 删除直接依赖并重写 lux.lock：

luxc remove @lux/gmod --project my_addon

不再被任何直接依赖需要的传递包会自然消失。删除只有传递来源的包会报错，因为它不属于 项目 manifest 的直接依赖。

#lock

按当前 lux.toml 重新生成 lux.lock：

luxc lock my_addon

这个命令不会查找新版本。Lux 的无 registry 模型中，版本选择来自 manifest 里的显式 source ref；lux.package.toml 里的 package version 只用于检查选定依赖图的兼容性。

#list

打印 lockfile 里的包：

luxc list my_addon

#doctor

检查 package manager 状态：

luxc doctor my_addon

#self

把当前 compiler 安装到用户 toolchain 目录，并设为全局默认。release zip 通常直接 运行 install-lux-path.ps1；这个命令主要用于显式版本管理和源码构建流程：

luxc self install --default

稳定用户入口是 Unix-like 系统下的 ~/.lux/bin/luxc，Windows 下是 %USERPROFILE%\.lux\bin\luxc.exe。已安装 compiler 位于 ~/.lux/toolchains/<version>/。

可以安装或更新指定版本：

luxc self update
luxc self install 0.1.0-alpha.2 --default

查看和选择已安装版本：

luxc self list
luxc self which
luxc self default 0.1.0-alpha.2

大多数项目使用全局默认版本。只有团队或 CI 需要固定 compiler 时才 pin：

luxc self pin 0.1.0-alpha.2 --project my_addon
luxc self unpin --project my_addon

#lsp

启动由 compiler 提供的 Language Server Protocol 进程：

luxc lsp

编辑器应该启动项目或用户配置选中的 compiler。这样 diagnostics、completion、package resolution 和 build 都使用同一个 luxc 版本。

#compile

编译单个 Lux 文件并把 Lua 打印到标准输出：

luxc compile examples\features.lux

写出源码映射：

luxc compile examples\features.lux `
  --map examples\features.lua.map.json

加入源码注释：

luxc compile examples\features.lux --source-comments readable

可用模式：

none      不插入源码注释
readable  适合人工阅读
boundary  在源码映射边界处插入
dense     尽量密集插入

compile 适合调试语言特性。真实 GMod 插件应使用 gmod build，因为它会处理模块图、 运行时包和 loader。

#map-error

把生成 Lua 的行号映射回 Lux 源码：

luxc map-error generated\lua\lux\client\my_addon\hud.lua.map.json 42

输出形状：

C:\path\to\src\client\hud.lux:18:5

GMod 报错通常给的是生成 Lua 路径和行号。保留 .lua.map.json 后，可以用这个命令 定位 Lux 源码位置。

#gmod build

使用配置文件：

luxc gmod build --manifest examples\gmod_project\lux.toml

只生成计划，不写文件：

luxc gmod build --manifest examples\gmod_project\lux.toml --dry-run

直接指定路径：

luxc gmod build src --out generated/lua

--out 会覆盖配置里的输出根，适合临时输出到测试目录。--no-autorun 只关闭 out/autorun 下的 addon forwarder，不会关闭 Lux loader tree。

#gmod package

先构建，再打印 gmad 命令计划：

luxc gmod package `
  --manifest path\to\lux.toml `
  --root generated `
  --gmad path\to\gmad.exe `
  --out dist\addon.gma

真正执行：

luxc gmod package --manifest path\to\lux.toml --root generated --gmad path\to\gmad.exe --out dist\addon.gma --run

没有 --run 时不会调用 gmad。这是为了避免构建命令意外生成或覆盖发布包。--root 是传给 gmad 的打包根，和构建输出 out 是两个概念。只有需要临时覆盖 manifest 构建输出时才使用 --build-out。

#gmod api update

重新生成内置官方 GMod API 数据库：

luxc gmod api update `
  --out lsp\crates\gmod-api-db\data\generated\gmod_api.json `
  --coverage-out lsp\crates\gmod-api-db\data\generated\coverage_manifest.json `
  --cache-dir lsp\target\gmod-api-cache

--offline 只适合已有 cache 的情况。--allow-failures 只用于 parser 开发，不应用于 发布质量的 bundled data。