A pure Elixir implementation of Google Protobuf.
A pure Elixir implementation of Google Protobuf.
It has some must-have and other cool features like:
The package can be installed by adding :protobuf
to your list of dependencies in mix.exs
:
def deps do
[
{:protobuf, "~> 0.10.0"},
# Only for files generated from Google's protos.
# Can be ignored if you don't use Google's protos.
# Or you can generate the code by yourself.
{:google_protos, "~> 0.1"}
]
end
Protobuf.Extension
)Download and
install the protocol buffer compiler (protoc
). MacOS users can also install it through
Homebrew with brew install protobuf
.
Install protoc
plugin protoc-gen-elixir
for Elixir using the command below. Make sure the
protoc-gen-elixir
binary is in your PATH
. Either add PATH=~/.mix/escripts:$PATH
to your
bash or zsh profile or, if you used asdf to install elixir, run asdf reshim
and then verify
that protoc-gen-elixir
works:
$ mix escript.install hex protobuf
Generate Elixir code for helloworld.proto using protoc
:
$ protoc --elixir_out=./lib helloworld.proto
A lib/helloworld.pb.ex
file will be generated, like:
defmodule Helloworld.HelloRequest do
@moduledoc false
use Protobuf, protoc_gen_elixir_version: "0.10.0", syntax: :proto3
field :name, 1, type: :string
end
defmodule Helloworld.HelloReply do
@moduledoc false
use Protobuf, protoc_gen_elixir_version: "0.10.0", syntax: :proto3
field :message, 1, type: :string
end
struct = %Foo{a: 3.2, c: %Foo.Bar{}}
encoded = Foo.encode(struct)
struct = Foo.decode(encoded)
Validation is done during encoding. An error will be raised if the struct is invalid: when it misses a required field or has a mistyped value.
If you use any custom options in your protobufs then to gain access to them you'll need to include
the raw descriptors in the generated modules. You can generate the descriptors by passing
gen_descriptors=true
in --elixir_out
.
The descriptors will be available on each module from the descriptor/0
function.
$ protoc --elixir_out=gen_descriptors=true:./lib/ *.proto
$ protoc --elixir_out=gen_descriptors=true,plugins=grpc:./lib/ *.proto
You can use the package_prefix
option to prefix generated Elixir code.
For example to prefix generated Elixir modules with MyApp.Protos
use my_app.protos
as package
prefix:
$ protoc --elixir_out=./lib --elixir_opt=package_prefix=my_app.protos *.proto
By defining a callback transform_module/0
function on your protobuf message module
you can add custom encoding and decoding logic for your message. See the documentation
for Protobuf.TransformModule
for more details.
If your protobufs are generated from a .proto
files you can add the callback function
by passing transform_module=...
in --elixir_out
.
$ protoc --elixir_out=transform_module=MyTransformModule:./lib/ *.proto
You can use the one_file_per_module=true
option to change the way that files
are generated into directories. By default, one .pb.ex
file is generated for
each .proto
file you compile and each of those .pb.ex
files can have
multiple Elixir module definitions in it.
With one_file_per_module=true
, one .pb.ex
file will be generated for each
generated Elixir module and the directory structure will respect Elixir
conventions. For example, a MyPackage.MyMessage
message will end up in the
my_package/my_message.pb.ex
file.
$ protoc --elixir_out=one_file_per_module=true:./lib *.proto
You can use the include_docs=true
option to set the visibility of the
generated modules documentation.
With include_docs=true
, the generated modules will not have the
@module false
attribute.
$ protoc --elixir_out=./lib --elixir_opt=include_docs=true *.proto
If you write services in
protobuf, you can generate gRPC code by passing
plugins=grpc
in --elixir_out
:
$ protoc --elixir_out=plugins=grpc:./lib/ *.proto
Custom protoc-gen-elixir name or path using --plugin
:
$ protoc --elixir_out=./lib --plugin=./protoc-gen-elixir *.proto
Pass -I
argument if you import other protobuf files:
$ protoc -I protos --elixir_out=./lib protos/hello.proto
Since extensions(Protobuf.Extension
) is supported now, some options are defined, like custom
module_prefix
.
Copy src/elixirpb.proto
to your protos path.
Import elixirpb.proto
and use the options.
syntax = "proto2";
package your.pkg;
import "elixirpb.proto";
option (elixirpb.file).module_prefix = "Foo.Bar";
Generate code as before.
More options will be added in the future, see elixirpb.proto
comments for details.
mix test
Many thanks to gpb and golang/protobuf as good examples of writing Protobuf decoder/encoder.