Built motion from commit 6a09e18b.|2.6.11

[motion2.git] / legacy-libs / grpc-cloned / deps / grpc / third_party / upb / README.md

diff --git a/legacy-libs/grpc-cloned/deps/grpc/third_party/upb/README.md b/legacy-libs/grpc-cloned/deps/grpc/third_party/upb/README.md
new file mode 100644 (file)
index 0000000..a08aa0e
--- /dev/null
+++ b/legacy-libs/grpc-cloned/deps/grpc/third_party/upb/README.md
@@ -0,0 +1,134 @@
+
+# μpb - a small protobuf implementation in C
+
+|Platform|Build Status|
+|--------|------------|
+|macOS|[![Build Status](https://storage.googleapis.com/upb-kokoro-results/status-badge/macos.png)](https://fusion.corp.google.com/projectanalysis/summary/KOKORO/prod%3Aupb%2Fmacos%2Fcontinuous)|
+|ubuntu|[![Build Status](https://storage.googleapis.com/upb-kokoro-results/status-badge/ubuntu.png)](https://fusion.corp.google.com/projectanalysis/summary/KOKORO/prod%3Aupb%2Fubuntu%2Fcontinuous)|
+
+μpb (often written 'upb') is a small protobuf implementation written in C.
+
+upb generates a C API for creating, parsing, and serializing messages
+as declared in `.proto` files.  upb is heavily arena-based: all
+messages always live in an arena (note: the arena can live in stack or
+static memory if desired).  Here is a simple example:
+
+```c
+#include "conformance/conformance.upb.h"
+
+void foo(const char* data, size_t size) {
+  upb_arena *arena;
+
+  /* Generated message type. */
+  conformance_ConformanceRequest *request;
+  conformance_ConformanceResponse *response;
+
+  arena = upb_arena_new();
+  request = conformance_ConformanceRequest_parse(data, size, arena);
+  response = conformance_ConformanceResponse_new(arena);
+
+  switch (conformance_ConformanceRequest_payload_case(request)) {
+    case conformance_ConformanceRequest_payload_protobuf_payload: {
+      upb_strview payload = conformance_ConformanceRequest_protobuf_payload(request);
+      // ...
+      break;
+    }
+
+    case conformance_ConformanceRequest_payload_NOT_SET:
+      fprintf(stderr, "conformance_upb: Request didn't have payload.\n");
+      break;
+
+    default: {
+      static const char msg[] = "Unsupported input format.";
+      conformance_ConformanceResponse_set_skipped(
+          response, upb_strview_make(msg, sizeof(msg)));
+      break;
+    }
+  }
+
+  /* Frees all messages on the arena. */
+  upb_arena_free(arena);
+}
+```
+
+API and ABI are both subject to change!  Please do not distribute
+as a shared library for this reason (for now at least).
+
+## Using upb in your project
+
+Currently only Bazel is supported (CMake support is partial and incomplete
+but full CMake support is an eventual goal).
+
+To use upb in your Bazel project, first add upb to your `WORKSPACE` file,
+either as a `git_repository()` or as a `new_local_repository()` with a
+Git Submodule.  (For an example, see `examples/bazel/ in this repo).
+
+```python
+# Add this to your WORKSPACE file.
+load("@bazel_tools//tools/build_defs/repo:git.bzl", "git_repository")
+
+git_repository(
+    name = "upb",
+    remote = "https://github.com/protocolbuffers/upb.git",
+    commit = "d16bf99ac4658793748cda3251226059892b3b7b",
+)
+
+load("@upb//bazel:workspace_deps.bzl", "upb_deps")
+
+upb_deps()
+```
+
+Then in your BUILD file you can add `upb_proto_library()` rules that
+generate code for a corresponding `proto_library()` rule.  For
+example:
+
+```python
+# Add this to your BUILD file.
+load("@upb//bazel:upb_proto_library.bzl", "upb_proto_library")
+
+proto_library(
+    name = "foo_proto",
+    srcs = ["foo.proto"],
+)
+
+upb_proto_library(
+    name = "foo_upbproto",
+    deps = [":foo_proto"],
+)
+
+cc_binary(
+    name = "test_binary",
+    srcs = ["test_binary.c"],
+    deps = [":foo_upbproto"],
+)
+```
+
+Then in your `.c` file you can #include the generated header:
+
+```c
+#include "foo.upb.h"
+
+/* Insert code that uses generated types. */
+```
+
+## Old "handlers" interfaces
+
+This library contains several semi-deprecated interfaces (see BUILD
+file for more info about which interfaces are deprecated).  These
+deprecated interfaces are still used in some significant projects,
+such as the Ruby and PHP C bindings for protobuf in the [main protobuf
+repo](https://github.com/protocolbuffers/protobuf).  The goal is to
+migrate the Ruby/PHP bindings to use the newer, simpler interfaces
+instead.  Please do not use the old interfaces in new code.
+
+## Lua bindings
+
+This repo has some Lua bindings for the core library.  These are
+experimental and very incomplete.  These are currently included in
+order to validate that the C API is suitable for wrapping.  As the
+project matures these Lua bindings may become publicly available.
+
+## Contact
+
+Author: Josh Haberman ([jhaberman@gmail.com](mailto:jhaberman@gmail.com),
+[haberman@google.com](mailto:haberman@google.com))