Skip to content

FAQ.md

Latest commit

 

History

History
360 lines (237 loc) · 8.93 KB

FAQ.md

File metadata and controls

360 lines (237 loc) · 8.93 KB

Cargo-Forge - Frequently Asked Questions

General Questions

What is Cargo-Forge?

Cargo-Forge is an interactive, intelligent Rust project generator that creates production-ready project structures with best practices, optional features, and comprehensive tooling setup. It's designed to get you from idea to implementation faster than traditional boilerplate approaches.

How does Cargo-Forge differ from cargo-generate?

While both tools generate Rust projects from templates, Cargo-Forge offers several unique advantages:

  • Interactive TUI: Beautiful terminal interface for selecting options
  • Intelligent defaults: Smart suggestions based on project type
  • Validated combinations: Ensures selected features work together
  • Built-in templates: No need to find external template repositories
  • Feature integration: Seamlessly combines multiple features (auth, database, CI)
  • Dry-run mode: Preview what will be generated before creation

Is Cargo-Forge free to use?

Yes! Cargo-Forge is completely free and open source under the MIT/Apache-2.0 dual license. There are no paid tiers or premium features - everything is available to everyone.

What are the system requirements?

  • Rust 1.70.0 or later
  • Cargo (comes with Rust)
  • Git (optional but recommended)
  • OS: Windows, macOS, or Linux

Installation & Setup

How do I install Cargo-Forge?

cargo install cargo-forge

That's it! The command will be available as cargo-forge.

Can I install from source?

Yes, you can build from source:

git clone https://github.com/marcuspat/cargo-forge
cd cargo-forge
cargo install --path .

How do I update Cargo-Forge?

cargo install cargo-forge --force

Can I use Cargo-Forge without installing it?

Yes, using cargo-run:

cargo run --git https://github.com/marcuspat/cargo-forge -- new my-project

Usage Questions

How do I create a new project?

The simplest way is to run:

cargo-forge new

This starts the interactive mode where you can choose all options step by step.

Can I use Cargo-Forge in CI/CD pipelines?

Yes! Use the --non-interactive flag:

cargo-forge new my-project --project-type api-server --non-interactive

This uses sensible defaults without prompting for input.

How do I save my preferences?

Create a configuration file at ~/.config/cargo-forge/config.toml:

[defaults]
author = "Your Name"
license = "MIT"
always_add_ci = true

Can I preview what will be generated?

Yes, use the --dry-run flag:

cargo-forge new my-project --dry-run

This shows what would be created without actually generating files.

How do I use Cargo-Forge with existing projects?

Use the init command in your project directory:

cd existing-project
cargo-forge init --project-type library

Project Types

Which project type should I choose?

  • cli-tool: For command-line applications and developer tools
  • library: For reusable Rust crates
  • api-server: For REST APIs and web services
  • wasm-app: For browser-based applications
  • game-engine: For game development with Bevy
  • embedded: For microcontroller/IoT projects
  • workspace: For multi-crate projects

Can I change project type after generation?

Not automatically, but you can:

  1. Generate a new project with the desired type
  2. Copy your existing code over
  3. Or manually add the required dependencies and structure

Can I combine multiple project types?

Yes, use the workspace project type to combine multiple crates with different purposes in a single repository.

Features & Customization

What features can I add to my project?

Common features include:

  • Authentication: JWT, OAuth, password-based
  • Database: PostgreSQL, MySQL, SQLite
  • CI/CD: GitHub Actions, GitLab CI
  • Docker: Containerization support
  • Testing: Property tests, benchmarks, E2E tests

Can I add features after project creation?

Currently, features must be selected during generation. We're working on a cargo-forge add-feature command for future releases.

How do I create custom templates?

While Cargo-Forge uses built-in templates, you can:

  1. Fork the repository
  2. Modify templates in the templates/ directory
  3. Build and use your custom version

Can I disable certain files from being generated?

Not directly, but you can:

  • Use --dry-run to preview
  • Delete unwanted files after generation
  • Submit a feature request for more granular control

Technical Questions

What template engine does Cargo-Forge use?

Cargo-Forge uses Tera, a Jinja2-like template engine for Rust.

How are templates packaged?

Templates are embedded in the binary using include_dir!, making Cargo-Forge a single self-contained executable.

Can I use environment variables in templates?

Not directly in templates, but you can pass values through the CLI:

cargo-forge new my-project --author "$USER"

Does Cargo-Forge support Windows paths?

Yes, Cargo-Forge automatically handles path conversions across platforms.

Troubleshooting

Why does project generation fail?

Common reasons:

  1. Invalid project name (must be valid Rust identifier)
  2. Directory already exists
  3. No write permissions
  4. Disk space issues

Why are my templates not rendering correctly?

Check for:

  • Typos in variable names
  • Missing .tera extension
  • Incorrect conditional syntax
  • Special characters in input values

How do I debug template issues?

Enable debug logging:

RUST_LOG=debug cargo-forge new my-project

Where are the error logs?

Cargo-Forge outputs errors directly to stderr. Capture them with:

cargo-forge new my-project 2> error.log

Best Practices

Should I commit generated files to version control?

Yes! Commit all generated files so other developers can:

  • See the complete project structure
  • Build without running Cargo-Forge
  • Track changes over time

How often should I update project dependencies?

After generation:

  1. Run cargo update monthly
  2. Use cargo audit for security updates
  3. Test thoroughly after updates

Should I modify generated files?

Absolutely! Generated files are just a starting point. Modify them to fit your needs - that's the whole point!

What's the recommended workflow?

  1. Run cargo-forge new interactively
  2. Review generated files
  3. Run tests to ensure everything works
  4. Start implementing your features
  5. Keep the README updated

Contributing

How can I contribute to Cargo-Forge?

We welcome contributions! See CONTRIBUTING.md for:

  • Code contributions
  • Template improvements
  • Documentation updates
  • Bug reports
  • Feature requests

Where do I report bugs?

Use the GitHub issue tracker with:

  • Clear description
  • Steps to reproduce
  • Expected vs actual behavior
  • System information

Can I add new project types?

Yes! New project types are welcome. See the contributing guide for details on adding project types.

How do I suggest new features?

Open a discussion on GitHub Discussions or create a feature request issue.

Advanced Usage

Can I script Cargo-Forge?

Yes, Cargo-Forge is designed to be scriptable:

#!/bin/bash
for proj in api cli lib; do
  cargo-forge new "$proj-service" \
    --project-type "$proj" \
    --non-interactive
done

How do I integrate with other tools?

Cargo-Forge generates standard Rust projects that work with:

  • cargo-watch
  • cargo-release
  • cargo-audit
  • rust-analyzer
  • Any Cargo subcommand

Can I use custom registries?

Yes, modify the generated Cargo.toml:

[registries]
my-registry = { index = "https://my-registry.com/index" }

Is there an API or library interface?

Currently, Cargo-Forge is CLI-only. A library API is planned for future releases.

Future Plans

What features are planned?

Upcoming features include:

  • Plugin system for custom generators
  • Web interface option
  • More project types (GraphQL, gRPC)
  • Template marketplace
  • Project update/migration commands

When will X feature be available?

Check the roadmap for planned features and timelines.

How can I stay updated?

  • Watch the GitHub repository
  • Join our Discord server
  • Follow the blog
  • Subscribe to release notifications

More Help

Where can I get more help?

Is there commercial support available?

Cargo-Forge is open source software.

How do I become a Cargo-Forge expert?

  1. Read all documentation
  2. Try each project type
  3. Experiment with features
  4. Contribute to the project
  5. Help others in the community

Don't see your question? Open a discussion on GitHub!