protoc_plugin - Dart API docs

This repository provides a Dart plugin for the protoc compiler. It generates Dart files for working with data in protocol buffers format.

Requirements

To compile a .proto file, you must use the protoc command which is installed separately. protoc 3.0.0 or above is required.

The generated files are pure Dart code that run either in the Dart VM or in a browser (using dart2js). They depend on the protobuf Dart package. A Dart project that includes generated files should add protobuf as a dependency in the pubspec.yaml file.

How to build

Make sure you have dart executable in your PATH. See the Dart installation instructions for details.

If you encounter any issues while following the instructions below, please make sure you have the latest version of Dart installed.

The recommended way is to activate the latest published version of the plugin:

$ dart pub global activate protoc_plugin

Make sure you have ~/.pub-cache/bin in your PATH.

This method installs a Dart script and requires presence of dart executable in your PATH.

To build from the source:

Run dart pub get in protoc_plugin directory
Add protoc_plugin/bin to your PATH, or pass the path to protoc_plugin/bin/protoc-gen-dart to protoc's --plugin option.

The protoc-gen-dart executable is a Dart script and requires presence of dart executable in your PATH.

To build a standalone executable from the source:

Run dart pub get in protoc_plugin
Build standalone executable with dart compile exe bin/protoc_plugin.dart in protoc_plugin

The generated executable does not require a dart executable to run. You should copy the generated executable protoc_plugin/bin/protoc_plugin.exe to your PATH with name protoc-gen-dart, or pass the path to it to protoc's --plugin option when invoking protoc.

How to use

Once you have protoc-gen-dart in the PATH the protocol buffer compiler can be invoked like this to generate Dart for the proto file test.proto:

$ protoc --dart_out=. test.proto

If you don't want to add protoc-gen-dart to PATH, you can specify the path to it like this:

$ protoc --dart_out=. test.proto --plugin=<path to plugin executable>

Options to control the generated Dart code

The protocol buffer compiler accepts options for each plugin. For the Dart plugin, these options are passed together with the --dart_out option. The individual options are separated using comma, and the final output directive is separated from the options using colon. Pass options <option 1> and <option 2> like this:

--dart_out="<option 1>,<option 2>:."

Generating grpc Headers

To generate code for grpc, you will need to pass in the grpc option:

--dart_out="grpc:."

Generating Code Info

The plugin includes the generate_kythe_info option, which, if passed at run time, will make the plugin generate metadata files alongside the .dart files generated for the proto messages and their enums. Pass this along with the other dart_out options:

--dart_out="generate_kythe_info,<other options>:."

Using protocol buffer libraries to build new libraries

The protocol buffer compiler produces several files for each .proto file it compiles. In some cases this is not exactly what is needed, e.g one would like to create new libraries which exposes the objects in these libraries or create new libraries combining object definitions from several .proto libraries into one.

The best way to approach this is to create the new libraries needed and re-export the relevant protocol buffer classes.

Say we have the file m1.proto with the following content

syntax = "proto3";

message M1 {
  string a = 1;
}

and m2.proto containing

syntax = "proto3";

message M2 {
  string b = 1;
}

Compiling these to Dart will produce two libraries in m1.pb.dart and m2.pb.dart. The following code shows a library M which combines these two protocol buffer libraries, exposes the classes M1 and M2 and adds some additional methods.

library M;

import "m1.pb.dart";
import "m2.pb.dart";

export "m1.pb.dart" show M1;
export "m2.pb.dart" show M2;

M1 createM1() => new M1();
M2 createM2() => new M2();

Hacking

Here are some ways to get protoc:

Linux: apt-get install protobuf-compiler
Mac homebrew: brew install protobuf

If the version installed this way doesn't work, an alternative is to compile protoc from source.

Remember to run the tests. That is as easy as dart pub get and then make run-tests.