prs-rs

关于

Rust 版本的 SEGA PRS 压缩方案。

您可以在专门的文档页面上了解更多关于这个项目的信息。

开发

如何开发此项目。

克隆此仓库

# When cloning, make sure symlinks are enabled
git clone -c core.symlinks=true https://github.com/Sewer56/prs-rs.git

安装 Rust

• 安装Rust 工具链。

设置 IDE

• 此仓库完全支持 VSCode。以下提供指南。

Visual Studio Code 集成

Code/VSCode 是事实上的 Rust 开发环境。

以下扩展是必需的

• rust-analyzer 用于 Rust 支持。
• coverage-gutters 用于覆盖率支持。
• CodeLLDB 用于调试。
• crates 更易于依赖管理。

在 Reloaded 项目的 VSCode 配置（.vscode）中包含以下内容

• 在保存时运行 Rust 检查器 clippy。
• 在保存时运行代码格式化 rustfmt。
• 常见操作的任务（生成文档、活动 CI/CD 等）。

这些配置在 .vscode 文件夹中；任务可以通过 Ctrl+Shift+P -> 运行任务 运行。

测试覆盖率

要运行覆盖率，运行任务（Ctrl+Shift+P -> 运行任务），您应该看到

可以在 VSCode 中打开 tarpaulin-report.html 文件（显示预览）以进行实时查看。

对于GUI集成，运行操作 覆盖率侧栏: 监视（在 Ctrl+Shift+P 操作菜单中）。

调试基准测试

如果您想在VSCode中调试基准测试，请转到 运行和调试 菜单并生成启动配置文件，您应该会得到一个用于调试基准测试的配置文件。

分析基准测试

Linux/OSX

执行以下操作

cargo bench --bench my_benchmark --profile profile -- --profile-time 10

这应该在 target/criterion/<方法名>/profile 中生成火焰图。您可以在网页浏览器中打开该火焰图。

Windows

执行以下操作

cargo bench --bench my_benchmark --no-run --profile profile

导航到命令行中列出的可执行文件

target/profile/deps/my_benchmark-eced832ac8f31257.exe

然后在外部分析器（如Visual Studio）下使用以下命令运行：my_benchmark-eced832ac8f31257.exe --bench --profile-time 10

创建C库时优化大小

1. 将 "cdylib" 包类型添加到 Cargo.toml（如果尚未存在）

[lib]
crate-type = ["cdylib"]

安装 cargo-bloat、nightly工具链 和 build-std

cargo install cargo-bloat
rustup toolchain install nightly
rustup component add rust-src --toolchain nightly

运行以下命令使用 cargo-bloat 计算包大小

RUSTFLAGS="-C panic=abort -C lto=fat -C embed-bitcode=yes" cargo +nightly bloat -Z build-std=std,panic_abort -Z build-std-features=panic_immediate_abort --target x86_64-pc-windows-gnu --profile profile --crate-type cdylib -n 100 --features c-exports

如有必要，更改 --target 以适应您的平台。
这应该会产生更适合从C动态链接的二进制文件。

C库的PGO（配置指导优化）

这个基于Reloaded的库是用 配置指导优化（PGO） 构建的。

PGO是一种编译器优化技术，它使用分析运行的数据来提高生成的代码质量。

本项目中PGO实现的详细信息如下

• 我们通过启用 pgo 功能来运行 benchmarks 来收集PGO数据。
• 这是在构建最终C库之前在CI中完成的。

您应确保仅使用实际的代表性工作负载来收集PGO数据。

例如，如果这是一个压缩库，您应该在基准测试中运行“压缩”和“解压缩”方法（不是随机数据）。

在基准测试中排除非现实/代表性工作负载，可以通过“pgo”功能标志进行，例如，可以像这样排除不切实际的基准测试

#[cfg(not(feature = "pgo"))]
{
    bench_create_dict(c);
}

测试PGO

PGO并不保证总是提供改进，在添加代表性工作负载后，始终进行测试。

我们将使用 cargo pgo 进行测试。

首先，安装以下内容

cargo install cargo-pgo
rustup toolchain install nightly
rustup component add llvm-tools-preview

然后运行一个“仪器化”的基准测试，这将运行您的代码在 pgo_benchmark 中，并收集一些数据

cargo +nightly pgo instrument bench

之后运行一个常规基准测试以创建“基线”数字

cargo +nightly bench

然后运行PGO优化构建

cargo +nightly pgo optimize bench

如果大多数结果相等或显示改进，PGO有帮助。否则，通过编辑 rust.yml 工作流程禁用库中的PGO。

文件布局

以下是你项目的预期文件布局

.vscode/
docs/
src/
Cargo.toml
mkdocs.yml

文件夹 docs 和 mkdocs.yml 包含项目的 MkDocs Material 文档。
文件夹 src 应包含你项目的所有源代码。

Cargo.toml 应位于项目的根目录。

C# 对 prs_rs 的绑定

这个基于 Reloaded 的项目提供了 C# 绑定，如 prs_rs.Net.Sys。

这些是对该 Rust 库 C 导出的原始绑定，并且是自动生成的。

项目位于 bindings/csharp 文件夹中。不应修改它。

相反，如果您想创建一个“更友好”的 API，可以创建一个单独的项目，将 prs_rs.Net.Sys 作为依赖项，并提供高级绑定。

贡献

有关如何为该项目贡献的指导，请参阅 CONTRIBUTING。

许可协议

在 GPL v3 (with Reloaded FAQ) 下许可。

了解 Reloaded 为项目选择的一般许可方式。.