[Notes] [Git][BuildGrid/buildgrid][mablanch/51-clients-usage] 7 commits: Instance and operation name errors now formatted with `[{}]`.

[Martin Blanchard <gitlab mg gitlab com>]

Title: GitLab

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

Commits:

• f7052140
  by finnball at 2018-09-17T13:40:08Z

  Instance and operation name errors now formatted with `[{}]`.
  
  Helps diagnose empty instance and operation name errors.
  

• 53257bac
  by Laurence Urhegyi at 2018-09-17T17:26:05Z

  Update README.rst
  
  Adds a link to Bazel in addition to BuildStream as a client.
  Amends some of the formatting of paragraphs so they are in a more logical order.

• f8e2b7c0
  by Laurence Urhegyi at 2018-09-17T17:34:59Z

  Update README.rst
  
  Adds links as hyperlinks so that the README page looks neater

• 37e735e5
  by Laurence Urhegyi at 2018-09-17T17:39:20Z

  Update index.rst
  
  Amends links to be hyperlinks so that the webpages look neater.

• 609a824b
  by Martin Blanchard at 2018-09-18T09:45:57Z

  CONTRIBUTING.rst: Add a sub-section about testing
  

• 7cac59b1
  by Martin Blanchard at 2018-09-18T09:45:57Z

  README.rst: Remove trailing whitespaces and newlines
  

• b15d3da4
  by Martin Blanchard at 2018-09-18T09:45:57Z

  docs: Add Bazel and BuildStream configuration instructions
  

18 changed files:

• CONTRIBUTING.rst
• README.rst
• buildgrid/bot/bot_session.py
• buildgrid/server/actioncache/service.py
• buildgrid/server/bots/instance.py
• buildgrid/server/bots/service.py
• buildgrid/server/cas/service.py
• buildgrid/server/execution/instance.py
• buildgrid/server/execution/service.py
• buildgrid/server/operations/instance.py
• buildgrid/server/operations/service.py
• buildgrid/server/referencestorage/service.py
• docs/source/index.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.

README.rst

---

1	1
2		-.. _about:
3		-
4		-About
5		-=====
6		-
7	2	.. image:: https://gitlab.com/Buildgrid/buildgrid/badges/master/pipeline.svg
8	3	:target: https://gitlab.com/BuildStream/buildstream/commits/master
9	4
10	5	.. image:: https://gitlab.com/BuildGrid/buildgrid/badges/master/coverage.svg?job=coverage
11	6	:target: https://buildgrid.gitlab.io/buildgrid/coverage
12	7
	8	+
	9	+.. _about:
	10	+
	11	+About BuildGrid
	12	+===============
	13	+
	14	+
	15	+.. _what-is-it:
	16	+
	17	+What is BuildGrid?
	18	+------------------
	19	+
13	20	BuildGrid is a Python remote execution service which implements Google's
14	21	`Remote Execution API`_ and the `Remote Workers API`_. The project's goal is to
15	22	be able to execute build jobs remotely on a grid of computers in order to
16	23	massively speed up build times. Workers on the grid should be able to run with
17		-different environments. It is designed to work with but not exclusively
	24	+different environments. It is designed to work with clients such as `Bazel`_ and
18	25	`BuildStream`_.
19	26
20	27	.. _Remote Execution API: https://github.com/bazelbuild/remote-apis
21	28	.. _Remote Workers API: https://docs.google.com/document/d/1s_AzRRD2mdyktKUj2HWBn99rMg_3tcPvdjx3MPbFidU/edit#heading=h.1u2taqr2h940
22	29	.. _BuildStream: https://wiki.gnome.org/Projects/BuildStream
	30	+.. _Bazel: https://bazel.build
23	31
24	32
25	33	.. _getting-started:
...	...	@@ -40,10 +48,15 @@ instructions.
40	48	Resources
41	49	---------
42	50
43		-- Homepage: https://buildgrid.build
44		-- GitLab repository: https://gitlab.com/BuildGrid/buildgrid
45		-- Bug tracking: https://gitlab.com/BuildGrid/buildgrid/issues
46		-- Mailing list: https://lists.buildgrid.build/cgi-bin/mailman/listinfo/buildgrid
47		-- Slack channel: https://buildteamworld.slack.com/messages/CC9MKC203 [`invite link`_]
48		-
	51	+- `Homepage`_
	52	+- `GitLab repository`_
	53	+- `Bug tracking`_
	54	+- `Mailing list`_
	55	+- `Slack channel`_ [`invite link`_]
	56	+
	57	+.. _Homepage: https://buildgrid.build
	58	+.. _GitLab repository: https://gitlab.com/BuildGrid/buildgrid
	59	+.. _Bug tracking: https://gitlab.com/BuildGrid/buildgrid/issues
	60	+.. _Mailing list: https://lists.buildgrid.build/cgi-bin/mailman/listinfo/buildgrid
	61	+.. _Slack channel: https://buildteamworld.slack.com/messages/CC9MKC203
