rust: add minimal complete Rust toolchain (#4279)

Summary:
This patch includes:

  - a WORKSPACE dependency on `rules_rust`;
  - a sample Rust library, with tests and doctests;
  - a sample Rust binary that depends on the library;
  - third-party Rust deps with build files generated by `cargo raze`;
  - a build structure that works with both Bazel and Cargo;
  - documentation.

Test Plan:
First, run Bazel tests:

```
bazel test //tensorboard/data/server/...
```

Note that if you change the `assert_eq!` in `lib.rs`’s docstring, the
doc test fails, and if you change its `#[test]` assertions, then the
normal test fails.

Then, run the binary:

```
bazel run //tensorboard/data/server
```

…and note that it prints `2 + 2 = 4`, thanks to our helpful library.

Next, `cd` into `tensorboard/data/server/` and note that `cargo run` and
`cargo test` still work, just as in a normal Rust toolchain. If you use
`rust-analyzer`, it should pick up this project automatically.

Googlers, see <http://cl/340933226> for Copybara changes.

wchargin-branch: rust-toolchain

Author: wchargin

Diff for: .gitattributes

@@ -0,0 +1 @@
+third_party/rust/** -diff -merge linguist-generated=true

Diff for: WORKSPACE

@@ -107,6 +107,17 @@ load("@upb//bazel:repository_defs.bzl", "bazel_version_repository")
 
 bazel_version_repository(name = "bazel_version")
 
+http_archive(
+    name = "io_bazel_rules_rust",
+    sha256 = "9beda941ab076d15428d8615475329bd65002a13a26c2837932af0fb3dc582c5",
+    strip_prefix = "rules_rust-9426a3820093e75ea07d14f875e42f789632507f",
+    urls = [
+        # Master branch as of 2020-10-23
+        "http://mirror.tensorflow.org/github.com/bazelbuild/rules_rust/archive/9426a3820093e75ea07d14f875e42f789632507f.tar.gz",
+        "https://github.com/bazelbuild/rules_rust/archive/9426a3820093e75ea07d14f875e42f789632507f.tar.gz",
+    ],
+)
+
 # Please add all new dependencies in workspace.bzl.
 load("//third_party:workspace.bzl", "tensorboard_workspace")
 tensorboard_workspace()

Diff for: tensorboard/data/server/.gitignore

@@ -0,0 +1,16 @@
+# Copyright 2020 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.
+# ==============================================================================
+
+target/

Diff for: tensorboard/data/server/BUILD

@@ -0,0 +1,33 @@
+load("@io_bazel_rules_rust//rust:rust.bzl", "rust_binary", "rust_doc_test", "rust_library", "rust_test")
+
+package(default_visibility = ["//tensorboard:internal"])
+
+licenses(["notice"])
+
+rust_library(
+    name = "rustboard_core",
+    srcs = [
+        "lib.rs",
+    ],
+    edition = "2018",
+)
+
+rust_test(
+    name = "rustboard_core_test",
+    crate = ":rustboard_core",
+)
+
+rust_doc_test(
+    name = "rustboard_core_doc_test",
+    dep = ":rustboard_core",
+)
+
+rust_binary(
+    name = "server",
+    srcs = ["main.rs"],
+    edition = "2018",
+    deps = [
+        ":rustboard_core",
+        "//third_party/rust:byteorder",
+    ],
+)

Diff for: tensorboard/data/server/Cargo.lock

@@ -0,0 +1,37 @@
+# Copyright 2020 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.
+# ==============================================================================
+
+[package]
+name = "rustboard"
+version = "0.1.0"
+authors = ["The TensorFlow Authors <[email protected]>"]
+edition = "2018"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+byteorder = "1.3.4"
+
+[[bin]]
+name = "rustboard"
+path = "main.rs"
+
+[lib]
+name = "rustboard_core"
+path = "lib.rs"
+
+[raze]
+workspace_path = "//third_party/rust"
+genmode = "Remote"

Diff for: tensorboard/data/server/Cargo.toml

@@ -0,0 +1,76 @@
+# Using Rust in TensorBoard
+
+## Building
+
+The `//tensorboard/data/server` package can be built with Bazel. It builds
+hermetically and with no additional setup. If you like using `bazel build`,
+`bazel run`, and `bazel test`, you can stop reading now.
+
+This package can also be built with Cargo, the standard Rust toolchain. You
+might want to use Cargo:
+
+-   …to use the `rust-analyzer` language server in your editor of choice.
+-   …to use tools like `cargo clippy` (a linter) or `cargo geiger` (an auditor
+    for unsafe code) or `cargo tree` (to show the crate dependency graph).
+-   …to use `cargo raze` to generate Bazel build files from the Cargo package
+    structure.
+-   …to use other Rust toolchains, like the beta or nightly channels.
+-   …to cross-compile.
+-   …simply because you’re more familiar with it or prefer it.
+
+The easiest way to get and use Cargo is with <https://rustup.rs>. Cargo resolves
+subcommands by looking for executables called `cargo-*` (analogous to Git), so
+you may want to `cargo install cargo-raze cargo-watch cargo-geiger` for some
+useful tools.
+
+To build with Cargo, change into the `tensorboard/data/server/` directory and
+use standard Cargo commands, like `cargo build --release` or `cargo test`.
+Running `cargo raze` from within `tensorboard/data/server/` will update the
+build files under `third_party/rust/`, using `Cargo.toml` as the source of
+truth.
+
+You should be able to use `rust-analyzer` without doing anything special or
+changing into the `tensorboard/data/server/` subdirectory: just open one of the
+Rust source files in your editor. For editor setup, consult
+[the `rust-analyzer` docs][ra-docs].
+
+[ra-docs]: https://rust-analyzer.github.io/
+
+## Adding third-party dependencies
+
+Rust dependencies are usually hosted on [crates.io]. We use [`cargo-raze`][raze]
+to automatically generate Bazel build files for these third-party dependencies.
+
+The source of truth for `cargo-raze` is the `Cargo.toml` file. To add a new
+dependency:
+
+1.  Run `cargo install cargo-raze` to ensure that you have [`cargo-raze`][raze]
+    installed.
+2.  Add an entry to the `[dependencies]` section of `Cargo.toml`. The new line
+    should look like `rand = "0.7.3"`. You can find the most recent version of a
+    package on <https://crates.io/>.
+3.  Change into the `tensorboard/data/server/` directory.
+4.  Run `cargo generate-lockfile` to update `Cargo.lock`. Running this before
+    `cargo raze` ensures that the `http_archive` workspace rules in the
+    generated build files will have `sha256` checksums.
+5.  Run `cargo raze` to update `third_party/rust/...`.
+
+This will add a new target like `//third_party/rust:rand`. Manually build it
+with Bazel to ensure that it works: `bazel build //third_party/rust:rand`. If
+the build fails, you’ll need to teach `cargo-raze` how to handle this package by
+adding crate-specific metadata to a `[raze.crates.CRATE-NAME.VERSION]` section
+of the `Cargo.toml` file. Failure modes may include:
+
+-   The package uses a `build.rs` script to generate code at compile time.
+    Solution: add `gen_buildrs = true`.
+-   The package needs certain features to be enabled. Solution: add
+    `additional_flags = ["--cfg=FEATURE_NAME"]`.
+
+See `Cargo.toml` for prior art. Googlers: you may be able to glean some hints
+from the corresponding Google-internal build files.
+
+When done, commit the changes to `Cargo.toml`, `Cargo.lock`, and the
+`third_party/rust/` directory.
+
+[crates.io]: https://crates.io/
+[raze]: https://github.com/google/cargo-raze

Diff for: tensorboard/data/server/DEVELOPMENT.md

@@ -0,0 +1,36 @@
+/* Copyright 2020 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.
+==============================================================================*/
+
+/// Adds two integers together and returns the result. Must not overflow.
+///
+/// # Examples
+///
+/// ```
+/// assert_eq!(rustboard_core::add(20, 22), 42);
+/// ```
+pub fn add(x: i32, y: i32) -> i32 {
+    x + y
+}
+
+#[cfg(test)]
+mod test {
+    use super::add;
+
+    #[test]
+    fn test_add() {
+        assert_eq!(add(2, 4), 6);
+        assert_eq!(add(999, 999), 1998);
+    }
+}

Diff for: tensorboard/data/server/lib.rs

@@ -0,0 +1,22 @@
+/* Copyright 2020 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.
+==============================================================================*/
+
+use byteorder::{ByteOrder, LittleEndian};
+
+fn main() {
+    let ptr = LittleEndian::read_u32(b"\x2e\x68\x63\x73"); // look, a dependency!
+    assert_eq!(ptr, 0x7363682e);
+    println!("Hello, server! 2 + 2 = {}", rustboard_core::add(2, 2)); // look, a sibling crate!
+}

Diff for: tensorboard/data/server/main.rs

@@ -17,7 +17,7 @@
 # tf_imports/*.html define their respective OSS license.
 files=$(git grep -L "Copyright 20[0-9][0-9] The TensorFlow" \
     'tensorboard/*.*' \
-    ':!*.'{pyc,json,png,wav,proto,pbtxt,md,in,rst,cfg,ipynb,svg} \
+    ':!*.'{pyc,json,png,wav,proto,pbtxt,md,in,rst,cfg,ipynb,svg,lock} \
     ':!tensorboard/components/tf_imports/*.html')
 
 count=$(echo "$files" | wc -l | awk '{print $1}')

Diff for: tensorboard/tools/license_test.sh

@@ -0,0 +1,27 @@
+# Copyright 2020 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.
+
+"""
+TensorBoard external Rust dependencies (both infrastructure and frontend libs)
+"""
+
+load("@io_bazel_rules_rust//rust:repositories.bzl", "rust_repositories")
+load("@io_bazel_rules_rust//:workspace.bzl", "rust_workspace")
+load("//third_party/rust:crates.bzl", "raze_fetch_remote_crates")
+
+def tensorboard_rust_workspace():
+    """TensorBoard Rust dependencies."""
+    rust_repositories()
+    rust_workspace()
+    raze_fetch_remote_crates()