1 | Protocol Buffers - Google's data interchange format
|
2 | ===================================================
|
3 |
|
4 | [![Build status](https://storage.googleapis.com/protobuf-kokoro-results/status-badge/linux-javascript.png)](https://fusion.corp.google.com/projectanalysis/current/KOKORO/prod:protobuf%2Fgithub%2Fmaster%2Fubuntu%2Fjavascript%2Fcontinuous) [![Build status](https://storage.googleapis.com/protobuf-kokoro-results/status-badge/macos-javascript.png)](https://fusion.corp.google.com/projectanalysis/current/KOKORO/prod:protobuf%2Fgithub%2Fmaster%2Fmacos%2Fjavascript%2Fcontinuous)
|
5 |
|
6 | Copyright 2008 Google Inc.
|
7 |
|
8 | This directory contains the JavaScript Protocol Buffers runtime library.
|
9 |
|
10 | The library is currently compatible with:
|
11 |
|
12 | 1. CommonJS-style imports (eg. `var protos = require('my-protos');`)
|
13 | 2. Closure-style imports (eg. `goog.require('my.package.MyProto');`)
|
14 |
|
15 | Support for ES6-style imports is not implemented yet. Browsers can
|
16 | be supported by using Browserify, webpack, Closure Compiler, etc. to
|
17 | resolve imports at compile time.
|
18 |
|
19 | To use Protocol Buffers with JavaScript, you need two main components:
|
20 |
|
21 | 1. The protobuf runtime library. You can install this with
|
22 | `npm install google-protobuf`, or use the files in this directory.
|
23 | If npm is not being used, as of 3.3.0, the files needed are located in binary subdirectory;
|
24 | arith.js, constants.js, decoder.js, encoder.js, map.js, message.js, reader.js, utils.js, writer.js
|
25 | 2. The Protocol Compiler `protoc`. This translates `.proto` files
|
26 | into `.js` files. The compiler is not currently available via
|
27 | npm, but you can download a pre-built binary
|
28 | [on GitHub](https://github.com/protocolbuffers/protobuf/releases)
|
29 | (look for the `protoc-*.zip` files under **Downloads**).
|
30 |
|
31 |
|
32 | Setup
|
33 | =====
|
34 |
|
35 | First, obtain the Protocol Compiler. The easiest way is to download
|
36 | a pre-built binary from [https://github.com/protocolbuffers/protobuf/releases](https://github.com/protocolbuffers/protobuf/releases).
|
37 |
|
38 | If you want, you can compile `protoc` from source instead. To do this
|
39 | follow the instructions in [the top-level
|
40 | README](https://github.com/protocolbuffers/protobuf/blob/master/src/README.md).
|
41 |
|
42 | Once you have `protoc` compiled, you can run the tests by typing:
|
43 |
|
44 | $ cd js
|
45 | $ npm install
|
46 | $ npm test
|
47 |
|
48 | # If your protoc is somewhere else than ../src/protoc, instead do this.
|
49 | # But make sure your protoc is the same version as this (or compatible)!
|
50 | $ PROTOC=/usr/local/bin/protoc npm test
|
51 |
|
52 | This will run two separate copies of the tests: one that uses
|
53 | Closure Compiler style imports and one that uses CommonJS imports.
|
54 | You can see all the CommonJS files in `commonjs_out/`.
|
55 | If all of these tests pass, you know you have a working setup.
|
56 |
|
57 |
|
58 | Using Protocol Buffers in your own project
|
59 | ==========================================
|
60 |
|
61 | To use Protocol Buffers in your own project, you need to integrate
|
62 | the Protocol Compiler into your build system. The details are a
|
63 | little different depending on whether you are using Closure imports
|
64 | or CommonJS imports:
|
65 |
|
66 | Closure Imports
|
67 | ---------------
|
68 |
|
69 | If you want to use Closure imports, your build should run a command
|
70 | like this:
|
71 |
|
72 | $ protoc --js_out=library=myproto_libs,binary:. messages.proto base.proto
|
73 |
|
74 | For Closure imports, `protoc` will generate a single output file
|
75 | (`myproto_libs.js` in this example). The generated file will `goog.provide()`
|
76 | all of the types defined in your .proto files. For example, for the unit
|
77 | tests the generated files contain many `goog.provide` statements like:
|
78 |
|
79 | goog.provide('proto.google.protobuf.DescriptorProto');
|
80 | goog.provide('proto.google.protobuf.DescriptorProto.ExtensionRange');
|
81 | goog.provide('proto.google.protobuf.DescriptorProto.ReservedRange');
|
82 | goog.provide('proto.google.protobuf.EnumDescriptorProto');
|
83 | goog.provide('proto.google.protobuf.EnumOptions');
|
84 |
|
85 | The generated code will also `goog.require()` many types in the core library,
|
86 | and they will require many types in the Google Closure library. So make sure
|
87 | that your `goog.provide()` / `goog.require()` setup can find all of your
|
88 | generated code, the core library `.js` files in this directory, and the
|
89 | Google Closure library itself.
|
90 |
|
91 | Once you've done this, you should be able to import your types with
|
92 | statements like:
|
93 |
|
94 | goog.require('proto.my.package.MyMessage');
|
95 |
|
96 | var message = proto.my.package.MyMessage();
|
97 |
|
98 | If unfamiliar with Closure or it's compiler, consider reviewing Closure documentation
|
99 | https://developers.google.com/closure/library/docs/tutorial
|
100 | https://developers.google.com/closure/library/docs/closurebuilder
|
101 | https://developers.google.com/closure/library/docs/depswriter
|
102 | At a high level, closurebuilder.py can walk dependencies, and compile your code, and all dependencies for Protobuf into a single .js file. Using depsbuilder.py to generate a dependency file can also be considered for non-production dev environments.
|
103 |
|
104 | CommonJS imports
|
105 | ----------------
|
106 |
|
107 | If you want to use CommonJS imports, your build should run a command
|
108 | like this:
|
109 |
|
110 | $ protoc --js_out=import_style=commonjs,binary:. messages.proto base.proto
|
111 |
|
112 | For CommonJS imports, `protoc` will spit out one file per input file
|
113 | (so `messages_pb.js` and `base_pb.js` in this example). The generated
|
114 | code will depend on the core runtime, which should be in a file called
|
115 | `google-protobuf.js`. If you are installing from `npm`, this file should
|
116 | already be built and available. If you are running from GitHub, you need
|
117 | to build it first by running:
|
118 |
|
119 | $ gulp dist
|
120 |
|
121 | Once you've done this, you should be able to import your types with
|
122 | statements like:
|
123 |
|
124 | var messages = require('./messages_pb');
|
125 |
|
126 | var message = new messages.MyMessage();
|
127 |
|
128 | The `--js_out` flag
|
129 | -------------------
|
130 |
|
131 | The syntax of the `--js_out` flag is:
|
132 |
|
133 | --js_out=[OPTIONS:]output_dir
|
134 |
|
135 | Where `OPTIONS` are separated by commas. Options are either `opt=val` or
|
136 | just `opt` (for options that don't take a value). The available options
|
137 | are specified and documented in the `GeneratorOptions` struct in
|
138 | [src/google/protobuf/compiler/js/js_generator.h](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/compiler/js/js_generator.h#L53).
|
139 |
|
140 | Some examples:
|
141 |
|
142 | - `--js_out=library=myprotos_lib.js,binary:.`: this contains the options
|
143 | `library=myprotos.lib.js` and `binary` and outputs to the current directory.
|
144 | The `import_style` option is left to the default, which is `closure`.
|
145 | - `--js_out=import_style=commonjs,binary:protos`: this contains the options
|
146 | `import_style=commonjs` and `binary` and outputs to the directory `protos`.
|
147 | `import_style=commonjs_strict` doesn't expose the output on the global scope.
|
148 |
|
149 | API
|
150 | ===
|
151 |
|
152 | The API is not well-documented yet. Here is a quick example to give you an
|
153 | idea of how the library generally works:
|
154 |
|
155 | var message = new MyMessage();
|
156 |
|
157 | message.setName("John Doe");
|
158 | message.setAge(25);
|
159 | message.setPhoneNumbers(["800-555-1212", "800-555-0000"]);
|
160 |
|
161 | // Serializes to a UInt8Array.
|
162 | var bytes = message.serializeBinary();
|
163 |
|
164 | var message2 = MyMessage.deserializeBinary(bytes);
|
165 |
|
166 | For more examples, see the tests. You can also look at the generated code
|
167 | to see what methods are defined for your generated messages.
|