OpenROAD/docs/user/Bazel-caching.md

Bazel Developer Guide: Caching

This document provides instructions for developers on how to use Bazel's caching features to accelerate local builds.

Caching Strategy Overview

Our Bazel setup uses a multi-layered caching strategy to provide optimal performance for different types of users:

1. Local Cache (Default): All builds use a local on-disk cache by default. This provides a speed-up for incremental builds without requiring any special configuration.
2. Remote Cache: We maintain a remote cache server at https://bazel.precisioninno.com. The contents of the cache are generated by the CI for all branches. This allows anyone that wishes to build OpenROAD locally and CI jobs to share build artifacts, dramatically reducing build times. All non-CI builds have read-only access to the remote cache.

---

1. Local On-Disk Cache

All builds use a local on-disk cache to speed up incremental builds. The default location is ~/.cache/bazel-disk-cache and is set inside the repo's .bazelrc file.

You can override this config by setting a systemwide or home .bazelrc file. See more at Write bazelrc configuration files or by passing the --disk_cache argument to your bazel commands.

Using a user.bazelrc file

For more advanced customization, you can create a user.bazelrc file in the root of the repository. This file is ignored by Git and can be used to override any default settings. For example, you could use it to specify a different remote cache or to enable features for your local builds.

Example user.bazelrc:

build --remote_cache=https://storage.googleapis.com/my-personal-cache
build --remote_upload_local_results=true
build --disk_cache=~/my-disk-cache

For a full list of command-line options, refer to the Bazel Command-Line Reference.

---

2. Remote Cache Access

All builds are configured to use our remote cache for shared build artifacts. This is configured in the main .bazelrc file with the following settings:

build --remote_cache=https://bazel.precisioninno.com
build --remote_cache_compression=true
build --remote_upload_local_results=false

This means that all developer builds will read from the public remote cache but cannot write to it. This provides significant build speed improvements without requiring any authentication.

Disabling the Remote Cache

If you encounter issues with the remote cache, you can disable it by overriding the --remote_cache flag. You can do this in your user.bazelrc file or by passing the flag directly to your Bazel command:

Option 1: Using user.bazelrc

Add the following line to your user.bazelrc file:

build --remote_cache=

Option 2: Command-Line Flag

Pass an empty --remote_cache flag to your build command:

bazel build --remote_cache= //...

This will cause Bazel to fall back to using only the local on-disk cache for the build

3. CI Access (Jenkins Pipeline)

The Jenkins pipeline uses a specific configuration for its builds. This is primarily for informational purposes, as developers will not typically use the ci configuration locally.

• All CI builds use the --config=ci profile.
• The ci config enables read/write access to the remote cache, populating it with the latest artifacts for all branches.
• It also disables the local disk cache for CI builds to ensure clean builds.

Here are the relevant settings from .bazelrc:

build:ci --remote_download_minimal
build:ci --remote_upload_local_results=true
build:ci --disk_cache=

---

"Build without the Bytes" (BwoB)

Our configurations include performance optimizations to reduce network traffic and improve build speeds using the "Build without the Bytes" (BwoB) feature, which minimizes the download of build artifacts from the remote cache.

There are two main BwoB settings:

• --remote_download_toplevel: This is the default setting in Bazel. It downloads only the outputs of the top-level targets you specify in your build command. This is ideal for interactive development, where you need to use the final build artifacts (e.g., run a binary or inspect a generated file).

• --remote_download_minimal: This is a more aggressive setting that downloads only the artifacts essential for the build to continue. It is primarily intended for CI environments, where you are only concerned with the success or failure of a build, not the artifacts themselves.

Our configurations use the default (--remote_download_toplevel) for developer builds and --remote_download_minimal for CI builds (ci) to provide the best balance of performance and usability for each environment.