protoc_plugin 0.7.11

  • README.md
  • CHANGELOG.md
  • Installing
  • Versions
  • 74

Dart plugin for the protoc compiler

Build Status pub package

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 3.0.0 or above is required.

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 dependencies
  • Now you can use the plugin either by adding the bin directory to your PATH, or passing it 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 bin/protoc-gen-dart are in the PATH the protocol buffer compiler can be invoked to generate like this:

$ protoc --dart_out=. test.proto

Optionally using pub global

$ pub global activate protoc_plugin

And then add .pub-cache/bin in your home dir to your PATH if you haven't already.

This will activate the latest published version of the plugin. If you wish to use a local working copy, use

$ pub global activate -s path <path/to/your/dart-protoc-plugin>

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.

Useful references

0.7.11 - 2018-04-09

  • Dart 2 fix.

0.7.10 - 2018-02-22

  • Small performance tweak for DDC.

0.7.9 - 2018-01-12

  • Add fast getters for common types.
  • Only pass index instead of tag and index in generated code.
  • Fix uses-dynamic-as-bottom error in generated gRPC code.

0.7.8 - 2017-10-25

  • Added enumValues to FieldInfo.

0.7.7 - 2017-09-25

  • Avoid name clashes between import prefix and field names.
  • Avoid name clashes between generated enum and extension class names.
  • Updated gRPC client stub generation to match latest changes to dart-lang/grpc-dart.

0.7.6 - 2017-08-22

  • Updated gRPC client stub generation to produce code matching latest changes to dart-lang/grpc-dart.

0.7.5 - 2017-08-04

  • Use real generic syntax instead of comment-based.
  • Support 2.0.0 dev SDKs.

0.7.4 - 2017-07-07

  • Added call options to gRPC client stubs.

0.7.3 - 2017-07-05

gRPC support

  • Added gRPC stub generation.
  • Updated descriptor.proto from google/protobuf v3.3.0.

0.7.2 - 2017-06-12

  • Added CHANGELOG.md

0.7.1 - 2017-06-12

  • Enable executable for pub global usage. Protoc plugin can now be installed by running pub global activate protoc_plugin.
  • Ensure generated extension class names don't conflict with message class names.
  • Function will soon be a reserved keyword, so don't generate classes with that name.
  • Strong mode tweaks and lint fixes.

0.7.0 - Not released

  • Change how to customize the Dart name of a field to using a dart_name option.
  • Implemented support for adding external mixins to generate Dart protos.

0.6.0+1 - Not released

  • Fix missing import when an extension uses an enum in the same .proto file.

0.6.0 - Not released

  • Move protobuf enums to a separate .pbenum.dart file.
  • Move server-side stubs to .pbserver.dart.

0.5.2 - Not released

  • Generate separate .pbjson.dart files for constants.

0.5.1 - 2016-04-12

Strong mode and Bazel

  • Fixed all analyzer diagnostics in strong mode.
  • Added experimental support for Bazel.

0.5.0 - 2015-10-02

Performance improvements

This release requires 0.5.0 of the protobuf library.

  • significantly improved performance for getters, setters, and hazzers
  • Each enum type now has a $json constant that contains its metadata.

0.4.1 - 2015-08-22

Fixed imports, $checkItem, $json

  • Fixed all warnings, including in generated code.
  • Started generating $checkItem function for verifying the values of repeated fields
  • Fixed service stubs to work when a message is in a different package
  • Started generating JSON constants to get the original descriptor data for services

0.4.0 - 2015-07-16

Getters for message fields changed

This release changes how getters work for message fields, to detect a common mistake.

Previously, the protobuf API didn't report any error for an incorrect usage of setters. For example, if field "foo" is a message field of type Foo, this code would silently have no effect:

var msg = new SomeMessage(); msg.foo.bar = 123; This is because "msg.foo" would call "new Foo()" and return it without saving it.

The example can be fixed like this:

var msg = new SomeMessage(); msg.foo = new Foo(); msg.foo.bar = 123; Or equivalently:

var msg = new SomeMessage() ..foo = (new Foo()..bar = 123); Starting in 0.4.0, the default value of "msg.foo" is an immutable instance of Foo. You can read the default value of a field the same as before, but writes will throw UnsupportedError.

0.3.11 - 2015-07-08

  • Fixes issues with reserved names

0.3.10 - 2015-07-06

  • Adds support for generating stubs from service definitions.

0.3.9 - 2015-06-24

  • Modify dart_options support so that it supports alternate mixins.
  • Move the experimental map implementation to PbMapMixin

For now, new mixins can only be added using a patch:

  • add the new class to the protobuf library
  • add the class to the list in mixin.dart.

0.3.8 - 2015-06-16

Added option for experimental map API

  • Changed the Map API so that operator [] and operator []= support dotted keys such as "foo.bar".

This new API is subject to change without notice, but if you want to try it out anyway, see the unit test.

0.3.7 - Unreleased

Added option for experimental map API

  • Added an option to have GeneratedMessage subclasses implement Map.

0.3.6 - 2016-04-22

Added writeToJsonMap and mergeFromJsonMap to reservedNames

The 0.3.6 version of the dart-protobuf library added two new functions, so this release changes the protobuf compiler to avoid using them.

0.3.5 - 2015-03-31

Protobuf changes for smaller dart2js code, Int64 fixes

This change is paired with https://chromiumcodereview.appspot.com/814213003

