diff options
author | dvshkurko <dvshkurko@yandex-team.ru> | 2022-02-10 16:45:52 +0300 |
---|---|---|
committer | Daniil Cherednik <dcherednik@yandex-team.ru> | 2022-02-10 16:45:52 +0300 |
commit | c768a99151e47c3a4bb7b92c514d256abd301c4d (patch) | |
tree | 1a2c5ffcf89eb53ecd79dbc9bc0a195c27404d0c /contrib/libs/grpc/third_party/upb/README.md | |
parent | 321ee9bce31ec6e238be26dbcbe539cffa2c3309 (diff) | |
download | ydb-c768a99151e47c3a4bb7b92c514d256abd301c4d.tar.gz |
Restoring authorship annotation for <dvshkurko@yandex-team.ru>. Commit 2 of 2.
Diffstat (limited to 'contrib/libs/grpc/third_party/upb/README.md')
-rw-r--r-- | contrib/libs/grpc/third_party/upb/README.md | 268 |
1 files changed, 134 insertions, 134 deletions
diff --git a/contrib/libs/grpc/third_party/upb/README.md b/contrib/libs/grpc/third_party/upb/README.md index b7379a3bf7..a08aa0e909 100644 --- a/contrib/libs/grpc/third_party/upb/README.md +++ b/contrib/libs/grpc/third_party/upb/README.md @@ -1,134 +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)) + +# μ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)) |