tarantool-runner

tarantool-runner 是一个 CLI 应用程序，用于执行基于 tarantool 的 Rust 应用程序。

在大多数基于 tarantool 的 Rust 应用程序中，即使是较小的实用程序，我们也需要编写特殊的运行套件，因为我们需要 tarantool 符号。此项目引入了二进制 tarantool-runner，它接受一个 tarantool 准备好的共享对象（例如 libexample.so），所需的入口点名称（导出的 C 函数）并在新创建的 tarantool 实例中执行它。执行完成后，tarantool 实例将被停止并清除。

快速查看 tarantool-runner 的用法

tarantool-runner -p ./target/debug/libexample.so -e my_exported_proc -- 'my_input_to_function'

tarantool-runner -p ./target/debug/libexample.so -e my_exported_proc -- '{"key": "value"}'

tarantool-runner 灵光闪现的示例

1. shors 模块引入了一个非常棒的功能：它可以直接从路由生成 openapi 规范。但是，此算法需要与 tarantool-module 进行轻微的交互，因此需要 tarantool 符号。没有 tarantool-runner，我们必须自己编写包装脚本以在 tarantool 环境中执行所需的 rust 二进制文件。相反，我们可以简单地使用带有所需入口点的 tarantool-runner。

2. 许多 tarantool 项目需要单元测试——甚至单元测试也可能无法在没有 tarantool 环境的情况下执行。因此，从项目到项目，我们编写功能测试套件以启动 tarantool 环境。《tarantool-runner》部分解决了此问题——它可以在 tarantool 环境中运行任何导出的函数，但您仍然需要使用一些测试模板来吸收和收集带有 #[tarantool::test] 标记的测试。如果这是您的首要任务，您最好使用 tarantool-test，它包括所需的模板并在内部使用 tarantool-runner，将其包装在漂亮的 CLI 界面中。

实用程序安装

您可以从 crates.io 安装二进制实用工具： cargo install tarantool-runner。或者直接从仓库安装。

git clone https://git.picodata.io/picodata/tarantool-runner
cd tarantool-runner
cargo install tarantool-runner

如果您想 扩展 tarantool-runner 或编写自己的面向 tarantool 的 CLI 应用程序，请参阅相关的 部分。

教程

您可以在 Makefile 中看到使用示例：目标 run-example 执行 example 应用程序中的几个入口点，该应用程序位于 example 子目录下。

对于您自己的项目，您的操作如下

1. 确保您的包的入口点可以从 Lua 代码中访问 - 如果您使用 tarantool-module，则必须已经完成。大多数情况下，您只需要用 tarantool::proc 标记它们。

#[tarantool::proc]
pub fn entrypoint_with_input(input: String) -> Result<()> {
    println!("{input}")

    Ok(())
}

2. 编译您的包： cargo build -p mypackage。在此阶段，请注意结果共享库的路径。对于 Linux，它通常是 ./target/debug/libmypackage.so，而对于 macOS，通常是 ./target/debug/libmypackage.dylib。

3. 使用所需的参数和输入（跟在 -- 后面）使用已安装的实用工具： tarantool-runner run -p ./target/debug/libmypackage.so -e entrypoint_with_input -- '{"input": "can be json or any other format"}'。您已经完成了！

作为 CLI 应用的基础

您还可以将 tarantool-runner 作为您自己的 CLI 应用的基础。只需将其作为您项目的依赖项即可，它导出所需的 Cli 结构，这是一个普通的 clap 应用程序。访问 tarantool-test 了解其可能的样子 - 它基于 tarantool-runner 构建。

详细信息

环境

默认情况下，tarantool 环境以这种方式构建

1. 创建基本目录 - 它是位于 /tmp 目录下的随机名称目录。基本目录的创建是通过 tempfile 完成的；初始化 Lua 脚本被复制到这里。
2. Tarantool 不占用任何地址和端口，它监听放置在之前创建的基本目录中的套接字。因此，您可以同时自由使用任意数量的 tarantool-runner，它们不会相互干扰。实际上，这里通过集成测试进行了测试和调试。
3. 创建 Tarantool 运行时文件的临时目录 - 它是基本目录内的 tmp 目录。
4. 将 WAL 模式设置为 none - 因为它将是单实例环境，所以我们不需要它。WAL 目录确实需要 - 我们将其设置为之前创建的临时目录。
5. memtx_dir 设置为临时目录。

为脚本和入口点提供了特殊的环境变量。

1. TARANTOOL_RUNNER_BASEDIR - 指向创建的基本目录；
2. TARANTOOL_RUNNER_TMPDIR - 指向创建的临时目录（tarantool的运行目录）；
3. TARANTOOL_RUNNER_PACKAGE_FULLPATH - 正在执行包的完整路径，例如：./target/debug/libexample.so；
4. TARANTOOL_RUNNER_PACKAGE_LOCATION - 包所在的目录，例如：./target/debug；
5. TARANTOOL_RUNNER_PACKAGE_NAME - 包的名称（不带扩展名）。因此，如果您有像这样的包完整路径：./target/debug/libexample.so，则此变量设置为 libexample；
6. TARANTOOL_RUNNER_PACKAGE_ENTRYPOINT - 正在被执行的入口点（导出函数名）。
7. TARANTOOL_RUNNER_INPUT - 在CLI界面中紧跟在 -- 之后的字符串。您的入口点将作为第一个参数接收此字符串，因此无需自己检索它。

入口点

入口点仅仅是导出的C函数 - 如果您想的话，它们甚至不需要输入参数。入口点的结果会影响tarantool实例的退出代码 - 如果它们产生错误，整个命令将失败。这对于测试套件的执行可能很有趣。

传递输入

输入从命令行传递到入口点 - 在 -- 之后传递。它作为字符串传递给您的入口点 - 您可以对其进行任何操作，例如反序列化。