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
inprotoc_plugin
directory - Add
protoc_plugin/bin
to yourPATH
, or pass the path toprotoc_plugin/bin/protoc-gen-dart
toprotoc
'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
inprotoc_plugin
- Build standalone executable with
dart compile exe bin/protoc_plugin.dart
inprotoc_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
.