Sebastien Rousseau
Contact ›

LibMake: Rust Library Scaffold Generator

Scaffold a production-ready Rust library with CI, tests, and docs in under 60 seconds

5 min de citit
Banner for: LibMake: Rust Library Scaffold Generator

Rezumat executiv / Concluzii cheie

  • LibMake ⧉ este un instrument CLI Rust cu sursă deschisă instalat prin cargo install libmake care generează o structură completă de bibliotecă din indicatoare CLI sau un fișier de configurare (TOML, YAML, JSON sau CSV), cu ieșire acoperind Cargo.toml, sursă, teste, benchmark-uri, documentație și CI într-o singură invocare.
  • Proiectul generat urmează convențiile Rust API Guidelines: comentarii de documentare la nivel de modul și element în src/lib.rs, #![deny(missing_docs)] în rădăcina crate-ului și un README legat la documentația crate-ului prin #![doc = include_str!("../README.md")].
  • Modul fișier de configurare (--config libmake.toml) permite echipelor să adauge un singur fișier care specifică complet șablonul lor de bibliotecă — autor, licență, categorii, ediție Rust, MSRV, URL depozit — făcând generarea structurii repetabilă și vizibilă în diff-urile Git.
  • Fluxul de lucru GitHub Actions generat de LibMake testează pe toolchains Rust stable, beta și nightly, impune clippy -D warnings, verifică rustfmt și rulează cargo-audit pentru CVE-uri cunoscute în arborele de dependențe.
  • Șabloanele Tera alimentează generarea codului: LibMake vine cu un set implicit de șabloane, dar acceptă un director de șabloane personalizat prin --template, astfel încât layout-urile de proiect nestandard și fișierele generate suplimentare sunt suportate fără a fork-ui instrumentul.

LibMake ⧉ este un instrument CLI și bibliotecă Rust cu sursă deschisă care generează o structură completă de proiect de bibliotecă dintr-o singură invocare. Vizează golul dintre cargo new --lib (care creează doar un Cargo.toml minim și src/lib.rs) și o configurare de bibliotecă pregătită pentru producție (care necesită adăugarea manuală a comentariilor de documentare, CI, harnessuri de testare, structura de benchmark, CONTRIBUTING.md și fișiere de licență).

Acest articol descrie ce generează LibMake, cum funcționează modurile fișier de configurare și CLI, structura CI generată și sistemul de șabloane.

Instalare și utilizare de bază #

LibMake este publicat pe crates.io și instalat prin Cargo:

cargo install libmake

Invocarea minimă CLI generează o bibliotecă numită în directorul curent:

libmake \
  --author "Jane Smith" \
  --email "jane@example.com" \
  --name "my_library" \
  --description "A Rust library for doing useful things" \
  --version "0.1.0" \
  --licence "MIT OR Apache-2.0" \
  --repository "https://github.com/example/my_library" \
  --rustversion "1.70.0" \
  --edition "2021" \
  --output "my_library"

Indicatoarele opționale suplimentare includ --categories, --keywords, --homepage, --documentation, --readme și --build.

Modul fișier de configurare #

Pentru utilizarea în echipă, toate indicatoarele CLI pot fi exprimate într-un fișier de configurare TOML:

# libmake.toml
author      = "Jane Smith"
email       = "jane@example.com"
name        = "my_library"
description = "A Rust library for doing useful things"
version     = "0.1.0"
licence     = "MIT OR Apache-2.0"
repository  = "https://github.com/example/my_library"
rustversion = "1.70.0"
edition     = "2021"
output      = "my_library"
categories  = ["algorithms", "data-structures"]
keywords    = ["rust", "library"]

Invocat ca:

libmake --config libmake.toml

LibMake acceptă, de asemenea, formatele de configurare JSON, YAML și CSV prin indicatoarele --config-json, --config-yaml și, respectiv, --config-csv. Adăugarea libmake.toml la rădăcina depozitului oferă fiecărui contribuitor o bază de structură reproductibilă, iar modificările la configurația șablonului sunt vizibile în diff-urile Git.

Structura proiectului generat #

O invocare LibMake creează următorul layout:

my_library/
├── .github/
│   └── workflows/
│       └── release.yml     # full CI matrix
├── benches/
│   └── lib_benchmarks.rs   # Criterion benchmark stub
├── src/
│   └── lib.rs              # doc-commented, deny(missing_docs)
├── tests/
│   └── lib_tests.rs        # integration test stub
├── CONTRIBUTING.md
├── Cargo.toml              # complete metadata
├── LICENSE-APACHE
├── LICENSE-MIT
└── README.md

