From 13b7466c57bba699be5abe89cef8ede712f81bdc Mon Sep 17 00:00:00 2001 From: dailz Date: Mon, 22 Jun 2026 16:41:29 +0800 Subject: [PATCH] =?UTF-8?q?docs(args):=20=E4=B8=AD=E6=96=87=E6=B3=A8?= =?UTF-8?q?=E9=87=8A=20src/args.rs=20CLI=20=E5=8F=82=E6=95=B0=E5=AE=9A?= =?UTF-8?q?=E4=B9=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/args.rs | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/src/args.rs b/src/args.rs index af213a7..9352f21 100644 --- a/src/args.rs +++ b/src/args.rs @@ -1,35 +1,75 @@ +//! CLI 参数定义模块（基于 `clap` derive 宏）。 +//! +//! 本文件用 `clap` 的 derive 宏把一个普通 struct 变成命令行解析器，思路类 +//! 似 Go 的 `flag` 包，但更贴近"struct tag 自动生成"——每个 `pub` 字段配 +//! 一行 `#[arg(...)]` 属性宏，clap 在编译期据此生成 `-x` / `--xxx` 选项、 +//! 帮助文案、默认值和类型校验。`#[derive(Parser, Debug, Clone)]` 三个 +//! derive 的作用： +//! - `Parser`：clap 的入口 trait，提供 `Args::parse()`，等价于 Go 里的 +//! `flag.Parse()`； +//! - `Debug`：支持 `{:?}` 调试打印； +//! - `Clone`：允许 `Args::clone()` 值复制（运行循环里会用到）。 +//! +//! Rust ↔ Go 类型对照（本文件用到的）： +//! - `Option` ≈ Go `*string`：`None` 表示用户没传该 flag，等价于 +//! `nil` 指针；`Some(s)` 表示传了； +//! - `String`（无 `Option`）≈ Go `string`：必有值，由 `default_value` +//! 兜底，所以运行期不会空； +//! - `u32` / `u64` / `u16` ≈ Go `uint32` / `uint64` / `uint16`； +//! - `bool` ≈ Go `bool`，但 clap 把它当开关：出现即 `true`，不出现即 +//! `false`，等价于 Go 里没有参数的 `flag.Bool`； +//! - `default_value_t = 30` ≈ Go `flag.Int("fps", 30, "...")` 的第二个 +//! 参数（默认值）； +//! - `default_value = "h264"` 用于 `String` 字段，等价意思； +//! - `#[arg(short, long)]` 同时生成短选项（`-o`，取字段首字母）和长选项 +//! （`--output`）； +//! - `#[arg(long)]` 只生成长选项 `--output-name`，没有短形式。 +//! +//! 注意：`AGENTS.md` 明确指出 README 的 CLI 表对 `--backend` 和 `--no-persist` +//! 已过时，**以本文件为准**。 + use clap::Parser; +// 根解析器 struct。下方 `#[command(...)]` 设置 `--help` 第一行的程序名和 +// `about` 文案；注意不要在此 struct 上加 `///`，否则 clap 会把 doc 注释 +// 注入 help 文案，可能覆盖 `about`，导致 byte-identical 不变量被破坏。 #[derive(Parser, Debug, Clone)] #[command(name = "wl-webrtc", about = "Wayland screen capture and encoding tool")] pub struct Args { /// Output file path (e.g., output.mp4, output.mkv). Optional when using --port for WebRTC mode #[arg(short, long)] pub output: Option, + // 输出文件路径（`-o`/`--output`）。`Option` ≈ Go `*string`，`None` 表示用户没传 /// Wayland output name to capture #[arg(long)] pub output_name: Option, + // 指定要抓取的 Wayland 输出（显示器）名；`None` 时由后端自动选主屏 /// Target frames per second #[arg(long, default_value_t = 30)] pub fps: u32, + // 目标帧率（`--fps`，默认 30）。`default_value_t = 30` ≈ Go `flag.Int("fps", 30, ...)` /// Video codec (h264 only for MVP) #[arg(long, default_value = "h264")] pub codec: String, + // 视频编码器（`--codec`，默认 `h264`）。MVP 阶段只支持 H.264，对比 Go 里 owned 的 `string` /// Hardware acceleration method (vaapi only for MVP) #[arg(long, default_value = "vaapi")] pub hw_accel: String, + // 硬件加速方式（`--hw-accel`，默认 `vaapi`），目前只接受 `vaapi` /// DRM render device path (e.g., /dev/dri/renderD128) #[arg(long)] pub drm_device: Option, + // DRM 渲染节点路径（如 `/dev/dri/renderD128`），VAAPI 上下文需要它；`None` 时自动探测 /// Target bitrate in bits per second #[arg(long)] pub bitrate: Option, + // 目标码率（bps）。`Option` ≈ Go `*uint64`，`None` 时编码器用内部默认码率 /// Maximum bitrate in bps for WebRTC mode. Caps BWE-driven escalation to /// prevent large IDR bursts from swamping the network. Default 8 Mbps covers @@ -37,28 +77,35 @@ pub struct Args { /// See issue #23. #[arg(long, default_value = "8000000")] pub max_bitrate: u64, + // WebRTC 模式下的码率上限（默认 8 Mbps），抑制 IDR 突发造成网络拥塞；MP4 模式忽略 /// Group of Pictures (GOP) size #[arg(long)] pub gop_size: Option, + // GOP 长度（关键帧间距）；`None` 时由编码器按内部策略自选 /// Enable verbose logging #[arg(short, long)] pub verbose: bool, + // 详细日志（`-v`/`--verbose`）。`bool` 在 clap 里是开关：出现即 `true`，等价 Go `flag.Bool` /// Capture backend to use: 'screencopy' (wlroots) or 'portal' (KWin/KDE). Auto-detected if omitted #[arg(long)] pub backend: Option, + // 抓屏后端（`screencopy` 或 `portal`）；`None` 时由 `backend_detect.rs` 自动选择 /// Port for WebRTC HTTP signaling server; 0 keeps MP4 file output mode #[arg(long, default_value_t = 0)] pub port: u16, + // WebRTC HTTP 信令端口（`--port`，默认 0）。`0` 走 MP4 文件输出模式，`>0` 走 WebRTC 模式 /// Force re-authorization dialog (ignore saved portal restore token) #[arg(long)] pub no_persist: bool, + // 忽略已保存的 portal restore token，强制每次都弹授权对话框（测试时常用） /// Enable per-second pipeline statistics output for stutter diagnosis #[arg(long)] pub stats: bool, + // 每秒打印管线统计（编码帧数、延迟等），用于卡顿诊断 }