rust_template

Rust Project Template

🚀 A production‑ready Rust project template to bootstrap new projects fast. It includes a clean Cargo layout, Docker, and a complete CI/CD suite.

Click Use this template to start a new repository from this scaffold.

Other Languages: English | 繁體中文 | 简体中文

🎯 Using This Template

IMPORTANT: This is a template repository. Before using it for your project, you must:

• Rename all occurrences of rust_template to your project name across the entire codebase
• Update metadata in Cargo.toml, cli/nodejs/package.json, and cli/python/pyproject.toml
• Update author information in all package manifests and Dockerfiles
• Update repository URLs in README badges, package manifests, and GitHub workflows
• Rename the Python package directory from cli/python/src/rust_template to your project name

For detailed step-by-step instructions, see .github/copilot-instructions.md.

Quick verification after setup:

grep -r "rust_template" . --exclude-dir=target --exclude-dir=.git  # Should find minimal matches
make fmt && cargo build && cargo test --all  # Verify everything works

✨ Highlights

• Modern Cargo layout (src/lib.rs, src/main.rs, tests/)
• Dynamic version information with git metadata (tag, commit hash, build tools)
• Lint & format with clippy and rustfmt
• GitHub Actions: tests, quality, package build, Docker publish, release drafter, Rust-aware labeler, secret scans, semantic PR, weekly dependency update
• Multi-stage Dockerfile producing a minimal runtime image

🚀 Quick Start

Requirements:

• Rust 1.85 or higher (using Edition 2024)
• Docker (optional)

Install Rust via rustup if you haven't already.

make fmt            # rustfmt + clippy
make test           # cargo test (all targets)
make test-verbose   # cargo test (all targets with verbose output)
make coverage       # generate LCOV coverage report
make build          # cargo build (release mode)
make build-release  # cargo build --release
make run            # run the release binary
make clean          # clean build artifacts and caches
make package        # build crate package (allow dirty)
make help           # list targets

📌 Version Information

The binary automatically displays dynamic version information including:

• Git tag version (or Cargo.toml version if no tags)
• Commit count since last tag
• Short commit hash
• Dirty working directory indicator
• Rust and Cargo versions used for building

Example output:

rust_template v0.1.25-2-gf4ae332-dirty
Built with Rust 1.90.0 and Cargo 1.90.0

This version information is embedded at build time through build.rs and automatically updated based on your git state.

🐳 Docker

docker build -f docker/Dockerfile --target prod -t ghcr.io/<owner>/<repo>:latest .
docker run --rm ghcr.io/<owner>/<repo>:latest

Or using the actual binary name:

docker build -f docker/Dockerfile --target prod -t rust_template:latest .
docker run --rm rust_template:latest

📦 Packaging

make package        # build crate package (allow dirty)
# or use cargo directly:
cargo package --locked --allow-dirty
# CARGO_REGISTRY_TOKEN=... cargo publish

CI builds run automatically on tags matching v* and upload the .crate file. Uncomment the publish step in build_package.yml to automate crates.io releases.

🧩 Cross Builds

This template does not ship cross-compile tooling by default. If you need cross or zig-based builds locally, install and configure them per your environment.

GitHub Actions build_release.yml builds multi-platform release binaries on tags matching v* and uploads them to the GitHub Release assets.

Targets:

• x86_64-unknown-linux-gnu, x86_64-unknown-linux-musl
• aarch64-unknown-linux-gnu, aarch64-unknown-linux-musl
• x86_64-apple-darwin, aarch64-apple-darwin
• x86_64-pc-windows-msvc, aarch64-pc-windows-msvc

Assets naming:

• <bin>-v<version>-<target>.tar.gz (all platforms)
• <bin>-v<version>-<target>.zip (Windows additionally)

🔁 CI/CD Workflows

Main Workflows

• Tests (test.yml): cargo build/test + generate LCOV coverage report and upload artifact
• Code Quality (code-quality-check.yml): rustfmt check + clippy (deny warnings)
• Build Package (build_package.yml): package on tag v*, optional crates.io publish
• Publish Docker Image (build_image.yml): push to GHCR on main/master and tags v*
• Build Release (build_release.yml): Linux release binaries uploaded on tags v*

Additional Automation

• Auto Labeler (auto_labeler.yml): automatically label PRs based on branch names and file changes
• Code Scan (code_scan.yml): multi-layer security scanning (GitLeaks, Trufflehog secret scanning, CodeQL code analysis, Trivy vulnerability scanning)
• Release Drafter (release_drafter.yml): auto-generate release notes
• Semantic PR (semantic-pull-request.yml): enforce PR title format
• Dependabot weekly dependency updates

🤝 Contributing

• Open issues/PRs

• Use Conventional Commits for PR titles

• Keep code formatted and clippy‑clean

• After every edit, run cargo build to confirm compilation is successful

• Before opening a PR, please run locally:

  • cargo fmt --all -- --check
  • cargo clippy --all-targets --all-features -- -D warnings
  • cargo test

📄 License

MIT — see LICENSE.