Tweak READMEs: (#610)
- Fix typos
- Shorten some long lines in markdown files using footnote-style
markdown links
- Use `#` header syntax instead of a mix of `#` and underscores: it's
unclear whether `---` is smaller than `##` or not. Using `#` for all
headers is also more consistent and makes it easier to read in
markdown format (rather than in rendered).
- Add syntax highlighting to Dart and proto code examples.
- Split "How to build and use" section into "How to build" and "How to
use" sections.
- Move `dart pub activate` method up and make it the recommended way of
installing the plugin.
- Describe how to build standalone native executables for the plugin.
- Addresses #576:
- For each installation method clarify whether they generate a Dart
script or standalone native executable.
- Addresses: #529:
- Mention that latest version of Dart may be needed. Older versions
don't have `dart pub` command and can cause errors when following
installation instructions.
- Link to protoc_plugin pub.dev page in protobuf README.
- Link to Dart installation instructions in protoc_plugin README.
Fixes #576
Fixes #529diff --git a/protobuf/README.md b/protobuf/README.md
index 25c67cd..0bba861 100644
--- a/protobuf/README.md
+++ b/protobuf/README.md
@@ -1,17 +1,17 @@
[](https://pub.dev/packages/protobuf)
-Provides runtime support for a Dart implementation of protobufs.
+Provides runtime support for a Dart implementation of [protobufs][1].
-Typically one do not need to import this library–only libraries
-generated by the protoc plugin import this library directly.
+Typically one does not need to import this library. The [protoc plugin][2]
+compiles proto definitions to Dart files that import this library. If your
+library or application uses generated protobuf libraries, add this library as a
+dependency.
-If your library or application uses generated protobuf libraries, add this
-library as a dependency.
+[1]: https://developers.google.com/protocol-buffers
+[2]: https://pub.dev/packages/protoc_plugin
### References
-* [Dart tutorial](https://developers.google.com/protocol-buffers/docs/darttutorial)
-* [Dart generated code guide](https://developers.google.com/protocol-buffers/docs/reference/dart-generated)
-* [Dart API](https://pub.dev/documentation/protobuf/latest/)
-* [Protobuf repository](https://github.com/google/protobuf)
-* [Protoc plugin project](https://github.com/google/protobuf.dart/tree/master/protoc_plugin)
+* [Protobuf Dart tutorial](https://developers.google.com/protocol-buffers/docs/darttutorial)
+* [Guide to generated Dart code](https://developers.google.com/protocol-buffers/docs/reference/dart-generated)
+* [Dart API](https://pub.dev/documentation/protobuf/latest/protobuf/protobuf-library.html)
diff --git a/protoc_plugin/README.md b/protoc_plugin/README.md
index ce98b99..041732b 100644
--- a/protoc_plugin/README.md
+++ b/protoc_plugin/README.md
@@ -2,64 +2,88 @@
[](https://pub.dev/packages/protoc_plugin)
-This repository provides a plugin for the [protoc
-compiler](https://developers.google.com/protocol-buffers/docs/cpptutorial#compiling-your-protocol-buffers).
-It generates Dart files for working with data in protocol buffers format.
+This repository provides a plugin for the [protoc compiler][1]. It generates
+Dart files for working with data in protocol buffers format.
-Requirements
-------------
+[1]: https://developers.google.com/protocol-buffers/docs/cpptutorial#compiling-your-protocol-buffers
-To compile a .proto file, you must use the 'protoc' command which is [installed
-separately](https://developers.google.com/protocol-buffers/docs/downloads).
-Protobuf 3.0.0 or above is required.
+## Requirements
-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](https://pub.dev/packages/protobuf). A Dart project that
-includes generated files should add "protobuf" to its pubspec.yaml file.
+To compile a .proto file, you must use the `protoc` command which is [installed
+separately][1]. 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][2]). They depend on the [protobuf Dart package][3]. A
+Dart project that includes generated files should add `protobuf` as a
+dependency in the `pubspec.yaml` file.
-How to build and use
---------------------
+[1]: https://developers.google.com/protocol-buffers/docs/downloads
+[2]: https://dart.dev/tools/dart2js
+[3]: https://pub.dev/packages/protobuf
-*Note:* currently the workflow is POSIX-oriented.
+## How to build
-To build standalone `protoc` plugin:
-- Run `dart pub get` 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.
+Make sure you have `dart` executable in your `PATH`. See the [Dart installation
+instructions][1] for details.
-Please, remember that the plugin is pure Dart script and requires the presence
-of `dart` executable in your `PATH`.
+If you encounter any issues while following the instructions below, please make
+sure you have the latest version of Dart installed.
-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:
+[1]: https://dart.dev/get-dart
+
+**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:
$ protoc --dart_out=. test.proto
-### Optionally using `pub global`
+If you don't want to add `protoc-gen-dart` to `PATH`, you can specify the path
+to it like this:
- $ 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>
-
+ $ 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 individial options are separated using comma, and the
+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 Code Info
+### 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
@@ -68,48 +92,52 @@
--dart_out="generate_kythe_info,<other options>:."
-Using protocol buffer libraries to build new libraries
-------------------------------------------------------
+## 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
+libraries or create new libraries combining object definitions from
several `.proto` libraries into one.
-The best way to aproach this is to create the new libraries needed and
+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
- message M1 {
- optional string a;
- }
+```proto
+message M1 {
+ optional string a;
+}
+```
and `m2.proto` containing
- message M2 {
- optional string b;
- }
+```proto
+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.
+adds some additional methods.
- library M;
+```dart
+library M;
- import "m1.pb.dart";
- import "m2.pb.dart";
+import "m1.pb.dart";
+import "m2.pb.dart";
- export "m1.pb.dart" show M1;
- export "m2.pb.dart" show M2;
+export "m1.pb.dart" show M1;
+export "m2.pb.dart" show M2;
- M1 createM1() => new M1();
- M2 createM2() => new M2();
+M1 createM1() => new M1();
+M2 createM2() => new M2();
+```
-Hacking
--------
+## Hacking
Here are some ways to get protoc:
@@ -119,10 +147,10 @@
If the version installed this way doesn't work, an alternative is to
[compile protoc from source](https://developers.google.com/protocol-buffers/docs/downloads).
-Remember to run the tests. That is as easy as `make run-tests`.
+Remember to run the tests. That is as easy as `dart pub get` and then `make
+run-tests`.
-Useful references
------------------
+## Useful references
* [Main Dart site](https://dart.dev)
* [Main protobuf site](https://github.com/protocolbuffers/protobuf)