Reduces code size for one app by 0.9%

  1. Allow constants for the default value to avoid many trivial closures.
  2. Generate and use static M.create() and M.createRepeated() methods on message classes M to ensure there is a shared copy of these closures rather than one copy per use.
  3. Parse Int64 values rather than generate from 'int' to ensure no truncation errors in JavaScript.

0.3.4 - 2015-03-31

Parameterize uri resolution and parsing of options, use package:path.

This helps make the compiler more configurable to embed it in other systems (like pub transformers)

0.3.3 - 2015-03-31

Update the version number

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  protoc_plugin: "^0.7.11"

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter packages get

Alternatively, your editor might support pub get or packages get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:protoc_plugin/base_type.dart';

import 'package:protoc_plugin/bazel.dart';

import 'package:protoc_plugin/client_generator.dart';

import 'package:protoc_plugin/code_generator.dart';

import 'package:protoc_plugin/const_generator.dart';

import 'package:protoc_plugin/enum_generator.dart';

import 'package:protoc_plugin/extension_generator.dart';

import 'package:protoc_plugin/file_generator.dart';

import 'package:protoc_plugin/grpc_generator.dart';

import 'package:protoc_plugin/indenting_writer.dart';

import 'package:protoc_plugin/linker.dart';

import 'package:protoc_plugin/message_generator.dart';

import 'package:protoc_plugin/names.dart';

import 'package:protoc_plugin/options.dart';

import 'package:protoc_plugin/output_config.dart';

import 'package:protoc_plugin/protobuf_field.dart';

import 'package:protoc_plugin/protoc.dart';

import 'package:protoc_plugin/service_generator.dart';

import 'package:protoc_plugin/testing/mixins.dart';
        
Version Uploaded Documentation Archive
0.7.11 Apr 9, 2018 Go to the documentation of protoc_plugin 0.7.11 Download protoc_plugin 0.7.11 archive
0.7.10 Feb 22, 2018 Go to the documentation of protoc_plugin 0.7.10 Download protoc_plugin 0.7.10 archive
0.7.9 Jan 12, 2018 Go to the documentation of protoc_plugin 0.7.9 Download protoc_plugin 0.7.9 archive
0.7.8 Oct 25, 2017 Go to the documentation of protoc_plugin 0.7.8 Download protoc_plugin 0.7.8 archive
0.7.7 Sep 25, 2017 Go to the documentation of protoc_plugin 0.7.7 Download protoc_plugin 0.7.7 archive
0.7.6 Aug 23, 2017 Go to the documentation of protoc_plugin 0.7.6 Download protoc_plugin 0.7.6 archive
0.7.5 Aug 14, 2017 Go to the documentation of protoc_plugin 0.7.5 Download protoc_plugin 0.7.5 archive
0.7.4 Jul 7, 2017 Go to the documentation of protoc_plugin 0.7.4 Download protoc_plugin 0.7.4 archive
0.7.3 Jul 5, 2017 Go to the documentation of protoc_plugin 0.7.3 Download protoc_plugin 0.7.3 archive
0.7.2 Jun 12, 2017 Go to the documentation of protoc_plugin 0.7.2 Download protoc_plugin 0.7.2 archive

All 11 versions...

Analysis

We analyzed this package on Apr 9, 2018, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.0.0-dev.46.0
  • pana: 0.10.6

Scores

Popularity:
Describes how popular the package is relative to other packages. [more]
48 / 100
Health:
Code health derived from static analysis. [more]
99 / 100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
99 / 100
Overall score:
Weighted score of the above. [more]
74
Learn more about scoring.

Platforms

Detected platforms: Flutter, other

Platform components identified in package: io, isolate.

Suggestions

  • The description is too short.

    Add more detail about the package, what it does and what is its target use case. Try to write at least 60 characters.

  • Fix analysis and formatting issues.

    Analysis or formatting checks reported 19 hints.

    Strong-mode analysis of lib/src/dart_options.pb.dart gave the following hint:

    line: 97 col: 7
    Name types using UpperCamelCase.

    Strong-mode analysis of lib/src/descriptor.pb.dart gave the following hint:

    line: 154 col: 7
    Name types using UpperCamelCase.

    Similar analysis of the following files failed:

    • lib/src/descriptor.pbenum.dart (hint)
    • lib/src/plugin.pb.dart (hint)
  • Package is pre-v1 release.

    While there is nothing inherently wrong with versions of 0.*.*, it usually means that the author is still experimenting with the general direction API.

  • Maintain an example.

    Create a short demo in the example/ directory to show how to use this package. Common file name patterns include: main.dart, example.dart or you could also use protoc_plugin.dart.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=1.21.0 <2.0.0
dart_style ^1.0.6 1.0.10
fixnum ^0.10.5 0.10.7
path ^1.0.0 1.5.1
protobuf ^0.7.1 0.7.2
Transitive dependencies
analyzer 0.31.2-alpha.1
args 1.4.1
async 2.0.6
charcode 1.1.1
cli_util 0.1.2+1
collection 1.14.9
convert 2.0.1
crypto 2.0.2+1
csslib 0.14.1
front_end 0.1.0-alpha.11
glob 1.1.5
html 0.13.3
isolate 1.1.0 2.0.0
kernel 0.3.0-alpha.11
logging 0.11.3+1
meta 1.1.2
package_config 1.0.3
plugin 0.2.0+2
source_span 1.4.0
string_scanner 1.0.2
typed_data 1.1.5
utf 0.9.0+4
watcher 0.9.7+7
yaml 2.1.13
Dev dependencies
browser any
test ^0.12.0