update readmes and add client examples

remove project local platform targets in favor of using bazel-tools

Author: emacski

.bazelrc

@@ -17,19 +17,20 @@ build --define=use_fast_cpp_protos=true
 build --define=allow_oversize_protos=true
 build --define=grpc_no_ares=true
 
-# build with shared gnu libstdc++ instead of static libc++
-build:gnulibcpp --@com_github_emacski_bazeltools//toolchain/cpp/clang:use_libcpp="libstdc++"
-build:gnulibcpp --cxxopt=-D_GLIBCXX_USE_CXX11_ABI=0
+# platform config groups
 
-build:linux_amd64 --platforms=//:linux_amd64
+build:linux_amd64 --platforms=@com_github_emacski_bazeltools//platform:linux_amd64
+# boringssl requires legacy toolchain resolution
+build:linux_amd64 --crosstool_top=@com_github_emacski_bazeltools//toolchain/cpp/clang:toolchain
+build:linux_amd64 --cpu=k8
 
-build:linux_arm64 --platforms=//:linux_arm64
-# for boringssl
+build:linux_arm64 --platforms=@com_github_emacski_bazeltools//platform:linux_arm64
+# boringssl requires legacy toolchain resolution
 build:linux_arm64 --crosstool_top=@com_github_emacski_bazeltools//toolchain/cpp/clang:toolchain
 build:linux_arm64 --cpu=aarch64
 
-build:linux_arm --platforms=//:linux_arm
-# for boringssl
+build:linux_arm --platforms=@com_github_emacski_bazeltools//platform:linux_arm
+# boringssl requires legacy toolchain resolution
 build:linux_arm --crosstool_top=@com_github_emacski_bazeltools//toolchain/cpp/clang:toolchain
 build:linux_arm --cpu=arm
 

BUILD

@@ -1,39 +1 @@
-# Copyright 2020 Erik Maciejewski
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#    http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-package(default_visibility = ["//visibility:public"])
-
-platform(
-    name = "linux_amd64",
-    constraint_values = [
-        "@platforms//os:linux",
-        "@platforms//cpu:x86_64",
-    ],
-)
-
-platform(
-    name = "linux_arm64",
-    constraint_values = [
-        "@platforms//os:linux",
-        "@platforms//cpu:aarch64",
-    ],
-)
-
-platform(
-    name = "linux_arm",
-    constraint_values = [
-        "@platforms//os:linux",
-        "@platforms//cpu:arm",
-    ],
-)
+# intentionally blank

README.md

@@ -9,14 +9,55 @@ standalone grpc api clients targeting popular arm architectures from an x86_64 h
 Currently, client libraries can be cross-built for c++, python and go targeting
 `linux_amd64`, `linux_arm64` and `linux_arm`.
 
