Restructure site/ directory into docs/ which only contains Bazel documentation.

The new docs/ directory in the bazel source tree will only contain the Bazel
docs site, which is hosted at docs.bazel.build. This change deletes the
marketing site and blog, which have been migrated to the bazel-website and
bazel-blog GitHub repositories respectively.

This change also updates the serve-docs.sh and ci/build.sh under scripts/ in
preparation for publishing the docs site.

Note that to help make reviews more manageable, this change is limited to
moving files to their new locations. Here are the follow-up changes:

* Update all links in docs to remove versions/master in paths and to add
  correct bazel.build subdomain when linking to pages on the marketing site
  or the blog.
* Set up versioned directories on GCS bucket and add tooling for versioning
  docs

This change is also coordinated with
https://bazel-review.googlesource.com/c/11568/ to have the PublishSite job
publish to docs.bazel.build rather than www.bazel.build.

Issue #2397

RELNOTES: None
PiperOrigin-RevId: 157612651

1 files changed, 129 insertions, 2 deletions

diff --git a/site/docs/output_directories.md b/site/docs/output_directories.md
index aa176bb43c..20858c6101 100644
--- a/site/docs/output_directories.md
+++ b/site/docs/output_directories.md
@@ -1,4 +1,131 @@
 ---
-layout: redirect
-redirect: docs/output_directories.html
+layout: documentation
+title: Output Directory Layout
 ---