src/lib.rs generat include un comentariu de documentare la nivel de crate, #![deny(missing_docs)], #![doc = include_str!("../README.md")] pentru a include README în rustdoc și un tip public stub cu un comentariu de documentare asociat. Aceste alegeri urmează cerința Rust API Guidelines ca toate elementele publice să aibă documentație.

benches/lib_benchmarks.rs generat folosește Criterion.rs și necesită adăugarea criterion ca dev-dependență, pe care LibMake o introduce automat în Cargo.toml.

Fluxul de lucru GitHub Actions CI #

.github/workflows/release.yml generat rulează cinci lucrări la fiecare push și pull request:

Lucrare Toolchain Ce verifică
test stable, beta, nightly (matrice) cargo test --all-features
clippy stable cargo clippy -- -D warnings
fmt stable cargo fmt --check
audit stable cargo audit (cargo-audit instalat în lucrare)
doc stable cargo doc --no-deps (eșuează la docuri lipsă)

Lucrarea nightly are continue-on-error: true, astfel încât o regresie nightly nu blochează îmbinările, în timp ce eșecul rămâne vizibil în rularea fluxului de lucru.

Șablonare cu Tera #

LibMake folosește motorul de șabloane Tera — o sintaxă asemănătoare Jinja2 pentru Rust — pentru a randa toate fișierele generate. Fiecare șablon primește structura completă de configurare ca context:

{{ name }}            → my_library
{{ author }}          → Jane Smith
{{ edition }}         → 2021
{{ description }}     → A Rust library for doing useful things

Directoarele de șabloane personalizate sunt suportate prin indicatorul --template:

libmake --config libmake.toml --template ./my_templates/

Directorul personalizat trebuie să oglindească structura implicită a șabloanelor (aceleași nume de fișiere). Orice fișier prezent în directorul personalizat suprascrie șablonul încorporat corespunzător; fișierele absente din directorul personalizat revin la versiunea încorporată. Aceasta permite suprascrieri parțiale — de exemplu, înlocuirea doar a șablonului fluxului de lucru CI, păstrând șabloanele implicite src/lib.rs și Cargo.toml.

Întrebări frecvente #

Cum diferă LibMake de cargo new --lib? cargo new --lib creează un proiect minimal cu doar Cargo.toml și src/lib.rs (conținând un singur bloc #[cfg(test)]). LibMake generează structura completă — teste de integrare, benchmark-uri, CI, CONTRIBUTING.md, fișiere de licență dublă și un src/lib.rs documentat corespunzător — configurat cu metadatele reale ale proiectului în loc de spații rezervate.

Poate fi utilizat LibMake cu un spațiu de lucru Cargo existent? LibMake generează un director de crate independent. Pentru a adăuga crate-ul generat la un spațiu de lucru existent, adăugați calea de ieșire la matricea members din Cargo.toml rădăcină. LibMake nu modifică fișierele de spațiu de lucru existente.

Pot actualiza șabloanele structurii după generarea inițială? LibMake generează fișiere o singură dată; nu urmărește sau actualizează proiectele generate anterior. Pentru a adopta șabloane actualizate, abordarea recomandată este să re-rulați LibMake într-un director temporar și să comparați rezultatul cu crate-ul existent, aplicând selectiv modificările dorite.

Ce ediții Rust și valori MSRV suportă LibMake? LibMake acceptă orice șir pentru --edition și --rustversion și scrie valorile direct în Cargo.toml. Nu validează dacă ediția sau MSRV specificat este o versiune Rust reală, astfel că apelatorii sunt responsabili pentru furnizarea valorilor corecte.

Referințe #

  1. Rousseau, S. LibMake — A code generator to reduce repetitive tasks and build high-quality Rust libraries. GitHub, 2023. https://github.com/sebastienrousseau/libmake
  2. The Rust Programming Language. Rust API Guidelines. GitHub, 2023. https://rust-lang.github.io/api-guidelines/
  3. The Cargo Book. Package Layout. The Rust Programming Language, 2023. https://doc.rust-lang.org/cargo/guide/project-layout.html
  4. Keats, V. et al. Tera — A template engine inspired by Jinja2 and Django templates. GitHub, 2023. https://keats.github.io/tera/

Ultima revizuire .

Ultima revizuire .