Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 42 additions & 0 deletions .github/workflows/template.yml
Original file line number Diff line number Diff line change
@@ -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
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -13,3 +13,7 @@
# Added by cargo

/target

# Claude

.claude/
13 changes: 3 additions & 10 deletions Brewfile
Original file line number Diff line number Diff line change
@@ -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
7 changes: 0 additions & 7 deletions Cargo.lock

This file was deleted.

32 changes: 7 additions & 25 deletions README.md
Original file line number Diff line number Diff line change
@@ -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:<owner>/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
28 changes: 28 additions & 0 deletions copier.yml
Original file line number Diff line number Diff line change
@@ -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
59 changes: 15 additions & 44 deletions justfile
Original file line number Diff line number Diff line change
@@ -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
3 changes: 0 additions & 3 deletions src/main.rs

This file was deleted.

File renamed without changes.
15 changes: 15 additions & 0 deletions template/.gitignore
Original file line number Diff line number Diff line change
@@ -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
15 changes: 15 additions & 0 deletions template/Brewfile
Original file line number Diff line number Diff line change
@@ -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
30 changes: 30 additions & 0 deletions template/CLAUDE.md
Original file line number Diff line number Diff line change
@@ -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`.
5 changes: 4 additions & 1 deletion Cargo.toml → template/Cargo.toml.jinja
Original file line number Diff line number Diff line change
@@ -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]
21 changes: 21 additions & 0 deletions template/LICENSE.jinja
Original file line number Diff line number Diff line change
@@ -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.
42 changes: 42 additions & 0 deletions template/README.md.jinja
Original file line number Diff line number Diff line change
@@ -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
33 changes: 33 additions & 0 deletions template/justfile
Original file line number Diff line number Diff line change
@@ -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
File renamed without changes.
File renamed without changes.
3 changes: 3 additions & 0 deletions template/src/main.rs.jinja
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
fn main() {
println!("{}", {{ crate_name }}::greeting());
}
2 changes: 1 addition & 1 deletion tests/greeting.rs → template/tests/greeting.rs.jinja
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
use rust_template::greeting;
use {{ crate_name }}::greeting;

#[test]
fn greeting_says_hello() {
Expand Down
Loading
Loading