+
+# Output Directory Layout
+
+## Requirements
+
+Requirements for an output directory layout:
+
+* Don't collide if multiple users are building on the same box.
+* Support building in multiple workspaces at the same time.
+* Support building for multiple target configurations in the same workspace.
+* Don't collide with any other tools.
+* Be easy to access.
+* Be easy to clean, even selectively.
+* Is unambiguous, even if the user relies on symbolic links when changing into
+  his/her client directory.
+* All the build state per user should be underneath one directory ("I'd like to
+  clean all the .o files from all my clients.")
+
+## Documentation of the current Bazel output directory layout
+
+The solution that's currently implemented:
+
+* Bazel must be invoked from a directory containing a WORKSPACE file. It reports
+  an error if it is not. We call this the _workspace directory_.
+* The _outputRoot_ directory is ~/.cache/bazel. (Unless `$TEST_TMPDIR` is
+  set, as in a test of bazel itself, in which case this directory is used
+  instead.)
+* We stick the Bazel user's build state beneath `outputRoot/_bazel_$USER`. This
+  is called the _outputUserRoot_ directory.
+* Beneath the `outputUserRoot` directory, we create an `installBase` directory
+  whose name is "install" plus the MD5 hash of the Bazel installation manifest.
+* Beneath the `outputUserRoot` directory, we also create an `outputBase`
+  directory whose name is the MD5 hash of the path name of the workspace
+  directory. So, for example, if Bazel is running in the workspace directory
+  `/home/user/src/my-project` (or in a directory symlinked to that one), then we
+  create an output base directory called:
+  `/home/.cache/bazel/_bazel_user/7ffd56a6e4cb724ea575aba15733d113`.
+* Users can use Bazel's `--output_base` startup option to override the default
+  output base directory. For example,
+  `bazel --output_base=/tmp/bazel/output build x/y:z`.
+* Users can also use Bazel's `--output_user_root` startup option to override the
+  default install base and output base directories. For example:
+  `bazel --output_user_root=/tmp/bazel build x/y:z`.
+
+We put symlinks "bazel-<workspace-name>" and "bazel-out", as well as
+"bazel-bin", "bazel-genfiles", and "bazel-includes" in the workspace directory;
+these symlinks points to some directories inside a target-specific directory
+inside the output directory. These symlinks are only for the user's convenience,
+as Bazel itself does not use them. Also, we only do this if the workspace
+directory is writable. The names of the "bazel-bin", "bazel-genfiles", and
+"bazel-include" symlinks are affected by the `--symlink_prefix` option to bazel,
+but "bazel-<workspace-name>" and "bazel-out" are not.
+
+## Bazel internals: Directory layout
+
+The directories are laid out as follows:
+
+<pre>
+&lt;workspace-name&gt;/                         <== The workspace directory
+  bazel-my-project => <...my-project>     <== Symlink to execRoot
+  bazel-out => <...bin>                   <== Convenience symlink to outputPath
+  bazel-bin => <...bin>                   <== Convenience symlink to most recent written bin dir $(BINDIR)
+  bazel-genfiles => <...genfiles>         <== Convenience symlink to most recent written genfiles dir $(GENDIR)
+
+/home/user/.cache/bazel/                  <== Root for all Bazel output on a machine: outputRoot
+  _bazel_$USER/                           <== Top level directory for a given user depends on the user name:
+                                              outputUserRoot
+    install/
+      fba9a2c87ee9589d72889caf082f1029/   <== Hash of the Bazel install manifest: installBase
+        _embedded_binaries/               <== Contains binaries and scripts unpacked from the data section of
+                                              the bazel executable on first run (e.g. helper scripts and the
+                                              main Java file BazelServer_deploy.jar)
+    7ffd56a6e4cb724ea575aba15733d113/     <== Hash of the client's workspace directory (e.g.
+                                              /home/some-user/src/my-project): outputBase
+      action_cache/                       <== Action cache directory hierarchy
+                                              This contains the persistent record of the file metadata
+                                              (timestamps, and perhaps eventually also MD5 sums) used by the
+                                              FilesystemValueChecker.
+      action_outs/                        <== Action output directory. This contains a file with the
+                                              stdout/stderr for every action from the most recent bazel run
+                                              that produced output.
+      command.log                         <== A copy of the stdout/stderr output from the most recent bazel
+                                              command.
+      external/                           <== The directory that remote repositories are downloaded/symlinked
+                                              into.
+      server/                             <== The Bazel server puts all server-related files (such as socket
+                                              file, logs, etc) here.
+        jvm.out                           <== The debugging output for the server.
+      &lt;workspace-name&gt;/             <== Working tree for the Bazel build & root of symlink forest: execRoot
+        _bin/                             <== Helper tools are linked from or copied to here.
+
+        bazel-out/                        <== All actual output of the build is under here: outputPath
+          local_linux-fastbuild/          <== one subdirectory per unique target BuildConfiguration instance;
+                                              this is currently encoded
+            bin/                          <== Bazel outputs binaries for target configuration here: $(BINDIR)
+              foo/bar/_objs/baz/          <== Object files for a cc_* rule named //foo/bar:baz
+                foo/bar/baz1.o            <== Object files from source //foo/bar:baz1.cc
+                other_package/other.o     <== Object files from source //other_package:other.cc
+              foo/bar/baz                 <== foo/bar/baz might be the artifact generated by a cc_binary named
+                                              //foo/bar:baz
+              foo/bar/baz.runfiles/       <== The runfiles symlink farm for the //foo/bar:baz executable.
+                MANIFEST
+                &lt;workspace-name&gt;/
+                  ...
+            genfiles/                     <== Bazel puts generated source for the target configuration here:
+                                              $(GENDIR)
+              foo/bar.h                       e.g. foo/bar.h might be a headerfile generated by //foo:bargen
+            testlogs/                     <== Bazel internal test runner puts test log files here
+              foo/bartest.log                 e.g. foo/bar.log might be an output of the //foo:bartest test with
+              foo/bartest.status              foo/bartest.status containing exit status of the test (e.g.
+                                              PASSED or FAILED (Exit 1), etc)
+            include/                      <== a tree with include symlinks, generated as needed.  The
+                                              bazel-include symlinks point to here. This is used for
+                                              linkstamp stuff, etc.
+          host/                           <== BuildConfiguration for build host (user's workstation), for
+                                              building prerequisite tools, that will be used in later stages
+                                              of the build (ex: Protocol Compiler)
+        &lt;packages&gt;/                       <== Packages referenced in the build appear as if under a regular workspace
+</pre>
+
+The layout of the *.runfiles directories is documented in more detail in the places pointed to by RunfilesSupport.
+
+## `bazel clean`
+
+`bazel clean` does an `rm -rf` on the `outputPath` and the `action_cache`
+directory. It also removes the workspace symlinks. The `--expunge` option
+will clean the entire outputBase.