How to Implement Rust Cache Action in GitHub Actions

name: 'Usage of rust-cache GitHub Action'
on:
  push:
      branches:
          - main
jobs:
  deploy:
      runs-on: ubuntu-latest
      steps:
      - uses: actions/checkout@v4
      # selecting a toolchain either by action or manual `rustup` calls should happen
      # before the plugin, as the cache uses the current rustc version as its cache key
      - run: rustup toolchain install stable --profile minimal
      - uses: Swatinem/rust-cache@v2

Rust Cache

A GitHub Action that implements smart caching for rust/cargo projects

What is Rust Cache?​

For Rust projects, efficient compilation is essential, especially in continuous integration environments like GitHub Actions, where build times can significantly affect the development workflow. The Rust Cache Action is a GitHub Action specifically designed to provide smart caching for Rust/Cargo projects, optimizing build times with sensible defaults. Here’s how you can integrate this action into your GitHub Actions workflows to enhance the efficiency of your Rust project builds.

The Rust Cache Action speeds up the build process for Rust projects by caching dependencies and build outputs, reducing the time spent on downloading and re-compiling dependencies over and over for each workflow run.

In-Depth Guide to Caching in Rust Cache Action for GitHub Actions​

Efficient caching is a cornerstone of fast and reliable build processes in continuous integration systems. The Rust Cache Action for GitHub Actions is designed to optimize Rust and Cargo project builds by effectively caching necessary components. Understanding what gets cached, how the cache keys are constructed, and the cleaning process can help us tailor the action to our specific needs. Here's a detailed look at how caching is handled in this action.

What Gets Cached?​

The Rust Cache Action caches several critical directories and files that contribute significantly to build times:

• ~/.cargo: This includes installed binaries, the cargo registry, cache, and git dependencies.
• ./target: Build artifacts of dependencies are stored here, speeding up subsequent builds.

Cache Key Construction​

The cache keys are automatically generated based on several factors to ensure uniqueness and relevance:

• GitHub job_id: Ensures cache specificity to each job.
• Rust Compiler Details: Includes the rustc release, host, and hash.
• Compiler-Specific Environment Variables: Variables such as RUSTFLAGS are considered.
• Project Dependency Files: A hash of all Cargo.lock / Cargo.toml files found in the repository.
• Rust Toolchain Files: A hash of rust-toolchain or rust-toolchain.toml files in the repository root.
• Cargo Config Files: A hash of .cargo/config.toml files in the repository root.

An additional custom key can be specified if the built-in keys do not meet specific requirements.

Cleaning the Cache​

Before the cache is saved, it undergoes a cleaning process to remove unnecessary or outdated items:

• Old Binaries: Removes any files in ~/.cargo/bin that were present before the action ran.
• Unused Dependencies: Cleans up dependencies that are no longer used in the project.
• Non-Dependency Files: Clears out non-dependency related files.
• Old Build Artifacts: Removes incremental build artifacts and any build artifacts older than one week.

This cleaning ensures that the cache remains relevant and efficient, avoiding bloating and potential conflicts.

What's Not Cached?​

• Workspace Crates: Caching workspace crates is typically not effective, hence they are not included.
• Incremental Compilation Artifacts: To save time and space, CARGO_INCREMENTAL is set to 0 to disable incremental compilation.
• Registry Source Code: The ~/.cargo/registry/src directory is not cached because it is more efficient for Cargo to recreate it from compressed crate archives in ~/.cargo/registry/cache.

Handling Specific Issues​

The action also includes workarounds for known issues such as cargo#8603 and actions/cache#403, which could otherwise corrupt the cache on macOS builds.

Cache Restoration​

The action attempts to restore from a previous Cargo.lock version, ensuring that only changed dependencies are rebuilt when lockfiles are updated. This is facilitated by invoking cargo metadata to accurately determine the current set of dependencies.

Configuration Options​

The Swatinem/rust-cache@v2 action provides a robust set of configuration options to enhance caching effectiveness for your Rust projects on GitHub Actions. Here’s a breakdown of each option and how to use them effectively in your .github/workflows/rust.yml file:

Configuration Options​

• prefix-key: Allows you to set a prefix for the cache key, useful for invalidating old caches manually.
• shared-key: Enables a stable cache key across different jobs or workflows, which is great for sharing caches.
• key:Adds a specific key that works alongside the job-based cache key, useful for differentiating similar jobs.
• env-vars: Targets environment variables that influence the cache key, ensuring the cache matches the build environment.
• workspaces: Defines cargo workspaces and their target directories for caching, allowing custom configurations.
• cache-directories: Lists additional directories for caching that aren’t automatically included.
• cache-targets: Allows you to control whether workspace target directories are cached.
• cache-on-failure: Decides if the cache should be saved even when the workflow fails.
• cache-all-crates: Determines if all crates are cached or only project dependencies.
• save-if: Sets conditions under which the cache should be saved, useful for specific branch caching.
• cache-provider: Specifies the backend for caching, supporting external providers beyond GitHub’s built-in cache.