[Notes] [Git][BuildGrid/buildgrid][mablanch/111-recc-usage-guide] docs: Add a RECC usage example

[Martin Blanchard <gitlab mg gitlab com>]

Title: GitLab

Martin Blanchard pushed to branch mablanch/111-recc-usage-guide at BuildGrid / buildgrid

Commits:

• dddc9f26
  by Martin Blanchard at 2018-10-02T16:28:19Z

  docs: Add a RECC usage example
  
  https://gitlab.com/BuildGrid/buildgrid/issues/111
  

2 changed files:

• docs/source/using.rst
• + docs/source/using_recc.rst

Changes:

docs/source/using.rst

---

...	...	@@ -12,3 +12,4 @@ This section covers how to run an use the BuildGrid build service.
12	12	using_internal.rst
13	13	using_bazel.rst
14	14	using_buildstream.rst
	15	+ using_recc.rst
		\ No newline at end of file

docs/source/using_recc.rst

---

	1	+
	2	+.. _recc-client:
	3	+
	4	+RECC client
	5	+===========
	6	+
	7	+`RECC`_ is the *Remote Execution Caching Compiler*, a build tool that wraps
	8	+compiler command calls and distribute them over a build farm using using the
	9	+remote execution API (REAPI) v2.
	10	+
	11	+.. _RECC: https://gitlab.com/bloomberg/recc
	12	+
	13	+
	14	+.. _recc-configuration:
	15	+
	16	+Configuration
	17	+-------------
	18	+
	19	+RECC reads its configuration from its execution environment. You can get a
	20	+complete list of environment variables it accepts by running:
	21	+
	22	+.. code-block:: sh
	23	+
	24	+ recc --help
	25	+
	26	+The variables are all prefixed with ``RECC_``. In order send compiler commands
	27	+to a remote execution service, the important one are:
	28	+
	29	+- ``RECC_SERVER``: URI of the remote execution server.
	30	+- ``RECC_CAS_SERVER``: URI of the CAS server, defaults to ``RECC_SERVER``.
	31	+- ``RECC_INSTANCE``: name of the remote execution instance.
	32	+
	33	+.. hint::
	34	+
	35	+ ``RECC_VERBOSE`` can be set in order to enable verbose output.
	36	+
	37	+As an example, in order to set compile commands to the ``main`` instance of the
	38	+remote execution server available at ``controller.grid.build`` on port ``50051``
	39	+you should define:
	40	+
	41	+.. code-block:: sh
	42	+
	43	+ export RECC_SERVER=controller.grid.build:50051
	44	+ export RECC_INSTANCE=main
	45	+
	46	+
	47	+.. _recc-example:
	48	+
	49	+Example build
	50	+-------------
	51	+
	52	+RECC can be use with any existing software package respecting ``GNU make common
	53	+variables``_ like ``CC`` for the C compiler or ``CXX`` for the C++ compiler.
	54	+We'll focus here on instructions on how to build the `GNU Hello`_ example
	55	+program using RECC and BuildGrid on your local machine.
	56	+
	57	+First, you need to download the hello source package:
	58	+
	59	+.. code-block:: sh
	60	+
	61	+ wget https://ftp.gnu.org/gnu/hello/hello-2.10.tar.gz
	62	+
	63	+Next, unpack it and change the current directory to the source root:
	64	+
	65	+ tar xvf hello-2.10.tar.gz
	66	+ cd hello-2.10
	67	+
	68	+.. hint::
	69	+
	70	+ All the commands in the instructions below are expected to be executed from
	71	+ that root source directory (the hello project's root directory).
	72	+
	73	+Before trying to build the hello example program, you'll have to setup and run a
	74	+BuildGrid server and bot. A minimal server's configuration is given below, paste
	75	+it in a ``server.conf`` file in the root directory:
	76	+
	77	+.. literalinclude:: ./data/bazel-example-server.conf
	78	+ :language: yaml
	79	+
	80	+This defines a single ``main`` server instance implementing a
	81	+``ContentAddressableStorage`` (CAS) + ``ByteStream`` service together with an
	82	+``Execution`` + ``ActionCache`` service, both using the same in-memory storage.
	83	+You can then start the BuildGrid server daemon using that configuration by
	84	+running:
	85	+
	86	+.. code-block:: sh
	87	+
	88	+ bgd server start server.conf
	89	+
	90	+In order to perform the actual build work, you need to attach a worker bot to
	91	+that server for that ``main`` instance. A simple host-tools based bot should be
	92	+enough to build the hello example program. Once you've make sure that your
	93	+machine has ``gcc`` installed, run:
	94	+
	95	+.. code-block:: sh
	96	+
	97	+ bgd bot --remote=http://localhost:50051 --parent=main temp-directory
	98	+
	99	+The ``--remote`` option is used to specify the server location (running on the
	100	+same machine here, and listening to port 50051). The ``--parent`` option is used
	101	+to specify the server instance you except the bot to be attached to. Refer to
	102	+the :ref:`CLI reference section <invoking-bgd-bot-temp-directory>` for command
	103	+line interface details.
	104	+
	105	+The BuildGrid server is now ready to accept jobs and execute them. RECC's
	106	+:ref:`configuration <bazel-configuration>` needs to be defined as environment
	107	+variables by running:
	108	+
	109	+.. code-block:: sh
	110	+
	111	+ export RECC_SERVER=localhost:50051
	112	+ export RECC_INSTANCE=main
	113	+
	114	+This points to the ``main`` remote execution server instance at
	115	+``localhost:50051``.
	116	+
	117	+The hello example is using ``The Autotools``_ as a build system. First you need
	118	+to configure your build. Simply run:
	119	+
	120	+.. code-block:: sh
	121	+
	122	+ ./configure
	123	+
	124	+You can finally build the hello program, using RECC. Run:
	125	+
	126	+.. code-block:: sh
	127	+
	128	+ make CC="recc cc"
	129	+
	130	+You can verify that the example program has been successfully build by running
	131	+the generated executable. Simply invoke:
	132	+
	133	+.. code-block:: sh
	134	+
	135	+ ./hello
	136	+
	137	+.. _GNU make common variables: https://www.gnu.org/software/make/manual/html_node/Implicit-Variables.html
	138	+.. _GNU Hello: https://www.gnu.org/software/hello
	139	+.. _The Autotools: https://www.gnu.org/software/automake/manual/html_node/Autotools-Introduction.html
		\ No newline at end of file

—
View it on GitLab.
You're receiving this email because of your account on gitlab.com. If you'd like to receive fewer emails, you can adjust your notification settings.