rust_lib_example 0.1.0

Rust project example
Documentation

Example of Rust project

Crates.io Docs.rs License CI Coverage with grcov Mutation tested with mutagen Lines of code

Purpose

This repository contains an example of Rust project structure.

Most of the components can be reusable in your own projects:

  • Project configuration
  • CI workflow to build, lint, test, check test coverage and run mutation tests
  • CD workflow to test on all platforms and publish on crates.io

Github Actions workflows

Jobs

The CI workflow is triggered for any commit or pull request on the develop branch and runs the following jobs:

  • Test the crate
    • Build the project for all targets and with default features to ensure everything compiles
    • Run unit, integration and doc tests with default features
  • Run test coverage and mutation tests
    • Run source-based coverage with grcov
    • Upload HTML coverage report in workflow artifacts
    • Upload HTML coverage report on Codecov
    • Fail if the coverage threshold is not reached
    • Run mutation tests with mutagen (note that the job automatically adds #[mutate] annotations)
    • Fail if the mutation threshold is not reached
  • Run several code checks
    • Run clippy
    • Run rustfmt to check code is correctly formatted
    • Run cargo-deny to check dependencies
    • Check encoding of all files is UTF-8
    • Check all line endings are LF
    • Check there is no TODO left in Rust code

This workflow is only run on Ubuntu virtual environment.

The CD workflow is triggered by a push in the main branch and runs the following jobs:

  • Check release name from CHANGELOG.md file
  • Test on Ubuntu
  • Test on Windows
  • Test on MacOS
  • Make a publication dry run on crates.io
  • Publish on crates.io
  • Create tag and Github release using first entry in CHANGELOG.md file

Secrets

The CD workflow requires a secret named CRATES_IO_TOKEN to be able to publish the crate(s). This secret must be stored in a repository environment called Deployment.

Settings

Settings of the CI workflow can be modified in the file .github/workflows/ci.yml, in the env section:

  • RUST_VERSION_STABLE: version of the stable Rust compiler to use
  • RUST_VERSION_NIGHTLY: version of the nightly Rust compiler to use when required
  • MUTAGEN_COMMIT: commit of the mutagen version to install (from mutagen repository)
  • COV_THRESHOLD: minimum threshold the coverage must reached to succeed the job
  • MUTAGEN_THRESHOLD: minimum threshold the mutation tests must reached to succeed the job
  • CRATE_PATHS: package names separated by ; in publication order if the repository is a Cargo workspace, else .

Settings of the CD workflow can be modified in the file .github/workflows/cd.yml, in the env section:

  • RUST_VERSION_STABLE: version of the stable Rust compiler to use
  • CRATE_PATHS: package names separated by ; in publication order if the repository is a Cargo workspace, else .

Export

You can use the workflows for your own project by copying the folder .github/workflows.

Run locally

act can be used to run the workflows on your own machine. Once installed, run act -P ubuntu-18.04=nektos/act-environments-ubuntu:18.04 in the repository folder to run all supported jobs.

Workspaces

This repository contains a single crate, but the workflows should also work with a Cargo workspace.

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.