cmd_lib

Rust 命令行库

常见的 Rust 命令行宏和工具，便于在 Rust 编程语言中轻松编写类似 shell 脚本的任务。可在 crates.io 上找到。

为什么你需要这个

如果你需要在 Rust 中运行一些外部命令，std::process::Command 是在各个操作系统系统调用之上的一个良好的抽象层。它提供了对如何创建新进程的精细控制，并允许你等待进程完成并检查退出状态或收集所有输出。然而，当需要 重定向 或 管道 时，你需要手动设置父亲和子进程的 I/O 处理程序，就像在 rust cookbook 中这样做，这通常是繁琐且容易出错的。

许多开发者会选择使用 shell（sh、bash、...）脚本来完成此类任务，通过使用 < 来重定向输入，> 来重定向输出，以及 | 来管道输出。在我的经验中，这 是 shell 脚本中唯一的好部分。你可以找到各种陷阱和神秘的技巧来让 shell 脚本的其它部分工作。随着 shell 脚本的增长，它们最终将变得难以维护，没有人愿意再接触它们。

此cmd_lib库旨在提供重定向和管道功能，以及其他方便编写类似shell脚本任务的设施，而无需启动任何shell。对于Rust菜谱示例，在库的帮助下，通常可以将其实现为一行Rust宏，例如在examples/rust_cookbook.rs中所示。由于它们是Rust代码，在必要时可以未来在Rust本地重写，而不需要启动外部命令。

该库的外观

为了获得初步印象，这里有一个examples/dd_test.rs的示例。

run_cmd! (
    info "Dropping caches at first";
    sudo bash -c "echo 3 > /proc/sys/vm/drop_caches";
    info "Running with thread_num: $thread_num, block_size: $block_size";
)?;
let cnt = DATA_SIZE / thread_num / block_size;
let now = Instant::now();
(0..thread_num).into_par_iter().for_each(|i| {
    let off = cnt * i;
    let bandwidth = run_fun!(
        sudo bash -c "dd if=$file of=/dev/null bs=$block_size skip=$off count=$cnt 2>&1"
        | awk r#"/copied/{print $(NF-1) " " $NF}"#
    )
    .unwrap_or_else(|_| cmd_die!("thread $i failed"));
    info!("thread {i} bandwidth: {bandwidth}");
});
let total_bandwidth = Byte::from_bytes((DATA_SIZE / now.elapsed().as_secs()) as u128).get_appropriate_unit(true);
info!("Total bandwidth: {total_bandwidth}/s");

输出将如下所示

➜  rust_cmd_lib git:(master) ✗ cargo run --example dd_test -- -b 4096 -f /dev/nvme0n1 -t 4
    Finished dev [unoptimized + debuginfo] target(s) in 0.04s
     Running `target/debug/examples/dd_test -b 4096 -f /dev/nvme0n1 -t 4`
[INFO ] Dropping caches at first
[INFO ] Running with thread_num: 4, block_size: 4096
[INFO ] thread 3 bandwidth: 317 MB/s
[INFO ] thread 1 bandwidth: 289 MB/s
[INFO ] thread 0 bandwidth: 281 MB/s
[INFO ] thread 2 bandwidth: 279 MB/s
[INFO ] Total bandwidth: 1.11 GiB/s

此库提供的内容

运行外部命令的宏

• run_cmd! -> CmdResult

let msg = "I love rust";
run_cmd!(echo $msg)?;
run_cmd!(echo "This is the message: $msg")?;

// pipe commands are also supported
let dir = "/var/log";
run_cmd!(du -ah $dir | sort -hr | head -n 10)?;

// or a group of commands
// if any command fails, just return Err(...)
let file = "/tmp/f";
let keyword = "rust";
run_cmd! {
    cat ${file} | grep ${keyword};
    echo "bad cmd" >&2;
    ignore ls /nofile;
    date;
    ls oops;
    cat oops;
}?;

• run_fun! -> FunResult

let version = run_fun!(rustc --version)?;
eprintln!("Your rust version is {}", version);

// with pipes
let n = run_fun!(echo "the quick brown fox jumped over the lazy dog" | wc -w)?;
eprintln!("There are {} words in above sentence", n);

无开销的抽象

由于所有宏的词法分析和语法分析都在编译时发生，因此它可以基本上生成与手动调用std::process API相同的代码。它还包括命令类型检查，因此大多数错误可以在编译时而不是在运行时发现。借助如rust-analyzer之类的工具，它可以为正在使用的损坏命令提供实时反馈。

您可以使用cargo expand来检查生成的代码。

直观的参数传递

在传递参数到run_cmd!和run_fun!宏时，如果它们不是Rust 字符串字面量的一部分，它们将作为原子组件转换为字符串，因此无需引用它们。参数将类似于在run_cmd!或run_fun!宏中的$a或${a}。

let dir = "my folder";
run_cmd!(echo "Creating $dir at /tmp")?;
run_cmd!(mkdir -p /tmp/$dir)?;

// or with group commands:
let dir = "my folder";
run_cmd!(echo "Creating $dir at /tmp"; mkdir -p /tmp/$dir)?;

您可以将""视为粘合剂，因此引号内的所有内容都将被视为单个原子组件。

如果它们是原始字符串字面量的一部分，则不会有字符串插值，这与惯用的Rust相同。但是，您始终可以使用format!宏来形成新的字符串。例如

