# Protobuf.Generate

[![GitHub actions Status](](

`protobuf.generate` is a mix task that allows you to generate Elixir code using [Protobuf]( without using the `protoc-gen-elixir` plugin.

The generator calls `protoc` using `descriptor_set_out` to output a `FileDescriptorSet` into a temporary file for input to [Protobuf](

The difference between `protobuf.generate` and `protoc-gen-elixir` is that `protoc-gen-elixir` is called as a plugin to `protoc` and therefor executes in a
_global_ context while `protobuf.generate` executes in the context of the _local_ project. 

By executing in the context of the local project:

* Extensions that needs to be populated during code generation are picked up automatically by `Protobuf.load_extensions/0` (which is not possible when using `protoc-gen-elixir`).

* Integration into the codegen by using generator plugins. See `ProtobufGenerate.Plugin`

## Prerequisites

* [Protoc]( (protocol buffer compiler) is required to be installed. [Download and install]( the protocol buffer compiler (protoc).

## Installation

This package can be installed by adding `protobuf_generate` to your list of dependencies in `mix.exs`:

def deps do
    {:protobuf_generate, "~> 0.1.0"}

## Usage

`mix protobuf.generate` supports the same options as [`protoc-gen-elixir`](

### Arguments

  * `file` - One or more `.proto` files to compile

### Required options

  * `--output-path` - Path to output directory

### Optional options

  * `--include-path` - Specify the directory in which to search for imports. Eqvivalent to `protoc` `-I` flag.

  * `--tranform-module` - Module to do custom encoding/decoding for messages. See `Protobuf.TransformModule` for details.

  * `--package-prefix` - Prefix generated Elixir modules. For example prefix modules with: `MyApp.Protos` use `--package-prefix=my_app.protos`.

  * `--generate-descriptors` - Includes raw descriptors in the generated modules

  * `--one-file-per-module` - Changes the way files are generated into directories. This option creates a file for each generated Elixir module.

  * `--include-documentation` - Controls visibility of documentation of the generated modules. Setting `true` will not  have `@moduleoc false`

  * `--plugins` - Generator plugins. If you write services in protobuf, you can generate gRPC code by passing `--plugins=ProtobufGenerate.Plugins.GRPC`.

$ mix protobuf.generate --output-path=./lib --include-path=./priv/protos helloworld.proto
$ mix protobuf.generate \
  --include-path=priv/proto \
  --include-path=deps/googleapis \
  --generate-descriptors=true \
  --output-path=./lib \
  --plugins=ProtobufGenerate.Plugins.GRPCWithOptions \
  google/api/annotations.proto google/api/http.proto helloworld.proto

## Available plugins

* `ProtobufGenerate.Plugins.GRPC` - Generate [gRPC]( services
* `ProtobufGenerate.Plugins.GRPCWithOptions` -  Generate [gRPC]( services with method extension options.

## Extensions

Extensions in the current project are loaded automatically when running `mix protobuf.generate`. However they need to be already generated in order for `Protobuf.load_extensions/0` to pick them up.

## Acknowledgements

* [`protox`]( for running `protoc` with `descriptor_set_out`