Automerge

Automerge 是一个库，它提供了多种不同 CRDT 的快速实现、用于这些 CRDT 的紧凑压缩格式，以及用于通过网络高效传输这些变更的同步协议。该项目的目标是支持本地优先应用程序，就像关系数据库支持服务器应用程序一样——通过提供持久化机制，让应用程序开发人员无需考虑复杂的分布式计算问题。Automerge 旨在成为本地优先应用的 PostgreSQL。

在我们的网站上，您可以找到 JavaScript 文档，其中包含完整的教程和 API 参考。此仓库还包含核心 Rust 库，该库被编译为 WebAssembly 并在 JavaScript 中公开，其文档可在 docs.rs 上找到。最后，rust/automerge-c 目录下有一个 C 库——有关更多详细信息，请查看该目录下的 README。

如果您熟悉 CRDT，并且对 Automerge 的设计特别感兴趣，请查看 二进制格式规范。

最后，如果您想与我们讨论这个项目，请 加入我们的 Discord 服务器！

状态

该项目由核心 Rust 实现构成，通过 FFI 在 JavaScript+WASM、C 以及即将支持的其他语言中公开。Alex（@alexjg）和 Orion（@orionz）全职负责维护 Automerge，Ink & Switch 的其他成员也在贡献时间，同时还有几位其他维护者。我们最近发布了 Automerge 3，实现了约 10 倍的内存使用量减少。

一般来说，我们会尽量遵循语义化版本控制（semver）。

JavaScript

JavaScript 包的稳定版本可通过 @automerge/automerge 获取。

Rust

Rust 代码库目前主要用于为 JavaScript 包装器提供高性能后端，因此 Rust 代码的 API 级别较低，且文档不够完善。我们将在未来几个月内改进这一情况，但就目前而言，您需要能够阅读测试代码并主动提问，才能弄清楚如何使用它。如果您希望构建使用 automerge 的 Rust 应用程序，不妨了解一下 autosurgeon。

仓库组织

• ./rust - Rust 实现以及特定平台包装器的 Rust 组件（例如，用于 WASM API 的 automerge-wasm 或用于 C FFI 绑定的 automerge-c）
• ./javascript - JavaScript 库，其内部使用 automerge-wasm，但提供了更符合 JavaScript 习惯的接口
• ./scripts - 对仓库维护有用的脚本，包括在 CI 中运行的脚本
• ./img - 用于 .md 文件的静态资源

构建

要构建此代码库，您需要：

• rust
• node

如果您有兴趣构建 automerge-c 库，还需要：

• cmake
• cmocka
• doxygen
• ninja

您还需要通过 cargo install 安装以下工具：

• wasm-bindgen-cli
• wasm-opt
• cargo-deny

并确保已添加 wasm32-unknown-unknown 目标用于 Rust 交叉编译。WASM 构建还需要 nightly 工具链和 rust-src 组件（具体命令见下文 macOS 说明）；automerge-wasm 和 JS 包使用这些来构建带有 panic=unwind 的标准库，以便将 panic 作为 JS 异常抛出。

各个子项目（Rust 代码、包装器项目）都有自己的构建说明，但要运行 CI 中会执行的测试，您可以运行 ./scripts/ci/run。

适用于 macOS

截至 2022 年 11 月 29 日，以下说明已在 macOS 13.1（arm64）上本地构建成功。

# clone the repo
git clone https://github.com/automerge/automerge
cd automerge

# install rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# install homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# install cmake, node, cmocka
brew install cmake node cmocka

# install javascript dependencies
npm --prefix ./javascript install

# install rust dependencies
cargo install wasm-bindgen-cli wasm-opt cargo-deny

# get nightly rust to produce optimized automerge-c builds
rustup toolchain install nightly
rustup component add rust-src --toolchain nightly

# add wasm target in addition to current architecture
rustup target add wasm32-unknown-unknown

# Run ci script
./scripts/ci/run

如果您的构建因找不到 cmocka.h 而失败，可能需要告知构建系统 homebrew 的安装位置：

export CPATH=/opt/homebrew/include
export LIBRARY_PATH=/opt/homebrew/lib
./scripts/ci/run

Nix Flake

如果您已安装 Nix，则有一个 flake 可用，其中包含所有已配置的依赖项和一些辅助脚本。

$ nix develop

  ____                                          _
 / ___|___  _ __ ___  _ __ ___   __ _ _ __   __| |___
| |   / _ \| '_ ` _ \| '_ ` _ \ / _` | '_ \ / _` / __|
| |__| (_) | | | | | | | | | | | (_| | | | | (_| \__ \
 \____\___/|_| |_| |_|_| |_| |_|\__,_|_| |_|\__,_|___/


build:deno          | Build Deno-wrapped Wasm library
build:host          | Build for aarch64-darwin
build:node          | Build JS-wrapped Wasm library
build:wasi          | Build for Wasm32-WASI
build:wasm:nodejs   | Build for wasm32-unknown-unknown with Node.js bindgings
build:wasm:web      | Build for wasm32-unknown-unknown with web bindings
docs:build:host     | Refresh the docs
docs:build:wasm     | Refresh the docs with the wasm32-unknown-unknown target
docs:open:host      | Open refreshed docs
docs:open:wasm      | Open refreshed docs
# ✂️  SNIP ✂️

$ rustc --version
rustc 1.82.0 (f6e511eec 2024-10-15) # latest at time of writing

贡献指南

请尽量将您的修改拆分为相对独立的提交，每次只修改一个子系统，并添加清晰的提交信息，说明修改内容及原因（提交信息宁长勿短）。git blame 应该能让未来的维护者清楚了解某项内容为何如此设计。

发布流程

本仓库中有四个制品需要发布：

• @automerge/automerge NPM 包
• @automerge/automerge-wasm NPM 包
• automerge deno crate
• automerge Rust crate

JS 包

每当创建新的 Github 发布时，CI 工具会自动发布 NPM 包。因此，发布新 JS 版本的流程如下：

1. 在 @automerge/automerge 以及 javascript/package.json 中更新版本号
2. 提交版本更新的 PR 至 main 分支，等待测试完成后合并到 main
3. 合并到 main 后，创建格式为 js/automerge-<version> 的标签
4. 在 Github 上创建引用该标签的新发布

此流程依赖于在 actions 环境中可用的访问令牌 NPM_TOKEN。该令牌的有效期为 30 天，因此需要定期（手动）刷新。

Rust 包

Rust 包的发布流程相对简单，但自动化程度较低。发布步骤如下：

1. 在 automerge/Cargo.toml 中更新版本号
2. 提交 PR 并在测试通过后合并
3. 创建格式为 rust/automerge@<version> 的发布标签
4. 将标签推送到仓库
5. 使用 cargo publish 发布版本