# 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](https://bazel.build/run/bazelrc) 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](https://bazel.build/reference/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:

```bash
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.