Add cargo-make with the ability to run code coverage locally (#291)

This adds cargo-make as a dependency for the project, and allows for
running commands locally from a central location.

.github/workflows/test.yaml

@@ -52,7 +52,25 @@ jobs:
           RUSTFLAGS: '-Zinstrument-coverage'
       - name: Run grcov
         if: matrix.rust-version == 'nightly' && matrix.cargo-args == '--all-features'
-        run: grcov . --binary-path target/debug/deps/ -s . -t lcov --branch --ignore-not-existing --ignore '../**' --ignore '/*' -o coverage.lcov
+        # Important! Keep in grcov flags in sync with Makefile.internal.toml.
+        run: >
+          grcov .
+          --binary-path target/debug/deps/
+          --source-dir  .
+          --branch
+          --ignore-not-existing
+          --ignore        '../**'
+          --ignore        '/*'
+          --ignore        'fluent-testing/*'
+          --ignore        'fluent-syntax/src/bin/*'
+          --output-type   'lcov'
+          --output-path   'coverage.lcov'
+          --excl-start    '^#\[cfg\(test\)\]|^// coverage\(off\)'
+          --excl-br-start '^#\[cfg\(test\)\]|^// coverage\(off\)'
+          --excl-stop     '^// coverage\(on\)'
+          --excl-br-stop  '^// coverage\(on\)'
+          --excl-line     '\#\[derive\(|// cov\(skip\)'
+          --excl-br-line  '\#\[derive\(|// cov\(skip\)'
       - name: Coveralls upload
         if: matrix.rust-version == 'nightly' && matrix.cargo-args == '--all-features'
         uses: coverallsapp/github-action@master

.gitignore

@@ -3,3 +3,4 @@
 **/*.rs.bk
 Cargo.lock
 .DS_Store
+coverage

Makefile.internal.toml

@@ -0,0 +1,63 @@
+[tasks.clean]
+command = "cargo"
+args = ["clean"]
+workspace = false
+
+[tasks.install-grcov]
+command = "cargo"
+args = ["install", "grcov"]
+workspace = false
+
+[tasks.install-llvm]
+command = "rustup"
+args = ["component", "add", "llvm-tools-preview"]
+workspace = false
+
+# This actually runs the tests and generates the .profraw file.
+[tasks.coverage-run-tests]
+workspace = false
+command = "cargo"
+args = ["test", "--all-features"]
+# toolchain = "nightly"
+env = { RUSTFLAGS = "-Cinstrument-coverage", RUSTDOCFLAGS = "-Cinstrument-coverage", LLVM_PROFILE_FILE = "llvm_profile-%p-%m.profraw" }
+
+# After generating the .profraw, this step creates the html report.
+# Important! Keep in grcov flags in sync with Makefile.internal.toml.
+[tasks.coverage-run-grcov]
+workspace = false
+command = "grcov"
+args = [
+  ".",
+  "--binary-path", "target/debug/deps/",
+  "--source-dir", ".",
+  "--branch", # Enables parsing branch coverage information
+  "--ignore-not-existing",
+  "--ignore",        "fluent-testing/*", # Test-only fixtures.
+  "--ignore",        "fluent-syntax/src/bin/*", # Small binary utility that doesn't require testing.
+  "--output-type",   "html",
+  "--output-path",   "coverage",
+  "--excl-start",    "^#\\[cfg\\(test\\)\\]|^// coverage\\(off\\)",
+  "--excl-br-start", "^#\\[cfg\\(test\\)\\]|^// coverage\\(off\\)",
+  "--excl-stop",     "^// coverage\\(on\\)",
+  "--excl-br-stop",  "^// coverage\\(on\\)",
+  "--excl-line",     "\\#\\[derive\\(|// cov\\(skip\\)",
+  "--excl-br-line",  "\\#\\[derive\\(|// cov\\(skip\\)",
+]
+env = { LLVM_PROFILE_FILE = "llvm_profile-%p-%m.profraw" }
+
+# Cleans up all of the .profraw files left over after running -C instrument-coverage
+[tasks.coverage-clean-profraw]
+workspace = false
+command = "find"
+args = [
+  ".",
+  "-name", "*.profraw",
+  "-maxdepth", "2",
+  "-delete"
+]
+
+# Notify the user the report is ready.
+[tasks.coverage-notify-completed]
+workspace = false
+command = "echo"
+args = ["\nThe coverage report is ready:\n./coverage\n"]

Makefile.toml

@@ -0,0 +1,34 @@
+# This file includes all of the documented and runnable commands.
+# See the Makefile.internal.toml for the internal implementation details of the commands.
+
+# Command implementation details:
+extend = "./Makefile.internal.toml"
+
+[env]
+CARGO_MAKE_EXTEND_WORKSPACE_MAKEFILE = true
+
+# Run all of the tests in all of the packages.
+[tasks.test]
+command = "cargo"
+args = ["test", "--all-features"]
+
+# Installs any tools needed for running commands, like for code coverage.
+[tasks.install-tools]
+workspace = false
+dependencies = [
+  "install-grcov",
+  "install-llvm"
+]
+
+# Create a local test coverage report that outputs as html to ./coverage
+# You may need to run `cargo make install-tools` first and make sure that
+# the llvm tools are on your path.
+[tasks.coverage]
+workspace = false
+dependencies = [
+  "clean",
+  "coverage-run-tests",
+  "coverage-run-grcov",
+  "coverage-clean-profraw",
+  "coverage-notify-completed"
+]

README.md

@@ -2,28 +2,53 @@
 
 `fluent-rs` is a collection of Rust crates implementing [Project Fluent](https://projectfluent.org).
 
+## Packages
+
 The crates perform the following functions:
 
-## fluent [![crates.io](https://img.shields.io/crates/v/fluent.svg)](https://crates.io/crates/fluent)
+### fluent [![crates.io](https://img.shields.io/crates/v/fluent.svg)](https://crates.io/crates/fluent)
 
 Umbrella crate combining crates that are ready to be used in production.
 
-## fluent-syntax [![crates.io](https://img.shields.io/crates/v/fluent_syntax.svg)](https://crates.io/crates/fluent_syntax)
+### fluent-syntax [![crates.io](https://img.shields.io/crates/v/fluent_syntax.svg)](https://crates.io/crates/fluent_syntax)
 
 Low level Fluent Syntax AST and parser API.
 
-## fluent-bundle [![crates.io](https://img.shields.io/crates/v/fluent_bundle.svg)](https://crates.io/crates/fluent_bundle)
+### fluent-bundle [![crates.io](https://img.shields.io/crates/v/fluent_bundle.svg)](https://crates.io/crates/fluent_bundle)
 
 Implementation of the low-level Fluent Localization System providing localization capabilities for any Rust project.
 
-## fluent-fallback [![crates.io](https://img.shields.io/crates/v/fluent_fallback.svg)](https://crates.io/crates/fluent_fallback)
+### fluent-fallback [![crates.io](https://img.shields.io/crates/v/fluent_fallback.svg)](https://crates.io/crates/fluent_fallback)
 
 Implementation of the high-level Fluent Localization System providing localization capabilities for any Rust project.
 
-## fluent-resmgr [![crates.io](https://img.shields.io/crates/v/fluent_resmgr.svg)](https://crates.io/crates/fluent_resmgr)
+### fluent-resmgr [![crates.io](https://img.shields.io/crates/v/fluent_resmgr.svg)](https://crates.io/crates/fluent_resmgr)
 
 Resource Manager for localization resources.
 
-## fluent-cli
+### fluent-cli
 
 Collection of command line tools for Fluent.
+
+## Running the project
+
+Each `fluent-*` directory works with the typical `cargo` commands. In addition there are some general `cargo-make` commands that can be run. First install `cargo-make` via `cargo install --force cargo-make`. The commands are documented in [Makefile.toml](Makefile.toml).
+
+### Tests
+
+To run all of the tests for the repo run:
+
+```sh
+cargo make test
+```
+
+For local code coverage reports run:
+
+```sh
+# Install the tools first if you haven't done so. The llvm tools must be available
+# on the path for this to work correctly.
+cargo make install-tools
+
+# Then coverage can be run like so:
+cargo make coverage
+```