49	62	.. _invite link: https://join.slack.com/t/buildteamworld/shared_invite/enQtMzkxNzE0MDMyMDY1LTRmZmM1OWE0OTFkMGE1YjU5Njc4ODEzYjc0MGMyOTM5ZTQ5MmE2YTQ1MzQwZDc5MWNhODY1ZmRkZTE4YjFhNjU

buildgrid/bot/bot_session.py

---

...	...	@@ -99,13 +99,13 @@ class BotSession:
99	99	session = self._interface.create_bot_session(self._parent, self.get_pb2())
100	100	self._name = session.name
101	101
102		- self.logger.info("Created bot session with name: {}".format(self._name))
	102	+ self.logger.info("Created bot session with name: [{}]".format(self._name))
103	103
104	104	for lease in session.leases:
105	105	self._update_lease_from_server(lease)
106	106
107	107	def update_bot_session(self):
108		- self.logger.debug("Updating bot session: {}".format(self._bot_id))
	108	+ self.logger.debug("Updating bot session: [{}]".format(self._bot_id))
109	109	session = self._interface.update_bot_session(self.get_pb2())
110	110	for k, v in list(self._leases.items()):
111	111	if v.state == LeaseState.COMPLETED.value:
...	...	@@ -141,12 +141,12 @@ class BotSession:
141	141	asyncio.ensure_future(self.create_work(lease))
142	142
143	143	async def create_work(self, lease):
144		- self.logger.debug("Work created: {}".format(lease.id))
	144	+ self.logger.debug("Work created: [{}]".format(lease.id))
145	145
146	146	loop = asyncio.get_event_loop()
147	147	lease = await loop.run_in_executor(None, self._work, self._context, lease)
148	148
149		- self.logger.debug("Work complete: {}".format(lease.id))
	149	+ self.logger.debug("Work complete: [{}]".format(lease.id))
150	150	self.lease_completed(lease)
151	151
152	152
...	...	@@ -161,14 +161,14 @@ class Worker:
161	161	if k == 'pool':
162	162	self.properties[k] = v
163	163	else:
164		- raise KeyError('Key not supported: {}'.format(k))
	164	+ raise KeyError('Key not supported: [{}]'.format(k))
165	165
166	166	if configs:
167	167	for k, v in configs.items():
168	168	if k == 'DockerImage':
169	169	self.configs[k] = v
170	170	else:
171		- raise KeyError('Key not supported: {}'.format(k))
	171	+ raise KeyError('Key not supported: [{}]'.format(k))
172	172
173	173	@property
174	174	def configs(self):
...	...	@@ -214,11 +214,11 @@ class Device:
214	214
215	215	elif k == 'docker':
216	216	if v not in ('True', 'False'):
217		- raise ValueError('Value not supported: {}'.format(v))
	217	+ raise ValueError('Value not supported: [{}]'.format(v))
218	218	self._properties[k] = v
219	219
220	220	else:
221		- raise KeyError('Key not supported: {}'.format(k))
	221	+ raise KeyError('Key not supported: [{}]'.format(k))
222	222
223	223	@property
224	224	def name(self):

buildgrid/server/actioncache/service.py

---

...	...	@@ -77,4 +77,4 @@ class ActionCacheService(remote_execution_pb2_grpc.ActionCacheServicer):
77	77	return self._instances[instance_name]
78	78
79	79	except KeyError:
80		- raise InvalidArgumentError("Invalid instance name: {}".format(instance_name))
	80	+ raise InvalidArgumentError("Invalid instance name: [{}]".format(instance_name))

buildgrid/server/bots/instance.py

---

...	...	@@ -60,7 +60,7 @@ class BotsInterface:
60	60
61	61	self._bot_ids[name] = bot_id
62	62	self._bot_sessions[name] = bot_session
63		- self.logger.info("Created bot session name={} with bot_id={}".format(name, bot_id))
	63	+ self.logger.info("Created bot session name=[{}] with bot_id=[{}]".format(name, bot_id))
64	64
65	65	for lease in self._scheduler.create_leases():
66	66	bot_session.leases.extend([lease])
...	...	@@ -92,7 +92,7 @@ class BotsInterface:
92	92	try:
93	93	server_lease = self._scheduler.get_job_lease(client_lease.id)
94	94	except KeyError:
95		- raise InvalidArgumentError("Lease not found on server: {}".format(client_lease))
	95	+ raise InvalidArgumentError("Lease not found on server: [{}]".format(client_lease))
