You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This document provides instructions for developers on how to use Bazel's caching features to accelerate local builds.
4
+
5
+
## Caching Strategy Overview
6
+
7
+
Our Bazel setup uses a multi-layered caching strategy to provide optimal performance for different types of users:
8
+
9
+
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 or authentication.
10
+
2.**Remote Cache (OpenROAD Developers & CI):** We maintain a remote cache on Google Cloud Storage. This allows team members and CI jobs to share build artifacts, dramatically reducing build times.
11
+
12
+
---
13
+
14
+
### 1. Local On-Disk Cache
15
+
16
+
By default, all builds use a local on-disk cache to speed up incremental builds. The default location is `~/.cache/bazel-disk-cache`.
17
+
18
+
You can override this location by setting the `OPENROAD_BAZEL_CACHE` environment variable:
19
+
20
+
```bash
21
+
export OPENROAD_BAZEL_CACHE=/path/to/your/cache
22
+
bazel build //...
23
+
```
24
+
25
+
No remote cache is accessed, and no authentication is required for the local cache. This provides a seamless experience for external contributors.
26
+
Secure VMs already have this set up, so no additional configuration is needed.
Team members can enable **read-only** access to the remote cache by using the `openroad-dev` configuration. This will dramatically speed up local builds by downloading artifacts already built by CI.
33
+
34
+
#### On Secure Development VMs
35
+
36
+
If you are working on a secure development VM provided by OpenROAD, you do **not** need to authenticate. The VM's service account already has the necessary read access to the cache.
37
+
38
+
#### On a Local Environment
39
+
40
+
If you are working on your local machine, you must first authenticate with Google Cloud using your @openroad.tools account. All OpenROAD team members have read access to the remote cache.
41
+
42
+
```bash
43
+
gcloud auth application-default login
44
+
```
45
+
46
+
After authenticating (if necessary), run your build with the `--config=openroad-dev` flag:
47
+
48
+
```bash
49
+
bazel build --config=openroad-dev //...
50
+
```
51
+
52
+
This configuration is **read-only** to prevent local, unverified builds from populating the shared cache.
53
+
54
+
---
55
+
56
+
### 3. CI Access (Jenkins Pipeline)
57
+
58
+
The Jenkins pipeline uses a unified caching strategy for all builds. This is primarily for informational purposes, as developers will not typically use the `ci` configuration locally.
59
+
60
+
* All CI builds use the `--config=ci` profile.
61
+
* Builds on the `master` branch have **read/write** access, populating the remote cache with the latest artifacts.
62
+
* Builds on PR branches are set to **read-only**.
63
+
64
+
---
65
+
66
+
## `.bazelrc` Configurations Summary
67
+
68
+
The caching behavior is controlled by two new configurations in the `.bazelrc` file:
69
+
70
+
***`build:ci` (Write Access):**
71
+
*`--remote_upload_local_results=true`: **Enables writing** to the remote cache.
72
+
* Uses service account credentials provided by Jenkins.
73
+
74
+
***`build:openroad-dev` (Read-Only Access):**
75
+
-`--remote_upload_local_results=false`: **Disables writing**, making the cache read-only.
76
+
-`--google_default_credentials=true`: Uses the developer's local `gcloud` credentials.
77
+
78
+
Both configurations include performance optimizations to reduce network traffic and improve build speeds. The primary mechanism for this is the "Build without the Bytes" (BwoB) feature, which minimizes the download of build artifacts from the remote cache.
79
+
80
+
There are two main BwoB settings:
81
+
82
+
*`--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).
83
+
84
+
*`--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.
85
+
86
+
Our configurations use `--remote_download_toplevel` for developer builds (`openroad-dev`) and `--remote_download_minimal` for CI builds (`ci`) to provide the best balance of performance and usability for each environment.
0 commit comments