rethinkdb / protobuf-plugin-closure Goto Github PK

# Copyright (c) 2010-2011 SameGoal LLC.
# All Rights Reserved.
# Author: Andy Hochhaus <[email protected]>

# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

The protobuf-plugin-closure project contains two protoc plugins that can be
used individually or together. The plugin that lives in the "js" directory
generates *.pb.js files for use with the closure-library proto2 package [1].
The "js" plugin is useful to access protocol buffers from javascript.
Additionally, the "ccjs" directory contains a plugin that (de)serializes
to/from the json based protocol buffer encodings assumed by closure-library.
You can use this plugin to share protocol buffers between a C++ based server
and a javascript client.

The supplied protobuf.gyp file is used with the GYP build system [2] to compile
the plugins and supporting library. Note that this file is written to assume
the protocol buffer source code is also compiled using gyp. See the chromium
source code for an example [3].

If you do not build with GYP, you can also compile manually from the command
line. In all steps, make sure you modify the paths to match your environment.

The "js" compiler plugin adds javascript_package and jstype options using
extensions. These options are defined in javascript_package.proto and
int64_encoding.proto. These *.proto files must be run through the protocol
compiler prior to compiling this plugin. To do so, run protoc as follows:

$ ./build/third_party/protobuf/bin/protoc \
    -I . \
    -I third_party/protobuf/src/ \
    --cpp_out=. \
    javascript_package.proto

Next compile the plugin(s) as follows:

$ g++ -I ./build/third_party/protobuf/include/ \
    -I . \
    ./protobuf/src/google/protobuf/compiler/plugin.pb.cc \
    ./protobuf/src/google/protobuf/compiler/plugin.cc \
    ./js/code_generator.cc \
    ./js/protoc_gen_js.cc \
    ./js/javascript_package.pb.cc \
    ./js/int64_encoding.pb.cc \
    -l:./build/third_party/protobuf/lib/libprotobuf.a \
    -l:./build/third_party/protobuf/lib/libprotoc.a \
    -o ./build/protobuf/js/protoc-gen-js \
    -lpthread

$ g++ -I ./build/third_party/protobuf/include/ \
    -I . \
    ./protobuf/src/google/protobuf/compiler/plugin.pb.cc \
    ./protobuf/src/google/protobuf/compiler/plugin.cc \
    ./ccjs/code_generator.cc \
    ./ccjs/protoc_gen_ccjs.cc \
    ./js/int64_encoding.pb.cc \
    -l:./build/third_party/protobuf/lib/libprotobuf.a \
    -l:./build/third_party/protobuf/lib/libprotoc.a \
    -o ./build/protobuf/ccjs/protoc-gen-ccjs \
    -lpthread

Finally, to run the protoc compiler with the plugin(s):

$ ./build/third_party/protobuf/bin/protoc \
    --plugin=build/protobuf/js/protoc-gen-js \
    --plugin=build/protobuf/ccjs/protoc-gen-ccjs \
    -I . \
    -I build/third_party/protobuf/src/ \
    --js_out=/tmp/foo/ \
    --cpp_out=/tmp/foo/ \
    --ccjs_out=/tmp/foo/ \
    test.proto

Notes:

* To the best of my knowledge, custom file options/extensions need to be
  explicitly defined in the *.proto files in order to be used. This *.proto to
  *.pb.js compiler is implemented as a plugin. Therefore, if you wish to use
  the javascript_package option you must import javascript_package.proto.
  This appears slightly different than the internal Google javascript compiler
  which appears to native support the javascript_package option. Therefore,
  the example files provided by Google [4] need to be modified a bit before
  running through the plugin. Most notably:

  The original files use javascript_package as follows:

    option javascript_package = "proto2";

  However, this plugin requires (javascript_package) to be specified:

    import "protobuf/js/javascript_package.proto";

    option (javascript_package) = "proto2";

* A few white-space and order differences exist between the *.pb.js files
  generated by this plugin and the sample files provided by Google [5].
  However, to the best of my knowledge they are functionally similar. If you
  discover any unexpected behavior please contact me.

* Protocol buffers in javascript behave differently than their c++/java/python
  counterparts with respect to default values. In c++/java/python when you
  get() a field that is not set the default value is returned. However, in
  javascript, null is returned instead of the default value. If you wish to
  have the default value returned, you must call the getFieldOrDefault()
  variant. This decision was made for performance reasons [6].

* The ccjs plugin currently generates sub-optimal (de)serialization code.
  I hope to improve the code as I have more time. Improvements are appreciated.

[1] http://closure-library.googlecode.com/svn/docs/namespace_goog_proto2.html

[2] http://code.google.com/p/gyp/

[3] http://src.chromium.org/viewvc/chrome/trunk/src/third_party/protobuf/protobuf.gyp

[4] https://groups.google.com/group/closure-library-discuss/browse_thread/thread/fc4446a2a61c28ee (See message from Erik Arvidsson)

[5] http://closure-library.googlecode.com/svn/trunk/closure/goog/proto2/test.pb.js
    http://closure-library.googlecode.com/svn/trunk/closure/goog/proto2/package_test.pb.js

[6] https://groups.google.com/group/closure-library-discuss/browse_thread/thread/fc4446a2a61c28ee (See message from Joseph Schorr)