[Notes] [Git][BuildGrid/buildgrid][mablanch/51-clients-usage] 2 commits: docs: Add Bazel and BuildStream configuration instructions

[Martin Blanchard <gitlab mg gitlab com>]

Title: GitLab

Martin Blanchard pushed to branch mablanch/51-clients-usage at BuildGrid / buildgrid

Commits:

• ec869529
  by Martin Blanchard at 2018-09-18T08:47:24Z

  docs: Add Bazel and BuildStream configuration instructions
  

• 8d055df0
  by Martin Blanchard at 2018-09-18T09:26:33Z

  CONTRIBUTING.rst: Add a sub-section about testing
  

6 changed files:

• CONTRIBUTING.rst
• docs/source/using.rst
• + docs/source/using_bazel.rst
• + docs/source/using_buildstream.rst
• − docs/source/using_dummy_build.rst
• docs/source/using_simple_build.rst → docs/source/using_internal.rst

Changes:

CONTRIBUTING.rst

---

...	...	@@ -142,13 +142,67 @@ their containing *package*, as such; modules which are entirely private to
142	142	BuildGrid are named as such, e.g. ``_roy.py``.
143	143
144	144
	145	+.. _codebase-testing:
	146	+
	147	+Testing
	148	+-------
	149	+
	150	+BuildGrid is using ``pytest``_ for regression and newly added code testing. The
	151	+test suite contains a serie of unit-tests and also run linting tools in order to
	152	+detect coding-style_ breakage. The full test suite is automatically executed by
	153	+GitLab CI system for every push to the server. Passing all the tests is a
	154	+mandatory requirement for any merge request to the trunk.
	155	+
	156	+.. _pytest: https://docs.pytest.org
	157	+
	158	+
	159	+Running tests
	160	+~~~~~~~~~~~~~
	161	+
	162	+In order to run the entire test suite, simply run:
	163	+
	164	+.. code-block:: sh
	165	+
	166	+ python3 setup.py test
	167	+
	168	+You can use the ``--addopt`` function to feed arguments to pytest. For example,
	169	+if you want to see the ``stdout`` and ``stderr`` generated y the test, run:
	170	+
	171	+.. code-block:: sh
	172	+
	173	+ python3 setup.py test --addopts -s
	174	+
	175	+If you want run a specific test instead of the entire suite use:
	176	+
	177	+.. code-block:: sh
	178	+
	179	+ python3 setup.py test --addopts tests/cas/test_client
	180	+
	181	+pyest's `usage documentation section`_ details the different command line
	182	+options that can be used when invoking the test runner.
	183	+
	184	+.. _usage documentation section: https://docs.pytest.org/en/latest/usage.html
	185	+
	186	+
	187	+Test coverage
	188	+~~~~~~~~~~~~~
	189	+
	190	+We are doing our best at keeping BuildGrid's test coverage score as high as
	191	+possible. Doing so, we ask for any merge request to include necessary test
	192	+additions and/or modifications in order to maintain that coverage level. A
	193	+detailed `coverage report`_ is produced and publish for any change merged to the
	194	+trunk.
	195	+
	196	+.. _coverage report: https://buildgrid.gitlab.io/buildgrid/coverage/
	197	+
	198	+
145	199	.. _committer-access:
146	200
147	201	Committer access
148	202	----------------
149	203
150	204	We'll hand out commit access to anyone who has successfully landed a single
151		-patch to the code base. Please request this via irc or the mailing list.
	205	+patch to the code base. Please request this via Slack or the mailing list.
152	206
153	207	This of course relies on contributors being responsive and show willingness to
154	208	address problems after landing branches there should not be any problems here.

docs/source/using.rst

---

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

docs/source/using_bazel.rst

