More explanations in README.md; update build-cpp-protos.sh to the lat… (

deephaven#4054)

* More explanations in README.md; update build-cpp-protos.sh to the latest build-dependencies.sh changes.

* Tweaks.

* Followup to review comment from Corey.

cpp-client/README.md

@@ -38,13 +38,15 @@ C++ compiler and tool suite (cmake etc).
    support tests runs; that's why it lives in a separate repo).
    The script downloads, builds and installs the dependent libraries
    (Protobuf, re2, gflags, absl, flatbuffers, c-ares, zlib, gRPC, and Arrow).
+   Decide on a directory for the dependencies to live (eg, "$HOME/dhcpp").
+   Create that directory and save the script there.
+
    Edit your local copy of the script if necessary to reflect your selection
    of build tools and build target;
    defaults point to Ubuntu system's g++, cmake, and a Debug build target for cmake.
    Comments in the script will help you in identifying customization points.
-   Decide on a directory for the dependencies to live (eg, "$HOME/dhcpp").
-   Create that directory, and run your local copy of `build-dependencies.sh` from
-   that directory.
+   Note however that defaults are tested by any deviation from defaults may require
+   manual modification of other files later, when building the C++ client proper.
 
    Example:
    ```
@@ -56,10 +58,36 @@ C++ compiler and tool suite (cmake etc).
    wget https://github.com/deephaven/deephaven-base-images/raw/main/cpp-client/build-dependencies.sh
    chmod +x ./build-dependencies.sh
    # Maybe edit build-dependencies.sh to reflect choices of build tools and build target, if you
-   # want anything different than defaults; defaults should work fine for supported platforms.
-   ./build-dependencies.sh
+   # want anything different than defaults; defaults are tested to work,
+   # any deviation from defaults may require changing other files later.
+   # Below we save the output of the script to keep a record of the commands ran during the build.
+   ./build-dependencies.sh 2>&1 | tee build-dependencies.log
    ```
 
+   The execution of `build-dependencies.sh` will create, on the
+   directory it is run, subdirectories `local` and `src` and a file
+   `env.sh`.  The `local` directory will contain the installation of
+   each dependent library (eg, `local/grpc` would be the location of
+   the grpc installation, etc).  The `src` directory is where the
+   sources for the libraries will be downloaded, cloned from their
+   github repositories.  You can ask `build-dependencies.sh` to remove
+   the downloaded sources once the libraries have been built by
+   passing to it the `--clean` flag.  The default cmake build target is `Debug`,
+   which would make it useful to keep the downloaded sources for
+   debug/development purposes.  If `Release` versions are preferred,
+   an environment variable `BUILD_TYPE` set to `Release` can be used
+   to override the `Debug` default, but note that some libraries change their
+   name (eg, `libprotobufd.a` versus `libprotobuf.a`) when compiled for
+   a release version, which may conflict with assumptions elsewhere
+   and may require manual modifications in other parts of the build
+   (if this is your first time building, we suggest you stick with defaults).
+
+   The `env.sh` file contains environment variable definitions in bourne
+   shell syntax (compatible with bash) that will indicate to cmake
+   the location of the libraries just built, via definition of a suitable
+   `CMAKE_PREFIX_PATH`.  This file is intended to be `source`'d
+   from a shell where you plan to build the C++ client.
+
 7. Build and install Deephaven C++ client.  Running `build-dependencies.sh` should have
    created an `env.sh` file that we source below to set relevant environment variables for
    the build.
@@ -89,3 +117,15 @@ C++ compiler and tool suite (cmake etc).
     cmake .. && make -j$NCPUS
     ./tests
     ```
+
+# Updating proto generated C++ stubs (intended for developers)
+   1. Ensure you have a local installation of the dependent libraries
+      as described earlier in this document.  Source the `env.sh`
+      file to ensure you have the correct environment variable definitions
+      in your shell for the steps below.
+
+   2. In the `proto/proto-backend-grpc/src/main/proto` directory
+      (relative from your deephave-core clone base directory),
+      run the `build-cpp-protos.sh` script.
+      This should generate up-to-date versions of the C++ stubs
+      according to the proto sources on the same clone.

proto/proto-backplane-grpc/src/main/proto/build-cpp-protos.sh

@@ -1,9 +1,10 @@
 #!/bin/bash
 
-: ${DHDEPS_HOME:=$HOME/dhcpp}
+set -euxo pipefail
+
+: ${DHCPP_LOCAL:=$HOME/dhcpp/local}
 : ${CPP_PROTO_BUILD_DIR:=build}
 
-set -eux
 mkdir -p "${CPP_PROTO_BUILD_DIR}"
-$DHDEPS_HOME/local/protobuf/bin/protoc `find . -name \*.proto` --cpp_out=${CPP_PROTO_BUILD_DIR} --grpc_out=${CPP_PROTO_BUILD_DIR} --plugin=protoc-gen-grpc=$DHDEPS_HOME/local/grpc/bin/grpc_cpp_plugin
-mv ${CPP_PROTO_BUILD_DIR}/deephaven/proto/*.{h,cc} ../../../../../cpp-client/deephaven/client/proto/deephaven/proto
+$DHCPP_LOCAL/protobuf/bin/protoc `find . -name \*.proto` --cpp_out=${CPP_PROTO_BUILD_DIR} --grpc_out=${CPP_PROTO_BUILD_DIR} --plugin=protoc-gen-grpc=$DHCPP_LOCAL/grpc/bin/grpc_cpp_plugin
+mv -f ${CPP_PROTO_BUILD_DIR}/deephaven/proto/*.{h,cc} ../../../../../cpp-client/deephaven/client/proto/deephaven/proto