Rust

License

Use the MIT license.

Development

• Install Rust via rustup rather than via Homebrew.

Preferences

• Prefer crates in the top 250 according to lib.rs

• Read the Cargo.toml files of OCP projects for inspiration

• Use unstable language features or compiler flags instead of related crates. For example:

  • let_chains instead of if_chain

  • once_cell instead of once_cell (crate) or lazy_static

  • on-broken-pipe instead of calm_io

See also

• Serde documentation

Performance

See also

coz profiler

Code style

• Avoid matching an Option or Result. Instead, use Option and Result methods.

• Don’t panic. This includes panic!, unreachable!, unwrap() and expect().

• Use the same word for macro tokens as for local variables, if appropriate.

• Use super::* in mod tests only. Use crate:: elsewhere.

See also

• Common Message Styles

Macros

Prefer functions, but use macros if you need:

• Variadic arguments, like println! or vec!.

• Code generation at the item level, like creating structs.

• Code generation at the expression level, like accessing struct fields dynamically.

See also

• The Little Book of Rust Macros

• Macros in The Rust Reference

Debugging:

• Debugging in The Little Book of Rust Macros

• cargo-expand

• proc-macro-error

Crates:

• paste, to use macro arguments to generate identifiers and strings.

• To write procedural macros more easily: quote, proc_macro2, darling.

Guard clauses

Code with too much indentation is hard to read. One option is to use guard clauses. For example:

let Some(inner_value) = outer_value else {
    return
};

let inner_value = match outer_value {
    Ok(o) => o,
    Err(e) => return e,
};

Continuous integration

Create a .github/workflows/ci.yml file. As a base, use:

name: CI
on: [push, pull_request]
jobs:
  build:
    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [macos-latest, windows-latest, ubuntu-latest]
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      - uses: Swatinem/rust-cache@v2
        with:
          key: ${{ matrix.os }}
      # https://github.com/Swatinem/rust-cache/issues/93#issuecomment-1321064841
      - run: cargo update
      - uses: taiki-e/install-action@cargo-llvm-cov
      - run: cargo llvm-cov --lcov --output-path coverage/lcov.info
      - if: matrix.os == 'ubuntu-latest'
        uses: coverallsapp/github-action@v2

Release process

1. Ensure that you are on an up-to-date main branch:

   git checkout main
   git pull --rebase
   

2. Ensure that the package is ready for release:

   • All tests pass on continuous integration

   • The version number is correct in Cargo.toml

   • The changelog is up-to-date and dated

3. Tag the release, replacing x.y.z twice:

   git tag -a x.y.z -m 'x.y.z release.'
   

4. Push the release:

   git push --follow-tags
   

5. Edit the GitHub release that is created by GitHub Actions, to add the description value from Cargo.toml followed by the relevant section of the changelog.

6. If the software has a formula in our Homebrew tap, update the url and sha256 values. For example, from the homebrew-tap directory, after updating the url values, prepare the sha256 values for the ocdscardinal formula with:

   grep --only-matching -E 'https://.+zip' Formula/ocdscardinal.rb | xargs -I{} sh -c 'curl -sSL {} | shasum -a 256'
   

   Then, push the changes.

7. Publish the crate:

   cargo publish
   

8. Announce on the discussion group if relevant

Development

Troubleshooting

If you’re getting confusing compile errors, especially any involving type annotations, check that:

• You wrote enough code. If you produce results that you don’t use, the compiler still wants to determine their definite type. Adding more code to give the compiler a hint can spare adding optional type annotations.

• Your annotations are correct. If you change your code but don’t change your annotations, the compiler might report errors that are distantly related to the misannotation.

• You duck type using trait objects: for example, Box<dyn Read> to use std::io:stdin() and File::open(file).unwrap() interchangeably. The compiler can’t determine which traits are relevant across the two types.

If errors relate to ownership, try using:

• Arc<Mutex<T>>, as discussed in sections 16.3 and 20.2 of The Rust Programming Language.

• Option with take(), as discussed in sections 17.3 and 20.3 of The Rust Programming Language.

To reduce the number of allocations, try using:

• mem::take or mem::replace (Rust Design Patterns).

See also

• Winning Fights against the Borrow Checker

Learning

Rust has no:

• Exception

• Reflection

Introductions

• The Rust Programming Language (Moving Captured Values Out of Closures and the Fn Traits)

• Exercism Rust Track: Read the most upvoted community solution after each exercise.

• Unofficial community Discord, in particular #rust-help and #rust-beginners

Tip

Use Rust Playground to test code snippets.

Topics

• Command line apps in Rust

Memory container cheatsheet

From usagi/rust-memory-container-cs.

Reference

• The Rust Standard Library

• The Rust Reference

• docs.rs for crate documentation

  Tip

  Scroll up after the page loads to access the within-crate search bar.