96	96
97	97	server_state = LeaseState(server_lease.state)
98	98	client_state = LeaseState(client_lease.state)
...	...	@@ -105,7 +105,7 @@ class BotsInterface:
105	105	# TODO: Lease was rejected
106	106	raise NotImplementedError("'Not Accepted' is unsupported")
107	107	else:
108		- raise OutofSyncError("Server lease: {}. Client lease: {}".format(server_lease, client_lease))
	108	+ raise OutofSyncError("Server lease: [{}]. Client lease: [{}]".format(server_lease, client_lease))
109	109
110	110	elif server_state == LeaseState.ACTIVE:
111	111
...	...	@@ -118,10 +118,10 @@ class BotsInterface:
118	118	return None
119	119
120	120	else:
121		- raise OutofSyncError("Server lease: {}. Client lease: {}".format(server_lease, client_lease))
	121	+ raise OutofSyncError("Server lease: [{}]. Client lease: [{}]".format(server_lease, client_lease))
122	122
123	123	elif server_state == LeaseState.COMPLETED:
124		- raise OutofSyncError("Server lease: {}. Client lease: {}".format(server_lease, client_lease))
	124	+ raise OutofSyncError("Server lease: [{}]. Client lease: [{}]".format(server_lease, client_lease))
125	125
126	126	elif server_state == LeaseState.CANCELLED:
127	127	raise NotImplementedError("Cancelled states not supported yet")
...	...	@@ -138,19 +138,19 @@ class BotsInterface:
138	138	if name is not None:
139	139	_bot_id = self._bot_ids.get(name)
140	140	if _bot_id is None:
141		- raise InvalidArgumentError('Name not registered on server: {}'.format(name))
	141	+ raise InvalidArgumentError('Name not registered on server: [{}]'.format(name))
142	142	elif _bot_id != bot_id:
143	143	self._close_bot_session(name)
144	144	raise InvalidArgumentError(
145		- 'Bot id invalid. ID sent: {} with name: {}.'
146		- 'ID registered: {} for that name'.format(bot_id, name, _bot_id))
	145	+ 'Bot id invalid. ID sent: [{}] with name: [{}].'
	146	+ 'ID registered: [{}] for that name'.format(bot_id, name, _bot_id))
147	147	else:
148	148	for _name, _bot_id in self._bot_ids.items():
149	149	if bot_id == _bot_id:
150	150	self._close_bot_session(_name)
151	151	raise InvalidArgumentError(
152		- 'Bot id already registered. ID sent: {}.'
153		- 'Id registered: {} with name: {}'.format(bot_id, _bot_id, _name))
	152	+ 'Bot id already registered. ID sent: [{}].'
	153	+ 'Id registered: [{}] with name: [{}]'.format(bot_id, _bot_id, _name))
