--- /dev/null
+
+# μ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))