serde-generate

此crate旨在将Rust通过 serde-reflection 提取的数据格式编译成其他编程语言的类型定义和（反）序列化方法。

它可以作为库或命令行工具使用（见下文 serdegen）。

支持的语言

以下编程语言作为目标语言完全支持

• C++ 17
• Java 8
• Python 3（需要 numpy >= 1.20.1）
• Rust 2018
• Go >= 1.14
• C#（NetCoreApp >= 2.1）
• Swift 5.3
• OCaml

以下语言部分支持，仍在开发中

• TypeScript 4（与 Deno 打包和测试） (跟进问题)
• Dart >= 2 (跟进问题)

支持的编码

目标语言中的类型定义旨在与提供特定 Serde 编码格式（反）序列化的运行时库一起使用。

此crate提供以下二进制格式，在所有支持的语言中易于部署的运行时库

• Bincode（默认配置仅限），
• BCS（表示二进制规范序列化，Diem 区块链中使用的格式）。

使用 Python 和 Bincode 快速入门

在以下示例中，我们使用 bincode 将 Test 值从 Rust 传输到 Python。

use serde::{Deserialize, Serialize};
use serde_reflection::{Registry, Tracer, TracerConfig};
use std::io::Write;

#[derive(Serialize, Deserialize)]
struct Test {
    a: Vec<u64>,
    b: (u32, u32),
}

// Obtain the Serde format of `Test`. (In practice, formats are more likely read from a file.)
let mut tracer = Tracer::new(TracerConfig::default());
tracer.trace_simple_type::<Test>().unwrap();
let registry = tracer.registry().unwrap();

// Create Python class definitions.
let mut source = Vec::new();
let config = serde_generate::CodeGeneratorConfig::new("testing".to_string())
    .with_encodings(vec![serde_generate::Encoding::Bincode]);
let generator = serde_generate::python3::CodeGenerator::new(&config);
generator.output(&mut source, &registry)?;

assert!(
    String::from_utf8_lossy(&source).contains(
    r#"
@dataclass(frozen=True)
class Test:
    a: typing.Sequence[st.uint64]
    b: typing.Tuple[st.uint32, st.uint32]
"#));

// Append some test code to demonstrate Bincode deserialization
// using the runtime in `serde_generate/runtime/python/bincode`.
writeln!(
    source,
    r#"
value = Test.bincode_deserialize(bytes({:?}))
assert value == Test(a=[4, 6], b=(3, 5))
"#,
    bincode::serialize(&Test { a: vec![4, 6], b: (3, 5) }).unwrap(),
)?;

// Execute the Python code.
let mut child = std::process::Command::new("python3")
    .arg("-")
    .env("PYTHONPATH", std::env::var("PYTHONPATH").unwrap_or_default() + ":runtime/python")
    .stdin(std::process::Stdio::piped())
    .spawn()?;
child.stdin.as_mut().unwrap().write_all(&source)?;
let output = child.wait_with_output()?;
assert!(output.status.success());

二进制工具

除了Rust库之外，此crate还提供了一个二进制工具 serdegen 来处理磁盘上保存的Serde格式。

工具 serdegen 假设 Rust 类型为 serde_reflection::Registry 的值已被序列化到一个 YAML 文件中。生成此类值的首选方法是使用库 serde-reflection 来检查 Rust 定义（也可以参考上面的示例）。

为了快速测试，可以创建一个测试文件如下

cat >test.yaml <<EOF
---
Foo:
  ENUM:
    0:
      A:
        NEWTYPE:
          U64
    1:
      B: UNIT
EOF

然后，以下命令将生成 Python 类定义并将其写入 test.py

cargo run -p serde-generate-bin -- --language python3 test.yaml > test.py

为了创建名为 test 的 Python 模块并在 $DEST 的目录中安装 bincode 运行时，可以运行

cargo run -p serde-generate-bin -- --language python3 --with-runtimes serde bincode --module-name test --target-source-dir "$DEST" test.yaml

使用 --help 查看工具的帮助信息，获取更多选项。

注意：在此存储库之外，可以使用 cargo install serde-generate-bin 安装工具，然后使用 $HOME/.cargo/bin/serdegen。

贡献

有关如何帮助的详细信息，请参阅 CONTRIBUTING 文件。

许可证

本项目可在 Apache 2.0 许可证或 MIT 许可证的条款下获得。