154	154
155	155	def _close_bot_session(self, name):
156	156	""" Before removing the session, close any leases and
...	...	@@ -159,14 +159,14 @@ class BotsInterface:
159	159	bot_id = self._bot_ids.get(name)
160	160
161	161	if bot_id is None:
162		- raise InvalidArgumentError("Bot id does not exist: {}".format(name))
	162	+ raise InvalidArgumentError("Bot id does not exist: [{}]".format(name))
163	163
164		- self.logger.debug("Attempting to close {} with name: {}".format(bot_id, name))
	164	+ self.logger.debug("Attempting to close [{}] with name: [{}]".format(bot_id, name))
165	165	for lease in self._bot_sessions[name].leases:
166	166	if lease.state != LeaseState.COMPLETED.value:
167	167	# TODO: Be wary here, may need to handle rejected leases in future
168	168	self._scheduler.retry_job(lease.id)
169	169
170		- self.logger.debug("Closing bot session: {}".format(name))
	170	+ self.logger.debug("Closing bot session: [{}]".format(name))
171	171	self._bot_ids.pop(name)
172		- self.logger.info("Closed bot {} with name: {}".format(bot_id, name))
	172	+ self.logger.info("Closed bot [{}] with name: [{}]".format(bot_id, name))

buildgrid/server/bots/service.py

---

...	...	@@ -90,4 +90,4 @@ class BotsService(bots_pb2_grpc.BotsServicer):
90	90	return self._instances[name]
91	91
92	92	except KeyError:
93		- raise InvalidArgumentError("Instance doesn't exist on server: {}".format(name))
	93	+ raise InvalidArgumentError("Instance doesn't exist on server: [{}]".format(name))

buildgrid/server/cas/service.py

---

...	...	@@ -70,7 +70,7 @@ class ContentAddressableStorageService(remote_execution_pb2_grpc.ContentAddressa
70	70	return self._instances[instance_name]
71	71
72	72	except KeyError:
73		- raise InvalidArgumentError("Invalid instance name: {}".format(instance_name))
	73	+ raise InvalidArgumentError("Invalid instance name: [{}]".format(instance_name))
74	74
75	75
76	76	class ByteStreamService(bytestream_pb2_grpc.ByteStreamServicer):
...	...	@@ -89,15 +89,15 @@ class ByteStreamService(bytestream_pb2_grpc.ByteStreamServicer):
89	89	# TODO: Decide on default instance name
90	90	if path[0] == "blobs":
91	91	if len(path) < 3 or not path[2].isdigit():
92		- raise InvalidArgumentError("Invalid resource name: {}".format(request.resource_name))
	92	+ raise InvalidArgumentError("Invalid resource name: [{}]".format(request.resource_name))
93	93	instance_name = ""
94	94
95	95	elif path[1] == "blobs":
96	96	if len(path) < 4 or not path[3].isdigit():
97		- raise InvalidArgumentError("Invalid resource name: {}".format(request.resource_name))
	97	+ raise InvalidArgumentError("Invalid resource name: [{}]".format(request.resource_name))
98	98
99	99	else:
100		- raise InvalidArgumentError("Invalid resource name: {}".format(request.resource_name))
	100	+ raise InvalidArgumentError("Invalid resource name: [{}]".format(request.resource_name))
101	101
102	102	instance = self._get_instance(instance_name)
103	103	yield from instance.read(path,
...	...	@@ -134,15 +134,15 @@ class ByteStreamService(bytestream_pb2_grpc.ByteStreamServicer):
134	134	# TODO: Sort out no instance name
135	135	if path[0] == "uploads":
136	136	if len(path) < 5 or path[2] != "blobs" or not path[4].isdigit():
137		- raise InvalidArgumentError("Invalid resource name: {}".format(first_request.resource_name))
	137	+ raise InvalidArgumentError("Invalid resource name: [{}]".format(first_request.resource_name))
138	138	instance_name = ""
139	139
140	140	elif path[1] == "uploads":
141	141	if len(path) < 6 or path[3] != "blobs" or not path[5].isdigit():
142		- raise InvalidArgumentError("Invalid resource name: {}".format(first_request.resource_name))
	142	+ raise InvalidArgumentError("Invalid resource name: [{}]".format(first_request.resource_name))
143	143
144	144	else:
145		- raise InvalidArgumentError("Invalid resource name: {}".format(first_request.resource_name))
	145	+ raise InvalidArgumentError("Invalid resource name: [{}]".format(first_request.resource_name))
146	146
147	147	instance = self._get_instance(instance_name)
148	148	return instance.write(requests)
...	...	@@ -169,4 +169,4 @@ class ByteStreamService(bytestream_pb2_grpc.ByteStreamServicer):
169	169	return self._instances[instance_name]
170	170
171	171	except KeyError:
172		- raise InvalidArgumentError("Invalid instance name: {}".format(instance_name))
	172	+ raise InvalidArgumentError("Invalid instance name: [{}]".format(instance_name))

buildgrid/server/execution/instance.py

---

...	...	@@ -47,7 +47,7 @@ class ExecutionInstance:
47	47	do_not_cache = action.do_not_cache
48	48
49	49	job = Job(action_digest, do_not_cache, message_queue)
50		- self.logger.info("Operation name: {}".format(job.name))
	50	+ self.logger.info("Operation name: [{}]".format(job.name))
51	51
52	52	self._scheduler.append_job(job, skip_cache_lookup)
53	53
...	...	@@ -58,14 +58,14 @@ class ExecutionInstance:
58	58	self._scheduler.register_client(name, queue)
59	59
60	60	except KeyError:
61		- raise InvalidArgumentError("Operation name does not exist: {}".format(name))
	61	+ raise InvalidArgumentError("Operation name does not exist: [{}]".format(name))
62	62
63	63	def unregister_message_client(self, name, queue):
64	64	try:
65	65	self._scheduler.unregister_client(name, queue)
66	66
67	67	except KeyError:
68		- raise InvalidArgumentError("Operation name does not exist: {}".format(name))
	68	+ raise InvalidArgumentError("Operation name does not exist: [{}]".format(name))
69	69
70	70	def stream_operation_updates(self, message_queue, operation_name):
71	71	operation = message_queue.get()

buildgrid/server/execution/service.py

---

...	...	@@ -92,4 +92,4 @@ class ExecutionService(remote_execution_pb2_grpc.ExecutionServicer):
92	92	return self._instances[name]
93	93
94	94	except KeyError:
95		- raise InvalidArgumentError("Instance doesn't exist on server: {}".format(name))
	95	+ raise InvalidArgumentError("Instance doesn't exist on server: [{}]".format(name))

buildgrid/server/operations/instance.py

---

...	...	@@ -34,7 +34,7 @@ class OperationsInstance:
34	34	operation = self._scheduler.jobs.get(name)
35	35
36	36	if operation is None:
37		- raise InvalidArgumentError("Operation name does not exist: {}".format(name))
	37	+ raise InvalidArgumentError("Operation name does not exist: [{}]".format(name))
38	38
39	39	else:
40	40	return operation.get_operation()
...	...	@@ -49,21 +49,21 @@ class OperationsInstance:
49	49	self._scheduler.jobs.pop(name)
50	50
51	51	except KeyError:
52		- raise InvalidArgumentError("Operation name does not exist: {}".format(name))
	52	+ raise InvalidArgumentError("Operation name does not exist: [{}]".format(name))
53	53
54	54	def register_message_client(self, name, queue):
55	55	try:
56	56	self._scheduler.register_client(name, queue)
57	57
58	58	except KeyError:
59		- raise InvalidArgumentError("Operation name does not exist: {}".format(name))
	59	+ raise InvalidArgumentError("Operation name does not exist: [{}]".format(name))
60	60
61	61	def unregister_message_client(self, name, queue):
62	62	try:
63	63	self._scheduler.unregister_client(name, queue)
64	64
65	65	except KeyError:
66		- raise InvalidArgumentError("Operation name does not exist: {}".format(name))
	66	+ raise InvalidArgumentError("Operation name does not exist: [{}]".format(name))
67	67
68	68	def stream_operation_updates(self, message_queue, operation_name):
69	69	operation = message_queue.get()

buildgrid/server/operations/service.py

---

...	...	@@ -132,4 +132,4 @@ class OperationsService(operations_pb2_grpc.OperationsServicer):
132	132	return self._instances[instance_name]
133	133
134	134	except KeyError:
135		- raise InvalidArgumentError("Instance doesn't exist on server: {}".format(name))
	135	+ raise InvalidArgumentError("Instance doesn't exist on server: [{}]".format(name))

buildgrid/server/referencestorage/service.py

---

...	...	@@ -86,4 +86,4 @@ class ReferenceStorageService(buildstream_pb2_grpc.ReferenceStorageServicer):
86	86	return self._instances[instance_name]
87	87
88	88	except KeyError:
89		- raise InvalidArgumentError("Invalid instance name: {}".format(instance_name))
	89	+ raise InvalidArgumentError("Invalid instance name: [{}]".format(instance_name))

docs/source/index.rst

---

...	...	@@ -24,10 +24,15 @@ Remote execution service implementing Google's REAPI and RWAPI.
24	24	Resources
25	25	---------
26	26
27		-- Homepage: https://buildgrid.build
28		-- GitLab repository: https://gitlab.com/BuildGrid/buildgrid
29		-- Bug tracking: https://gitlab.com/BuildGrid/buildgrid/issues
30		-- Mailing list: https://lists.buildgrid.build/cgi-bin/mailman/listinfo/buildgrid
31		-- Slack channel: https://buildteamworld.slack.com/messages/CC9MKC203 [`invite link`_]
32		-
	27	+- `Homepage`_
	28	+- `GitLab repository`_
	29	+- `Bug tracking`_
	30	+- `Mailing list`_
	31	+- `Slack channel`_ [`invite link`_]
	32	+
	33	+.. _Homepage: https://buildgrid.build
	34	+.. _GitLab repository: https://gitlab.com/BuildGrid/buildgrid
	35	+.. _Bug tracking: https://gitlab.com/BuildGrid/buildgrid/issues
	36	+.. _Mailing list: https://lists.buildgrid.build/cgi-bin/mailman/listinfo/buildgrid
	37	+.. _Slack channel: https://buildteamworld.slack.com/messages/CC9MKC203
33	38	.. _invite link: https://join.slack.com/t/buildteamworld/shared_invite/enQtMzkxNzE0MDMyMDY1LTRmZmM1OWE0OTFkMGE1YjU5Njc4ODEzYjc0MGMyOTM5ZTQ5MmE2YTQ1MzQwZDc5MWNhODY1ZmRkZTE4YjFhNjU

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.