Rust Ecosystem

Relevant source files

The following files were used as context for generating this wiki page:

• packages/core/src/ecosystem/rust.ts
• packages/core/src/ecosystem/ecosystem.ts
• packages/core/tests/unit/ecosystem/rust.test.ts
• packages/core/tests/unit/ecosystem/manifest-delegation.test.ts
• plugins/pubm-plugin/skills/publish-setup/references/ci-templates.md
• packages/pubm/src/commands/init-workflows.ts

The Rust Ecosystem within pubm provides a specialized implementation for managing Rust projects and crates. It handles the lifecycle of Rust packages, including versioning via Cargo.toml, dependency synchronization, and publishing to the crates.io registry. This ecosystem is designed to work both in standalone Rust projects and as part of multi-ecosystem monorepos where JavaScript and Rust code coexist.

The system abstracts Rust-specific operations such as lockfile synchronization using cargo update and sibling dependency management to ensure that internal workspace references are correctly versioned during the release process.

Architecture and Core Components

The Rust ecosystem is centered around the RustEcosystem class, which extends the base Ecosystem abstraction. It provides the necessary logic to interact with the Rust toolchain and manifest files.

Key Classes and Methods

Component	Description	Source
RustEcosystem	Main class implementing Rust-specific lifecycle logic.	[rust.ts:13](https://github.com/syi0808/pubm/blob/HEAD/rust.ts#L13)
detect()	Static method that checks for the existence of Cargo.toml to identify a Rust package.	[rust.ts:14-16](https://github.com/syi0808/pubm/blob/HEAD/rust.ts#L14-L16)
writeVersion()	Updates the version field in Cargo.toml using smol-toml for parsing and stringifying.	[rust.ts:22-31](https://github.com/syi0808/pubm/blob/HEAD/rust.ts#L22-L31)
syncLockfile()	Runs cargo update to synchronize Cargo.lock with manifest changes.	[rust.ts:70-93](https://github.com/syi0808/pubm/blob/HEAD/rust.ts#L70-L93)
updateSiblingDependencyVersions()	Updates versions for internal path-based dependencies within a workspace.	[rust.ts:37-68](https://github.com/syi0808/pubm/blob/HEAD/rust.ts#L37-L68)

Ecosystem Inheritance

The following diagram illustrates the relationship between the base Ecosystem class and the Rust-specific implementation.

Manifest and Registry Management

The Rust ecosystem specifically targets the crates registry and utilizes Cargo.toml as its primary manifest file.

Supported Registries and Files

• Primary Registry: crates (crates.io).
• Manifest File: Cargo.toml.
• Lock File: Cargo.lock.
• Default Commands:
  • Test: cargo test
  • Build: cargo build --release

Sources: [rust.ts:99-111](https://github.com/syi0808/pubm/blob/HEAD/rust.ts#L99-L111), [rust.test.ts:101-115](https://github.com/syi0808/pubm/blob/HEAD/rust.test.ts#L101-L115)

Dependency Synchronization Logic

When managing a monorepo or a project with multiple crates, pubm ensures that dependencies referring to sibling crates via path are updated to include the correct version strings. This is critical for successful publishing to crates.io.

CI/CD Integration

For Rust projects, pubm supports a CI/CD flow that can bypass Node.js requirements if installed via Homebrew.

Publishing Workflow in CI

The publishing phase in CI (--phase publish) performs the following actions for Rust:

1. Skips standard prerequisite checks (branch, remote, working tree).
2. Reads the version directly from Cargo.toml.
3. Executes cargo publish via the pubm CLI.
4. Creates a GitHub Release and uploads pre-built binaries if configured.

Sources: [ci-templates.md:8-15](https://github.com/syi0808/pubm/blob/HEAD/ci-templates.md#L8-L15), [ci-templates.md:88-100](https://github.com/syi0808/pubm/blob/HEAD/ci-templates.md#L88-L100)

Environment Variables

To publish to crates.io in a CI environment, the following secret must be provided:

• CARGO_REGISTRY_TOKEN: The API token generated from crates.io account settings.
• GITHUB_TOKEN: Used for creating releases and uploading assets.

Sources: [ci-templates.md:28-35](https://github.com/syi0808/pubm/blob/HEAD/ci-templates.md#L28-L35), [init-workflows.ts:114-118](https://github.com/syi0808/pubm/blob/HEAD/init-workflows.ts#L114-L118)

GitHub Actions Template Example

A typical Rust release workflow uses the dtolnay/rust-toolchain and installs pubm to handle the orchestration.

      - uses: dtolnay/rust-toolchain@stable
      - name: Install pubm
        run: |
          brew tap syi0808/tap
          brew install pubm
      - name: Publish and release
        run: pubm --mode ci --phase publish
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}

Sources: [ci-templates.md:218-237](https://github.com/syi0808/pubm/blob/HEAD/ci-templates.md#L218-L237), [init-workflows.ts:98-103](https://github.com/syi0808/pubm/blob/HEAD/init-workflows.ts#L98-L103)

Implementation Details

Version Writing

The system uses smol-toml to ensure that the Cargo.toml file is parsed correctly and that the version update does not corrupt other TOML sections or comments. It specifically targets the [package].version field.
Sources: [rust.ts:22-31](https://github.com/syi0808/pubm/blob/HEAD/rust.ts#L22-L31), [rust.test.ts:63-75](https://github.com/syi0808/pubm/blob/HEAD/rust.test.ts#L63-L75)

Lockfile Discovery

pubm searches for a Cargo.lock file by traversing upwards from the package directory to the root of the workspace. This allows it to handle both single-package repositories and large monorepos with a central lockfile.
Sources: [rust.ts:95-108](https://github.com/syi0808/pubm/blob/HEAD/rust.ts#L95-L108), [rust.test.ts:182-195](https://github.com/syi0808/pubm/blob/HEAD/rust.test.ts#L182-L195)

Conclusion

The Rust Ecosystem provides a robust bridge between the pubm publishing pipeline and the standard Rust cargo toolchain. By automating the complexities of TOML manipulation, lockfile updates, and sibling dependency versioning, it ensures reliable and consistent releases for Rust crates within any repository structure.