Dart plugin for protobuf compiler (protoc)
Dart Protocol Buffer Other
Latest commit 3c53389 Mar 20, 2017 @jakobr-google jakobr-google committed on GitHub Merge pull request #69 from mehaase/patch-1
Allow bash script to execute from any directory
Permalink
Failed to load latest commit information.
benchmark fix analyzer warning Aug 19, 2016
bin Allow bash script to execute from any directory Mar 20, 2017
lib Merge pull request #60 from dart-lang/tweaks Jan 25, 2017
test
.analysis_options Fix all strong mode warnings in protoc-plugin Apr 4, 2016
.gitignore Add more environmental data to benchmark reports Sep 4, 2015
AUTHORS Initial import. May 14, 2013
CONTRIBUTING.md Add CONTRIBUTING.md file Aug 27, 2014
LICENSE
Makefile Stop using dart2dart in Makefile Aug 19, 2016
PATENTS Initial import. May 14, 2013
README.md
codereview.settings Fix location of the repo in codereview settings Jan 5, 2015
pubspec.yaml

README.md

Protoc compiler Dart plugin

This repository provides a plugin for the protoc compiler. It generates Dart files for working with data in protocol buffers format. At this time we only support proto2, but proto3 may work in simple cases due to backwards compatibility.

Requirements

To compile a .proto file, you must use the 'protoc' command which is installed separately. Protobuf 2.6.1 or above is recommended. Many features may still work as far back as Protobuf 2.5.0 but we are no longer testing this.

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

How to build and use

Note: currently the workflow is POSIX-oriented.

To build standalone protoc plugin:

  • run pub install to install all dependecies
  • run make build-plugin. That will create a file out/protoc-gen-dart which is a plugin
  • Now you can use it either by adding into PATH or passing directly with protoc's --plugin option.

Please, remember that the plugin is pure Dart script and requires the presence of dart executable in your PATH.

When both the dart executable and out/protoc-gen-dart are in the PATH the protocol buffer compiler can be invoked to generate like this:

$ protoc --dart_out=. test.proto

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 individial 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>:."

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 librares combining object definitions from several .proto libraries into one.

The best way to aproach 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

message M1 {
  optional string a;
}

and m2.proto containing

message M2 {
  optional string b;
}

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 som 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 make run-tests.

The default way of running the Dart protoc plugin is through the generated out/protoc-gen-dart script. However when run this way the Dart code is assembled into one large Dart file using dart2dart. To run with the actual source in the repository create an executable script called protoc-gen-dart with the following content:

#! /bin/bash
dart bin/protoc_plugin.dart

When running protoc just ensure that this script is first when PATH is searched. If the script is in the current directory run protoc like this:

$ PATH=.:$PATH protoc --dart_out=. test.proto

It is also possible to call the script something else than protoc-gen-dart and then refer directly to it using the --plugin option. If the script is called dart-plugin run protoc like this:

$ protoc --plugin=protoc-gen-dart=./plugin --dart_out=. test.proto

Useful references