Razel

具有缓存的命令执行器。它是

• 快速：命令以多线程方式执行，本地缓存加快了试错开发（避免重复执行已处理过的命令）
• 可扩展：可选的远程缓存允许在 CI 作业之间共享结果
• 可靠：命令在沙盒中执行以检测缺失的依赖项
• 易于使用：命令使用高级 TypeScript 或 Python API 指定，并内置了便利函数/任务
• 适用于：在文件上工作的可执行程序和具有许多依赖项的数据加工管道

Razel 不是一个构建软件的最佳选择，特别是没有内置的编译器和头文件依赖项支持。

入门

Razel 的原生输入格式是 razel.jsonl 文件，请参阅示例 examples/razel.jsonl。可以使用 razel exec -f examples/razel.jsonl 运行。

首选方式是使用高级 API 之一。两者都允许以面向对象的方式指定命令，并提供一个 run() 函数，该函数创建 razel.jsonl 文件，下载原生的 razel 二进制文件并使用它执行命令。

输入文件的路径相对于工作区（razel.jsonl所在的目录）。输出文件创建在<cwd>/razel-out。额外的元数据写入到<cwd>/razel-out/razel-metadata。

TypeScript API

安装Deno以使用TypeScript API。运行示例Deno脚本

deno run -A --check examples/deno.ts -- -v

Python API

Python API需要Python >= 3.8。安装包并运行示例Python脚本

pip install --upgrade razel
python examples/python.py -v

批处理文件（实验性）

除了razel.jsonl外，Razel可以直接执行包含命令的批处理文件。需要指定输入和输出文件，目前处于WIP状态。

使用Razel执行示例examples/batch.sh

razel exec -f examples/batch.sh

在Docker/Podman容器中运行

工作区目录可以挂载到容器中

podman run -t -v $PWD:$PWD -w $PWD denoland/deno deno run -A examples/deno.ts

从源代码构建Razel

使用rustup安装Rust。安装protobuf-compiler。然后运行cargo install --locked razel。

项目状态

Razel处于活跃开发状态，并在生产中使用。

CLI和razel.jsonl的格式可能会更改，同样，输出在razel-out/razel-metadata中也可能更改。虽然Linux是主要开发平台，但Razel也已在Mac和Windows上进行测试。

特性

测量

Razel解析执行命令的stdout以捕获运行时测量并将它们写入到razel-out/razel-metadata/log.json和razel-out/razel-metadata/measurements.csv。目前，支持CTest/CDash使用的<CTestMeasurement>和<DartMeasurement>标签

<CTestMeasurement type="numeric/double" name="score">12.3</CTestMeasurement>
<CTestMeasurement type="text/string" name="result">ok</CTestMeasurement>

计划支持自定义格式。

标签

可以在命令上设置标签。可以使用任何自定义字符串作为标签，用于分组的冒号应该使用。标签将被添加到razel-out/razel-metadata/execution_times.json。计划使用标签来过滤命令和创建报告。

带有razel:前缀的标签是保留的，并具有特殊含义

• razel:quiet：如果命令成功则不详细输出
• razel:verbose：始终显示详细输出
• razel:condition：如果命令失败则继续运行且不详细输出
• razel:no-cache：始终不缓存地执行命令
• razel:no-remote-cache：不使用远程缓存
• razel:no-sandbox：禁用沙盒以及缓存 - 对于未指定输入/输出文件的命令

条件执行 / 跳过命令

可以根据另一个命令的执行结果跳过命令。在一个命令上设置razel:condition标签，并将其用作其他命令的依赖项。

WebAssembly

Razel集成了WebAssembly运行时，并可以使用WebAssembly系统接口（WASI）直接执行WASM模块。

WebAssembly非常适合与Razel一起创建可移植的数据处理管道。只需要一个WebAssembly模块就可以在所有平台上运行 - 并创建精确的输出 - 但WebAssembly的执行速度比本地二进制文件慢，但启动时间可能更快（没有进程开销）。

参数/响应文件

具有大量参数的命令可能会导致命令行过长，无法由操作系统执行。Razel会检测这些情况，并用响应文件替换参数。文件名以@开头。

内存不足（OOM）处理

如果进程被操作系统终止，则会以较低的并发性重试命令和类似命令，以减少总内存使用。 （在K8s中不起作用，因为整个pod被终止。）

沙盒

命令在包含针对一个命令的特定输入文件的符号链接的临时目录中执行。这允许检测会破坏缓存的未指定依赖关系。

沙盒不适用于执行不受信任的代码。

本地缓存

本地缓存默认启用，并存储有关先前执行的命令和输出文件的信息。输出目录razel-out包含指向本地缓存中存储的文件的符号链接。

使用razel exec --info获取默认缓存目录，并使用--cache-dir（环境变量：RAZEL_CACHE_DIR）移动它。

远程缓存

Razel支持与Bazel远程执行API兼容的远程缓存。远程执行尚未实现。

使用--remote-cache（环境变量：RAZEL_REMOTE_CACHE）指定以逗号分隔的远程缓存URL列表。将使用第一个可用的URL。可选地设置--remote-cache-threshold（REMOTE_CACHE_THRESHOLD），仅缓存命令，其中outputSize / execTime < threshold [kilobyte / s]。如果您的远程缓存没有无限的存储容量，这将大大加快执行速度，因为带有大输出文件的小命令将不再被缓存，为昂贵命令提供更多存储空间。

以下远程缓存实现已与Razel进行测试

• bazel-remote-cache
  • 使用podman run --p 9092:9092 buchgr/bazel-remote-cache --max_size 10运行
  • 使用RAZEL_REMOTE_CACHE=grpc://localhost:9092调用razel
• nativelink
  • 在端口50051上使用实例名称main运行

    mkdir -p nativelink-config
    curl https://raw.githubusercontent.com/TraceMachina/nativelink/main/nativelink-config/examples/basic_cas.json --output nativelink-config/basic_cas.json
    podman run -p 50051:50051 -v $PWD/nativelink-config:/nativelink-config:ro ghcr.io/tracemachina/nativelink:v0.2.0 /nativelink-config/basic_cas.json
    

  • 使用RAZEL_REMOTE_CACHE=grpc://localhost:50051/main调用razel

配置

使用razel exec -h列出执行配置选项。某些选项也可以设置为环境变量，这些变量将从.env文件中加载。

以下源按顺序使用，覆盖之前的值

• 当前目录或其父目录中的.env文件
• 当前目录或其父目录中的.env.local文件
• 环境变量
• 命令行选项

致谢

构建快速且正确想法基于Bazel。