Starting Point for Rust projects. Feel free to adapt as needed.
One will notice the lack of any Rust code in this template. That is intentional. This is why the CI badge up above is red. This is a collection of supporting files that I find useful beyond what is provided by cargo init. Rather than try to replace what it does, I just wanted a way to add the things that I find useful.
This template is designed to be cruel to be kind in the right measure.
You can see an example of it in use at devplaybooks/rust_blank_example.
- Use the template. (Note that your first build will fail because there is no code yet.)
- Check out your new repo locally.
- Navigate into the repo
- Run cargo init
- If you want a library instead of an executable, run
cargo init --lib
- If you want a library instead of an executable, run
- Choice of licenses:
- .rustfmt.toml file
- GitHub CI Actions
- GitHub VSCode Dev Container that also acts as an online GitHub Codespace courtesy of codespaces-examples
I've added all the licenses I generally use for maximum flexibility.
My version of Robbepop's .rustfmt.toml file.
It allows you to customize how the rstfmt cargo command does its job. In my case, that means changing the max width of a file from 80 characters to 100:
# Ideal width of each line.
# Default: 80
max_width = 100
David Tolnay's Rust Toolchain GitHub Action
I've been a big fan of svartalf's actions-rs libraries, but it doesn't seem to be maintained, and I'm getting warnings now from GitHub, so I'm switching. It's surprisingly simple and flexible.
This workflow contains a cron schedule to run every 1st day of the month. Note that GitHub says that it will disable scheduled workflows on forked repos or if there has been no activity in 60 days.
If you're not familiar with GitHub Actions, I recommend that you check them out.
.github/workflows/CI.yaml contains the following jobs:
test
Tests the code against Rust's stable, beta, and nightly channels, as well as the 1.72.1 release of Rust.
clippy
I like my Clippy lints to be dialed up to 11, so it's configured at the pedantic level. Feel free to dial it down as you see fit.
Note that if you don't add #![warn(clippy::pedantic)] at the beginning of your
crate, Clippy will pass locally, but fail when you push. For example:
#![warn(clippy::pedantic)]
fn main() {
println!("Hello, world!");
}fmt
Fails the build if the developer didn't run rustfmt against the build.
miri
I had never heard of Miri before I saw it in this example, but it looks interesting, so why not?
Miri is a heavy test, so it may be wise to remove it.
outdated
Runs the outdated cargo subcommand against the repo. Fails the build if you have any outdated dependencies in your project. If you keep the cron schedule, it will check every month to see if any of your dependencies are outdated.