Topic describing "what is Bazel" at a high-level, with a focus on: build files and their language, the dependency graph, and Bazel being fast/correct/reproducible.

--
PiperOrigin-RevId: 149114565
MOS_MIGRATED_REVID=149114565

3 files changed, 141 insertions, 0 deletions

diff --git a/site/_layouts/documentation.html b/site/_layouts/documentation.html
index d53f07ea4a..f623326e4a 100644
--- a/site/_layouts/documentation.html
+++ b/site/_layouts/documentation.html
@@ -25,6 +25,8 @@ version_prefix: /versions/master
           </a>
           <nav class="sidebar collapse" id="sidebar-nav">
             <ul class="sidebar-nav">
+              <li><a href="{{ page.version_prefix }}/docs/bazel-overview.html">Bazel Overview</a></li>
+
               <li>
                 <a class="sidebar-nav-heading" data-toggle="collapse"
                     href="#installing-menu" aria-expanded="false"
diff --git a/site/assets/graph_hello-world.svg b/site/assets/graph_hello-world.svg
new file mode 100644
index 0000000000..93b6144477
--- /dev/null
+++ b/site/assets/graph_hello-world.svg
@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 2.36.0 (20140111.2315)
+ -->
+<!-- Title: mygraph Pages: 1 -->
+<svg width="406pt" height="190pt"
+ viewBox="0.00 0.00 406.00 190.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 186)">
+<title>mygraph</title>
+<polygon fill="white" stroke="none" points="-4,4 -4,-186 402,-186 402,4 -4,4"/>
+<!-- //main:hello&#45;world -->
+<g id="node1" class="node"><title>//main:hello&#45;world</title>
+<polygon fill="none" stroke="black" points="264.25,-182 145.75,-182 145.75,-146 264.25,-146 264.25,-182"/>
+<text text-anchor="middle" x="205" y="-160.3" font-family="Times,serif" font-size="14.00">//main:hello&#45;world</text>
+</g>
+<!-- //main:hello&#45;time -->
+<g id="node2" class="node"><title>//main:hello&#45;time</title>
+<polygon fill="none" stroke="black" points="119.5,-110 8.5,-110 8.5,-74 119.5,-74 119.5,-110"/>
+<text text-anchor="middle" x="64" y="-88.3" font-family="Times,serif" font-size="14.00">//main:hello&#45;time</text>
+</g>
+<!-- //main:hello&#45;world&#45;&gt;//main:hello&#45;time -->
+<g id="edge1" class="edge"><title>//main:hello&#45;world&#45;&gt;//main:hello&#45;time</title>
+<path fill="none" stroke="black" d="M170.508,-145.876C151.56,-136.469 127.868,-124.708 107.644,-114.667"/>
+<polygon fill="black" stroke="black" points="109.138,-111.502 98.6251,-110.19 106.026,-117.771 109.138,-111.502"/>
+</g>
+<!-- //main:hello&#45;world.cc -->
+<g id="node3" class="node"><title>//main:hello&#45;world.cc</title>
+<polygon fill="none" stroke="black" points="272,-110 138,-110 138,-74 272,-74 272,-110"/>
+<text text-anchor="middle" x="205" y="-88.3" font-family="Times,serif" font-size="14.00">//main:hello&#45;world.cc</text>
+</g>
+<!-- //main:hello&#45;world&#45;&gt;//main:hello&#45;world.cc -->
+<g id="edge2" class="edge"><title>//main:hello&#45;world&#45;&gt;//main:hello&#45;world.cc</title>
+<path fill="none" stroke="black" d="M205,-145.697C205,-137.983 205,-128.712 205,-120.112"/>
+<polygon fill="black" stroke="black" points="208.5,-120.104 205,-110.104 201.5,-120.104 208.5,-120.104"/>
+</g>
+<!-- //lib:hello&#45;greet -->
+<g id="node4" class="node"><title>//lib:hello&#45;greet</title>
+<polygon fill="none" stroke="black" points="391.25,-110 290.75,-110 290.75,-74 391.25,-74 391.25,-110"/>
+<text text-anchor="middle" x="341" y="-88.3" font-family="Times,serif" font-size="14.00">//lib:hello&#45;greet</text>
+</g>
+<!-- //main:hello&#45;world&#45;&gt;//lib:hello&#45;greet -->
+<g id="edge3" class="edge"><title>//main:hello&#45;world&#45;&gt;//lib:hello&#45;greet</title>
+<path fill="none" stroke="black" d="M238.269,-145.876C256.463,-136.512 279.191,-124.814 298.64,-114.803"/>
+<polygon fill="black" stroke="black" points="300.313,-117.878 307.603,-110.19 297.11,-111.654 300.313,-117.878"/>
+</g>
+<!-- //main:hello&#45;time.cc\n//main:hello&#45;time.h -->
+<g id="node5" class="node"><title>//main:hello&#45;time.cc\n//main:hello&#45;time.h</title>
+<polygon fill="none" stroke="black" points="128,-38 0,-38 0,-0 128,-0 128,-38"/>
+<text text-anchor="middle" x="64" y="-22.8" font-family="Times,serif" font-size="14.00">//main:hello&#45;time.cc</text>
+<text text-anchor="middle" x="64" y="-7.8" font-family="Times,serif" font-size="14.00">//main:hello&#45;time.h</text>
+</g>
+<!-- //main:hello&#45;time&#45;&gt;//main:hello&#45;time.cc\n//main:hello&#45;time.h -->
+<g id="edge4" class="edge"><title>//main:hello&#45;time&#45;&gt;//main:hello&#45;time.cc\n//main:hello&#45;time.h</title>
+<path fill="none" stroke="black" d="M64,-73.8129C64,-66.1101 64,-56.8234 64,-48.149"/>
+<polygon fill="black" stroke="black" points="67.5001,-48.0195 64,-38.0196 60.5001,-48.0196 67.5001,-48.0195"/>
+</g>
+<!-- //lib:hello&#45;greet.cc\n//lib:hello&#45;greet.h -->
+<g id="node6" class="node"><title>//lib:hello&#45;greet.cc\n//lib:hello&#45;greet.h</title>
+<polygon fill="none" stroke="black" points="398.5,-38 283.5,-38 283.5,-0 398.5,-0 398.5,-38"/>
+<text text-anchor="middle" x="341" y="-22.8" font-family="Times,serif" font-size="14.00">//lib:hello&#45;greet.cc</text>
+<text text-anchor="middle" x="341" y="-7.8" font-family="Times,serif" font-size="14.00">//lib:hello&#45;greet.h</text>
+</g>
+<!-- //lib:hello&#45;greet&#45;&gt;//lib:hello&#45;greet.cc\n//lib:hello&#45;greet.h -->
+<g id="edge5" class="edge"><title>//lib:hello&#45;greet&#45;&gt;//lib:hello&#45;greet.cc\n//lib:hello&#45;greet.h</title>
+<path fill="none" stroke="black" d="M341,-73.8129C341,-66.1101 341,-56.8234 341,-48.149"/>
+<polygon fill="black" stroke="black" points="344.5,-48.0195 341,-38.0196 337.5,-48.0196 344.5,-48.0195"/>
+</g>
+</g>
+</svg>
diff --git a/site/versions/master/docs/bazel-overview.md b/site/versions/master/docs/bazel-overview.md
new file mode 100644
index 0000000000..d93430b994
--- /dev/null
+++ b/site/versions/master/docs/bazel-overview.md
@@ -0,0 +1,69 @@
+---
+layout: documentation
+title: Bazel Overview
+---
+
+# Bazel Overview
+
+Bazel is a build tool which coordinates builds and run tests. It works with
+source files written in any language, with native support for Java, C, C++ and
+Python. Bazel produces builds and runs tests for multiple platforms.
+
+## BUILD files use a simple declarative language
+
+Bazel’s BUILD files describe how Bazel should build your project. They have a
+declarative structure and use a build language similar to Python. BUILD files
+allow you to work at a high level of the system by listing rules and their
+attributes. The complexity of the build process is handled by these pre-existing
+rules. You can modify rules to tweak the build process, or write new rules to
+extend Bazel to work with any language or platform.
+
+Below is the content of one of the BUILD files from a Hello World program. The
+two rules used here are cc_library and cc_binary.
+
+```
+cc_library(
+    name = "hello-time",
+    srcs = ["hello-time.cc"],
+    hdrs = ["hello-time.h"],
+)
+
+cc_binary(
+    name = "hello-world",
+    srcs = ["hello-world.cc"],
+    deps = [
+        ":hello-time",
+        "//lib:hello-greet",
+    ],
+)
+```
+
+## The Dependency Graph Describes the Entire System
+
+Build dependencies are declared explicitly in the BUILD files, allowing Bazel
+to create an accurate dependency graph of the entire source code. The graph is
+maintained in memory, and incremental builds and parallel execution are possible
+because of this accurate dependency graph.
+
+Here’s the graph of the target ‘hello-world’ from the BUILD file above:
+
+![Dependency graph of a hello-world target](/assets/graph_hello-world.svg)
+
+
+Bazel’s query language allows you to produce images of the graph like the one
+above. You can also use the query language to access information about build
+dependencies and their relationships.
+
+## Build and Tests are Fast, Correct, and Reproducible
+
+Hermetic rules and sandboxing allows Bazel to produce correct, reproducible
+artifacts and test results. Caching allows reuse of build artifacts and test
+results.
+
+Bazel’s builds are fast. Incremental builds allows Bazel to do the minimum
+required work for a rebuild or retest. Correct and reproducible builds allow
+Bazel to reuse cached artifacts for whatever is not changed. If you change a
+library, Bazel will not rebuild your entire source.
+
+Confidence in these correct results also means that you will never need to run
+`bazel clean`. If you ever need to run `bazel clean`, there’s a bug in Bazel.