---

	1	+
	2	+.. _bazel-builds:
	3	+
	4	+Bazel builds
	5	+============
	6	+
	7	+`Bazel`_ is a *“fast, scalable, multi-language and extensible build system”*
	8	+that supports remote build execution using the remote execution API (REAPI) v2
	9	+since its `0.17 release`_.
	10	+
	11	+.. _Bazel: https://bazel.build
	12	+.. _0.17 release: https://blog.bazel.build/2018/09/14/bazel-0.17.html
	13	+
	14	+
	15	+.. _bazel-configuration:
	16	+
	17	+Configuration
	18	+-------------
	19	+
	20	+Bazel accepts many options that can either be specified as command line
	21	+arguments when involking the ``bazel`` tool or stored in a `.bazelrc`_
	22	+configuration file.
	23	+
	24	+In order to activate remote execution, Bazel's ``build`` subcommand needs to be
	25	+given specific `build options`_. Most important ones include:
	26	+
	27	+- ``--remote_executor``: remote execution endpoint's location, ``{host}:{port}``.
	28	+- ``--remote_instance_name``: remote execution instance's name.
	29	+- ``--spawn_strategy``: action execution method.
	30	+- ``--genrule_strategy``: `genrules`_ execution method.
	31	+
	32	+Spawn and genrule strategies need to be set to ``remote`` for remote execution.
	33	+As an example, in order to activate remote execution on the ``main`` instance of
	34	+the remote execution server available at ``controller.grid.build`` on port
	35	+``50051`` you should amend your ``.bazelrc`` with:
	36	+
	37	+.. code-block:: sh
	38	+
	39	+ build --spawn_strategy=remote --genrule_strategy=remote --remote_executor=controller.grid.build:50051 --remote_instance_name=main
	40	+
	41	+.. _.bazelrc: https://docs.bazel.build/versions/master/user-manual.html#bazelrc
	42	+.. _build options: https://docs.bazel.build/versions/master/command-line-reference.html#build-options
	43	+.. _genrules: https://docs.bazel.build/versions/master/be/general.html#genrule
	44	+
	45	+
	46	+.. _bazel-example:
	47	+
	48	+Example build
	49	+-------------
	50	+
	51	+
	52	+.. _bazel-build:
	53	+
	54	+Complete build
	55	+--------------

docs/source/using_buildstream.rst

---

	1	+
	2	+.. _buildstream-builds:
	3	+
	4	+BuildStream builds
	5	+==================
	6	+

docs/source/using_dummy_build.rst deleted

---

1		-.. _dummy-build:
2		-
3		-Dummy build
4		-===========
5		-
6		-In one terminal, start a server:
7		-
8		-.. code-block:: sh
9		-
10		- bgd server start buildgrid/_app/settings/default.yml
11		-
12		-In another terminal, send a request for work:
13		-
14		-.. code-block:: sh
15		-
16		- bgd execute request-dummy
17		-
18		-The stage should show as ``QUEUED`` as it awaits a bot to pick up the work:
19		-
20		-.. code-block:: sh
21		-
22		- bgd execute list
23		-
24		-Create a bot session:
25		-
26		-.. code-block:: sh
27		-
28		- bgd bot dummy
29		-
30		-Show the work as completed:
31		-
32		-.. code-block:: sh
33		-
34		- bgd execute list

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

---

	1	+
	2	+.. _internal-builds:
	3	+
	4	+Internal builds
	5	+===============
	6	+
	7	+
	8	+.. _dummy-test:
	9	+
	10	+Dummy test
	11	+----------
	12	+
	13	+In one terminal, start a server:
	14	+
	15	+.. code-block:: sh
	16	+
	17	+ bgd server start buildgrid/_app/settings/default.yml
	18	+
	19	+In another terminal, send a request for work:
	20	+
	21	+.. code-block:: sh
	22	+
	23	+ bgd execute request-dummy
	24	+
	25	+The stage should show as ``QUEUED`` as it awaits a bot to pick up the work:
	26	+
	27	+.. code-block:: sh
	28	+
	29	+ bgd execute list
	30	+
	31	+Create a bot session:
	32	+
	33	+.. code-block:: sh
	34	+
	35	+ bgd bot dummy
	36	+
	37	+Show the work as completed:
	38	+
	39	+.. code-block:: sh
	40	+
	41	+ bgd execute list
	42	+
	43	+
1	44	.. _simple-build:
2	45
3	46	Simple build
4		-============
	47	+------------
5	48
6	49	This example covers a simple build. The user will upload a directory containing
7	50	a C file and a command to the CAS. The bot will then fetch the uploaded

—
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.