diff --git a/docs/developers.md b/docs/developers.md new file mode 100644 index 00000000..2bc2f71e --- /dev/null +++ b/docs/developers.md @@ -0,0 +1,124 @@ +# Developer Guide + +This guide provides technical information for developers working on the MathCAT codebase. + +## Prerequisites + +To develop MathCAT, you need to have Rust installed. If you haven't already: + +1. [Download and install Rust](https://www.rust-lang.org/tools/install) +2. Clone the MathCAT repository +3. Open the project directory in your IDE + +## Working with Cargo + +Cargo is Rust's build system and package manager. Here are the essential commands you'll use: + +### Building the Project + +```bash +# Build the project in debug mode +cargo build + +# Build the project in release mode (optimized) +cargo build --release +``` + +### Running the Project + +```bash +# Run the main executable +cargo run + +# Run with specific arguments +cargo run -- +``` + +### Managing Dependencies + +Dependencies are defined in `Cargo.toml`. Cargo automatically downloads and manages them. + +```bash +# Update dependencies to their latest compatible versions +cargo update +``` + +## Testing + +Testing is crucial for maintaining code quality and ensuring that changes don't break existing functionality. + +### Running Tests + +```bash +# Run all tests +cargo test + +# Run a specific test +cargo test test_name +``` + +### Writing Tests + +Tests in MathCAT verify that MathML expressions produce the expected speech output. Example: + +```rust +#[test] +fn test_simple_fraction() { + let expr = " + + 1 + 2 + + "; + test("en", "SimpleSpeak", expr, "1 half"); +} +``` + +### Test Coverage + +Test coverage helps identify which parts of the code are exercised by tests and which parts need more testing. + +
+Using grcov on macOS + +This approach uses `llvm-cov` and `grcov` to generate test coverage reports. Other operating systems should also work with [grcov](https://github.com/mozilla/grcov), but may require some adjustments regarding LLVM paths and configuration. + +**One-time setup:** + +```bash +# Install required components +rustup component add llvm-tools-preview +cargo install grcov +``` + +**Generate coverage report:** + +```bash +# Set environment variable for profiling data +export LLVM_PROFILE_FILE="target/coverage/%p-%m.profraw" + +# Run tests with coverage instrumentation +RUSTFLAGS="-Cinstrument-coverage" cargo test + +# Example: Run a single test +# RUSTFLAGS="-Cinstrument-coverage" cargo test Languages::zh::tw::units::without_prefix_powers_of_2 + +# Generate HTML report +grcov . \ + --source-dir . \ + --binary-path ./target/debug/deps \ + -t html \ + --branch \ + --ignore-not-existing \ + --ignore "target/*" \ + -o target/coverage/html + +# Open the report in your browser +open target/coverage/html/index.html +``` + +
+ +**Alternative: IDE Integration** + +Many Rust IDEs provide built-in test coverage support, like RustRover or VSCode. \ No newline at end of file diff --git a/docs/helpers.md b/docs/helpers.md index f10f4e47..1d2e2d17 100644 --- a/docs/helpers.md +++ b/docs/helpers.md @@ -252,6 +252,8 @@ Whether you are developing code or writing rules, writing and running the tests The `tests` directory is similar to the `Rules` directory. If you are a translator, see the section above that describes what you should do. +Rust provides testing support with the command `cargo test`. For more information about testing and test coverage, see the [Developer Guide](developers.md). + ## Files MathCAT reads the following files for critical information: diff --git a/docs/index.md b/docs/index.md index 4b969bd0..8c09fff6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -17,7 +17,7 @@ There are many different audiences for MathCAT and each audience has different i * AT users: [information about preferences you can set](users.md) * AT developers/library users: [information about the API that MathCAT exposes](callers.md) * Translators/Rule writers: [information about the files that need to be translated](helpers.md) -* MathCAT developers: information about MathCAT's design +* MathCAT developers: [information about development workflow and testing](developers.md) # Some Technical Details MathCAT is written in Rust and can be built to interface with many languages. To date there are interfaces for: