HACKING.rst: Add note about protocol buffers and code generation

1 files changed, 22 insertions, 0 deletions

diff --git a/HACKING.rst b/HACKING.rst
index dd791bd24..5d3ec1834 100644
--- a/HACKING.rst
+++ b/HACKING.rst
@@ -409,6 +409,28 @@ regenerate them locally in order to build the docs.
      command: build hello.bst
 
 
+Protocol Buffers
+----------------
+BuildStream uses protobuf and gRPC for serialization and communication with
+artifact cache servers.  This requires ``.proto`` files and Python code
+generated from the ``.proto`` files using protoc.  All these files live in the
+``buildstream/_protos`` directory.  The generated files are included in the
+git repository to avoid depending on grpcio-tools for user installations.
+
+
+Regenerating code
+~~~~~~~~~~~~~~~~~
+When ``.proto`` files are modified, the corresponding Python code needs to
+be regenerated.  As a prerequisite for code generation you need to install
+``grpcio-tools`` using pip or some other mechanism::
+
+  pip3 install --user grpcio-tools
+
+To actually regenerate the code::
+
+  ./setup.py build_grpc
+
+
 Testing BuildStream
 -------------------
 BuildStream uses pytest for regression tests and testing out