+## Contents
+* [Cross-Building](#cross-building)
+* [Project Artifacts](#project-artifacts)
+* [Client Examples](#client-examples)
+
+## Cross-Building
+
+Using the project's development docker image, all platform specific targets in this
+project can be cross-built, from an x86_64 host, for the following platforms by
+specifying the corresponding config group when building.
+
+| Config Group | CLI Option |
+|--------------|----------|
+| `linux_amd64` | `--config=linux_amd64` |
+| `linux_arm64` | `--config=linux_arm64` |
+| `linux_arm` | `--config=linux_arm` |
+
+Docker Devel Image
+```sh
+git clone git@github.com:emacski/tensorflow-serving-arm-client.git
+cd tensorflow-serving-arm-client
+# devel image includes all necessary deps to build and run project targets
+docker run --rm -ti \
+    -w /tensorflow-serving-arm-client \
+    -v $PWD:/tensorflow-serving-arm-client \
+    emacski/tensorflow-serving-arm-client:latest-devel /bin/bash
+```
+
+Examples
+```sh
+# build platform wheel for 32-bit arm
+bazel run //py/wheel:build_platform --config=linux_arm
+# build go client library for amd64
+bazel build //py:tensorflow_serving --config=linux_amd64
+# build go client library for arm64
+bazel build //go:tensorflow_serving --config=linux_arm64
+```
+
+[Back to Top](#contents)
+
 ## Project Artifacts
 ### Python3 Client Library (Wheels)
 
-Currently, platform specific wheels are published for CPython 3.7 on
-`linux_amd64`, `linux_arm64` and `linux_arm`. These wheels are full self-contained
-grpc client libs and include the `tensorflow_serving`, (protobuf only) `tensorflow`,
-`grpcio` and `protobuf` py packages with corresponding extensions where applicable
-(no compiling or dev-tools required on the install host).
+Platform specific wheels are published for the current version of python 3
+on debian 10 (CPython 3.7) targeting `linux_amd64`, `linux_arm64` and `linux_arm`.
+These wheels are full self-contained grpc client libs and include the
+`tensorflow_serving`, (protobuf only) `tensorflow`, `grpcio` and `protobuf` py
+packages with corresponding extensions where applicable (no compiling or dev-tools
+required on the install host).
 
 Additionally, a pure python3 wheel is published that includes the `tensorflow_serving`,
 (protobuf only) `tensorflow` packages and depends on external `grpcio` and
@@ -30,7 +71,7 @@ pip install https://github.com/emacski/tensorflow-serving-arm-client/releases/do
 pip install https://github.com/emacski/tensorflow-serving-arm-client/releases/download/2.4.1/tensorflow_serving_arm_client-2.4.1-cp37-none-manylinux2014_aarch64.whl
 # on linux_arm python 3.7
 pip install https://github.com/emacski/tensorflow-serving-arm-client/releases/download/2.4.1/tensorflow_serving_arm_client-2.4.1-cp37-none-manylinux2014_armv7l.whl
-# pure python 3 (will also install grpcio and protobuf pypi packages)
+# pure python 3 (will require grpcio and protobuf pypi packages)
 pip install https://github.com/emacski/tensorflow-serving-arm-client/releases/download/2.4.1/tensorflow_serving_arm_client-2.4.1-py3-none-any.whl
 ```
 
@@ -43,14 +84,66 @@ cd tensorflow-serving-arm-client
 docker run --rm -ti \
     -w /tensorflow-serving-arm-client \
     -v $PWD:/tensorflow-serving-arm-client \
-    emacski/tensorflow-serving:latest-devel /bin/bash
+    emacski/tensorflow-serving-arm-client:latest-devel /bin/bash
 ```
 By default, wheel artifacts will be output to the workspace root
 ```sh
 # pure python
 bazel run //py/wheel:build_pure
-# with extension
+# with platform specific deps
 bazel run //py/wheel:build_platform --config=linux_amd64
 bazel run //py/wheel:build_platform --config=linux_arm64
 bazel run //py/wheel:build_platform --config=linux_arm
 ```
+
+[Back to Top](#contents)
+
+## Client Examples
+
+The client examples are designed to query the same model in the official tensorflow serving example
+[TensorFlow Serving with Docker](https://www.tensorflow.org/tfx/serving/docker) using the predict API.
+
+### Model Server Example
+Reference instructions for setting up [TensorFlow Serving with Docker](https://www.tensorflow.org/tfx/serving/docker),
+substituting the `docker run` command for the one below:
+```sh
+# this version includes the addition of mapping the grpc port (8500) to the host
+docker run -t --rm -p 8501:8501 -p 8500:8500 \
+    -v "$TESTDATA/saved_model_half_plus_two_cpu:/models/half_plus_two" \
+    -e MODEL_NAME=half_plus_two \
+    tensorflow/serving &
+```
+
+### gRPC Client Examples
+```sh
+git clone git@github.com:emacski/tensorflow-serving-arm-client.git
+cd tensorflow-serving-arm-client
+# devel env image includes all deps to build and run examples
+docker run --rm -ti \
+    -w /tensorflow-serving-arm-client \
+    -v $PWD:/tensorflow-serving-arm-client \
+    emacski/tensorflow-serving-arm-client:latest-devel /bin/bash
+
+# client examples accept exactly one command-line argument in the form of:
+# <model_server_host>:<model_server_port>
+
+# python
+bazel run //py/example:half_plus_two -- host.docker.internal:8500
+# or
+bazel build //py/example:half_plus_two
+./bazel-bin/py/example/half_plus_two host.docker.internal:8500
+
+# cc
+bazel run //cc/example:half_plus_two -- host.docker.internal:8500
+# or
+bazel build //cc/example:half_plus_two
+./bazel-bin/cc/example/half_plus_two host.docker.internal:8500
+
+# go
+bazel run //go/example:half_plus_two -- host.docker.internal:8500
+# or
+bazel build //go/example:half_plus_two
+./bazel-bin/go/example/half_plus_two host.docker.internal:8500
+```
+
+[Back to Top](#contents)

WORKSPACE

@@ -18,9 +18,9 @@ load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
 
 http_archive(
     name = "com_github_emacski_bazeltools",
-    sha256 = "ac040d00f7f00c9947d61c7b8970a877d907c92e088966c24a0eaeeba5551b19",
-    strip_prefix = "bazel-tools-250e4a98908fa0c6631ebccdeae930a60fd4c0d5",
-    urls = ["https://github.com/emacski/bazel-tools/archive/250e4a98908fa0c6631ebccdeae930a60fd4c0d5.tar.gz"],
+    sha256 = "ef868ef493a8fc9609a32093a90b57f320646fa5af3b3eb49bb7380f5e0580c6",
+    strip_prefix = "bazel-tools-9cbf59fc288489ab3c7e42ed124507e1b1adba3a",
+    urls = ["https://github.com/emacski/bazel-tools/archive/9cbf59fc288489ab3c7e42ed124507e1b1adba3a.tar.gz"],
 )
 
 register_toolchains("@com_github_emacski_bazeltools//toolchain/cpp/clang:all")

cc/README.md

@@ -0,0 +1,72 @@
+C++ Client
+==========
+
+## Bazel Workspace
+
+`WORKSPACE` Dependencies
+```python
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+
+http_archive(
+    name = "com_github_emacski_bazeltools",
+    sha256 = "ef868ef493a8fc9609a32093a90b57f320646fa5af3b3eb49bb7380f5e0580c6",
+    strip_prefix = "bazel-tools-9cbf59fc288489ab3c7e42ed124507e1b1adba3a",
+    urls = ["https://github.com/emacski/bazel-tools/archive/9cbf59fc288489ab3c7e42ed124507e1b1adba3a.tar.gz"],
+)
+
+# OPTIONAL: only required if using the cross-build cc toolchain
+register_toolchains("@com_github_emacski_bazeltools//toolchain/cpp/clang:all")
+
+http_archive(
+    name = "com_github_emacski_tensorflowservingarmclient",
+    sha256 = "[BAZEL_HTTP_ARCHIVE_SHA]",
+    strip_prefix = "tensorflow-serving-arm-client-[GIT_COMMIT_SHA]",
+    urls = ["https://github.com/emacski/tensorflow-serving-arm-client/archive/[GIT_COMMIT_SHA].tar.gz"],
+)
+
+http_archive(
+    name = "com_github_grpc_grpc",
+    sha256 = "bb6de0544adddd54662ba1c314eff974e84c955c39204a4a2b733ccd990354b7",
+    strip_prefix = "grpc-1.36.3",
+    urls = ["https://github.com/grpc/grpc/archive/v1.36.3.tar.gz"],
+)
+
+load("@com_github_grpc_grpc//bazel:grpc_deps.bzl", "grpc_deps")
+
+grpc_deps()
+
+load("@com_github_grpc_grpc//bazel:grpc_extra_deps.bzl", "grpc_extra_deps")
+
+grpc_extra_deps()
+```
+
+Bazel Build Options
+```sh
+# grpc
+--define=grpc_no_ares=true
+```
+
+Optional Bazel Build Options
+(only required if using the cross-build cc toolchain)
+```sh
+# enable proper toolchain resolution
+--incompatible_enable_cc_toolchain_resolution
+
+# amd64 (x86_64)
+--platforms=@com_github_emacski_bazeltools//platform:linux_amd64
+# some deps still require legacy toolchain resolution
+--crosstool_top=@com_github_emacski_bazeltools//toolchain/cpp/clang:toolchain
+--cpu=k8
+
+# arm64 (aarch64)
+--platforms=@com_github_emacski_bazeltools//platform:linux_arm64
+# some deps still require legacy toolchain resolution
+--crosstool_top=@com_github_emacski_bazeltools//toolchain/cpp/clang:toolchain
+--cpu=aarch64
+
+# arm (armhf)
+--platforms=@com_github_emacski_bazeltools//platform:linux_arm
+# some deps still require legacy toolchain resolution
+--crosstool_top=@com_github_emacski_bazeltools//toolchain/cpp/clang:toolchain
+--cpu=arm
+```

cc/example/BUILD

@@ -0,0 +1,28 @@
+# Copyright 2021 Erik Maciejewski
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+load("@rules_cc//cc:defs.bzl", "cc_binary", "cc_library")
+
+cc_binary(
+    name = "half_plus_two",
+    deps = [":half_plus_two_library"],
+)
+
+cc_library(
+    name = "half_plus_two_library",
+    srcs = ["half_plus_two.cc"],
+    deps = [
+        "@com_github_emacski_tensorflowservingarmclient//cc:tensorflow_serving",
+    ],
+)

cc/example/half_plus_two.cc

@@ -0,0 +1,69 @@
+// Copyright 2021 Erik Maciejewski
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <iostream>
+#include <string>
+#include <vector>
+
+#include "grpcpp/grpcpp.h"
+#include "tensorflow/core/framework/types.pb.h"
+#include "tensorflow/core/framework/tensor.pb.h"
+#include "tensorflow_serving/apis/prediction_service.grpc.pb.h"
+
+using namespace tensorflow::serving;
+
+int main(int argc, char* argv[]) {
+    if (argc != 2) {
+        std::cout << "error: only 1 argument accepted" << std::endl;
+        return 1;
+    }
+
+    const std::string server_host_port = argv[1];
+
+    std::unique_ptr<PredictionService::Stub> stub;
+    stub = PredictionService::NewStub(grpc::CreateChannel(
+      server_host_port, grpc::InsecureChannelCredentials()));
+
+    // same example inputs from https://www.tensorflow.org/tfx/serving/docker
+    std::vector<float> inputs = {1.0, 2.0, 5.0};
+
+    std::unique_ptr<tensorflow::TensorProto> input_tensor;
+    input_tensor = std::make_unique<tensorflow::TensorProto>();
+
+    input_tensor->mutable_tensor_shape()->add_dim()->set_size(inputs.size());
+    input_tensor->set_dtype(tensorflow::DataType::DT_FLOAT);
+
+    for (auto i = inputs.begin(); i != inputs.end(); i++) {
+        input_tensor->add_float_val(*i);
+    }
+
+    std::unique_ptr<PredictRequest> req = std::make_unique<PredictRequest>();
+
+    req->mutable_model_spec()->set_name("half_plus_two");
+    req->mutable_model_spec()->set_signature_name("serving_default");
+    (*req->mutable_inputs())["x"] = *input_tensor;
+
+    PredictResponse res;
+    grpc::ClientContext ctx;
+
+    grpc::Status status = stub->Predict(&ctx, *req, &res);
+
+    if (status.ok()) {
+        std::cout << res.DebugString() << std::endl;
+    } else {
+        std::cout << status.error_code() << ": " << status.error_message() << std::endl;
+    }
+
+    return 0;
+}