Add documentation for memory-saving mode to Bazel.
PiperOrigin-RevId: 246910398
diff --git a/site/_layouts/documentation.html b/site/_layouts/documentation.html
index d115c24..c713fff 100644
--- a/site/_layouts/documentation.html
+++ b/site/_layouts/documentation.html
@@ -104,6 +104,7 @@
<li><a href="/versions/{{ current_version }}/configurable-attributes.html">Configurable Attributes</a></li>
<li><a href="/versions/{{ current_version }}/best-practices.html">Best Practices</a></li>
+ <li><a href="/versions{{ current_version }}/memory-saving-mode.html">Memory-saving Mode</a></li>
<li>
<a class="sidebar-nav-heading" data-toggle="collapse"
href="#remote-execution-menu" aria-expanded="false"
diff --git a/site/docs/memory-saving-mode.md b/site/docs/memory-saving-mode.md
new file mode 100644
index 0000000..28f7d9b
--- /dev/null
+++ b/site/docs/memory-saving-mode.md
@@ -0,0 +1,34 @@
+---
+layout: documentation
+title: Memory-saving Mode
+---
+
+# Running Bazel with limited RAM
+
+In certain situations, you may want Bazel to use minimal memory. You can set the
+maximum heap via the startup flag
+[`--host_jvm_args`](user-manual.html#flag--host_jvm_args),
+like `--host_jvm_args=-Xmx2g`.
+
+However, if your builds are big enough, Bazel may throw an `OutOfMemoryError`
+(OOM) when it doesn't have enough memory. You can make Bazel use less memory, at
+the cost of slower incremental builds, by passing the following command flags:
+[`--discard_analysis_cache`](user-manual.html#flag--discard_analysis_cache),
+`--nokeep_state_after_build`, and `--notrack_incremental_state`.
+
+These flags will minimize the memory that Bazel uses in a build, at the cost of
+making future builds slower than a standard incremental build would be.
+
+You can also pass any one of these flags individually:
+
+ * `--discard_analysis_cache` will reduce the memory used during execution (not
+analysis). Incremental builds will not have to redo package loading, but will
+have to redo analysis and execution (although the on-disk action cache can
+prevent most re-execution).
+ * `--notrack_incremental_state` will not store any edges in Bazel's internal
+ dependency graph, so that it is unusable for incremental builds. The next build
+ will discard that data, but it is preserved until then, for internal debugging,
+ unless `--nokeep_state_after_build` is specified.
+ * `--nokeep_state_after_build` will discard all data after the build, so that
+ incremental builds have to build from scratch (except for the on-disk action
+ cache). Alone, it does not affect the high-water mark of the current build.
diff --git a/site/docs/user-manual.html b/site/docs/user-manual.html
index a29b589..3a2a054 100644
--- a/site/docs/user-manual.html
+++ b/site/docs/user-manual.html
@@ -976,7 +976,10 @@
When this option is enabled, Bazel will discard the analysis cache
right before execution starts, thus freeing up additional memory
(around 10%) for the <a href="guide.html#execution-phase">execution phase</a>.
- The drawback is that further incremental builds will be slower.
+ The drawback is that further incremental builds will be slower. See also
+ -->
+ <a href="/versions{{ current_version }}/memory-saving-mode.html">
+memory-saving mode<a/>.
</p>
<h4 id='flag--keep_going'><code class='flag'>--[no]keep_going</code> (-k)</h4>
