1 2# μpb - a small protobuf implementation in C 3 4|Platform|Build Status| 5|--------|------------| 6|macOS|[](https://fusion.corp.google.com/projectanalysis/summary/KOKORO/prod%3Aupb%2Fmacos%2Fcontinuous)| 7|ubuntu|[](https://fusion.corp.google.com/projectanalysis/summary/KOKORO/prod%3Aupb%2Fubuntu%2Fcontinuous)| 8 9μpb (often written 'upb') is a small protobuf implementation written in C. 10 11upb generates a C API for creating, parsing, and serializing messages 12as declared in `.proto` files. upb is heavily arena-based: all 13messages always live in an arena (note: the arena can live in stack or 14static memory if desired). Here is a simple example: 15 16```c 17#include "conformance/conformance.upb.h" 18 19void foo(const char* data, size_t size) { 20 upb_arena *arena; 21 22 /* Generated message type. */ 23 conformance_ConformanceRequest *request; 24 conformance_ConformanceResponse *response; 25 26 arena = upb_arena_new(); 27 request = conformance_ConformanceRequest_parse(data, size, arena); 28 response = conformance_ConformanceResponse_new(arena); 29 30 switch (conformance_ConformanceRequest_payload_case(request)) { 31 case conformance_ConformanceRequest_payload_protobuf_payload: { 32 upb_strview payload = conformance_ConformanceRequest_protobuf_payload(request); 33 // ... 34 break; 35 } 36 37 case conformance_ConformanceRequest_payload_NOT_SET: 38 fprintf(stderr, "conformance_upb: Request didn't have payload.\n"); 39 break; 40 41 default: { 42 static const char msg[] = "Unsupported input format."; 43 conformance_ConformanceResponse_set_skipped( 44 response, upb_strview_make(msg, sizeof(msg))); 45 break; 46 } 47 } 48 49 /* Frees all messages on the arena. */ 50 upb_arena_free(arena); 51} 52``` 53 54API and ABI are both subject to change! Please do not distribute 55as a shared library for this reason (for now at least). 56 57## Using upb in your project 58 59Currently only Bazel is supported (CMake support is partial and incomplete 60but full CMake support is an eventual goal). 61 62To use upb in your Bazel project, first add upb to your `WORKSPACE` file, 63either as a `git_repository()` or as a `new_local_repository()` with a 64Git Submodule. (For an example, see `examples/bazel/ in this repo). 65 66```python 67# Add this to your WORKSPACE file. 68load("@bazel_tools//tools/build_defs/repo:git.bzl", "git_repository") 69 70git_repository( 71 name = "upb", 72 remote = "https://github.com/protocolbuffers/upb.git", 73 commit = "d16bf99ac4658793748cda3251226059892b3b7b", 74) 75 76load("@upb//bazel:workspace_deps.bzl", "upb_deps") 77 78upb_deps() 79``` 80 81Then in your BUILD file you can add `upb_proto_library()` rules that 82generate code for a corresponding `proto_library()` rule. For 83example: 84 85```python 86# Add this to your BUILD file. 87load("@upb//bazel:upb_proto_library.bzl", "upb_proto_library") 88 89proto_library( 90 name = "foo_proto", 91 srcs = ["foo.proto"], 92) 93 94upb_proto_library( 95 name = "foo_upbproto", 96 deps = [":foo_proto"], 97) 98 99cc_binary( 100 name = "test_binary", 101 srcs = ["test_binary.c"], 102 deps = [":foo_upbproto"], 103) 104``` 105 106Then in your `.c` file you can #include the generated header: 107 108```c 109#include "foo.upb.h" 110 111/* Insert code that uses generated types. */ 112``` 113 114## Old "handlers" interfaces 115 116This library contains several semi-deprecated interfaces (see BUILD 117file for more info about which interfaces are deprecated). These 118deprecated interfaces are still used in some significant projects, 119such as the Ruby and PHP C bindings for protobuf in the [main protobuf 120repo](https://github.com/protocolbuffers/protobuf). The goal is to 121migrate the Ruby/PHP bindings to use the newer, simpler interfaces 122instead. Please do not use the old interfaces in new code. 123 124## Lua bindings 125 126This repo has some Lua bindings for the core library. These are 127experimental and very incomplete. These are currently included in 128order to validate that the C API is suitable for wrapping. As the 129project matures these Lua bindings may become publicly available. 130 131## Contact 132 133Author: Josh Haberman ([jhaberman@gmail.com](mailto:jhaberman@gmail.com), 134[haberman@google.com](mailto:haberman@google.com)) 135
){kind=link}
){kind=link}