cooperwalbrun/rust-template

A project template suitable for new Rust 2021 Edition projects with cargo-make/rustfmt/rust-clippy.

rust-template

1. Checklist
2. Overview
3. Contributing

Checklist

Did you just clone this repository? Here is a checklist of things you should change before you start developing!

1. Determine whether to delete the Cargo.lock file and add an entry for it to the .gitignore. The decision to do this will depend on your project's dependency management needs. Refer to this section of the Rust FAQs for more information about the benefits and drawbacks of making this change.
2. Rename src/main.rs to src/lib.rs (and remove the main function) if your project will not be an executable binary. Likewise, be sure to remove all mentions of run command(s) from the CONTRIBUTING.md and Makefile.toml files.
3. Update other files according to your project's needs (e.g. Cargo.toml, README.md, CODEOWNERS, etc).

Overview

This is a template repository. It comes with support for the following:

• Support for all the items below on both Windows and Linux
• Linting via rust-clippy
• Formatting via rustfmt
• Unit testing
• Code coverage analysis and "pretty" coverage reporting via cargo-llvm-cov
• Orchestration of all of the above via cargo-make (see CONTRIBUTING.md for details)

This repository also includes other features which are not necessarily specific to Rust, but they have been added for demonstrative purposes:

• Sample Codecov configuration
• Execution of unit testing-, code coverage-, and Codecov-oriented tasks in an automated fashion via GitHub Actions workflows

Contributing

See CONTRIBUTING.md for developer-oriented information.

rust-template's Issues

Use Miri during Testing and Running

See https://github.com/rust-lang/miri.

Tasks

• Update Makefile.toml to install Miri and use it for the test and run commands
• Using Miri means that this template will continue to depend on the nightly toolchain, regardless of #4
• Evaluate current environment variable setup: should RUST_BACKTRACE be set?
• Mention Miri in CONTRIBUTING.md

Add GitHub Actions Worfklows

This project should showcase some workflows for GitHub Actions for each of the following circumstances:

• Pull requests
• Master branch push
• New tag pushed Update: this is better left for end users to determine as not all projects will use a tag-driven workflow

Rust API Guidelines

Add a link/reference to the Rust API Guidelines somewhere in the README.md. This is an important document to be aware of for all new Rust applications.

instrument-coverage Stabilization

Refer to rust-lang/rust#90132.

Once instrument-coverage becomes available under the -C switch:

• Update this template's documentation to no longer indicate a dependency on the nightly toolchain Update: with the merge of #7, the nightly toolchain documentation should only be updated to exclude a mention of code coverage; nightly is now needed for Miri
• Update this template's configuration to use -C instead of -Z

Code Coverage Consistency between Linux and Windows

I noticed that the code coverage report is not equivalent between Linux (ubuntu-latest, i.e. the GitHub Actions environment) and Windows (my machine, i.e. Windows 10). Below, you will see the difference between the two (output generated using cargo make test-coverage).

Windows

Filename	Regions	Missed Regions	Cover	Functions	Missed Functions	Executed	Lines	Missed Lines	Cover	Branches	Missed Branches	Cover
src/main.rs	5	1	80.00%	4	1	75.00%	8	3	62.50%	0	0	-
TOTAL	5	1	80.00%	4	1	75.00%	8	3	62.50%	0	0	-

Linux

Filename	Regions	Missed Regions	Cover	Functions	Missed Functions	Executed	Lines	Missed Lines	Cover	Branches	Missed Branches	Cover
src/main.rs	5	5	0.00%	4	4	0.00%	8	8	0.00%	0	0	-
TOTAL	5	5	0.00%	4	4	0.00%	8	8	0.00%	0	0	-

Details

For reference, the approach taken to gather coverage/profiling data is documented here in the rustc book. There are two scripts in the repository for facilitating the jq and llvm-cov/cargo cov parts of the workflow (one for Linux, one for Windows) but these scripts should have no bearing on the coverage reporting discrepancies. I believe it has to do with how the code gets instrumented, or how the profiler analyzes the code.

Based on the tables above, on Windows it appears that the tooling believes our assert_eq!(true, true) test is actually hitting some part of the (very trivial) main(). Currently, I am not sure I understand why this is the case. To be honest, the numbers generally confound me, as the report claims that there are 5 functions, when the only thing that exists in our program is a one-line main()...

Anyway, I will do more research/investigation and comment on this issue with my findings.

Implement an Integration with Codecov

In order to implement an integration with Codecov, this project will need the necessary YAML configuration as well as a way to generate the XML (a.k.a. Cobertura format) code coverage report.

This issue depends directly on taiki-e/cargo-llvm-cov#106.