跳到正文

配置参考 ​

catter 命令行 ​

catter <command> [options] -- <build-command>

每次运行都要指定一个命令,选项写在命令之后。catter --help 列出所有命令,catter <command> --help 显示某个命令的选项。不指定命令时,catter 列出所有命令并报错退出。

命令 ​

命令说明
compile-commands根据捕获的编译器命令生成 compile_commands.json 文件。见编译数据库。
tree把捕获的命令渲染为命令树。见命令树。
targets把捕获的构建目标渲染为扁平的目标森林。见目标树。
profile把构建中各条命令的时间线写成供 Perfetto 使用的 trace。见构建分析。
explain打印 catter 如何分析 -- 之后的命令,而不运行它。见命令分析。
run只用 handler 运行构建,由它们对构建的命令做决定或观察它们。见 Handler。

compile-commands、tree、targets 和 profile 各自在构建上运行一个内置功能,命令行指定的 handler(如果有的话)与它一起运行。run 只运行 handler,至少要指定一个。

选项 ​

compile-commands、tree、targets、profile 和 run 除了各自的选项,还接受以下选项:

选项说明默认值
-C, --directory <path>命令运行所在的目录。当前目录
--capture <backend>构建的命令如何被捕获:hook、wrapper、macOS 上的 eslogger,或者 Linux 上的 ptrace。见捕获后端。hook
--from <file>回放该文件中录制的构建,而不运行构建。
--handler <command>启动一个 handler,它经自己的 stdin 和 stdout 对构建的命令做决定或观察它们;可多次指定。
--connect <host:port>连接在该地址监听的 handler,未指定 --allow-remote 时只限本机;可多次指定。
--allow-remote允许 --connect 连接其他机器上的 handler。
--handler-timeout <seconds>catter 等待 handler 应答、以及会话结束后等待它退出的时长;0 表示一直等下去。60

--from 代替 -- 之后的构建命令:一次运行只能给出两者之一。相对路径从 -C 指定的目录算起。录制的构建不经过捕获:--from 不接受 --capture。

explain 也接受 -C,要分析的命令写在 -- 之后。

退出状态 ​

catter 像构建那样结束:以构建的退出码退出;构建被信号结束时,catter 也以同一个信号结束。重放的构建以其文件记录的退出码结束。catter 自身失败时,比如命令行有误、handler 中止了构建,或者编译数据库或 trace 无法写入,catter 打印原因并以 1 退出。

停止 catter 就会停止构建:发给 catter 的 SIGTERM、SIGINT 或 SIGHUP 会转给构建命令,构建命令像直接收到它一样结束,catter 随后像构建那样结束。catter 被杀死时,构建命令随之结束,eslogger 下除外。

数据目录 ​

catter 把日志和每个运行中会话的套接字放在 $HOME/.catter(Linux、macOS)或 %LOCALAPPDATA%\catter(Windows)。设置了环境变量 CATTER_HOME 时,改用它指定的目录(须为绝对路径)。在 Linux 和 macOS 上,构建中的进程把日志写到它们所属会话的目录,不管构建步骤给它们设置了什么 HOME 或 CATTER_HOME。

catter-proxy 命令行 ​

WARNING

catter-proxy 是 catter 的内部组件,由 catter 自动调用,不需要用户直接使用。

catter-proxy <program> <argv>...
参数说明
<program>要运行的程序,即钩子找到的那个
<argv>程序的参数,第一个是程序名

它从环境中找到要向其报告命令的会话,即下面这些变量。

环境变量 ​

以下环境变量由 catter 在运行时自动设置,此处仅作参考,无需手动配置。

Unix(Linux / macOS) ​

变量用途
__key_catter_proxy_path_v1catter-proxy 可执行文件的路径
__key_catter_command_id_v1IPC 命令标识符
__key_catter_ipc_v1catter 会话的管道
__key_catter_decided_v1(Linux)catter-proxy 启动程序时所用的 exec
LD_PRELOAD(Linux)注入 catter 钩子共享库
DYLD_INSERT_LIBRARIES(macOS)注入 catter 钩子共享库

Windows ​

catter 不设置任何环境变量:它直接把会话交给构建中每个进程里的钩子,构建的环境保持构建自己设置的样子。