Update Go API installation guide for TensorFlow 2.5.0 (#30)

CODEOWNERS

@@ -4,6 +4,7 @@
 # These should match the Maintainer: line in your README.md
 # Please sort them in alphabetical order.
 /directory_template @angerson @perfinion
+/golang_install_guide @wamuir
 /manylinux_2014_docker_images @sub-mod
 /ppc64le @wdirons
 /tekton @perfinion

README.md

@@ -45,8 +45,8 @@ Want to add your own project to this list? It's easy: check out
 
 ### Language Bindings
 
-* [**Golang Install Guide**](golang_install_guide): TensorFlow's old official
-  docs for installing the (deprecated) Go bindings. Needs an owner.
+* [**Golang Install Guide**](golang_install_guide): Documentation for installing
+  the Go bindings.
 
 ### Platforms
 

golang_install_guide/README.md

 # Golang Install Guide 
 
-TensorFlow's old official docs for installing the (unsupported) Go bindings.
-Needs an owner.
+Documentation for installing the Go bindings for Tensorflow.
 
-Maintainer: @angerson (TensorFlow, SIG Build)
+Maintainer: @wamuir
 
 * * *
 
 **Important: TensorFlow for Go is no longer supported by the
 TensorFlow team.**
 
-**This guide is a mirror of the old official documentation and may not work. If
-you'd like to own this and keep it up-to-date, please file a PR!**
-
 # Install TensorFlow for Go
 
 TensorFlow provides a
@@ -26,35 +22,114 @@ Caution: The TensorFlow Go API is *not* covered by the TensorFlow
 
 ## Supported Platforms
 
-TensorFlow for Go is supported on the following systems:
+The Go bindings for TensorFlow work on the following systems, and likely others:
 
 * Linux, 64-bit, x86
 * macOS, Version 10.12.6 (Sierra) or higher
 
 
-## Setup
+## Installation and Setup
+
+### 1. Install the TensorFlow C library
+
+Install the [TensorFlow C library](https://www.tensorflow.org/install/lang_c). This
+library is required for use of the TensorFlow Go package at runtime. For example,
+on Linux (64-bit, x86):
+
+  ```sh
+  $ curl -L https://storage.googleapis.com/tensorflow/libtensorflow/libtensorflow-cpu-linux-x86_64-2.5.0.tar.gz | tar xz --directory /usr/local
+  $ ldconfig
+  ```
+
+### 2. Install the Protocol Buffer Compiler (Protoc)
+
+Install the [Protocol Buffer Compiler](https://developers.google.com/protocol-buffers).
+This compiler is required to install the Go bindings but is not needed at runtime.
+
+- Linux, using `apt` or `apt-get`, for example:
+
+  ```sh
+  $ apt install -y protobuf-compiler
+  ```
+
+- MacOS, using [Homebrew](https://brew.sh/):
+
+  ```sh
+  $ brew install protobuf
+  ```
+
+### 3. Install and Setup the Tensorflow Go API
+
+***The use of `go get` is not currently supported for installation of the Tensorflow Go API.
+Instead, follow these instructions.***
+
+- Decide on a location to install the API, such as within the `src` folder immediately below
+the Go workspace (e.g., the location of $GOPATH).  The location `/go/src/github.com/tensorflow/tensorflow`
+will be used in these instructions.
+
+- Clone the Tensorflow source respository to the install location
+
+  ```sh
+  $ git clone --branch v2.5.0 https://github.com/tensorflow/tensorflow.git /go/src/github.com/tensorflow/tensorflow
+  ```
+
+- Change the working directory to the install location.
  
-### TensorFlow C library
+   ```sh
+   $ cd /go/src/github.com/tensorflow/tensorflow
+   ```
 
-Install the [TensorFlow C library](https://www.tensorflow.org/install/lang_c) which is required for the
-TensorFlow Go package.
+- Apply a patch to declare the Go package within Tensorflow's proto definition files
 
-### Download
+   ```sh
+   $ git format-patch -1 835d7da --stdout | git apply
+   ```
 
-Download and install the TensorFlow Go package and its dependencies:
+- Initialize a new go.mod file
 
+   ```sh
+   $ go mod init github.com/tensorflow/tensorflow
    ```
-go get github.com/tensorflow/tensorflow/tensorflow/go
+
+- Generate the protocol buffers and move the generating files to their correct locations.  You
+will receive two errors (`no required module provides package ...`), which you can ignore.
+
+   ```sh
+   $ cd tensorflow/go
+   $ go generate ./...
+   $ mv vendor/github.com/tensorflow/tensorflow/tensorflow/go/* .
    ```
 
-And validate your installation:
+- Add missing modules
 
+   ```sh
+   $ go mod tidy
    ```
-go test github.com/tensorflow/tensorflow/tensorflow/go
+
+- Test the installation
+   ```sh
+   $ go test ./...
    ``` 
 
 
-## Build
+## Usage
+
+### Applications must use Go Mod's `replace` directive
+
+The `replace` directive instructs Go to use the local installation.  Point this
+to the installation location (such as `/go/src/github.com/tensorflow/tensorflow`
+from the above installation instructions).
+
+This directive must be added for each Go module that uses the Go API. As an
+example: 
+
+```sh
+$ go mod init hello-world
+$ go mod edit -require github.com/tensorflow/tensorflow@v2.5.0+incompatible
+$ go mod edit -replace github.com/tensorflow/tensorflow=/go/src/github.com/tensorflow/tensorflow
+$ go mod tidy
+```
+
 
 ### Example program
 
@@ -92,12 +167,19 @@ func main() {
 }
 ```
 
-### Run
-
-Run the example program:
+#### Initialize go.mod for the example program:
 
+```sh
+$ go mod init app
+$ go mod edit -require github.com/tensorflow/tensorflow@v2.5.0+incompatible
+$ go mod edit -replace github.com/tensorflow/tensorflow=/go/src/github.com/tensorflow/tensorflow
+$ go mod tidy
 ```
-go run hello_tf.go
+
+#### Then, run the example program:
+
+```sh
+$ go run hello_tf.go
 ```
 
 The command outputs: `Hello from TensorFlow version *number*`
@@ -112,6 +194,19 @@ wasn't compiled to use *Type* instructions, but these are available on your
 machine and could speed up CPU computations.
 ```
 
+## Docker Example
+
+A [Dockerfile is available](https://github.com/tensorflow/build/tree/master/golang_install_guide/example-program),
+which executes the installation and setup process for the Go bindings and
+builds the example program.  To use,
+[install Docker](https://www.docker.com/get-started) and then run the
+following commands:
+
+```sh
+$ docker build -t tensorflow/build:golang-example https://github.com/tensorflow/build.git#:golang_install_guide/example-program
+$ docker run -it --rm tensorflow/build:golang-example
+```
+
 ## Build from source
 
 TensorFlow is open source. Read

golang_install_guide/example-program/Dockerfile

+# Copyright 2021 The TensorFlow Authors. All Rights Reserved.
+#
+# 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.
+# ============================================================================
+
+
+FROM golang:1.16-buster
+
+# 1. Install the TensorFlow C library (v2.5.0)
+RUN curl -L https://storage.googleapis.com/tensorflow/libtensorflow/libtensorflow-cpu-linux-$(uname -m)-2.5.0.tar.gz \
+    | tar xz --directory /usr/local \
+    && ldconfig
+
+# 2. Install the Protocol Buffer Compiler (Protoc)
+RUN apt-get update && apt-get -y install --no-install-recommends \
+    libprotobuf-dev \
+    protobuf-compiler 
+
+# 3. Install and setup the Tensorflow Go API
+RUN git clone --branch v2.5.0 https://github.com/tensorflow/tensorflow.git /go/src/github.com/tensorflow/tensorflow \
+    && cd /go/src/github.com/tensorflow/tensorflow \
+    && git format-patch -1 835d7da --stdout | git apply  \
+    && go mod init github.com/tensorflow/tensorflow \
+    && cd tensorflow/go \
+    && (go generate ./... || true) \
+    && mv vendor/github.com/tensorflow/tensorflow/tensorflow/go/* . \
+    && go mod tidy \
+    && go test ./...
+
+
+# Build example program
+WORKDIR /example-program
+COPY hello_tf.go .
+RUN go mod init app \
+    && go mod edit -require github.com/tensorflow/tensorflow@v2.5.0+incompatible \
+    && go mod edit -replace github.com/tensorflow/tensorflow=/go/src/github.com/tensorflow/tensorflow \
+    && go mod tidy \
+    && go build
+
+
+ENTRYPOINT ["/example-program/app"]

golang_install_guide/example-program/hello_tf.go

+package main
+
+import (
+	tf "github.com/tensorflow/tensorflow/tensorflow/go"
+	"github.com/tensorflow/tensorflow/tensorflow/go/op"
+	"fmt"
+)
+
+func main() {
+	// Construct a graph with an operation that produces a string constant.
+	s := op.NewScope()
+	c := op.Const(s, "Hello from TensorFlow version " + tf.Version())
+	graph, err := s.Finalize()
+	if err != nil {
+		panic(err)
+	}
+
+	// Execute the graph in a session.
+	sess, err := tf.NewSession(graph, nil)
+	if err != nil {
+		panic(err)
+	}
+	output, err := sess.Run(nil, []tf.Output{c}, nil)
+	if err != nil {
+		panic(err)
+	}
+	fmt.Println(output[0].Value())
+}