Greatly expanded README.md.
This commit is contained in:
Josh Haberman
parent
59ea5000bb
commit
5195b7f296
1 changed files with 130 additions and 10 deletions
140
js/README.md
140
js/README.md
|
|
@ -1,14 +1,134 @@
|
|||
This directory contains Protocol Buffer support for JavaScript. This code works
|
||||
in browsers and in Node.js.
|
||||
Protocol Buffers - Google's data interchange format
|
||||
===================================================
|
||||
|
||||
The packaging work for this is still in-progress. For now you can just run the
|
||||
tests. First you need to build the main C++ distribution because the code
|
||||
generator for JavaScript is written in C++:
|
||||
[](https://travis-ci.org/google/protobuf)
|
||||
|
||||
$ ./autogen.sh
|
||||
$ ./configure
|
||||
$ make
|
||||
Copyright 2008 Google Inc.
|
||||
|
||||
Then you can run the JavaScript tests in this directory:
|
||||
This directory contains the JavaScript Protocol Buffers runtime library.
|
||||
|
||||
$ cd js && gulp test
|
||||
The library is currently compatible with:
|
||||
|
||||
1. CommonJS-style imports (eg. `var protos = require('my-protos');`)
|
||||
2. Closure-style imports (eg. `goog.require('my.package.MyProto');`)
|
||||
|
||||
Support for ES6-style imports is not implemented yet. Browsers can
|
||||
be supported by using Browserify, webpack, Closure Compiler, etc. to
|
||||
resolve imports at compile time.
|
||||
|
||||
To use Protocol Buffers with JavaScript, you need two main components:
|
||||
|
||||
1. The protobuf runtime library. You can install this with
|
||||
`npm install google-protobuf`, or use the files in this directory.
|
||||
2. The Protocol Compiler `protoc`. This translates `.proto` files
|
||||
into `.js` files. The compiler is not currently available via
|
||||
npm -- you must download and compile it from GitHub or a tarball.
|
||||
|
||||
|
||||
Setup
|
||||
=====
|
||||
|
||||
First, compile the Protocol Compiler.
|
||||
You can compile `protoc` from GitHub or a source tarball. From the
|
||||
top level directory type:
|
||||
|
||||
$ ./autogen.sh (only necessary for GitHub)
|
||||
$ ./configure
|
||||
$ make
|
||||
|
||||
|
||||
Once you have `protoc` compiled, you can run the tests by typing:
|
||||
|
||||
$ npm install
|
||||
$ npm test
|
||||
|
||||
This will run two separate copies of the tests: one that uses
|
||||
Closure Compiler style imports and one that uses CommonJS imports.
|
||||
You can see all the CommonJS files in `commonjs_out/`.
|
||||
If all of these tests pass, you know you have a working setup.
|
||||
|
||||
|
||||
Using Protocol Buffers in your own project
|
||||
==========================================
|
||||
|
||||
To use Protocol Buffers in your own project, you need to integrate
|
||||
the Protocol Compiler into your build system. The details are a
|
||||
little different depending on whether you are using Closure imports
|
||||
or CommonJS imports:
|
||||
|
||||
Closure Imports
|
||||
---------------
|
||||
|
||||
If you want to use Closure imports, your build should run a command
|
||||
like this:
|
||||
|
||||
$ protoc --js_out=library=myproto_libs,binary:. messages.proto base.proto
|
||||
|
||||
For Closure imports, `protoc` will generate a single output file
|
||||
(`myproto_libs.js` in this example). The generated file will `goog.provide()`
|
||||
all of the types defined in your .proto files. For example, for the unit
|
||||
tests the generated files contain many `goog.provide` statements like:
|
||||
|
||||
goog.provide('proto.google.protobuf.DescriptorProto');
|
||||
goog.provide('proto.google.protobuf.DescriptorProto.ExtensionRange');
|
||||
goog.provide('proto.google.protobuf.DescriptorProto.ReservedRange');
|
||||
goog.provide('proto.google.protobuf.EnumDescriptorProto');
|
||||
goog.provide('proto.google.protobuf.EnumOptions');
|
||||
|
||||
The generated code will also `goog.require()` many types in the core library,
|
||||
and they will require many types in the Google Closure library. So make sure
|
||||
that your `goog.provide()` / `goog.require()` setup can find all of your
|
||||
generated code, the core library `.js` files in this directory, and the
|
||||
Google Closure library itself.
|
||||
|
||||
Once you've done this, you should be able to import your types with
|
||||
statements like:
|
||||
|
||||
goog.require('proto.my.package.MyMessage');
|
||||
|
||||
var message = proto.my.package.MyMessage();
|
||||
|
||||
CommonJS imports
|
||||
----------------
|
||||
|
||||
If you want to use CommonJS imports, your build should run a command
|
||||
like this:
|
||||
|
||||
$ protoc --js_out=import_style=commonjs,binary:. messages.proto base.proto
|
||||
|
||||
For CommonJS imports, `protoc` will spit out one file per input file
|
||||
(so `messages_pb.js` and `base_pb.js` in this example). The generated
|
||||
code will depend on the core runtime, which should be in a file called
|
||||
`google-protobuf.js`. If you are installing from `npm`, this file should
|
||||
already be built and available. If you are running from GitHub, you need
|
||||
to build it first by running:
|
||||
|
||||
$ gulp dist
|
||||
|
||||
Once you've done this, you should be able to import your types with
|
||||
statements like:
|
||||
|
||||
var messages = require('./messages_pb');
|
||||
|
||||
var message = new messages.MyMessage();
|
||||
|
||||
API
|
||||
===
|
||||
|
||||
The API is not well-documented yet. Here is a quick example to give you an
|
||||
idea of how the library generally works:
|
||||
|
||||
var message = new MyMessage();
|
||||
|
||||
message.setName("John Doe");
|
||||
message.setAge(25);
|
||||
message.setPhoneNumbers(["800-555-1212", "800-555-0000"]);
|
||||
|
||||
// Serializes to a UInt8Array.
|
||||
bytes = message.serializeBinary();
|
||||
|
||||
var message2 = new MyMessage();
|
||||
message2.deserializeBinary(bytes);
|
||||
|
||||
For more examples, see the tests. You can also look at the generated code
|
||||
to see what methods are defined for your generated messages.
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue