{"id":15287997,"url":"https://github.com/elixir-protobuf/protobuf","last_synced_at":"2025-05-13T17:14:00.087Z","repository":{"id":36961277,"uuid":"82948039","full_name":"elixir-protobuf/protobuf","owner":"elixir-protobuf","description":"A pure Elixir implementation of Google Protobuf.","archived":false,"fork":false,"pushed_at":"2025-05-03T14:39:02.000Z","size":1281,"stargazers_count":861,"open_issues_count":19,"forks_count":146,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-05-03T14:39:55.016Z","etag":null,"topics":["elixir","google-protocol-buffers","protobuf","protobuf-elixir","protoc","protocol-buffers","serialization"],"latest_commit_sha":null,"homepage":"https://hexdocs.pm/protobuf/readme.html","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/elixir-protobuf.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-02-23T16:38:38.000Z","updated_at":"2025-05-01T15:09:00.000Z","dependencies_parsed_at":"2024-05-11T22:22:10.906Z","dependency_job_id":"d2bb7d8d-3765-4d6d-a31f-b1b4d88d2835","html_url":"https://github.com/elixir-protobuf/protobuf","commit_stats":{"total_commits":447,"total_committers":46,"mean_commits":9.717391304347826,"dds":0.6241610738255033,"last_synced_commit":"ce9a031a5cae97336d4674670d313d54f1f80bf6"},"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elixir-protobuf%2Fprotobuf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elixir-protobuf%2Fprotobuf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elixir-protobuf%2Fprotobuf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elixir-protobuf%2Fprotobuf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elixir-protobuf","download_url":"https://codeload.github.com/elixir-protobuf/protobuf/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253990498,"owners_count":21995776,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["elixir","google-protocol-buffers","protobuf","protobuf-elixir","protoc","protocol-buffers","serialization"],"created_at":"2024-09-30T15:43:42.841Z","updated_at":"2025-05-13T17:13:55.073Z","avatar_url":"https://github.com/elixir-protobuf.png","language":"Elixir","readme":"# protobuf-elixir\n\n[![CI](https://github.com/elixir-protobuf/protobuf/actions/workflows/main.yml/badge.svg)](https://github.com/elixir-protobuf/protobuf/actions/workflows/main.yml)\n[![Coverage Status](https://coveralls.io/repos/github/elixir-protobuf/protobuf/badge.svg?branch=main)](https://coveralls.io/github/elixir-protobuf/protobuf?branch=main)\n\nA pure Elixir implementation of [Google Protobuf](https://developers.google.com/protocol-buffers/).\n\n## Why this instead of exprotobuf(gpb)?\n\nIt has some must-have and other cool features like:\n\n1. A protoc [plugin](https://developers.google.com/protocol-buffers/docs/cpptutorial#compiling-your-protocol-buffers) to generate Elixir code just like what other official libs do, which is powerful and reliable.\n2. Generate **simple and explicit** code with the power of Macro. See [test/support/test_msg.ex](https://github.com/tony612/protobuf-elixir/blob/master/test/support/test_msg.ex).\n3. Plugins support. Only [grpc](https://github.com/tony612/grpc-elixir) is supported now.\n4. Use **structs** for messages instead of Erlang records.\n5. Support Typespec in generated code.\n\n## Installation\n\nThe package can be installed by adding `:protobuf` to your list of dependencies in `mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:protobuf, \"~\u003e 0.14.1\"}\n  ]\nend\n```\n\n### Google Protos\n\nSince `:protobuf` version `0.14.0` we include all of the well known Google Protobuf modules. This conflicts with the deprecated `:google_protos` package. Please remove the `:google_protos` package from your dependencies and run `mix deps.unlock --unused`.\n\n## Features\n\n* Define messages with DSL\n* Decode basic messages\n* Skip unknown fields\n* Decode embedded messages\n* Decode packed and repeated fields\n* Encode messages\n* protoc plugin\n* map\n* Support default values\n* Validate values\n* Generate typespecs\n* oneof\n* (proto2) Extension (Experiment, see `Protobuf.Extension`)\n\n## Usage\n\n### Generate Elixir code\n\n1. [Download](https://github.com/protocolbuffers/protobuf#protocol-compiler-installation) and\n   install the protocol buffer compiler (`protoc`). MacOS users can also install it through\n   Homebrew with `brew install protobuf`.\n\n2. Install `protoc` plugin `protoc-gen-elixir` for Elixir using the command below. Make sure the\n   `protoc-gen-elixir` binary is in your `PATH`. Either add `PATH=~/.mix/escripts:$PATH` to your\n   bash or zsh profile or, if you used asdf to install elixir, run `asdf reshim` and then verify\n   that `protoc-gen-elixir` works:\n\n    ```bash\n    $ mix escript.install hex protobuf 0.14.0\n    ```\n    Note: make sure to use the same version of the escript and dependency in your application.\n\n3. Generate Elixir code for [helloworld.proto](https://raw.githubusercontent.com/grpc/grpc/master/examples/protos/helloworld.proto) using `protoc`:\n\n    ```bash\n    $ protoc --elixir_out=./lib helloworld.proto\n    ```\n\n4. A `lib/helloworld.pb.ex` file will be generated, like:\n\n    ```elixir\n    defmodule Helloworld.HelloRequest do\n      @moduledoc false\n      use Protobuf, protoc_gen_elixir_version: \"0.10.0\", syntax: :proto3\n\n      field :name, 1, type: :string\n    end\n\n    defmodule Helloworld.HelloReply do\n      @moduledoc false\n      use Protobuf, protoc_gen_elixir_version: \"0.10.0\", syntax: :proto3\n\n      field :message, 1, type: :string\n    end\n    ```\n\n### Encode and decode in your code\n\n```elixir\nstruct = %Foo{a: 3.2, c: %Foo.Bar{}}\nencoded = Foo.encode(struct)\nstruct = Foo.decode(encoded)\n```\n\nValidation is done during encoding. An error will be raised if the struct is invalid: when it\nmisses a required field or has a mistyped value.\n\n### Descriptor support\n\nIf you use any custom options in your protobufs then to gain access to them you'll need to include\nthe raw descriptors in the generated modules. You can generate the descriptors by passing\n`gen_descriptors=true` in `--elixir_out`.\n\nThe descriptors will be available on each module from the `descriptor/0` function.\n\n```\n$ protoc --elixir_out=gen_descriptors=true:./lib/ *.proto\n$ protoc --elixir_out=gen_descriptors=true,plugins=grpc:./lib/ *.proto\n```\n\n### Package prefix\n\nYou can use the `package_prefix` option to prefix generated Elixir code.\n\nFor example to prefix generated Elixir modules with `MyApp.Protos` use `my_app.protos` as package\nprefix:\n\n```\n$ protoc --elixir_out=./lib --elixir_opt=package_prefix=my_app.protos *.proto\n```\n\n### Transformer module\n\nBy defining a callback `transform_module/0` function on your protobuf message module\nyou can add custom encoding and decoding logic for your message. See the documentation\nfor `Protobuf.TransformModule` for more details.\n\nIf your protobufs are generated from a `.proto` files you can add the callback function\nby passing `transform_module=...` in `--elixir_out`.\n\n```\n$ protoc --elixir_out=transform_module=MyTransformModule:./lib/ *.proto\n```\n\n### One file per module\n\nYou can use the `one_file_per_module=true` option to change the way that files\nare generated into directories. By default, one `.pb.ex` file is generated for\neach `.proto` file you compile and each of those `.pb.ex` files can have\nmultiple Elixir module definitions in it.\n\nWith `one_file_per_module=true`, one `.pb.ex` file will be generated for each\ngenerated Elixir module and the directory structure will respect Elixir\nconventions. For example, a `MyPackage.MyMessage` message will end up in the\n`my_package/my_message.pb.ex` file.\n\n```\n$ protoc --elixir_out=one_file_per_module=true:./lib *.proto\n```\n\n### Include documentation\n\nYou can use the `include_docs=true` option to set the visibility of the\ngenerated modules documentation.\n\nWith `include_docs=true`, the generated modules will not have the\n`@module false` attribute.\n\n```\n$ protoc --elixir_out=./lib --elixir_opt=include_docs=true *.proto\n```\n\n### gRPC Support\n\nIf you write [services](https://developers.google.com/protocol-buffers/docs/proto#services) in\nprotobuf, you can generate [gRPC](https://github.com/elixir-grpc/grpc) code by passing\n`plugins=grpc` in `--elixir_out`:\n\n```\n$ protoc --elixir_out=plugins=grpc:./lib/ *.proto\n```\n\n### Tips for protoc\n\nCustom protoc-gen-elixir name or path using `--plugin`:\n\n```bash\n$ protoc --elixir_out=./lib --plugin=./protoc-gen-elixir *.proto\n```\n\nPass `-I` argument if you import other protobuf files:\n\n```bash\n$ protoc -I protos --elixir_out=./lib protos/hello.proto\n```\n\n### Custom options\n\nSince extensions(`Protobuf.Extension`) is supported now, some options are defined, like custom\n`module_prefix`.\n\n1. Copy `src/elixirpb.proto` to your protos path.\n\n2. Import `elixirpb.proto` and use the options.\n\n    ```proto\n    syntax = \"proto2\";\n\n    package your.pkg;\n\n    import \"elixirpb.proto\";\n\n    option (elixirpb.file).module_prefix = \"Foo.Bar\";\n    ```\n\n3. Generate code as before.\n\nMore options will be added in the future, see `elixirpb.proto` comments for details.\n\n## Tests\n\n```bash\nmix test\n```\n\n## Sponsors\n\n* [Tubi](https://tubitv.com/)\n\n\u003cimg src=\"https://user-images.githubusercontent.com/1253659/37473536-4db44048-28a9-11e8-90d5-f8a2f5a8d53c.jpg\" height=\"80\"\u003e\n\n* [Community](https://www.community.com)\n\n\u003cimg src=\"https://user-images.githubusercontent.com/1253659/84641850-3f163d80-af2e-11ea-98a2-cfb854180222.png\" height=\"80\"\u003e\n\n## Acknowledgements\n\nMany thanks to [gpb](https://github.com/tomas-abrahamsson/gpb) and\n[golang/protobuf](https://github.com/golang/protobuf) as good examples of\nwriting Protobuf decoder/encoder.\n","funding_links":[],"categories":["Elixir"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felixir-protobuf%2Fprotobuf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felixir-protobuf%2Fprotobuf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felixir-protobuf%2Fprotobuf/lists"}