docs: Add Bazel and BuildStream configuration instructions

docs/source/using.rst

@@ -9,5 +9,6 @@ This section covers how to run an use the BuildGrid build service.
 .. toctree::
    :maxdepth: 2
 
-   using_dummy_build.rst
-   using_simple_build.rst
+   using_internal.rst
+   using_bazel.rst
+   using_buildstream.rst

docs/source/using_bazel.rst

+
+.. _bazel-builds:
+
+Bazel builds
+============
+
+`Bazel`_ is a *“fast, scalable, multi-language and extensible build system”*
+that supports remote build execution using the remote execution API (REAPI) v2
+since its `0.17 release`_.
+
+.. _Bazel: https://bazel.build
+.. _0.17 release: https://blog.bazel.build/2018/09/14/bazel-0.17.html
+
+
+.. _bazel-configuration:
+
+Configuration
+-------------
+
+Bazel accepts many options that can either be specified as command line
+arguments when involking the ``bazel`` tool or stored in a `.bazelrc`_
+configuration file.
+
+In order to activate remote execution, Bazel's ``build`` subcommand needs to be
+given specific `build options`_. Most important ones include:
+
+- ``--remote_executor``: remote execution endpoint's location, ``{host}:{port}``.
+- ``--remote_instance_name``: remote execution instance's name.
+- ``--spawn_strategy``: action execution method.
+- ``--genrule_strategy``: `genrules`_ execution method.
+
+Spawn and genrule strategies need to be set to ``remote`` for remote execution.
+As an example, in order to activate remote execution on the ``main`` instance of
+the remote execution server available at ``controller.grid.build`` on port
+``50051`` you should amend your ``.bazelrc`` with:
+
+.. code-block:: sh
+
+   build --spawn_strategy=remote --genrule_strategy=remote --remote_executor=controller.grid.build:50051 --remote_instance_name=main
+
+.. _.bazelrc: https://docs.bazel.build/versions/master/user-manual.html#bazelrc
+.. _build options: https://docs.bazel.build/versions/master/command-line-reference.html#build-options
+.. _genrules: https://docs.bazel.build/versions/master/be/general.html#genrule
+
+
+.. _bazel-example:
+
+Example build
+-------------
+
+
+.. _bazel-build:
+
+Complete build
+--------------

docs/source/using_buildstream.rst

+
+.. _buildstream-builds:
+
+BuildStream builds
+==================
+

docs/source/using_dummy_build.rst

-.. _dummy-build:
-
-Dummy build
-===========
-
-In one terminal, start a server:
-
-.. code-block:: sh
-
-   bgd server start buildgrid/_app/settings/default.yml
-
-In another terminal, send a request for work:
-
-.. code-block:: sh
-
-   bgd execute request-dummy
-
-The stage should show as ``QUEUED`` as it awaits a bot to pick up the work:
-
-.. code-block:: sh
-
-   bgd execute list
-
-Create a bot session:
-
-.. code-block:: sh
-
-   bgd bot dummy
-
-Show the work as completed:
-
-.. code-block:: sh
-
-   bgd execute list

docs/source/using_simple_build.rst → docs/source/using_internal.rst

+
+.. _internal-builds:
+
+Internal builds
+===============
+
+
+.. _dummy-test:
+
+Dummy test
+----------
+
+In one terminal, start a server:
+
+.. code-block:: sh
+
+   bgd server start buildgrid/_app/settings/default.yml
+
+In another terminal, send a request for work:
+
+.. code-block:: sh
+
+   bgd execute request-dummy
+
+The stage should show as ``QUEUED`` as it awaits a bot to pick up the work:
+
+.. code-block:: sh
+
+   bgd execute list
+
+Create a bot session:
+
+.. code-block:: sh
+
+   bgd bot dummy
+
+Show the work as completed:
+
+.. code-block:: sh
+
+   bgd execute list
+
+
 .. _simple-build:
 
 Simple build
-============
+------------
 
 This example covers a simple build. The user will upload a directory containing
 a C file and a command to the CAS. The bot will then fetch the uploaded