Rust Project Template

A production-ready Rust project template with interactive CLI initialization.

Features

• 🎨 Interactive Setup - Beautiful CLI wizard guides you through project configuration
• 🦀 Rust Best Practices - Pre-configured Cargo.toml with proper metadata
• 📝 Auto-Generated Docs - README, LICENSE, and AUTHORS files created automatically
• 🔧 Flexible Project Types - Support for library, binary, or both
• 📦 Git Integration - Optional git initialization with first commit
• ✅ Cargo Validation - Automatic cargo check after setup
• 🎯 Clean Structure - Well-organized directory layout

Quick Start

1. Clone the Template

git clone https://github.com/GafelSon/template-rs.git my-project
cd my-project

2. Run Setup Script

bash setup.sh

Or manually:

python3 init.py

3. Follow the Interactive Prompts

The initializer will ask you for:

• Project name - Your project's name (e.g., my-awesome-tool)
• Crate name - Rust crate name (defaults to project name with underscores)
• Version - Semantic version (default: 0.1.0)
• Author - Your name and email (auto-detected from git config)
• Description - Brief description of your project
• License - Choose from MIT, Apache-2.0, GPL-3.0, BSD-3-Clause, MPL-2.0
• Repository - GitHub/GitLab repository URL
• Keywords - Comma-separated keywords for crates.io
• Categories - Select from predefined Rust categories
• Project type:
  • 1 - Library only (lib.rs)
  • 2 - Binary only (main.rs)
  • 3 - Both library and binary

4. Start Coding

cd sources
cargo build
cargo test
cargo run  # if binary type

Project Structure

template-rs/
├── .gitignore           # Git ignore rules
├── README.md            # Generated project documentation
├── LICENSE              # Generated license file
├── AUTHORS              # Generated authors file
├── BEDEL                # Notes and reflections space
├── CHANGELOG            # Project changelog (use logcast.py)
├── TODO                 # Project task tracking
├── init.py              # Interactive project initializer
├── setup.sh             # Quick setup script
├── logcast.py           # Git log to changelog converter
├── docs/
│   ├── _site/           # Generated documentation site
│   └── wiki.md          # Project wiki
└── sources/             # Rust project directory
    ├── Cargo.toml       # Generated Rust manifest
    ├── src/
    │   ├── lib.rs       # Library entry point (if type: lib/both)
    │   └── main.rs      # Binary entry point (if type: bin/both)
    ├── lib/             # Additional library modules
    ├── man/             # Man pages
    └── unit-tests/      # Unit tests

What Gets Generated

After Running init.py:

In project root:

• README.md - Complete project documentation with badges
• LICENSE - Full license text based on your selection
• AUTHORS - Author and contributor information
• .git/ - Git repository (if you chose to initialize)

In sources/ directory:

• Cargo.toml - Complete Rust manifest with all metadata
• src/lib.rs - Library template (if library type)
• src/main.rs - Binary with "Hello Gafelson!" (if binary type)

Usage Examples

Example 1: Creating a CLI Tool

python3 init.py
# Project name: my-cli-tool
# Type: 2 (binary)
# ... answer prompts ...

cd sources
cargo run
# Output: Hello Gafelson!

Example 2: Creating a Library

python3 init.py
# Project name: awesome-lib
# Type: 1 (library)
# ... answer prompts ...

cd sources
cargo build
cargo test

Example 3: Both Library and Binary

python3 init.py
# Project name: my-app
# Type: 3 (both)
# ... answer prompts ...

cd sources
cargo build --lib      # Build library
cargo build --bin      # Build binary
cargo run              # Run binary

Additional Tools

logcast.py - Changelog Generator

Converts git commit history into a formatted changelog:

./logcast.py
# Generates ChangeLog file from git history

Project Files

• BEDEL - Document your thoughts, inspirations, and reflections
• TODO - Track project tasks and priorities
• CHANGELOG - Maintain version history

Configuration

Git Configuration

The initializer auto-detects git user info:

git config --global user.name "Your Name"
git config --global user.email "your@email.com"

Python Requirements

• Python 3.6 or higher
• No external dependencies (uses only standard library)

Rust Requirements

• Rust 1.70.0 or higher (edition 2021)
• Cargo (comes with Rust)

Project Types Explained

Library (lib)

• Creates lib.rs with module structure template
• No [[bin]] section in Cargo.toml
• Use for reusable libraries published to crates.io

Binary (bin)

• Creates main.rs with simple "Hello Gafelson!" example
• Includes [[bin]] section in Cargo.toml
• Use for executable applications/CLI tools

Both (both)

• Creates both lib.rs and main.rs
• Library can be used as dependency
• Binary can use the library and provide CLI interface

Customization

Modifying Templates

Edit init.py to customize generated files:

• write_cargo() - Modify Cargo.toml template
• write_src() - Customize source file templates
• write_readme() - Change README structure
• write_license() - Add more license options

Adding Categories

Edit the cats list in init.py:

cats = [
    "cli",
    "web",
    # Add your categories here
]

Tips & Best Practices

1. Use Meaningful Names - Project names should be descriptive and follow Rust conventions
2. Choose Right Type - Use lib for libraries, bin for executables, both for apps with library API
3. Add Keywords - Help others discover your crate on crates.io
4. Pick Appropriate License - MIT/Apache-2.0 are common for open source Rust projects
5. Update CHANGELOG - Use logcast.py or manually maintain version history
6. Track Tasks - Use the TODO file to organize development priorities

Publishing to GitHub

# Template is already initialized with git
git remote add origin https://github.com/yourusername/your-project.git
git push -u origin main

Publishing to crates.io

cd sources
cargo login
cargo publish

Troubleshooting

"No such file or directory: src/main.rs"

You selected library type but Cargo.toml has [[bin]] section. Run init.py again and choose the correct project type.

Git initialization failed

Ensure git is installed and configured:

git --version
git config --list

Cargo check fails

Make sure you're in the sources/ directory:

cd sources
cargo check

License

This template itself is released to the public domain. Generated projects use the license you select during initialization.

Author

Soheil Fouladvandi <@gafelson>

Contributing

Contributions welcome! Feel free to:

• Report bugs
• Suggest features
• Submit pull requests
• Improve documentation

---

Made with ❤️ for the Rust community