// string interpolation
let key_word = "time";
let awk_opts = format!(r#"/{}/ {{print $(NF-3) " " $(NF-1) " " $NF}}"#, key_word);
run_cmd!(ping -c 10 www.google.com | awk $awk_opts)?;

注意这里$awk_opts将被视为传递给awk命令的单个选项。

如果您想使用动态参数，可以使用$[]来访问向量变量

let gopts = vec![vec!["-l", "-a", "/"], vec!["-a", "/var"]];
for opts in gopts {
    run_cmd!(ls $[opts])?;
}

重定向和管道

目前支持管道和stdin、stdout、stderr重定向。大部分与bash脚本相同。

日志记录

此库提供方便的宏和内置命令用于日志记录。所有打印到stderr的消息都将被记录。它还会在错误结果中包括完整的运行命令。

let dir: &str = "folder with spaces";
run_cmd!(mkdir /tmp/$dir; ls /tmp/$dir)?;
run_cmd!(mkdir /tmp/$dir; ls /tmp/$dir; rmdir /tmp/$dir)?;
// output:
// [INFO ] mkdir: cannot create directory ‘/tmp/folder with spaces’: File exists
// Error: Running ["mkdir" "/tmp/folder with spaces"] exited with error; status code: 1

它使用Rust log crate，您可以使用您最喜欢的日志记录实现。注意，如果您不提供任何日志记录器，它将使用env_logger从进程的stderr打印消息。

您还可以使用main()函数标记，通过#[cmd_lib::main]，默认情况下它将记录main()的错误。例如：

[ERROR] FATAL: Running ["mkdir" "/tmp/folder with spaces"] exited with error; status code: 1

内置命令

cd

cd：设置进程当前目录。

run_cmd! (
    cd /tmp;
    ls | wc -l;
)?;

请注意，内置的cd命令只会更改当前作用域，并在退出作用域时恢复先前的当前目录。

如果想要改变整个程序的工作目录，请使用std::env::set_current_dir。

ignore

忽略命令执行错误。

echo

将消息打印到标准输出。

-n     do not output the trailing newline

error, warn, info, debug, trace

将消息以不同级别打印到日志。如果您不需要在命令组内部进行日志记录，也可以使用正常的日志宏。

run_cmd!(error "This is an error message")?;
run_cmd!(warn "This is a warning message")?;
run_cmd!(info "This is an information message")?;
// output:
// [ERROR] This is an error message
// [WARN ] This is a warning message
// [INFO ] This is an information message

低级别进程创建宏

spawn!宏将整个命令作为子进程执行，返回对其的句柄。默认情况下，stdin、stdout和stderr将从父进程继承。进程将在后台运行，因此您可以并发运行其他任务。您可以调用wait()等待进程完成。

使用spawn_with_output!，您可以通过调用wait_with_output()、wait_with_all()甚至使用wait_with_pipe()进行流处理来获取输出。

还有一些其他有用的API，您可以查看文档以获取更多详细信息。

let mut proc = spawn!(ping -c 10 192.168.0.1)?;
// do other stuff
// ...
proc.wait()?;

let mut proc = spawn_with_output!(/bin/cat file.txt | sed s/a/b/)?;
// do other stuff
// ...
let output = proc.wait_with_output()?;

spawn_with_output!(journalctl)?.wait_with_pipe(&mut |pipe| {
    BufReader::new(pipe)
        .lines()
        .filter_map(|line| line.ok())
        .filter(|line| line.find("usb").is_some())
        .take(10)
        .for_each(|line| println!("{}", line));
})?;

注册自定义命令的宏

使用正确的签名声明您的函数，并通过use_custom_cmd!宏进行注册。

fn my_cmd(env: &mut CmdEnv) -> CmdResult {
    let args = env.get_args();
    let (res, stdout, stderr) = spawn_with_output! {
        orig_cmd $[args]
            --long-option xxx
            --another-option yyy
    }?
    .wait_with_all();
    writeln!(env.stdout(), "{}", stdout)?;
    writeln!(env.stderr(), "{}", stderr)?;
    res
}

use_custom_cmd!(my_cmd);

定义、获取和设置线程局部全局变量的宏

• tls_init!用于定义线程局部全局变量
• tls_get!用于获取值
• tls_set!用于设置值

tls_init!(DELAY, f64, 1.0);
const DELAY_FACTOR: f64 = 0.8;
tls_set!(DELAY, |d| *d *= DELAY_FACTOR);
let d = tls_get!(DELAY);
// check more examples in examples/tetris.rs

其他注意事项

环境变量

您可以使用std::env::var从当前进程获取环境变量键。如果环境变量不存在，它将报告错误，并包括其他检查以避免静默失败。

要设置环境变量，请使用std::env::set_var。在std::env模块中还有其他相关的API。

要仅针对命令设置环境变量，您可以将赋值放在命令之前。如下所示：

run_cmd!(FOO=100 /tmp/test_run_cmd_lib.sh)?;

安全注意事项

使用宏实际上可以避免命令注入，因为我们会在变量替换之前进行解析。例如，下面的代码即使在没有任何引号的情况下也是安全的

fn cleanup_uploaded_file(file: &Path) -> CmdResult {
    run_cmd!(/bin/rm -f /var/upload/$file)
}

在bash中情况并非如此，它总是会先进行变量替换。

全局/通配符

此库不提供glob函数，以避免静默错误和其他惊喜。您可以使用glob包代替。

线程安全

此库非常努力地避免设置全局状态，因此可以正常执行并行cargo test。在多线程环境中不支持的唯一已知API是tls_init!/tls_get!/tls_set!宏，并且您应该只使用它们来声明线程局部变量。

许可证：MIT OR Apache-2.0