home / skills / zhanghandong / rust-skills / m11-ecosystem

m11-ecosystem skill

safe

This skill helps you choose the right Rust crate and integration approach for a project by evaluating maintenance, scope, and compatibility.

npx playbooks add skill zhanghandong/rust-skills --skill m11-ecosystem

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

4.4 KB

---
name: m11-ecosystem
description: "Use when integrating crates or ecosystem questions. Keywords: E0425, E0433, E0603, crate, cargo, dependency, feature flag, workspace, which crate to use, using external C libraries, creating Python extensions, PyO3, wasm, WebAssembly, bindgen, cbindgen, napi-rs, cannot find, private, crate recommendation, best crate for, Cargo.toml, features, crate 推荐, 依赖管理, 特性标志, 工作空间, Python 绑定"
user-invocable: false
---

## Current Dependencies (Auto-Injected)

!`grep -A 100 '^\[dependencies\]' Cargo.toml 2>/dev/null | head -30 || echo "No Cargo.toml found"`

---

# Ecosystem Integration

> **Layer 2: Design Choices**

## Core Question

**What's the right crate for this job, and how should it integrate?**

Before adding dependencies:
- Is there a standard solution?
- What's the maintenance status?
- What's the API stability?

---

## Integration Decision → Implementation

| Need | Choice | Crates |
|------|--------|--------|
| Serialization | Derive-based | serde, serde_json |
| Async runtime | tokio or async-std | tokio (most popular) |
| HTTP client | Ergonomic | reqwest |
| HTTP server | Modern | axum, actix-web |
| Database | SQL or ORM | sqlx, diesel |
| CLI parsing | Derive-based | clap |
| Error handling | App vs lib | anyhow, thiserror |
| Logging | Facade | tracing, log |

---

## Thinking Prompt

Before adding a dependency:

1. **Is it well-maintained?**
   - Recent commits?
   - Active issue response?
   - Breaking changes frequency?

2. **What's the scope?**
   - Do you need the full crate or just a feature?
   - Can feature flags reduce bloat?

3. **How does it integrate?**
   - Trait-based or concrete types?
   - Sync or async?
   - What bounds does it require?

---

## Trace Up ↑

To domain constraints (Layer 3):

```
"Which HTTP framework should I use?"
    ↑ Ask: What are the performance requirements?
    ↑ Check: domain-web (latency, throughput needs)
    ↑ Check: Team expertise (familiarity with framework)
```

| Question | Trace To | Ask |
|----------|----------|-----|
| Framework choice | domain-* | What constraints matter? |
| Library vs build | domain-* | What's the deployment model? |
| API design | domain-* | Who are the consumers? |

---

## Trace Down ↓

To implementation (Layer 1):

```
"Integrate external crate"
    ↓ m04-zero-cost: Trait bounds and generics
    ↓ m06-error-handling: Error type compatibility

"FFI integration"
    ↓ unsafe-checker: Safety requirements
    ↓ m12-lifecycle: Resource cleanup
```

---

## Quick Reference

### Language Interop

| Integration | Crate/Tool | Use Case |
|-------------|------------|----------|
| C/C++ → Rust | `bindgen` | Auto-generate bindings |
| Rust → C | `cbindgen` | Export C headers |
| Python ↔ Rust | `pyo3` | Python extensions |
| Node.js ↔ Rust | `napi-rs` | Node addons |
| WebAssembly | `wasm-bindgen` | Browser/WASI |

### Cargo Features

| Feature | Purpose |
|---------|---------|
| `[features]` | Optional functionality |
| `default = [...]` | Default features |
| `feature = "serde"` | Conditional deps |
| `[workspace]` | Multi-crate projects |

## Error Code Reference

| Error | Cause | Fix |
|-------|-------|-----|
| E0433 | Can't find crate | Add to Cargo.toml |
| E0603 | Private item | Check crate docs |
| Feature not enabled | Optional feature | Enable in `features` |
| Version conflict | Incompatible deps | `cargo update` or pin |
| Duplicate types | Different crate versions | Unify in workspace |

---

## Crate Selection Criteria

| Criterion | Good Sign | Warning Sign |
|-----------|-----------|--------------|
| Maintenance | Recent commits | Years inactive |
| Community | Active issues/PRs | No response |
| Documentation | Examples, API docs | Minimal docs |
| Stability | Semantic versioning | Frequent breaking |
| Dependencies | Minimal, well-known | Heavy, obscure |

---

## Anti-Patterns

| Anti-Pattern | Why Bad | Better |
|--------------|---------|--------|
| `extern crate` | Outdated (2018+) | Just `use` |
| `#[macro_use]` | Global pollution | Explicit import |
| Wildcard deps `*` | Unpredictable | Specific versions |
| Too many deps | Supply chain risk | Evaluate necessity |
| Vendoring everything | Maintenance burden | Trust crates.io |

---

## Related Skills

| When | See |
|------|-----|
| Error type design | m06-error-handling |
| Trait integration | m04-zero-cost |
| FFI safety | unsafe-checker |
| Resource management | m12-lifecycle |

Overview

This skill helps pick and integrate crates into Rust projects and troubleshoot common ecosystem issues. It focuses on dependency selection, feature flags, workspace layout, FFI bindings, and common compiler errors to get integrations working reliably. Use it to evaluate trade-offs and apply concrete fixes for integration problems.

How this skill works

It inspects the integration surface: whether you need a derive-based API, async runtime compatibility, FFI bindings, or conditional features. It guides dependency choice by maintenance, docs, and stability, and maps common error codes (E0425, E0433, E0603) to actionable fixes. It also suggests tooling and crates for language interop (bindgen, cbindgen, pyo3, napi-rs, wasm-bindgen) and recommends workspace and Cargo feature strategies.

When to use it

Choosing the right crate for serialization, HTTP, DB, CLI, logging, or async runtime
Integrating Rust with C, Python, Node, or WebAssembly
Resolving compiler errors about missing crates, private items, or disabled features
Designing workspace layout to avoid duplicate versions and unify types
Deciding which features to enable to reduce binary size or avoid optional deps

Best practices

Prefer well-maintained crates with active repos and good docs
Enable only needed features; use feature flags to limit bloat
Unify dependency versions in a workspace to avoid duplicate types and version conflicts
Favor trait-based, generic integrations when library boundaries require flexibility
Avoid outdated patterns like extern crate or #[macro_use]; import explicitly

Example use cases

Add serde and serde_json for derive-based serialization with minimal bloat
Choose tokio for most async runtimes and reqwest for ergonomic HTTP clients
Use bindgen or cbindgen when interfacing with C/C++ and pyo3 or napi-rs for Python/Node bindings
Enable specific Cargo features in Cargo.toml to fix “feature not enabled” errors
Rework workspace Cargo.toml to resolve duplicate-type issues caused by multiple crate versions

FAQ

I see E0433: can't find crate — what should I check?

Ensure the crate is listed in Cargo.toml under [dependencies] with a compatible version, run cargo update, and confirm the crate name matches the use path.

How do I fix types that conflict across crates?

Unify the dependency version via workspace dependency overrides or move shared types into a single crate so all members depend on the same version.