[v2] doc: bitbake-user-manual: expand BB_HASHSERVE and document BB_HASHSERVE_UPSTREAM

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 .../bitbake-user-manual-ref-variables.rst     | 23 +++++++++++++++++--
 1 file changed, 21 insertions(+), 2 deletions(-)

Hi Michael,

On December 16, 2021 10:52:04 AM GMT+01:00, Michael Opdenacker <michael.opdenacker@bootlin.com> wrote:
>Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
>---
> .../bitbake-user-manual-ref-variables.rst     | 23 +++++++++++++++++--
> 1 file changed, 21 insertions(+), 2 deletions(-)
>
>diff --git a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
>index bb996e84..fdcd08d8 100644
>--- a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
>+++ b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
>@@ -374,12 +374,31 @@ overview of their function and contents.
>       Specifies the Hash Equivalence server to use.
> 
>       If set to ``auto``, BitBake automatically starts its own server
>-      over a UNIX domain socket.
>+      over a UNIX domain socket. An option is to connect this server
>+      to an upstream one, by setting :term:`BB_HASHSERVE_UPSTREAM`.
> 
>-      If set to ``host:port``, BitBake will use a remote server on the
>+      If set to ``unix://path``, BitBake will connect to an existing a

s/a//

>+      hash server available over a UNIX domain socket.
>+
>+      If set to ``host:port``, BitBake will connect to a remote server on the
>       specified host. This allows multiple clients to share the same
>       hash equivalence data.
> 
>+      This last kind of server can be started manually through

s/This last kind of server/The remote server/

>+      the ``bin/bitbake-hashserv`` script provided by BitBake,
>+      which supports UNIX domain sockets too.
>+
>+   :term:`BB_HASHSERVE_UPSTREAM`
>+      Specifies an upstream Hash Equivalence server.
>+
>+      This optional setting is only useful when a local Hash Equivalence
>+      server is started (setting :term:`BB_HASHSERVE` to ``auto``),
>+      and you wish the local server to query an upstream server for
>+      Hash Equivalence data.
>+
>+      Example usage::

Do we not need a newline after the ::?

>+         BB_HASHSERVE_UPSTREAM = "typhoon.yocto.io:8687"
>+

Is this the address of an actual hashserver? Is this supposed to be used? Is it able to handle many requests? Basically asking if we should have a real hashserver here?

Cheers,
Quentin

Hi Quentin,

Many thanks for the review!

On 12/16/21 6:32 PM, Quentin Schulz wrote:
>
>>
>> -      If set to ``host:port``, BitBake will use a remote server on the
>> +      If set to ``unix://path``, BitBake will connect to an existing a
> s/a//

Fixed.
>
>
>
> +      This last kind of server can be started manually through
> s/This last kind of server/The remote server/


Much better, adopted!

>
>
> +
> +      Example usage::
> Do we not need a newline after the ::?


Oops yes, otherwise the rendering is different.

>
>> +         BB_HASHSERVE_UPSTREAM = "typhoon.yocto.io:8687"
>> +
> Is this the address of an actual hashserver? Is this supposed to be used? Is it able to handle many requests? Basically asking if we should have a real hashserver here?


Yes, that's the server proposed in Poky's
meta-poky/conf/local.conf.sample file, though it is commented out by
default.
We talked about that in a meeting, and if I recall correctly, we agreed
to document its usage, but not turn it on by default. Effectively, if
everyone starts using it at the same time, runs could become slower than
if the corresponding artifacts were built locally.

There's a proper warning in my patch, anyway.

Don't hesitate to disagree, that's not too late!

Thanks again
Michael.