Give Rust proto enums name(), from_name() and EnumValueNames, except under Lite. Every other protobuf language converts an enum value to and from its .proto name: C++ has `Foo_Name` and `Foo_Parse`, Java `getValueDescriptor().getName()` and `valueOf`, Python `Name` and `Value`, Go `String()` and `Foo_value`. Rust has neither. The generator already emits every value name into each binary through the private `constant_name()` that backs `Debug`, but callers can't reach it, and it returns the prefix-stripped Rust constant name (`NotFound`) rather than the .proto name (`STATUS_NOT_FOUND`). Rust code that has to produce or accept the same strings as other languages (logs, metric labels, config files, flags, and text formats that carry enum names) therefore hand-writes a two-way match for each enum, which drifts whenever a value is added to the .proto file. Generic libraries can't do it at all, since there is nothing to call through `T: Enum`. Add `pub const fn name(self) -> Option<&'static str>` and `pub fn from_name(&str) -> Option<Self>` to the inherent impl generated for each enum. Both use the .proto names. For an aliased number, `name()` returns the first declared name, like `EnumDescriptor::FindValueByNumber`, and `from_name()` accepts every alias. `name()` returns `None` for an unknown value of an open enum. `name()` is a generated `match` on the number. `from_name()` binary-searches a `(name, number)` table, aliases included, that the generator sorts by name, as C++ lite does, so lookups stay O(log n) for large enums; the search is a shared runtime helper, so each enum only adds its table. Both work the same on the C++ and upb kernels. Add a `protobuf::EnumValueNames` trait, with `Enum` as its supertrait, that each such enum implements by forwarding to the inherent functions, so that generic code bounded by `T: EnumValueNames` can convert any of them without knowing its type. The trait method isn't `const`, since stable Rust has no `const` trait methods; the inherent `const fn` remains for constant contexts. Method calls and `Type::name` paths on a concrete enum resolve to the inherent functions, which take precedence over the trait's. Lite and mobile builds must not embed value names, which leak internal identifiers from shipped binaries (Java on Android has the getter, but R8/ProGuard flags its use). So, as `HasReflectionSupport()` does for messages, enums from `optimize_for = LITE_RUNTIME` files, and every enum when the lite runtime is forced, get neither the functions nor `EnumValueNames`: code that needs the names fails to compile with them instead of retaining the names. Keeping the names out of `Enum` itself is what allows this, since every enum implements `Enum`. Neither name can collide with a value constant, because those are always UpperCamelCase; the same reasoning already permits `constant_name()` and `number()`. Code that calls a user-defined trait method named `name` or `from_name` on a generated enum would now resolve to the inherent method. `enum_test` covers the functions and `EnumValueNames`, including every name of an enum whose names are declared out of order, and skips them when the lite runtime is forced. The new `lite_enum_test`, on both kernels, checks that an `optimize_for = LITE_RUNTIME` enum doesn't implement `EnumValueNames`, and that other enums do unless the lite runtime is forced. PiperOrigin-RevId: 996243501
Copyright 2008 Google LLC
Protocol Buffers (a.k.a., protobuf) are Google's language-neutral, platform-neutral, extensible mechanism for serializing structured data. You can learn more about it in protobuf's documentation.
This README file contains protobuf installation instructions. To install protobuf, you need to install the protocol compiler (used to compile .proto files) and the protobuf runtime for your chosen programming language.
Most users will find working from supported releases to be the easiest path.
If you choose to work from the head revision of the main branch your build will occasionally be broken by source-incompatible changes and insufficiently-tested (and therefore broken) behavior.
If you are using C++ or otherwise need to build protobuf from source as a part of your project, you should pin to a release commit on a release branch.
This is because even release branches can experience some instability in between release commits.
Protobuf supports Bzlmod with Bazel 8 +. Users should specify a dependency on protobuf in their MODULE.bazel file as follows.
bazel_dep(name = "protobuf", version = <VERSION>)
Users can optionally override the repo name, such as for compatibility with WORKSPACE.
bazel_dep(name = "protobuf", version = <VERSION>, repo_name = "com_google_protobuf")
Users can also add the following to their legacy WORKSPACE file.
Note that with the release of 30.x there are a few more load statements to properly set up rules_java and rules_python.
http_archive(
name = "com_google_protobuf",
strip_prefix = "protobuf-VERSION",
sha256 = ...,
url = ...,
)
load("@com_google_protobuf//:protobuf_deps.bzl", "protobuf_deps")
protobuf_deps()
load("@rules_java//java:rules_java_deps.bzl", "rules_java_dependencies")
rules_java_dependencies()
load("@rules_java//java:repositories.bzl", "rules_java_toolchains")
rules_java_toolchains()
load("@rules_python//python:repositories.bzl", "py_repositories")
py_repositories()
The protobuf compiler is written in C++. If you are using C++, please follow the C++ Installation Instructions to install protoc along with the C++ runtime.
For non-C++ users, the simplest way to install the protocol compiler is to download a pre-built binary from our GitHub release page.
In the downloads section of each release, you can find pre-built binaries in zip packages: protoc-$VERSION-$PLATFORM.zip. It contains the protoc binary as well as a set of standard .proto files distributed along with protobuf.
If you are looking for an old version that is not available in the release page, check out the Maven repository.
These pre-built binaries are only provided for released versions. If you want to use the github main version at HEAD, or you need to modify protobuf code, or you are using C++, it's recommended to build your own protoc binary from source.
If you would like to build protoc binary from source, see the C++ Installation Instructions.
Protobuf supports several different programming languages. For each programming language, you can find instructions in the corresponding source directory about how to install protobuf runtime for that specific language:
| Language | Source |
|---|---|
| C++ (include C++ runtime and protoc) | src |
| Java | java |
| Python | python |
| Objective-C | objectivec |
| C# | csharp |
| Ruby | ruby |
| Go | protocolbuffers/protobuf-go |
| PHP | php |
| Dart | dart-lang/protobuf |
| JavaScript | protocolbuffers/protobuf-javascript |
The best way to learn how to use protobuf is to follow the tutorials in our developer guide.
If you want to learn from code examples, take a look at the examples in the examples directory.
The complete documentation is available at the Protocol Buffers doc site.
Read about our version support policy to stay current on support timeframes for the language libraries.
To be alerted to upcoming changes in Protocol Buffers and connect with protobuf developers and users, join the Google Group.