diff --git a/.github/workflows/template.yml b/.github/workflows/template.yml new file mode 100644 index 0000000..62ed463 --- /dev/null +++ b/.github/workflows/template.yml @@ -0,0 +1,42 @@ +name: Template + +on: + push: + branches: ["main"] + pull_request: + branches: ["main"] + workflow_dispatch: + +permissions: + contents: read + +# Cancel in-progress runs for the same branch/PR when new commits are pushed +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +env: + CARGO_TERM_COLOR: always + +jobs: + generate: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v7 + + # Installs the toolchain and components pinned in the template's rust-toolchain.toml + - name: Install Rust + working-directory: template + run: rustup toolchain install + + - name: Install just + uses: taiki-e/install-action@v2 + with: + tool: just + + - name: Install Copier + run: pipx install copier + + - name: Generate and test project + run: just test-template diff --git a/.gitignore b/.gitignore index 3dd439d..c94ab23 100644 --- a/.gitignore +++ b/.gitignore @@ -13,3 +13,7 @@ # Added by cargo /target + +# Claude + +.claude/ \ No newline at end of file diff --git a/Brewfile b/Brewfile index 7be69e6..628849b 100644 --- a/Brewfile +++ b/Brewfile @@ -1,12 +1,5 @@ -# Local macOS dev setup. Install with: brew bundle -# After installing, run `rustup default stable` once to download the toolchain. +# Local macOS setup for working on this template. Install with: brew bundle -# Rust toolchain manager (provides rustc, cargo, clippy, rustfmt) -brew "rustup" - -# Command runner for project scripts (see justfile) +# Project template tool (see copier.yml) +brew "copier" brew "just" - -# Dev tools -# brew "bacon" # background checker: re-runs clippy/tests on save -# brew "cargo-nextest" # faster test runner diff --git a/Cargo.lock b/Cargo.lock deleted file mode 100644 index a406adc..0000000 --- a/Cargo.lock +++ /dev/null @@ -1,7 +0,0 @@ -# This file is automatically @generated by Cargo. -# It is not intended for manual editing. -version = 4 - -[[package]] -name = "rust-template" -version = "0.1.0" diff --git a/README.md b/README.md index f7bef74..96101f2 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,13 @@ # rust-template -Rust Project Template +Rust project template for [Copier](https://copier.readthedocs.io/). -## Setup +## Usage -### macOS +- Create a new project - `copier copy gh:/rust-template path/to/new-project` +- Pull in template updates from inside a generated project - `copier update` -- Install Homebrew dependencies - `brew bundle` - - May require updating path - `export PATH="$(brew --prefix rustup)/bin:$HOME/.cargo/bin:$PATH"` - - Add it to `~/.zshrc` to make it permanent -- Install the Rust toolchain pinned in `rust-toolchain.toml` - `rustup toolchain install` -- Verify the setup - `just test` +## Layout -### Dev Container - -- Open the repo in VS Code and run **Dev Containers: Reopen in Container** - - Rust, `just`, and the recommended extensions are installed automatically - -## Project Commands - -Commands are defined in the `justfile` and run with [just](https://github.com/casey/just). - -- List available commands - `just` or `just help` -- Add rustup to PATH if missing and install the pinned toolchain - `just setup` -- Build the project - `just build` - - Pass extra flags - `just build --release` -- Run tests - `just test` - - Pass extra args - `just test greeting` -- Format all code - `just fmt` -- Check formatting and run clippy with warnings as errors - `just lint` +- `copier.yml` - template questions and settings +- `template/` - files rendered into new projects; files ending in `.jinja` are templated diff --git a/copier.yml b/copier.yml new file mode 100644 index 0000000..a1820e1 --- /dev/null +++ b/copier.yml @@ -0,0 +1,28 @@ +_min_copier_version: "9.0.0" +_subdirectory: template + +project_name: + type: str + help: Cargo package name (lowercase letters, digits, hyphens and underscores) + validator: >- + {% if not (project_name | regex_search('^[a-z][a-z0-9_-]*$')) %} + Must start with a lowercase letter and contain only lowercase letters, digits, hyphens and underscores + {% endif %} + +crate_name: + type: str + default: "{{ project_name | replace('-', '_') }}" + when: false + +description: + type: str + help: Short description of the project + default: "" + +author_name: + type: str + help: Name used in the LICENSE copyright line + +copyright_year: + type: str + help: Year used in the LICENSE copyright line diff --git a/justfile b/justfile index 321dbf0..1cc96d1 100644 --- a/justfile +++ b/justfile @@ -1,49 +1,20 @@ # List available recipes -help: +[private] +default: @just --list -# Add rustup to PATH if missing, then install the pinned toolchain -setup: +# Render the template into a temp directory, then lint and test the generated project +test-template: #!/usr/bin/env bash set -euo pipefail - # Homebrew links rustup but not the cargo/rustc proxies, so check for cargo - if ! command -v cargo >/dev/null; then - if ! command -v brew >/dev/null; then - echo "rustup not found. Install it with 'brew bundle' or from https://rustup.rs" >&2 - exit 1 - fi - rustup_bin="$(brew --prefix rustup)/bin" - if [ ! -x "$rustup_bin/rustup" ]; then - echo "rustup not installed. Run 'brew bundle' first." >&2 - exit 1 - fi - case "$(basename "${SHELL:-zsh}")" in - bash) rc="$HOME/.bash_profile" ;; - *) rc="$HOME/.zshrc" ;; - esac - if ! grep -qs 'brew --prefix rustup' "$rc"; then - echo 'export PATH="$(brew --prefix rustup)/bin:$HOME/.cargo/bin:$PATH"' >> "$rc" - echo "Added rustup to PATH in $rc. Restart your terminal or run: source $rc" - fi - export PATH="$rustup_bin:$HOME/.cargo/bin:$PATH" - fi - rustup toolchain install - rustc --version - cargo --version - -# Build the project (pass extra flags, e.g. `just build --release`) -build *args: - cargo build {{args}} - -# Run tests (pass extra args, e.g. `just test greeting`) -test *args: - cargo test {{args}} - -# Format all code -fmt: - cargo fmt --all - -# Check formatting and run clippy with warnings as errors -lint: - cargo fmt --all --check - cargo clippy --all-targets --all-features -- -D warnings + tmp="$(mktemp -d "${TMPDIR:-/tmp}/test-template.XXXXXX")" + trap 'rm -rf "$tmp"' EXIT + # -r HEAD renders the current checkout, including uncommitted changes + copier copy --defaults -r HEAD \ + -d project_name=test-project \ + -d author_name=Test \ + -d copyright_year={{ datetime("%Y") }} \ + "{{ justfile_directory() }}" "$tmp/test-project" + cd "$tmp/test-project" + just lint + just test diff --git a/src/main.rs b/src/main.rs deleted file mode 100644 index 6d59104..0000000 --- a/src/main.rs +++ /dev/null @@ -1,3 +0,0 @@ -fn main() { - println!("{}", rust_template::greeting()); -} diff --git a/.devcontainer/devcontainer.json b/template/.devcontainer/devcontainer.json similarity index 100% rename from .devcontainer/devcontainer.json rename to template/.devcontainer/devcontainer.json diff --git a/.github/workflows/rust.yml b/template/.github/workflows/rust.yml similarity index 100% rename from .github/workflows/rust.yml rename to template/.github/workflows/rust.yml diff --git a/template/.gitignore b/template/.gitignore new file mode 100644 index 0000000..3dd439d --- /dev/null +++ b/template/.gitignore @@ -0,0 +1,15 @@ +# Generated by Cargo +# will have compiled files and executables +/target/ + +# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries +# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html +# Cargo.lock + +# These are backup files generated by rustfmt +**/*.rs.bk + + +# Added by cargo + +/target diff --git a/template/Brewfile b/template/Brewfile new file mode 100644 index 0000000..378b003 --- /dev/null +++ b/template/Brewfile @@ -0,0 +1,15 @@ +# Local macOS dev setup. Install with: brew bundle +# After installing, run `rustup default stable` once to download the toolchain. + +# Rust toolchain manager (provides rustc, cargo, clippy, rustfmt) +brew "rustup" + +# Command runner for project scripts (see justfile) +brew "just" + +# Project template tool; run `copier update` to pull in template changes +brew "copier" + +# Dev tools +# brew "bacon" # background checker: re-runs clippy/tests on save +# brew "cargo-nextest" # faster test runner diff --git a/template/CLAUDE.md b/template/CLAUDE.md new file mode 100644 index 0000000..fb98913 --- /dev/null +++ b/template/CLAUDE.md @@ -0,0 +1,30 @@ +# CLAUDE.md + +Guidance for Claude Code when working in this repository. + +## Commands + +Run project tasks through `just` (see `justfile`) rather than calling `cargo` directly. On macOS, Homebrew's `rustup` is keg-only, so `cargo` may not be on the shell PATH; the `justfile` adds it for every recipe. + +- `just setup` - install Homebrew dependencies and the pinned toolchain +- `just build` - build (pass extra flags, e.g. `just build --release`) +- `just test` - run tests (pass a filter, e.g. `just test greeting`) +- `just fmt` - format all code +- `just lint` - check formatting and run clippy with warnings as errors + +Run `just fmt` and `just lint` after making changes; CI runs `just lint` and `just test` and fails on any warning. + +## Layout + +- `src/lib.rs` - library crate; put application logic here so it can be tested +- `src/main.rs` - thin binary entry point that calls into the library +- `tests/` - integration tests against the library's public API + +## Toolchain + +- The Rust version is pinned in `rust-toolchain.toml`; don't change it unless asked +- Edition 2024; minimum supported Rust version is set by `rust-version` in `Cargo.toml` + +## Template + +This project was generated from a Copier template. `.copier-answers.yml` is managed by Copier; don't edit it by hand. Template updates are pulled in with `copier update`. diff --git a/Cargo.toml b/template/Cargo.toml.jinja similarity index 50% rename from Cargo.toml rename to template/Cargo.toml.jinja index 18b691a..6b16710 100644 --- a/Cargo.toml +++ b/template/Cargo.toml.jinja @@ -1,8 +1,11 @@ [package] -name = "rust-template" +name = "{{ project_name }}" version = "0.1.0" edition = "2024" rust-version = "1.85" +{%- if description %} +description = "{{ description }}" +{%- endif %} license = "MIT" [dependencies] diff --git a/template/LICENSE.jinja b/template/LICENSE.jinja new file mode 100644 index 0000000..360dcee --- /dev/null +++ b/template/LICENSE.jinja @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) {{ copyright_year }} {{ author_name }} + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/template/README.md.jinja b/template/README.md.jinja new file mode 100644 index 0000000..386097a --- /dev/null +++ b/template/README.md.jinja @@ -0,0 +1,42 @@ +# {{ project_name }} + +{{ description }} + +## Setup + +### macOS + +- Install `just` - `brew install just` +- Install Homebrew dependencies and the Rust toolchain pinned in `rust-toolchain.toml` - `just setup` +- Verify the setup - `just test` + +Homebrew's `rustup` is keg-only, so `cargo` and `rustc` aren't on your shell PATH. The `justfile` adds them for every recipe, so use `just` commands rather than calling `cargo` directly. To use `cargo` in your shell, add this to `~/.zshrc`: + +```sh +export PATH="$(brew --prefix rustup)/bin:$PATH" +``` + +### Dev Container + +- Open the repo in VS Code and run **Dev Containers: Reopen in Container** + - Rust, `just`, and the recommended extensions are installed automatically + +## Project Commands + +Commands are defined in the `justfile` and run with [just](https://github.com/casey/just). + +- List available commands - `just` +- Install Homebrew dependencies and the pinned toolchain - `just setup` +- Build the project - `just build` + - Pass extra flags - `just build --release` +- Run tests - `just test` + - Pass extra args - `just test greeting` +- Format all code - `just fmt` +- Check formatting and run clippy with warnings as errors - `just lint` + +## Template + +This project was generated from a [Copier](https://copier.readthedocs.io/) template. + +- Pull in template updates - `copier update` +- Don't edit `.copier-answers.yml` by hand; Copier uses it to apply updates diff --git a/template/justfile b/template/justfile new file mode 100644 index 0000000..b0bd9b0 --- /dev/null +++ b/template/justfile @@ -0,0 +1,33 @@ +# List available recipes +[private] +default: + @just --list + +# Homebrew's rustup is keg-only, so neither rustup nor its cargo/rustc proxies +# are on PATH. Prepend its bin directory for all recipes when Homebrew is available. +rustup_prefix := `brew --prefix rustup 2>/dev/null || true` +export PATH := if rustup_prefix != "" { rustup_prefix / "bin" + ":" + env("PATH") } else { env("PATH") } + +# Install Homebrew dependencies and the pinned toolchain +setup: + brew bundle install + rustup toolchain install + rustc --version + cargo --version + +# Build the project (pass extra flags, e.g. `just build --release`) +build *args: + cargo build {{args}} + +# Run tests (pass extra args, e.g. `just test greeting`) +test *args: + cargo test {{args}} + +# Format all code +fmt: + cargo fmt --all + +# Check formatting and run clippy with warnings as errors +lint: + cargo fmt --all --check + cargo clippy --all-targets --all-features -- -D warnings diff --git a/rust-toolchain.toml b/template/rust-toolchain.toml similarity index 100% rename from rust-toolchain.toml rename to template/rust-toolchain.toml diff --git a/src/lib.rs b/template/src/lib.rs similarity index 100% rename from src/lib.rs rename to template/src/lib.rs diff --git a/template/src/main.rs.jinja b/template/src/main.rs.jinja new file mode 100644 index 0000000..0e6a302 --- /dev/null +++ b/template/src/main.rs.jinja @@ -0,0 +1,3 @@ +fn main() { + println!("{}", {{ crate_name }}::greeting()); +} diff --git a/tests/greeting.rs b/template/tests/greeting.rs.jinja similarity index 72% rename from tests/greeting.rs rename to template/tests/greeting.rs.jinja index 08648d5..5e76592 100644 --- a/tests/greeting.rs +++ b/template/tests/greeting.rs.jinja @@ -1,4 +1,4 @@ -use rust_template::greeting; +use {{ crate_name }}::greeting; #[test] fn greeting_says_hello() { diff --git a/template/{{ _copier_conf.answers_file }}.jinja b/template/{{ _copier_conf.answers_file }}.jinja new file mode 100644 index 0000000..3d2f8bf --- /dev/null +++ b/template/{{ _copier_conf.answers_file }}.jinja @@ -0,0 +1,2 @@ +# Changes here will be overwritten by Copier +{{ _copier_answers | to_nice_yaml -}}