From ae107c7ab983f22791897569ec7b8356e76d72fb Mon Sep 17 00:00:00 2001 From: Joshua Haberman Date: Wed, 15 May 2019 13:51:18 -0700 Subject: [PATCH] New README.md. --- README.md | 135 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 107 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 36d1273a39..6edb2454b9 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,132 @@ # μpb - a small protobuf implementation in C -[![Build Status](https://travis-ci.org/google/upb.svg?branch=master)](https://travis-ci.org/google/upb) -[![Coverage Status](https://img.shields.io/coveralls/google/upb.svg)](https://coveralls.io/r/google/upb?branch=master) - -μpb is a small protobuf implementation written 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. You control where the arena gets +memory from, so the arena can come from stack memory, for example. +Here is a simple example (`ConformanceRequest` and `ConformanceResponse` +are generated message types): + +```c +#include "conformance/conformance.upb.h" + +void foo(const char* data, size_t size) { + upb_arena *arena; + 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; + } + } + + upb_arena_free(arena); +} +``` + +Messages are opaque, so you always have to use generated getter/setter +methods to read/write fields. This is somewhat unfortunate for C +because the function names are long, but this is necessary to provide +correct semantics for oneof fields, proto2 presence, etc. It is also +necessary for providing a stable ABI, in cases where that is desired. API and ABI are both subject to change! Please do not distribute as a shared library for this reason (for now at least). -## Building the core libraries +## Using upb in your project -The core libraries are pure C99 and have no dependencies. +Currently only Bazel is supported (CMake support is partial and incomplete +but full CMake support is an eventual goal). - $ make +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: -This will create a separate C library for each core library -in `lib/`. They are built separately to help your binaries -slim, so you don't need to link in things you neither want -or need. +```python +# Add this to your WORKSPACE file. +git_repository( + name = "upb", + remote = "https://github.com/protocolbuffers/upb.git", + # You may want to substitute a more recent commit here. + commit = "d5af87d06bbe3abad66970ce9c7ae0a7de8bb3c6", +) +``` -Other useful targets: +Then in your BUILD file you can add `upb_proto_library()` rules that +generate code for a corresponding `proto_library()` rule. For +example: - $ make tests - $ make test +```python +# Add this to your BUILD file. +load(":upb_proto_library.bzl", "upb_proto_library") -## C and C++ API +proto_library( + name = "foo_proto", + srcs = ["foo.proto"], +) -The public C/C++ API is defined by all of the .h files in -`upb/` except `.int.h` files (which are internal-only). +upb_proto_library( + name = "foo_upbproto", + deps = [":foo_proto"], +) -## Lua bindings +cc_library( + name = "lib_that_uses_protos", + srcs = ["lib_that_uses_protos.cc"], + deps = [":foo_upbproto"], +) +``` -Lua bindings provide μpb's functionality to Lua programs. -The bindings target Lua 5.1, Lua 5.2, LuaJIT, and (soon) Lua 5.3. +Then in your `.c` file you can #include the generated header: -To build the Lua bindings, the Lua libraries must be installed. Once -they are installed, run: +```c +#include "foo.upb.h" - $ make lua +/* Insert code that uses generated types. */ +``` -Note that if the Lua headers are not in a standard place, you may -need to pass custom flags: +## Old "handlers" interfaces - $ make lua USER_CPPFLAGS=`pkg-config lua5.2 --cflags` +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. -To test the Lua bindings: +## Lua bindings - $ make testlua +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